@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.

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

figma.config.json maps stable collection roles to Figma collection names. The fetch writes one complete DTCG file at the configured outputFile.

# 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:

• tokens/base.json
• 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.

Development

From the workspace root:

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