# @cdx-ui/styles

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

## Install

```sh
pnpm add @cdx-ui/styles
```

## CSS entry points

Import the files needed by the target application:

```css
@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:

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

## Runtime overrides

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

```ts
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:

```ts
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:

```ts
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`.

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

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