FlyUI Tokens

@wayflyer/flyui-tokens turns the canonical design tokens that live in Figma into:

• Hashed CSS bundles with custom properties (per theme) that can be loaded in any product.
• TypeScript-friendly theme objects that expose the same values for runtime logic.
• A canonical validCssCustomProperties list that powers lint rules and keeps ad‑hoc CSS vars out of our apps.
• A themeManifest that maps theme keys to the hashed CSS filenames we publish to /fly-assets/themes.

System overview

• The supernova directory contains JSON snapshots that are synced from Figma via the Supernova service. Never edit these by hand, rerun the sync instead. This is done from here (run the Styled Dictionary pipeline to open a PR).
• scripts/build-tokens.mts is the single build script that ingests the JSON, and transforms it into CSS and TS artifacts for the consuming apps.
• pnpm generate-tokens (declared in package.json) runs the build script, formats the generated TS, and is invoked before pnpm build.
• Generated files land in src/build (for consumption inside the package) and public/themes (hashed CSS that other apps fetch from the CDN).

Data flow

flowchart TB
  Figma[Figma variables] -->|Supernova sync| SupernovaJSON[packages/flyui-tokens/src/supernova/*.json]
  SupernovaJSON --> buildScript[scripts/build-tokens.mts]
  buildScript --> cssLocal[src/build/*.css]
  buildScript --> tsTheme[src/build/theme.ts]
  buildScript --> manifest[src/build/theme-manifest.ts]
  cssHashed --> CDN["CDN: /fly-assets/themes"]
  tsTheme --> npmDist["flyui-tokens exports"]

Repository layout

| Path | Purpose | | --- | --- | | src/supernova/{wayflyer,light,dark}/*.json | Raw design tokens from Supernova sync (colors, dimensions, typography). | | src/scripts/build-tokens.mts | The end-to-end build pipeline described below. | | src/extended-theme.ts | Extra palette + layout defaults that do not exist in Figma. | | src/build/* | Generated CSS, theme.ts, and theme-manifest.ts. |

Running the build

pnpm nx build flyui-tokens

That command runs tsx ./src/scripts/build-tokens.mts and then formats any generated TypeScript so diffs stay readable.

The pnpm build script depends on this, so publishing always ships fresh tokens.

build-tokens.mts in detail

The script performs the following high-level steps:

1. Read synced JSON – color.json, dimension.json, and string.json (from the wayflyer directory) contain both Wayflyer and white-label primitives. The script selects the correct primitive set per brand/theme.
2. Resolve references – tokens often reference one another ({palette.color.grey.50}). The resolveReference helper walks the JSON hierarchy, swaps primitive types where needed, and ensures the final value is a concrete CSS value.
3. Flatten categories – colors (processColors), sizes (processDimensions), typography (processTypography), and font sizes (processFontSize) are flattened into CSS custom properties and mirrored TypeScript paths. Spacing tokens are validated to guarantee they are n * 4px (plus the special 0-5/1-5 steps). The build fails fast if Supernova drifts from these rules, which keeps the source of truth clean.
4. Inject derived tokens – certain values are not in Figma: global breakpoints, focus/blur/shadow effects, CTA defaults, line heights, and the extendedTheme palette/defaults. These are appended after the Supernova data.
5. Generate CSS – tokens are sorted into sensible sections (defaults, spacing, other tokens, extended palette) and written to src/build/*.css. The helper copyToPublicThemes hashes each CSS file, cleans up old versions in public/themes, and updates an in-memory manifest so apps can look up /fly-assets/themes/<theme>.<hash>.css.
6. Generate TypeScript – all token paths are assembled into a deeply nested tokens object plus literal string types. The same pass emits validCssCustomProperties, which contains every custom property name (without the -- prefix) alongside a few hardcoded wildcard patterns (e.g., app-*, scoped-*, grid-*).
7. Write the manifest – theme-manifest.ts exports a ThemeManifest object with a schemaVersion and a styles map of { [themeKey]: "/fly-assets/themes/<hashed>.css" }. This is what apps load at runtime when swapping themes.

Token categories

• Palette tokens – built from palette.mapped, plus top-level bg/content sections if needed. Alias references are resolved so white-label builds can reuse Wayflyer primitives automatically.
• Sizes – includes spacing, radius, stroke, blur, and hard-coded breakpoints. Special-case spacing keys (0-5, 1-5) are added, and both CSS and TypeScript representations keep numeric ordering intact.
• Typography – includes font families, weights (converted to numeric values), line heights, and aliases. When secondary typefaces are missing, they fall back to the primary definition.
• Extended palette + defaults – extended-theme.ts houses data like chart colors and layout defaults that are not managed in Figma yet. These are treated like any other CSS var so downstream apps can reference them consistently.

ESLint integration

The exported validCssCustomProperties list is consumed inside @wayflyer/eslint-plugin rules so only sanctioned CSS custom properties are used. For example, packages/flyui/eslint.config.mjs extends the @wayflyer/allowed-css-variables rule with the allowlist:

import { validCssCustomProperties } from "@wayflyer/flyui-tokens";

export default {
  rules: {
    "@wayflyer/allowed-css-variables": [
      "error",
      {
        allowlist: [...validCssCustomProperties, "disclosure-panel-height"],
      },
    ],
  },
};

Outputs & consumption

CSS assets

• Local development can import the un-hashed CSS directly:

  import "@wayflyer/flyui-tokens/wayflyer-theme.css";

• Production apps should prefer the hashed files referenced by themeManifest so they get CDN cache-busting OR re-bundle and hash the un-hashed CSS themeselves.

  import { themeManifest } from "@wayflyer/flyui-tokens";
  
  const link = document.createElement("link");
  link.rel = "stylesheet";
  link.href = themeManifest.whiteLabel; // e.g. /fly-assets/themes/whiteLabel.ab12cd34.css
  document.head.appendChild(link);

JavaScript / TypeScript API

import {
  theme,
  themeManifest,
  validCssCustomProperties,
  applyThemeOverrides,
  fetchThemeOverrides,
  getThemeFlags,
  type Theme,
  type ThemeOverrides,
} from "@wayflyer/flyui-tokens";

const Card = styled.div`
  background: var(--palette-bg-surface-default);
  padding: var(--sizes-spacing-4);
  border-radius: var(--defaults-borderRadius);
`;

const nextBreakpoint = theme.sizes.breakpoint.lg; // "1280px"

Theme override utilities

The package exports utility functions for applying runtime theme overrides:

import {
  applyThemeOverrides,
  fetchThemeOverrides,
  getThemeFlags,
  type ThemeOverrides,
} from "@wayflyer/flyui-tokens";

// Fetch theme overrides for a partner
const overrides = await fetchThemeOverrides({ partnerId: "partner-id" });

// Apply overrides to the document root (returns an undo function)
const undo = applyThemeOverrides(overrides);

// Later, revert the changes
undo();

// Or apply to a specific element
const undo = applyThemeOverrides(overrides, document.querySelector(".container"));

// Read current theme flags from CSS custom properties
const flags = getThemeFlags({ rootElement: document.documentElement });
// Returns: { cta: { content: "default", surface: "brand" } }

• applyThemeOverrides – Applies theme overrides (brand colors, border radius, fonts, CTA styles) to CSS custom properties on a given element. Returns a function that can undo all changes.
• fetchThemeOverrides – Fetches theme override JSON from the CDN for a given partner ID. Accepts { partnerId, onError? } options object.
• getThemeFlags – Reads current theme flags (e.g., CTA content/surface settings) from CSS custom properties on a root element.

Lint rule usage

All repos that use @wayflyer/eslint-plugin can wire in the allowlist exactly as FlyUI does:

import { validCssCustomProperties } from "@wayflyer/flyui-tokens";

const allowlist = [...validCssCustomProperties, "disclosure-panel-height"];

Updating tokens

1. Change Figma – update the canonical variable in Figma.
2. Sync via Supernova – run the Supernova job so the JSON snapshots under src/supernova are refreshed.
3. Regenerate – run pnpm nx build flyui-tokens to rebuild CSS/TS artifacts. The script will fail if validations (e.g., spacing) are violated.
4. Commit – include the updated JSON, generated CSS/TS, and any new hashed theme files or manifest changes. Never edit generated files manually.

By keeping this loop tight we ensure every consumer of @wayflyer/flyui-tokens (FlyUI, FlyUI Dataviz, app-shells, etc.) receives a predictable, lint-enforced set of design tokens.