@cdx-ui/styles

Forge UI design tokens, generated CSS, color utilities, and runtime theme overrides.

Install

pnpm add @cdx-ui/styles

CSS entry points

Import the files needed by the target application:

@import '@cdx-ui/styles/theme.css';
@import '@cdx-ui/styles/utilities.css';

• theme.css registers Forge tokens for Tailwind and Uniwind.
• utilities.css provides generated typography utilities.
• web.css provides unlayered .light and .dark overrides for web applications.
• vanilla.css provides framework-independent custom properties and typography classes.
• mui.css and cds.css bridge Forge semantic tokens to MUI and CDS variables.

The generated source theme is also exported:

import baseTheme from '@cdx-ui/styles/tokens/base.json';

Runtime overrides

A ThemeOverride stores FI intent. Its metadata contains only the override schema version:

import { applyThemeOverride, type ThemeOverride } from '@cdx-ui/styles';

const override = {
  $extensions: {
    'com.forge.ui.themeOverride': {
      schemaVersion: '1.0.0',
    },
  },
  inputs: {
    brandPrimary: '#0052cc',
    displayFont: 'Bitter',
  },
  selections: {
    actionSurface: {
      mode: 'linked',
      source: { ref: 'color.brand.700' },
    },
  },
  overrides: {
    'color.content.link': {
      light: { value: '#0052cc' },
      dark: { value: '#80bfff' },
    },
  },
} satisfies ThemeOverride;

const result = applyThemeOverride(override);

Expansion starts from the generated base theme, applies input generation, then selections, then direct token overrides. Runtime writes are sparse and concrete. Unknown additive fields are preserved by the parser for forward-compatible editing.

The public display-font catalog is generated from the base theme and Figma configuration:

import { displayFontCatalog } from '@cdx-ui/styles';

displayFontCatalog.defaultFamily;
displayFontCatalog.families;

Each family entry contains family, normalWeights, and italicWeights.

Web fonts

@cdx-ui/styles/fonts states what a browser has to register for the font tokens to resolve. The spec is generated from the token pipeline, so it cannot drift from theme.css.

import { buildWebFontProviderUrl, forgeWebFontSpec } from '@cdx-ui/styles/fonts';

forgeWebFontSpec.platform; // the `--font-sans` / `--font-mono` families
forgeWebFontSpec.display; // every Display family a ThemeOverride can select

buildWebFontProviderUrl([...forgeWebFontSpec.platform, forgeWebFontSpec.display[0]]);

Entries are base families with the weights and italics they ship. Register each family once per weight and let font-weight select the face — that is how a browser resolves weight, and it is what makes font-medium, font-semibold and italic reach the right file. Availability differs per family, and a provider rejects the entire request if asked for a weight a family does not have, which is why the weights travel with the family name.

Register statically where you can, so the preload scanner finds the fonts while the HTML parses: paste the built URL into a <link>, or write your own @font-face rules against self-hosted files (one rule per face, under the base family, with font-weight and font-style descriptors). loadForgeWebFonts injects the link at runtime and is for families not known until then, such as an FI font picker.

Font weight and style

Font tokens name one family per role — --font-sans, --font-body, --font-mono, --font-display. Set weight and style with font-medium / font-semibold / font-bold / italic over the family a composite typography utility already applies; every platform resolves them inside a family registered with all of its faces. Native builds get that registration from the @cdx-ui/native config plugin.

A family that ships no italic faces renders italic text upright rather than slanted. The Display family can change at runtime, so its support travels with it as --font-display-italic-style (italic or normal); style italic Display text with [font-style:var(--font-display-italic-style)] instead of italic. The sans and mono families always ship italics, so italic is correct for body and mono text.

Target adapters

The package includes adapters for Uniwind and MUI:

import { expandThemeOverride, toMuiThemeOptions, toUniwindMaps } from '@cdx-ui/styles';

Covering Uniwind sessions are available when an editor must clear values written by earlier previews without touching unrelated CSS variables.

Token pipeline

tokens/base.json is the token source for the build. Most tokens mirror Figma Variables and are written by the fetch; figma.config.json maps stable collection roles to Figma collection names and sets the outputFile.

Tokens that exist only in code are added to tokens/base.json by hand and marked code-owned:

"ai-start": {
  "$type": "color",
  "$value": "{color.brand.400}",
  "$extensions": { "com.forge.ui.token": { "source": "code" } }
}

The fetch keeps every marked token unchanged and drops unmarked tokens that Figma no longer defines. When Figma defines a variable at a code-owned path, the fetch fails so a person decides which value wins and removes the marker. Mark each mode (modes.light, modes.dark) separately.

# Fetch and atomically write tokens/base.json
FIGMA_VARIABLES_TOKEN=... pnpm --filter @cdx-ui/styles tokens:fetch

# Validate the complete result without writing
FIGMA_VARIABLES_TOKEN=... pnpm --filter @cdx-ui/styles tokens:fetch -- --dry-run

# Inspect one configured role without writing
FIGMA_VARIABLES_TOKEN=... pnpm --filter @cdx-ui/styles tokens:fetch -- --dry-run --role semantics

# Generate CSS and runtime artifacts
pnpm --filter @cdx-ui/styles tokens:build

# Verify generated artifacts are current and deterministic
pnpm --filter @cdx-ui/styles tokens:check

Supported inspection roles are primitives, fiPrimitives, semantics, and platform. Full fetches fail when a configured collection or required mode is missing.

Generated outputs:

• css/theme.css
• css/utilities.css
• css/web.css
• css/vanilla.css
• css/mui.css
• css/cds.css
• runtime/token-to-css-var.json
• runtime/override-artifacts.json

Do not edit generated outputs by hand. In tokens/base.json, hand-edit only code-owned tokens; the next fetch overwrites edits to Figma-owned tokens.

Development

From the workspace root:

pnpm --filter @cdx-ui/styles test
pnpm --filter @cdx-ui/styles lint
pnpm --filter @cdx-ui/styles build