@apollion-dsi/tokens 4.0.0 → 4.2.0

package/src/ir.ts

@@ -0,0 +1,715 @@
+/**
+ * Token Intermediate Representation (IR) — the typed, tool-agnostic model that
+ * every renderer (JSON/CSS/TS) projects from.
+ *
+ * **Why (improve-architecture B3):** the IR centralizes token typing so a
+ * renderer is a pure projection — a new token type or output format is added in
+ * one place.
+ *
+ * **Layers:**
+ * - `primitives` — the reference SSOT, keyed by namespace: `color.*` (palette,
+ *   R4), `space.*` (density-aware spacing, S5), `border-width.*` (S5).
+ * - `groups` — foundation aliases (`bg`/`text`/`spacing`) + composite/scale
+ *   layers (`border`/`font`/`shadow`, S4). Foundation colours reference colour
+ *   primitives (`{color.x.y}`); `spacing` + `border.width` reference dimension
+ *   primitives (`{space.medium}` / `{border-width.thin}`) — built per-variant
+ *   with the same multiplier so refs match under every dimension; diverging
+ *   values fall back to inline.
+ *
+ * **DTCG-expressibility (S4):** values DTCG cannot model (font `letterSpacing`
+ * in `em`, `textTransform`, `fontStyle`, border `circular: 100%`) are carried in
+ * the document `$extensions` under `com.apollion.*` rather than dropped.
+ *
+ * **Byte-fidelity:** each value keeps its original resolved CSS string (`raw`)
+ * so CSS/TS projections (which resolve references) stay faithful, while JSON
+ * emits the DTCG-structured + referenced form.
+ *
+ * @see renderers/json.ts · renderers/css.ts · renderers/ts.ts
+ * @see ADR-006 §3.10 · tech-radar R1/R2 (structured) + R4 (references) + R3/B3
+ */
+
+import { defaultInputBorder } from '@apollion-dsi/core/themes/border';
+import { createDeth, levelValues } from '@apollion-dsi/core/themes/depth';
+import type { Dimension } from '@apollion-dsi/core/themes/dimension';
+import { defaultInputFont } from '@apollion-dsi/core/themes/font';
+import type { FoundationLayer } from '@apollion-dsi/core/themes/foundation';
+import type { SpacingAlias } from '@apollion-dsi/core/themes/spacing';
+import { defaultInputSpacing } from '@apollion-dsi/core/themes/spacing';
+import { converter, formatHex, parse } from 'culori';
+
+import { createSpacing } from './builders/spacing';
+import type { Variant } from './config-schema';
+import type { ColorsThemeInterface } from './theme-factory';
+import { assertTokenMetaResolves, TOKEN_META } from './token-meta';
+
+const toOklch = converter('oklch');
+
+export type IRTokenType = 'color' | 'dimension' | 'fontFamily' | 'fontWeight' | 'number' | 'strokeStyle' | 'shadow';
+
+export interface IRColorValue {
+  readonly kind: 'color';
+  /** Original resolved CSS color string — preserves CSS/TS byte-fidelity. */
+  readonly raw: string;
+  /** OKLch components `[L, C, H]` — L ∈ [0,1], C ≥ 0, H in degrees. */
+  readonly components: readonly [number, number, number];
+  readonly alpha?: number;
+  /** sRGB hex fallback (normalized). */
+  readonly hex: string;
+}
+
+export interface IRDimensionValue {
+  readonly kind: 'dimension';
+  readonly raw: string;
+  readonly value: number;
+  readonly unit: 'px' | 'rem';
+}
+
+export interface IRFontFamilyValue {
+  readonly kind: 'fontFamily';
+  readonly raw: string;
+  readonly family: string;
+}
+
+export interface IRFontWeightValue {
+  readonly kind: 'fontWeight';
+  readonly raw: string;
+  readonly weight: number;
+}
+
+export interface IRNumberValue {
+  readonly kind: 'number';
+  readonly raw: string;
+  readonly number: number;
+}
+
+export interface IRStrokeStyleValue {
+  readonly kind: 'strokeStyle';
+  readonly raw: string;
+  readonly style: string;
+}
+
+export interface IRShadowLayer {
+  readonly color: IRColorValue;
+  readonly offsetX: IRDimensionValue;
+  readonly offsetY: IRDimensionValue;
+  readonly blur: IRDimensionValue;
+  readonly spread: IRDimensionValue;
+  readonly inset: boolean;
+}
+
+export interface IRShadowValue {
+  readonly kind: 'shadow';
+  readonly raw: string;
+  readonly shadow: IRShadowLayer;
+}
+
+/** A reference to another token (DTCG alias). `resolved` carries the target's
+ * value so CSS/TS can project a concrete value without graph traversal. */
+export interface IRReference {
+  readonly kind: 'ref';
+  readonly path: string;
+  readonly resolved: IRColorValue | IRDimensionValue;
+}
+
+export type IRValue =
+  | IRColorValue
+  | IRDimensionValue
+  | IRFontFamilyValue
+  | IRFontWeightValue
+  | IRNumberValue
+  | IRStrokeStyleValue
+  | IRShadowValue
+  | IRReference;
+
+export interface IRToken {
+  readonly type: IRTokenType;
+  readonly value: IRValue;
+  readonly description?: string;
+  readonly deprecated?: boolean | string;
+}
+
+export interface IRGroup {
+  readonly [key: string]: IRToken | IRGroup;
+}
+
+export interface IRVariantMeta {
+  readonly brand: string;
+  readonly mode: string;
+  readonly surface: string;
+  readonly dimension: string;
+}
+
+export interface IRDocument {
+  readonly description: string;
+  readonly meta: IRVariantMeta;
+  /**
+   * Reference SSOT layers, keyed by primitive namespace. Each top-level key
+   * projects to a sibling JSON group (`color`, `space`, `border-width`):
+   * - `color` — structural colour palette (`color.*`), R4.
+   * - `space` — density-aware spacing scale (`space.*`), S5 dimension refs.
+   * - `borderWidth` — border-width scale (`border-width.*`), S5 dimension refs.
+   *
+   * CSS/TS surfaces omit this whole layer (they emit fully-resolved values).
+   */
+  readonly primitives: IRGroup;
+  /** Foundation + scale + composite layers (`bg`/`text`/`spacing`/`border`/`font`/`shadow`). */
+  readonly groups: IRGroup;
+  readonly extensions: Readonly<Record<string, unknown>>;
+}
+
+/** Narrow an IR node to a token (vs a nested group). */
+export function isToken(node: IRToken | IRGroup): node is IRToken {
+  return typeof (node as IRToken).type === 'string' && 'value' in node;
+}
+
+/** `camelCase` → `kebab-case` token-name normalization (JSON/CSS). */
+export function kebab(key: string): string {
+  return key.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+}
+
+/** Kebab-case each segment of a dotted IR path (for DTCG `{...}` aliases). */
+export function kebabPath(path: string): string {
+  return path.split('.').map(kebab).join('.');
+}
+
+/** Concrete value of an IR value — resolving references to their target. */
+export function rawValue(value: IRValue): string {
+  return value.kind === 'ref' ? value.resolved.raw : value.raw;
+}
+
+function round(value: number, dp: number): number {
+  return Number(value.toFixed(dp)) || 0;
+}
+
+/** Build an OKLch IR color value from a resolved CSS color string. */
+export function toColorValue(raw: string): IRColorValue {
+  const oklch = toOklch(parse(raw));
+  if (!oklch) return { kind: 'color', raw, components: [0, 0, 0], hex: '#000000' };
+
+  const components: readonly [number, number, number] = [round(oklch.l, 4), round(oklch.c, 4), round(oklch.h ?? 0, 2)];
+  const hex = formatHex(oklch) ?? '#000000';
+
+  return oklch.alpha !== undefined && oklch.alpha !== 1
+    ? { kind: 'color', raw, components, alpha: round(oklch.alpha, 4), hex }
+    : { kind: 'color', raw, components, hex };
+}
+
+const DIMENSION_RE = /^(-?(?:\d+\.?\d*|\.\d+))(px|rem)$/;
+
+/** Build an IR dimension value from a resolved CSS length string. */
+export function toDimensionValue(raw: string): IRDimensionValue {
+  const match = DIMENSION_RE.exec(raw.trim());
+  if (match) return { kind: 'dimension', raw, value: Number(match[1]), unit: match[2] as 'px' | 'rem' };
+
+  const value = Number.parseFloat(raw);
+  return { kind: 'dimension', raw, value: Number.isFinite(value) ? value : 0, unit: 'rem' };
+}
+
+function colorToken(raw: string): IRToken {
+  return { type: 'color', value: toColorValue(raw) };
+}
+
+function recordColorGroup(record: Record<string, string>): IRGroup {
+  const out: Record<string, IRToken> = {};
+  for (const [key, value] of Object.entries(record)) out[key] = colorToken(value);
+  return out;
+}
+
+const NAMED_PALETTES = [
+  'main',
+  'opposite',
+  'complementary',
+  'primary',
+  'secondary',
+  'tertiary',
+  'success',
+  'danger',
+  'warning',
+  'information',
+] as const;
+
+/** Structural palette → colour primitives (`color.*`). The colour SSOT. */
+function buildColorPrimitives(colors: ColorsThemeInterface): IRGroup {
+  const out: Record<string, IRToken | IRGroup> = {};
+  for (const name of NAMED_PALETTES) {
+    const palette = colors[name];
+    out[name] = {
+      base: colorToken(palette.base),
+      dark: colorToken(palette.dark),
+      action: colorToken(palette.action),
+      active: colorToken(palette.active),
+      light: colorToken(palette.light),
+    };
+  }
+  out.grayscale = recordColorGroup(colors.grayscale);
+  out.neutral = recordColorGroup(colors.neutral);
+  out.baseDark = colorToken(colors.baseDark ?? '#000000');
+  out.baseLight = colorToken(colors.baseLight ?? '#ffffff');
+  out.deepDark = colorToken(colors.deepDark ?? '#000000');
+  out.deepLight = colorToken(colors.deepLight ?? '#ffffff');
+  return out;
+}
+
+/**
+ * Density-aware spacing primitives (`space.*`) — the dimension-reference SSOT.
+ *
+ * CRITICAL: built with the SAME `(input, dimension)` the foundation used
+ * (`createSpacing`), so a foundation spacing value (e.g. `spacing.md = 1rem`
+ * at normal density) is byte-equal to its primitive (`space.medium`) and the
+ * reference matches under compact/normal/spacious alike. Build with a different
+ * multiplier and every `spacing.*` would silently fall back to inline.
+ */
+function buildSpacePrimitives(dimension: Dimension): IRGroup {
+  const spacing = createSpacing(defaultInputSpacing, dimension);
+  const out: Record<string, IRToken> = {};
+  for (const alias of Object.keys(defaultInputSpacing.alias) as SpacingAlias[]) {
+    out[alias] = { type: 'dimension', value: toDimensionValue(spacing(alias)) };
+  }
+  return out;
+}
+
+/** Border-width primitives (`border-width.*`) — the border-width reference SSOT. */
+function buildBorderWidthPrimitives(): IRGroup {
+  const out: Record<string, IRToken> = {};
+  for (const [key, value] of Object.entries(defaultInputBorder.borderWidth)) {
+    out[key] = { type: 'dimension', value: toDimensionValue(value) };
+  }
+  return out;
+}
+
+/** All reference SSOT primitives, keyed by namespace (`color`/`space`/`borderWidth`). */
+function buildPrimitives(colors: ColorsThemeInterface, dimension: Dimension): IRGroup {
+  return {
+    color: buildColorPrimitives(colors),
+    space: buildSpacePrimitives(dimension),
+    borderWidth: buildBorderWidthPrimitives(),
+  };
+}
+
+/** Foundation role → primitive IR path (static mapping, verified vs core). */
+const BG_REF: Readonly<Record<string, string>> = {
+  primary: 'color.primary.base',
+  secondary: 'color.secondary.base',
+  tertiary: 'color.tertiary.base',
+  success: 'color.success.base',
+  danger: 'color.danger.base',
+  warning: 'color.warning.base',
+  info: 'color.information.base',
+};
+
+const TEXT_REF: Readonly<Record<string, string>> = {
+  onPrimary: 'color.baseLight',
+  onSecondary: 'color.baseLight',
+  onTertiary: 'color.baseDark',
+  onSuccess: 'color.baseLight',
+  onDanger: 'color.baseLight',
+  onWarning: 'color.baseDark',
+  onInfo: 'color.baseLight',
+};
+
+/** Navigate the structural palette by IR path (`color.x.y`). */
+function lookupPrimitive(colors: ColorsThemeInterface, path: string): string | undefined {
+  let node: unknown = colors;
+  for (const segment of path.split('.').slice(1)) {
+    if (node && typeof node === 'object' && segment in node) {
+      node = (node as Record<string, unknown>)[segment];
+    } else {
+      return undefined;
+    }
+  }
+  return typeof node === 'string' ? node : undefined;
+}
+
+/** Colour layer: reference the primitive when the resolved value matches, else inline. */
+function colorRefGroup(
+  layer: Record<string, string>,
+  colors: ColorsThemeInterface,
+  refMap: Readonly<Record<string, string>>,
+): IRGroup {
+  const out: Record<string, IRToken> = {};
+  for (const [key, value] of Object.entries(layer)) {
+    const path = refMap[key];
+    const primitive = path ? lookupPrimitive(colors, path) : undefined;
+    out[key] =
+      path && primitive === value
+        ? { type: 'color', value: { kind: 'ref', path, resolved: toColorValue(value) } }
+        : colorToken(value);
+  }
+  return out;
+}
+
+function dimensionGroup(layer: Record<string, string>): IRGroup {
+  const out: Record<string, IRToken> = {};
+  for (const [key, value] of Object.entries(layer)) {
+    out[key] = { type: 'dimension', value: toDimensionValue(value) };
+  }
+  return out;
+}
+
+/**
+ * Foundation spacing alias → `space.*` primitive path.
+ *
+ * Encodes the foundation→core key rename (Foundation.helpers.ts): the
+ * foundation exposes `xs/sm/md/lg/xl/xxl`, the core spacing scale is keyed
+ * `xs/small/medium/large/xl/xxl`. So `sm`→`small`, `md`→`medium`, `lg`→`large`;
+ * the rest are identity.
+ */
+const SPACE_REF: Readonly<Record<string, string>> = {
+  xs: 'space.xs',
+  sm: 'space.small',
+  md: 'space.medium',
+  lg: 'space.large',
+  xl: 'space.xl',
+  xxl: 'space.xxl',
+};
+
+/** Border-width key → `border-width.*` primitive path (identity — same keys). */
+const BORDER_WIDTH_REF: Readonly<Record<string, string>> = {
+  none: 'border-width.none',
+  thin: 'border-width.thin',
+  regular: 'border-width.regular',
+  great: 'border-width.great',
+  bold: 'border-width.bold',
+};
+
+/** Navigate a primitives namespace by IR path (`space.x` / `border-width.x`). */
+function lookupDimensionPrimitive(primitives: IRGroup, path: string): string | undefined {
+  // The `borderWidth` namespace is keyed `borderWidth` in the IR but addressed
+  // as `border-width` in DTCG paths — normalize the head segment.
+  const segments = path.split('.');
+  const head = segments[0] === 'border-width' ? 'borderWidth' : segments[0];
+  let node: IRToken | IRGroup | undefined = primitives[head];
+  for (const segment of segments.slice(1)) {
+    if (node && !isToken(node) && segment in node) node = node[segment];
+    else return undefined;
+  }
+  return node && isToken(node) && node.value.kind === 'dimension' ? node.value.raw : undefined;
+}
+
+/**
+ * Dimension layer (spacing / border-width): reference the primitive when the
+ * resolved value is byte-equal, else inline. Mirrors `colorRefGroup`.
+ *
+ * Best-effort by design: a foundation value that doesn't coincide with any
+ * scale primitive (custom override, or a shadow offset that happens not to land
+ * on the scale) legitimately falls back to an inline `{ value, unit }`.
+ */
+function dimensionRefGroup(
+  layer: Record<string, string>,
+  primitives: IRGroup,
+  refMap: Readonly<Record<string, string>>,
+): IRGroup {
+  const out: Record<string, IRToken> = {};
+  for (const [key, value] of Object.entries(layer)) {
+    const path = refMap[key];
+    const primitive = path ? lookupDimensionPrimitive(primitives, path) : undefined;
+    out[key] =
+      path && primitive === value
+        ? { type: 'dimension', value: { kind: 'ref', path, resolved: toDimensionValue(value) } }
+        : { type: 'dimension', value: toDimensionValue(value) };
+  }
+  return out;
+}
+
+/**
+ * Border scales: px → dimension, style → strokeStyle. Non-px radii (e.g.
+ * `100%`) go to `$extensions`. `width` references the `border-width.*`
+ * primitives (S5) so the scale has a single SSOT, like colour/spacing.
+ */
+function buildBorder(primitives: IRGroup): { group: IRGroup; extensions: Record<string, string> } {
+  const radius: Record<string, IRToken> = {};
+  const extRadius: Record<string, string> = {};
+  for (const [key, value] of Object.entries(defaultInputBorder.borderRadius)) {
+    if (DIMENSION_RE.test(value)) radius[key] = { type: 'dimension', value: toDimensionValue(value) };
+    else extRadius[key] = value;
+  }
+  const width = dimensionRefGroup(
+    defaultInputBorder.borderWidth as unknown as Record<string, string>,
+    primitives,
+    BORDER_WIDTH_REF,
+  );
+  const style: Record<string, IRToken> = {};
+  for (const [key, value] of Object.entries(defaultInputBorder.borderStyle)) {
+    style[key] = { type: 'strokeStyle', value: { kind: 'strokeStyle', raw: value, style: value } };
+  }
+  return { group: { radius, width, style }, extensions: extRadius };
+}
+
+/** Font scales: family/size/weight/lineHeight as DTCG types; non-DTCG bits
+ * (letterSpacing/textTransform/fontStyle) go to `$extensions`. */
+function buildFont(): { group: IRGroup; extensions: Record<string, unknown> } {
+  const family: Record<string, IRToken> = {};
+  for (const [key, value] of Object.entries(defaultInputFont.fontFamily)) {
+    const clean = value.replace(/;\s*$/, '').trim();
+    family[key] = { type: 'fontFamily', value: { kind: 'fontFamily', raw: clean, family: clean } };
+  }
+  const size: Record<string, IRToken> = {};
+  for (const [key, value] of Object.entries(defaultInputFont.fontSize)) {
+    size[key] = { type: 'dimension', value: { kind: 'dimension', raw: `${value}px`, value, unit: 'px' } };
+  }
+  const weight: Record<string, IRToken> = {};
+  for (const [key, value] of Object.entries(defaultInputFont.fontWeight)) {
+    weight[key] = { type: 'fontWeight', value: { kind: 'fontWeight', raw: `${value}`, weight: value } };
+  }
+  const lineHeight: Record<string, IRToken> = {};
+  for (const [key, value] of Object.entries(defaultInputFont.lineHeight)) {
+    lineHeight[key] = { type: 'number', value: { kind: 'number', raw: `${value}`, number: value } };
+  }
+  const extensions = {
+    letterSpacing: defaultInputFont.letterSpacing,
+    textTransform: defaultInputFont.textTransform,
+    fontStyle: defaultInputFont.fontStyle,
+  };
+  return { group: { family, size, weight, lineHeight }, extensions };
+}
+
+const SHADOW_COLOR_RE = /rgba?\([^)]*\)|#[0-9a-fA-F]+|[a-zA-Z]+$/;
+
+/** Parse a CSS box-shadow string into a DTCG-shaped shadow layer. */
+function parseShadow(css: string): IRShadowValue {
+  let body = css.trim();
+  const inset = body.startsWith('inset');
+  if (inset) body = body.slice('inset'.length).trim();
+
+  const colorMatch = body.match(SHADOW_COLOR_RE);
+  const colorStr = colorMatch ? colorMatch[0] : '#000000';
+  const lengthsPart = colorMatch ? body.slice(0, colorMatch.index).trim() : body;
+  const lengths = lengthsPart.split(/\s+/).filter(Boolean);
+  const dim = (i: number): IRDimensionValue => toDimensionValue(lengths[i] ?? '0px');
+
+  return {
+    kind: 'shadow',
+    raw: css,
+    shadow: { color: toColorValue(colorStr), offsetX: dim(0), offsetY: dim(1), blur: dim(2), spread: dim(3), inset },
+  };
+}
+
+/**
+ * Depth levels → DTCG shadow composites (geometry from core, colour resolved).
+ *
+ * **Dimension references (S5) — intentionally inline.** Unlike `spacing` and
+ * `border.width`, a shadow's `offsetX/offsetY/blur/spread` are NOT referenced to
+ * the `space.*` / `border-width.*` primitives. Shadow geometry is a tuned,
+ * continuous design space (e.g. a `3px` blur) that only ever coincides with a
+ * scale step by accident; emitting `{border-width.great}` for a `4px` blur would
+ * assert a semantic link that isn't there and would break the moment depth is
+ * recalibrated. They therefore stay inline `{ value, unit }` composites by
+ * design — the legitimate best-effort fallback (PRD S5).
+ */
+function buildShadow(colors: ColorsThemeInterface): IRGroup {
+  const depth = createDeth(colors as never);
+  const out: Record<string, IRToken> = {};
+  for (const level of Object.keys(levelValues)) {
+    out[level] = { type: 'shadow', value: parseShadow(depth(level as never)) };
+  }
+  return out;
+}
+
+/**
+ * Re-key a group, attaching `TOKEN_META` onto each token by its reconstructed
+ * dotted (kebab) path. Pure: returns a new group; the input is untouched.
+ *
+ * `prefix` is the dotted path of the parent group (kebab-normalized). Every
+ * visited token path is recorded in `seen` so the caller can fail on stale
+ * `TOKEN_META` keys (paths documented but no longer emitted).
+ */
+function decorateGroup(group: IRGroup, prefix: string, seen: Set<string>): IRGroup {
+  const out: Record<string, IRToken | IRGroup> = {};
+  for (const [key, node] of Object.entries(group)) {
+    const path = prefix ? `${prefix}.${kebab(key)}` : kebab(key);
+    if (isToken(node)) {
+      seen.add(path);
+      const meta = TOKEN_META[path];
+      // Only allocate a new token when there's prose to attach — keeps the
+      // common (undocumented) path identity-cheap and the diff minimal.
+      out[key] =
+        meta && (meta.description !== undefined || meta.deprecated !== undefined)
+          ? {
+              ...node,
+              ...(meta.description !== undefined ? { description: meta.description } : {}),
+              ...(meta.deprecated !== undefined ? { deprecated: meta.deprecated } : {}),
+            }
+          : node;
+    } else {
+      out[key] = decorateGroup(node, path, seen);
+    }
+  }
+  return out;
+}
+
+/**
+ * Post-pass: stitch `TOKEN_META` ($description / $deprecated) onto a finished
+ * IR document, then assert no documentation key is stale.
+ *
+ * Walks both `primitives` and `groups` at the root — the primitives namespace
+ * keys (`color`/`space`/`borderWidth`) already form the head segment, so paths
+ * reconstruct exactly the `{...}` aliases the JSON surface emits. Running this
+ * once at the tail of `buildIR` is a far smaller diff than threading a path
+ * prefix through every builder.
+ *
+ * @throws via `assertTokenMetaResolves` if any `TOKEN_META` key resolves to no
+ *   token in this document.
+ */
+function decorateMeta(doc: IRDocument): IRDocument {
+  const seen = new Set<string>();
+  const primitives = decorateGroup(doc.primitives, '', seen);
+  const groups = decorateGroup(doc.groups, '', seen);
+  assertTokenMetaResolves(seen);
+  return { ...doc, primitives, groups };
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// IR slices (R5) — composable cuts of the full document along the modifier
+// axes, so the Resolver can emit one reference-closed set per axis instead of
+// re-emitting the whole document per (brand × mode × surface × dimension) cell.
+//
+// Closure invariant: each slice contains BOTH the primitives it introduces and
+// the foundation groups that reference them, so a set is self-resolving:
+// - base    → border (+ `border-width.*` it references) + font   [axis-invariant]
+// - color   → `color.*` primitives + bg/text (refs) + shadow     [brand×mode×surface]
+// - spacing → `space.*` primitives + spacing (refs)              [dimension]
+// `decorateMeta` runs per-slice to attach prose; the build asserts the UNION of
+// all emitted paths is meta-complete (a single set is intentionally partial).
+// ───────────────────────────────────────────────────────────────────────────
+
+/** A reference-closed cut of the IR: groups (already meta-decorated) + extensions. */
+export interface IRSlice {
+  readonly groups: IRGroup;
+  readonly extensions: Readonly<Record<string, unknown>>;
+}
+
+/** Attach `TOKEN_META` to a slice's groups, recording every visited path in `seen`. */
+function decorateSlice(groups: IRGroup, seen: Set<string>): IRGroup {
+  return decorateGroup(groups, '', seen);
+}
+
+/** Collect every kebab dotted token path emitted by a group (for meta-completeness). */
+function collectPaths(group: IRGroup, prefix: string, out: Set<string>): void {
+  for (const [key, node] of Object.entries(group)) {
+    const path = prefix ? `${prefix}.${kebab(key)}` : kebab(key);
+    if (isToken(node)) out.add(path);
+    else collectPaths(node, path, out);
+  }
+}
+
+/**
+ * Assert the UNION of all emitted set paths is `TOKEN_META`-complete.
+ *
+ * A single Resolver set is intentionally partial (e.g. the base set has no
+ * `bg.*`), so the stale-key guard must run over every set the build emits
+ * together — never per-set.
+ *
+ * @throws if any `TOKEN_META` key resolves to no token across `slices`.
+ */
+export function assertSlicesMetaComplete(slices: readonly IRSlice[]): void {
+  const seen = new Set<string>();
+  for (const slice of slices) collectPaths(slice.groups, '', seen);
+  assertTokenMetaResolves(seen);
+}
+
+/**
+ * Axis-invariant base slice: border (radius/width/style) + font. `border.width`
+ * references the `border-width.*` primitives, which travel WITH this slice
+ * (`border-width` namespace) so the set is reference-closed. Identical for every
+ * brand/mode/surface/dimension.
+ */
+export function buildBaseIR(): IRSlice {
+  const borderWidth = buildBorderWidthPrimitives();
+  const primitives: IRGroup = { borderWidth };
+  const border = buildBorder(primitives);
+  const font = buildFont();
+
+  const extensions: Record<string, unknown> = { 'com.apollion.font': font.extensions };
+  if (Object.keys(border.extensions).length > 0) {
+    extensions['com.apollion.border'] = { radius: border.extensions };
+  }
+
+  const seen = new Set<string>();
+  const groups = decorateSlice({ 'border-width': borderWidth, border: border.group, font: font.group }, seen);
+  return { groups, extensions };
+}
+
+/**
+ * Colour slice for one (brand × mode × surface): the `color.*` palette SSOT plus
+ * the `bg`/`text` foundation aliases (which reference it) and `shadow`. `mode` is
+ * a no-op placeholder in S5 (dark == light until S6) but is threaded so the set
+ * topology is correct ahead of time.
+ */
+export function buildColorIR(foundation: FoundationLayer, colors: ColorsThemeInterface): IRSlice {
+  const color = buildColorPrimitives(colors);
+  const seen = new Set<string>();
+  const groups = decorateSlice(
+    {
+      color,
+      bg: colorRefGroup(foundation.bg as unknown as Record<string, string>, colors, BG_REF),
+      text: colorRefGroup(foundation.text as unknown as Record<string, string>, colors, TEXT_REF),
+      shadow: buildShadow(colors),
+    },
+    seen,
+  );
+  return { groups, extensions: {} };
+}
+
+/**
+ * Spacing slice for one dimension: the `space.*` density scale plus the
+ * `spacing` foundation aliases that reference it. Built with the dimension's
+ * multiplier so the refs match (see `buildSpacePrimitives`).
+ */
+export function buildSpacingIR(foundation: FoundationLayer, dimension: Dimension): IRSlice {
+  const space = buildSpacePrimitives(dimension);
+  const primitives: IRGroup = { space };
+  const seen = new Set<string>();
+  const groups = decorateSlice(
+    {
+      space,
+      spacing: dimensionRefGroup(foundation.spacing as unknown as Record<string, string>, primitives, SPACE_REF),
+    },
+    seen,
+  );
+  return { groups, extensions: {} };
+}
+
+/**
+ * Build the FULL IR document for one resolved variant (all axes baked in).
+ *
+ * This is the per-variant document the CSS/TS surfaces project from, the
+ * `renderers.test.ts` helper, and the composition-equivalence oracle for the
+ * Resolver sets (R5): composing `buildBaseIR + buildColorIR + buildSpacingIR`
+ * must reproduce these exact tokens. `buildFullIR` is an explicit alias.
+ */
+export function buildIR(foundation: FoundationLayer, colors: ColorsThemeInterface, variant: Variant): IRDocument {
+  const meta: IRVariantMeta = {
+    brand: variant.brand,
+    mode: variant.mode,
+    surface: variant.surface,
+    dimension: variant.dimension,
+  };
+  const primitives = buildPrimitives(colors, variant.dimension);
+  const border = buildBorder(primitives);
+  const font = buildFont();
+
+  const extensions: Record<string, unknown> = { 'com.apollion.variant': meta, 'com.apollion.font': font.extensions };
+  if (Object.keys(border.extensions).length > 0) {
+    extensions['com.apollion.border'] = { radius: border.extensions };
+  }
+
+  const doc: IRDocument = {
+    description: `Apollion DS tokens — DTCG 2025.10. Variant: ${meta.brand}/${meta.mode}/${meta.surface}/${meta.dimension}.`,
+    meta,
+    primitives,
+    groups: {
+      bg: colorRefGroup(foundation.bg as unknown as Record<string, string>, colors, BG_REF),
+      text: colorRefGroup(foundation.text as unknown as Record<string, string>, colors, TEXT_REF),
+      spacing: dimensionRefGroup(foundation.spacing as unknown as Record<string, string>, primitives, SPACE_REF),
+      border: border.group,
+      font: font.group,
+      shadow: buildShadow(colors),
+    },
+    extensions,
+  };
+
+  return decorateMeta(doc);
+}
+
+/** Explicit alias for {@link buildIR} — the full per-variant document (R5 oracle). */
+export const buildFullIR = buildIR;