@apollion-dsi/tokens 4.0.0 → 4.2.0

package/src/theme-factory.ts

@@ -31,7 +31,14 @@ import { mountGreyscaleColors, mountNeutralColors, mountSingleColor } from './bu
 import { createSpacing } from './builders/spacing';
 import type { Variant } from './config-schema';
 
-type ColorsThemeInterface = ReturnType<typeof composeColors>;
+export type ColorsThemeInterface = ReturnType<typeof composeColors>;
+
+/** A variant's resolved themes: the consumer Foundation layer + the structural
+ * palette (colour primitives / SSOT). */
+export interface VariantThemes {
+  foundation: FoundationLayer;
+  colors: ColorsThemeInterface;
+}
 
 function composeColors(input: Variant['colors']) {
   return {
@@ -56,25 +63,33 @@ function composeColors(input: Variant['colors']) {
 }
 
 /**
- * Build the Foundation layer for one variant. Pure function, deterministic.
+ * Build a variant's resolved themes — the Foundation layer plus the structural
+ * palette (colour SSOT consumed by the IR for reference emission). Pure +
+ * deterministic.
  */
-export function buildFoundationForVariant(
-  variant: Variant,
-  spacingInput: SpacingInput = defaultInputSpacing,
-): FoundationLayer {
+export function buildVariantThemes(variant: Variant, spacingInput: SpacingInput = defaultInputSpacing): VariantThemes {
   const themeColors = composeColors(variant.colors) as unknown as ColorsThemeInterface;
   const themeSpacing = createSpacing(spacingInput, variant.dimension);
   const semantic = createSemantic({ colors: themeColors as never, spacing: themeSpacing as never });
 
-  const baseFoundation = createFoundation(semantic);
+  let foundation = createFoundation(semantic);
 
   if (variant.surface === 'negative') {
     // invertForSurface acts on the full Theme — assemble a minimal shim.
     // S6 will refactor to accept (semantic, surface) directly.
     const fullTheme = { semantic, colors: themeColors as never } as never;
-    const inverted = invertForSurface(fullTheme, 'negative');
-    return createFoundation(inverted.semantic);
+    foundation = createFoundation(invertForSurface(fullTheme, 'negative').semantic);
   }
 
-  return baseFoundation;
+  return { foundation, colors: themeColors };
+}
+
+/**
+ * Build the Foundation layer for one variant. Pure function, deterministic.
+ */
+export function buildFoundationForVariant(
+  variant: Variant,
+  spacingInput: SpacingInput = defaultInputSpacing,
+): FoundationLayer {
+  return buildVariantThemes(variant, spacingInput).foundation;
 }

package/src/token-meta.ts

@@ -0,0 +1,86 @@
+/**
+ * Token metadata registry — the SSOT for DTCG `$description` / `$deprecated`
+ * annotations (Format Module 2025.10 §"Description" + §"Deprecation").
+ *
+ * **Why a side-table (not inline on each builder):** descriptions and
+ * deprecations are editorial metadata, not derived from the foundation math.
+ * Keeping them in one keyed map lets the IR stay a pure projection of the
+ * resolved theme while `decorateMeta` (see `ir.ts`) stitches the prose on in a
+ * single post-pass — smaller diff than threading copy through every builder.
+ *
+ * **Keying:** each key is a token's dotted IR path **after** kebab-case
+ * normalization (`kebabPath`), i.e. exactly the path the JSON renderer emits in
+ * a `{...}` alias. So `bg.primary`, `border.radius.md`, `space.medium`. A dev
+ * assertion (`assertTokenMetaResolves`) fails the build/tests on any stale key
+ * that no longer maps to an IR node, so this map can never silently rot.
+ *
+ * **Deprecation values:** `true` is a bare DTCG deprecation flag; a string is a
+ * human-readable reason (DTCG allows either). Prefer the string form — it
+ * surfaces the migration path to consumers reading the JSON.
+ *
+ * @see ir.ts (`decorateMeta` post-pass + `assertTokenMetaResolves`)
+ * @see renderers/json.ts (`projectToken` emits `$description` / `$deprecated`)
+ * @see https://www.designtokens.org/TR/drafts/format/ §Description, §Deprecation
+ */
+
+export interface TokenMetaEntry {
+  /** DTCG `$description` — human-readable intent of the token. */
+  readonly description?: string;
+  /** DTCG `$deprecated` — `true` (bare flag) or a string migration reason. */
+  readonly deprecated?: boolean | string;
+}
+
+/**
+ * Editorial metadata keyed by kebab-normalized dotted IR path.
+ *
+ * Starter set covers the well-known foundation roles + a couple of scale
+ * anchors; extend as tokens gain documented intent. Every key MUST resolve to
+ * a live IR node (enforced by `assertTokenMetaResolves`).
+ */
+export const TOKEN_META: Readonly<Record<string, TokenMetaEntry>> = {
+  // ── Foundation backgrounds (semantic surface roles) ──────────────────────
+  'bg.primary': { description: 'Primary action surface — the brand’s dominant call-to-action background.' },
+  'bg.secondary': { description: 'Secondary action surface — supporting actions paired with the primary.' },
+  'bg.danger': { description: 'Destructive / error surface — irreversible or failing actions.' },
+  'bg.success': { description: 'Positive confirmation surface — completed or healthy states.' },
+  'bg.info': {
+    description: 'Informational surface — neutral, non-blocking notices.',
+    deprecated: 'Use bg.information once the foundation role is renamed (tracked for S6).',
+  },
+
+  // ── Foundation text-on roles ─────────────────────────────────────────────
+  'text.on-primary': { description: 'Text/icon colour with guaranteed contrast over bg.primary.' },
+  'text.on-danger': { description: 'Text/icon colour with guaranteed contrast over bg.danger.' },
+
+  // ── Spacing primitives (density-aware dimension scale) ────────────────────
+  'space.medium': { description: 'Base spacing step (1rem at normal density) — the layout rhythm unit.' },
+  'space.large': { description: 'Comfortable spacing step — section padding and card gutters.' },
+
+  // ── Spacing foundation aliases ───────────────────────────────────────────
+  'spacing.md': { description: 'Medium foundation spacing alias — references the space.medium primitive.' },
+  'spacing.lg': { description: 'Large foundation spacing alias — references the space.large primitive.' },
+
+  // ── Border scale ─────────────────────────────────────────────────────────
+  'border.radius.md': { description: 'Default card corner radius.' },
+  'border.width.thin': { description: 'Hairline border — dividers and default input outlines.' },
+  'border.width.regular': { description: 'Standard emphasis border — focused/active controls.' },
+};
+
+/**
+ * Dev assertion: every {@link TOKEN_META} key must map to a live IR node.
+ *
+ * `resolvedPaths` is the set of kebab-normalized dotted paths the IR currently
+ * emits (built by `decorateMeta`'s walk). Throws listing every stale key so a
+ * rename in the foundation can never leave dangling documentation behind.
+ *
+ * @throws if any `TOKEN_META` key is absent from `resolvedPaths`.
+ */
+export function assertTokenMetaResolves(resolvedPaths: ReadonlySet<string>): void {
+  const stale = Object.keys(TOKEN_META).filter((key) => !resolvedPaths.has(key));
+  if (stale.length > 0) {
+    throw new Error(
+      `token-meta: ${stale.length} stale TOKEN_META key(s) resolve to no IR node: ${stale.join(', ')}. ` +
+        `Update src/token-meta.ts to match the current IR paths.`,
+    );
+  }
+}