@cdx-ui/styles 0.0.1-beta.8 → 0.0.1-beta.81

package/README.md

@@ -1,6 +1,6 @@
 # @cdx-ui/styles
 
-Design tokens and theme infrastructure for the Candescent Design System. Tokens flow from Figma Variables through a Style Dictionary pipeline into CSS custom properties, Tailwind v4 theme variables, and runtime theming artifacts — supporting three presets (Poise, Prestige, Pulse), light/dark modes, cross-platform fonts, and FI white-label overrides.
+Design tokens and theme infrastructure for the Forge Design System. Tokens flow from Figma Variables through a Style Dictionary pipeline into CSS custom properties, Tailwind v4 theme variables, and runtime theming artifacts — supporting three presets (Poise, Prestige, Pulse), light/dark modes, cross-platform fonts, and FI white-label overrides.
 
 ## Installation
 
@@ -22,7 +22,7 @@ Import `theme.css` and `utilities.css` in your global stylesheet, after Tailwind
 @import '@cdx-ui/styles/utilities.css';
 ```
 
-`theme.css` declares all token variables — primitives in `@theme static`, mode-dependent semantics in `@variant light/dark`, and platform fonts in `@variant ios/android/web`. `utilities.css` provides composite typography utilities (`heading-xl` through `body-xs`).
+`theme.css` declares all token variables — primitives in `@theme static`, mode-dependent semantics in `@variant light/dark`, and platform fonts in `@variant ios/android/web`. `utilities.css` provides composite typography utilities (`heading-xl` through `body-xs`, plus `label-sm` and `label-xs`).
 
 Components then use standard Tailwind utilities backed by theme variables:
 
@@ -51,9 +51,9 @@ import prestige from '@cdx-ui/styles/presets/prestige.json';
 import pulse from '@cdx-ui/styles/presets/pulse.json';
 ```
 
-### TypeScript types
+### TypeScript exports
 
-The package exports DTCG-compatible type definitions for theme objects, overrides, and related structures:
+The package exports DTCG-compatible type definitions, runtime constants, palette generation utilities, theming functions, and the `useForgeFonts` hook:
 
 ```typescript
 import type {
@@ -63,13 +63,97 @@ import type {
   ThemeOverrideMetadata,
   TokenGroup,
   TokenValue,
+  Preset,
   Mode,
   Platform,
+  CssVariableMaps,
+  RuntimeMap,
+  PaletteCategory,
+  PaletteScale,
+  PaletteStep,
+  PaletteTokenMap,
+  ApplyThemeOverrideOptions,
+  ApplyThemeOverrideResult,
 } from '@cdx-ui/styles';
+
+import {
+  useForgeFonts,
+  OVERRIDE_SCHEMA_VERSION,
+  SUPPORTED_OVERRIDE_SCHEMA_VERSIONS,
+  INPUT_TOKEN_MAP,
+  presetFonts,
+  DEFAULT_PRESET,
+  generateColorScale,
+  generatePalettesFromInputs,
+  deriveBaseColorKey,
+  applyThemeOverride,
+  isSchemaVersionSupported,
+  presetPatchToUniwindMaps,
+  themeOverrideToUniwindMaps,
+} from '@cdx-ui/styles';
+```
+
+**Types:**
+
+- `ThemeObject` — Complete Forge UI theme object (DTCG-compatible), including `modes`, `platform`, and `$extensions`.
+- `ThemeOverride` — Hybrid FI override structure with `inputs` (brand values for palette generation) and optional per-mode `overrides`.
+- `ThemeMetadata` / `ThemeOverrideMetadata` — Metadata stored under `$extensions.com.forge.ui.theme` and `$extensions.com.forge.ui.themeOverride`.
+- `Preset` — Union type: `'poise' | 'prestige' | 'pulse'`.
+- `TokenValue` / `TokenGroup` — DTCG leaf node and recursive group types.
+- `Mode` / `Platform` — `'light' | 'dark'` and `'web' | 'ios' | 'android'`.
+- `CssVariableMaps` — Per-mode CSS variable maps ready for `Uniwind.updateCSSVariables`.
+- `RuntimeMap` — Token dot-paths → CSS custom property names.
+- `PaletteCategory` / `PaletteScale` / `PaletteStep` / `PaletteTokenMap` — Palette generation types.
+- `ApplyThemeOverrideOptions` / `ApplyThemeOverrideResult` — Options and result types for `applyThemeOverride`.
+
+**Constants:**
+
+- `OVERRIDE_SCHEMA_VERSION` — Current override contract version (`'1.0.0'`). Consuming apps gate FI override compatibility on this value.
+- `SUPPORTED_OVERRIDE_SCHEMA_VERSIONS` — Array of schema versions accepted by this package version (includes current and optionally one prior version during transition windows).
+- `INPUT_TOKEN_MAP` — Maps known input keys (`brandPrimary`, `accentPrimary`, `basePrimary`, `displayFont`) to the token path pattern each affects. Used by override application to route inputs to the correct palette namespace.
+- `presetFonts` — Allowed display font families per preset, used by the Theme Editor for font selection and by consuming apps for validation.
+- `DEFAULT_PRESET` — The default preset (`'poise'`).
+
+**Palette generation:**
+
+- `generateColorScale(hex, category)` — Generates an 11-step Leonardo contrast scale (50–950) plus an `input` step from a single hex color. Categories: `'brand' | 'accent' | 'base'`. Returns a `PaletteTokenMap` keyed by token dot-paths (e.g. `color.brand.50` through `color.brand.input`).
+- `generatePalettesFromInputs(inputs)` — Iterates `brandPrimary`, `accentPrimary`, `basePrimary` from an override's `inputs` object; calls `generateColorScale` for each present value. Returns a merged `PaletteTokenMap`.
+- `deriveBaseColorKey(brandHex)` — Derives a neutral base color key from a brand hex (brand hue/lightness at 5% saturation). Used by the Theme Editor to automatically compute `basePrimary` from `brandPrimary`.
+
+**Theming utilities:**
+
+- `applyThemeOverride(override, options?)` — High-level orchestrator: validates schema version → applies preset patch (if non-default base) → generates palettes from inputs → merges FI overrides → calls `Uniwind.updateCSSVariables` per mode. Returns a discriminated union: `{ applied: true, light, dark }` or `{ applied: false, reason }`. Options: `runtimeMap`, `runtimePlatform`. Bundles the default runtime map internally. Requires `uniwind` as a peer dependency.
+- `isSchemaVersionSupported(override)` — Schema version gate; returns `true` if the override's `schemaVersion` is in `SUPPORTED_OVERRIDE_SCHEMA_VERSIONS`.
+- `presetPatchToUniwindMaps(patch, runtimeMap, runtimePlatform)` — Walks a nested DTCG preset patch; buckets leaves by mode/platform into per-mode CSS variable maps.
+- `themeOverrideToUniwindMaps(override, runtimeMap)` — Processes a hybrid FI override: palette generation from `inputs`, font mapping, per-mode `overrides` merge, and token-reference alias resolution.
+
+A tree-shakeable subpath is also available:
+
+```typescript
+import {
+  applyThemeOverride,
+  presetPatchToUniwindMaps,
+  themeOverrideToUniwindMaps,
+} from '@cdx-ui/styles/theming';
 ```
 
-- `ThemeMetadata` — metadata stored under `$extensions.com.candescent.theme` (name, preset, schema version).
-- `ThemeOverrideMetadata` — metadata for FI overrides under `$extensions.com.candescent.themeOverride` (base preset, FI id/name, schema version).
+**Hooks:**
+
+- `useForgeFonts` — Loads all preset display fonts (nine families, three per preset) plus platform web fonts (Inter, IBM Plex Mono) via `expo-font`. Returns `{ loaded: boolean; error: Error | null }`. Call in your root layout and gate rendering on the returned `loaded` boolean. See [Getting Started](../../docs/getting-started.md) for usage.
+- `useCdxFonts` — **Deprecated** alias for `useForgeFonts`. Retained for backward compatibility during the CDX → Forge rename transition. See [Getting Started](../../docs/getting-started.md) for the migration path.
+
+### Runtime artifacts
+
+The build produces runtime JSON artifacts importable from the package:
+
+```typescript
+import runtimeMap from '@cdx-ui/styles/runtime/token-to-css-var.json';
+import prestigePatch from '@cdx-ui/styles/runtime/prestige-vs-default.json';
+import pulsePatch from '@cdx-ui/styles/runtime/pulse-vs-default.json';
+```
+
+- **`runtime/token-to-css-var.json`** — Flat map of ~664 token dot-paths to CSS custom property names (e.g. `"color.brand.500": "--color-brand-500"`). Used internally by `applyThemeOverride`; importable for custom apply logic.
+- **`runtime/prestige-vs-default.json`** / **`runtime/pulse-vs-default.json`** — Sparse preset patches (diff from build default to target preset). Used internally by `applyThemeOverride` when `basePreset` differs from the build default.
 
 ## Token pipeline
 
@@ -90,8 +174,11 @@ tokens/presets/
   poise.json        # Default build preset
   prestige.json
   pulse.json
+  .manifest.json    # SHA-256 checksums (written by fetch)
 ```
 
+`.manifest.json` records the SHA-256 hash of each preset JSON after fetch. It is used by CI and downstream tooling to detect whether preset files changed between fetches — if the checksums match, the build step can be skipped.
+
 Each file is assembled from four Figma collections: **Primitives** (shared), **FI Primitives** (Candescent mode — brand/accent/base colors), **Semantics ({Preset})** (Light + Dark modes), and **Platform** (Web/iOS/Android fonts). Alias references are preserved as DTCG `"{path.to.token}"` syntax.
 
 #### Figma MCP alternative
@@ -111,26 +198,25 @@ pnpm tokens:build
 | File            | Contents                                                                                            |
 | --------------- | --------------------------------------------------------------------------------------------------- |
 | `theme.css`     | `@theme static` (primitives + semantic defaults), `@variant light/dark`, `@variant ios/android/web` |
-| `utilities.css` | `@utility` blocks for composite typography (headings, body, labels)                                 |
+| `utilities.css` | `@utility` blocks for composite typography (headings, body-xl through body-xs, label-sm, label-xs)  |
 | `vanilla.css`   | Non-Tailwind fallback — `:root` variables + `@media (prefers-color-scheme: dark)` + classes         |
 
-**Generated artifacts** (from the same build pass):
+**Runtime artifacts** (generated by `tokens:build`):
 
-| Artifact            | Ships to          | Purpose                                                            |
-| ------------------- | ----------------- | ------------------------------------------------------------------ |
-| Runtime map         | Package (JSON)    | Theme object path → CSS custom property name for sparse flattening |
-| Preset patches      | Package (JSON)    | Sparse diff from build default → each non-default preset           |
-| Validation manifest | API deploy bundle | Allow-listed paths and types for server-side override validation   |
+| Artifact           | File                               | Purpose                                                            |
+| ------------------ | ---------------------------------- | ------------------------------------------------------------------ |
+| **Runtime map**    | `runtime/token-to-css-var.json`    | Theme object path → CSS custom property name for sparse flattening |
+| **Preset patches** | `runtime/{preset}-vs-default.json` | Sparse diff from build default → each non-default preset           |
 
 ### Validating font tokens
 
-Font registration names in `useCdxFonts` must exactly match the `--font-*` values emitted into `theme.css` — a mismatch causes silent fallback to platform default fonts with no error. The validation script catches this drift as a build/CI failure:
+Font registration names in `useForgeFonts` must exactly match the `--font-*` values emitted into `theme.css` — a mismatch causes silent fallback to platform default fonts with no error. The validation script catches this drift as a build/CI failure:
 
 ```bash
 pnpm fonts:validate
 ```
 
-It parses every `--font-*` declaration from `css/theme.css` (across `@theme static`, `@variant light/dark`, and `@variant ios/android/web`), reads the font map keys from `src/useCdxFonts.ts` source, and verifies a matching key exists for every non-system value. System fonts (`SF Pro`, `SF Mono`, `Roboto`, `Roboto Mono`) are read from `figma.config.json` and excluded — they are platform built-ins resolved natively by React Native. `var()` aliases are skipped because they resolve to other variables that are themselves validated.
+It parses every `--font-*` declaration from `css/theme.css` (across `@theme static`, `@variant light/dark`, and `@variant ios/android/web`), reads the font map keys from `src/useForgeFonts.ts` source, and verifies a matching key exists for every non-system value. System fonts (`SF Pro`, `SF Mono`, `Roboto`, `Roboto Mono`) are read from `figma.config.json` and excluded — they are platform built-ins resolved natively by React Native. `var()` aliases are skipped because they resolve to other variables that are themselves validated.
 
 On success the script prints `Font validation: N CSS values checked, N matched, 0 mismatches.` and exits 0. On failure it lists each mismatch with its variable name, value, and CSS section, then exits non-zero. The script is wired into `.github/workflows/ci.yml` as a pre-build step so font-token drift fast-fails before the heavier build/lint/test stages.
 
@@ -146,7 +232,7 @@ Light/dark mode switching is handled by Uniwind `@variant light/dark` blocks in
 
 ### FI overrides
 
-Financial institution white-labelling uses sparse JSON overrides — only the token paths that differ from the base preset. Overrides are validated server-side against a generated validation manifest and applied at runtime via the runtime map + `Uniwind.updateCSSVariables`. See [Theme Definition](../../docs/internal/token-architecture/02-theme-definition.md) for the full override flow.
+Financial institution white-labelling uses the hybrid override format — brand inputs (a single hex color expanded into a full palette at runtime) plus optional per-mode semantic token overrides. The Theme API is a pass-through store; validation is performed by the Theme Editor before save. Consuming apps apply overrides at runtime via `applyThemeOverride` (which handles palette generation, runtime map lookup, and `Uniwind.updateCSSVariables` calls internally). See [Override Structure](../../docs/internal/token-architecture/16-override-structure.md) for the payload format and responsibility contract, and [Theme Definition](../../docs/internal/token-architecture/02-theme-definition.md) for the full theme object schema.
 
 ## Package structure
 
@@ -156,15 +242,25 @@ styles/
 │   ├── theme.css              # Auto-generated — all token variable declarations
 │   ├── utilities.css          # Auto-generated — composite typography @utility blocks
 │   └── vanilla.css            # Auto-generated — non-Tailwind fallback
+├── runtime/
+│   ├── token-to-css-var.json       # Build-generated — token path → CSS variable name map
+│   ├── prestige-vs-default.json    # Build-generated — sparse preset patch (Poise → Prestige)
+│   └── pulse-vs-default.json       # Build-generated — sparse preset patch (Poise → Pulse)
 ├── scripts/
 │   ├── figma-fetch-variables.mjs   # Figma Variables REST API fetch
 │   ├── build-tokens.mjs            # Style Dictionary build + artifact generation
-│   └── validate-font-tokens.mjs    # CI check: --font-* values match useCdxFonts keys
+│   └── validate-font-tokens.mjs    # CI check: --font-* values match useForgeFonts keys
 ├── src/
-│   ├── index.ts               # TypeScript type exports (ThemeObject, ThemeOverride, etc.)
-│   └── useCdxFonts.ts         # Font loader hook (expo-font) — loads all preset display fonts
+│   ├── index.ts               # Public barrel: types, constants, palette, theming, hooks
+│   ├── palette.ts             # Color scale generation (Leonardo contrast algorithm)
+│   ├── theming.ts             # Sparse flatten helpers (presetPatchToUniwindMaps, themeOverrideToUniwindMaps)
+│   ├── applyThemeOverride.ts  # High-level orchestrator (schema gate → patch → palette → apply)
+│   ├── types.ts               # DTCG types, override contract, constants
+│   ├── useForgeFonts.ts       # Font loader hook (expo-font) — loads all preset display fonts
+│   └── useCdxFonts.ts         # Deprecated alias for useForgeFonts
 ├── tokens/
 │   └── presets/
+│       ├── .manifest.json     # SHA-256 checksums (written by fetch)
 │       ├── poise.json         # Poise theme object (build default)
 │       ├── prestige.json      # Prestige theme object
 │       └── pulse.json         # Pulse theme object
@@ -175,7 +271,7 @@ styles/
 └── tsconfig.build.json
 ```
 
-`css/` files are auto-generated — do not edit directly.
+`css/` and `runtime/` files are auto-generated — do not edit directly.
 
 ## Building