@apollion-dsi/tokens 4.1.0 → 4.3.0

package/src/ir.ts

@@ -7,10 +7,14 @@
  * one place.
  *
  * **Layers:**
- * - `primitives` — the structural palette as the colour SSOT (`color.*`, R4).
- * - `groups` — foundation aliases (`bg`/`text`) + scales (`spacing`) +
- *   composite/scale layers (`border`/`font`/`shadow`, S4). Foundation colours
- *   reference primitives (`{color.x.y}`); diverging values fall back to inline.
+ * - `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
@@ -26,12 +30,17 @@
 
 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');
 
@@ -133,7 +142,15 @@ export interface IRVariantMeta {
 export interface IRDocument {
   readonly description: string;
   readonly meta: IRVariantMeta;
-  /** Colour SSOT — structural palette primitives (`color.*`). */
+  /**
+   * 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;
@@ -211,8 +228,8 @@ const NAMED_PALETTES = [
   'information',
 ] as const;
 
-/** Structural palette → colour primitives (`color.*`). The SSOT layer. */
-function buildPrimitives(colors: ColorsThemeInterface): IRGroup {
+/** 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];
@@ -233,6 +250,42 @@ function buildPrimitives(colors: ColorsThemeInterface): IRGroup {
   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',
@@ -293,19 +346,88 @@ function dimensionGroup(layer: Record<string, string>): IRGroup {
   return out;
 }
 
-/** Border scales: px → dimension, style → strokeStyle. Non-px (e.g. `100%`)
- * goes to `$extensions`. */
-function buildBorder(): { group: IRGroup; extensions: Record<string, string> } {
+/**
+ * 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: Record<string, IRToken> = {};
-  for (const [key, value] of Object.entries(defaultInputBorder.borderWidth)) {
-    width[key] = { type: 'dimension', value: toDimensionValue(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 } };
@@ -362,7 +484,18 @@ function parseShadow(css: string): IRShadowValue {
   };
 }
 
-/** Depth levels → DTCG shadow composites (geometry from core, colour resolved). */
+/**
+ * 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> = {};
@@ -372,7 +505,178 @@ function buildShadow(colors: ColorsThemeInterface): IRGroup {
   return out;
 }
 
-/** Build the IR document for one resolved variant. */
+/**
+ * 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,
@@ -380,7 +684,8 @@ export function buildIR(foundation: FoundationLayer, colors: ColorsThemeInterfac
     surface: variant.surface,
     dimension: variant.dimension,
   };
-  const border = buildBorder();
+  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 };
@@ -388,18 +693,23 @@ export function buildIR(foundation: FoundationLayer, colors: ColorsThemeInterfac
     extensions['com.apollion.border'] = { radius: border.extensions };
   }
 
-  return {
+  const doc: IRDocument = {
     description: `Apollion DS tokens — DTCG 2025.10. Variant: ${meta.brand}/${meta.mode}/${meta.surface}/${meta.dimension}.`,
     meta,
-    primitives: buildPrimitives(colors),
+    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: dimensionGroup(foundation.spacing as unknown as Record<string, string>),
+      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;

package/src/renderers/dtcg-project.ts

@@ -0,0 +1,108 @@
+/**
+ * Shared DTCG projection — the pure IR→DTCG-value mapping reused by the
+ * single-document JSON renderer (`json.ts`) and the Resolver set renderers
+ * (`resolver.ts`).
+ *
+ * Factored out so both surfaces emit byte-identical token shapes ($value /
+ * $type / $description / $deprecated) and a composed (base + color + spacing)
+ * set reproduces exactly what the full per-variant document used to emit.
+ *
+ * @see json.ts (full single-doc surface) · resolver.ts (sliced sets surface)
+ * @see https://www.designtokens.org/TR/drafts/format/ (DTCG 2025.10)
+ */
+
+import type { IRColorValue, IRDimensionValue, IRGroup, IRShadowValue, IRToken, IRValue } from '../ir';
+import { isToken, kebab, kebabPath } from '../ir';
+
+export interface DtcgColorValue {
+  colorSpace: 'oklch';
+  components: number[];
+  alpha?: number;
+  hex: string;
+}
+
+export interface DtcgDimensionValue {
+  value: number;
+  unit: 'px' | 'rem';
+}
+
+export interface DtcgShadowValue {
+  color: DtcgColorValue;
+  offsetX: DtcgDimensionValue;
+  offsetY: DtcgDimensionValue;
+  blur: DtcgDimensionValue;
+  spread: DtcgDimensionValue;
+  inset?: boolean;
+}
+
+export type DtcgTokenValue = DtcgColorValue | DtcgDimensionValue | DtcgShadowValue | string | number;
+
+export interface DtcgToken {
+  $value: DtcgTokenValue;
+  $type: string;
+  $description?: string;
+  $deprecated?: boolean | string;
+}
+
+export interface DtcgGroup {
+  [key: string]: DtcgToken | DtcgGroup;
+}
+
+function colorValue(v: IRColorValue): DtcgColorValue {
+  return v.alpha !== undefined
+    ? { colorSpace: 'oklch', components: [...v.components], alpha: v.alpha, hex: v.hex }
+    : { colorSpace: 'oklch', components: [...v.components], hex: v.hex };
+}
+
+function dimensionValue(v: IRDimensionValue): DtcgDimensionValue {
+  return { value: v.value, unit: v.unit };
+}
+
+function shadowValue(v: IRShadowValue): DtcgShadowValue {
+  const s = v.shadow;
+  const out: DtcgShadowValue = {
+    color: colorValue(s.color),
+    offsetX: dimensionValue(s.offsetX),
+    offsetY: dimensionValue(s.offsetY),
+    blur: dimensionValue(s.blur),
+    spread: dimensionValue(s.spread),
+  };
+  if (s.inset) out.inset = true;
+  return out;
+}
+
+export function projectValue(value: IRValue): DtcgTokenValue {
+  switch (value.kind) {
+    case 'ref':
+      return `{${kebabPath(value.path)}}`;
+    case 'color':
+      return colorValue(value);
+    case 'dimension':
+      return dimensionValue(value);
+    case 'fontFamily':
+      return value.family;
+    case 'fontWeight':
+      return value.weight;
+    case 'number':
+      return value.number;
+    case 'strokeStyle':
+      return value.style;
+    case 'shadow':
+      return shadowValue(value);
+  }
+}
+
+export function projectToken(token: IRToken): DtcgToken {
+  const out: DtcgToken = { $value: projectValue(token.value), $type: token.type };
+  if (token.description !== undefined) out.$description = token.description;
+  if (token.deprecated !== undefined) out.$deprecated = token.deprecated;
+  return out;
+}
+
+export function projectGroup(group: IRGroup): DtcgGroup {
+  const out: DtcgGroup = {};
+  for (const [key, node] of Object.entries(group)) {
+    out[kebab(key)] = isToken(node) ? projectToken(node) : projectGroup(node);
+  }
+  return out;
+}

package/src/renderers/json.ts

@@ -1,11 +1,13 @@
 /**
- * JSON renderer — project the token IR to DTCG-compliant JSON.
+ * JSON renderer — project the token IR to DTCG-compliant JSON (the full
+ * single-document surface, used by `renderers.test.ts` and as the oracle for
+ * resolver composition-equivalence).
  *
  * **Spec:** [Design Tokens Format Module 2025.10](https://www.designtokens.org/TR/drafts/format/)
  * (DTCG / W3C Community Group draft track).
  *
- * Pure projection of the IR (`ir.ts`):
- * - `primitives` → the `color` group (structural SSOT) of OKLch objects.
+ * Pure projection of the IR (`ir.ts`) via the shared `dtcg-project` mapping:
+ * - `primitives` → sibling top-level groups (`color` / `space` / `border-width`).
  * - colour/dimension → `{ colorSpace, components, hex, alpha? }` / `{ value, unit }`.
  * - references → DTCG aliases, e.g. `"$value": "{color.primary.base}"`.
  * - composites/scales (S4) → `fontFamily`/`fontWeight`/`number`/`strokeStyle`
@@ -13,109 +15,25 @@
  *
  * Non-DTCG values travel in the document `$extensions` (`com.apollion.*`).
  *
- * @see ../ir.ts (source of truth) · tech-radar R1/R2/R3/R4 · ADR-006 §3.10
+ * **Build surface note:** `build.ts` no longer emits this full per-variant
+ * document to `dist/json/` — the shipped JSON surface is the Resolver + sets
+ * (`resolver.ts`). This renderer remains the in-memory SSOT/oracle.
+ *
+ * @see ../ir.ts (source of truth) · ./dtcg-project.ts · ./resolver.ts
+ * @see tech-radar R1/R2/R3/R4 · ADR-006 §3.10
  */
 
-import type { IRColorValue, IRDimensionValue, IRDocument, IRGroup, IRShadowValue, IRToken, IRValue } from '../ir';
-import { isToken, kebab, kebabPath } from '../ir';
-
-interface DtcgColorValue {
-  colorSpace: 'oklch';
-  components: number[];
-  alpha?: number;
-  hex: string;
-}
-
-interface DtcgDimensionValue {
-  value: number;
-  unit: 'px' | 'rem';
-}
-
-interface DtcgShadowValue {
-  color: DtcgColorValue;
-  offsetX: DtcgDimensionValue;
-  offsetY: DtcgDimensionValue;
-  blur: DtcgDimensionValue;
-  spread: DtcgDimensionValue;
-  inset?: boolean;
-}
-
-type DtcgTokenValue = DtcgColorValue | DtcgDimensionValue | DtcgShadowValue | string | number;
-
-interface DtcgToken {
-  $value: DtcgTokenValue;
-  $type: string;
-  $description?: string;
-  $deprecated?: boolean | string;
-}
-
-interface DtcgGroup {
-  [key: string]: DtcgToken | DtcgGroup;
-}
-
-function colorValue(v: IRColorValue): DtcgColorValue {
-  return v.alpha !== undefined
-    ? { colorSpace: 'oklch', components: [...v.components], alpha: v.alpha, hex: v.hex }
-    : { colorSpace: 'oklch', components: [...v.components], hex: v.hex };
-}
-
-function dimensionValue(v: IRDimensionValue): DtcgDimensionValue {
-  return { value: v.value, unit: v.unit };
-}
-
-function shadowValue(v: IRShadowValue): DtcgShadowValue {
-  const s = v.shadow;
-  const out: DtcgShadowValue = {
-    color: colorValue(s.color),
-    offsetX: dimensionValue(s.offsetX),
-    offsetY: dimensionValue(s.offsetY),
-    blur: dimensionValue(s.blur),
-    spread: dimensionValue(s.spread),
-  };
-  if (s.inset) out.inset = true;
-  return out;
-}
-
-function projectValue(value: IRValue): DtcgTokenValue {
-  switch (value.kind) {
-    case 'ref':
-      return `{${kebabPath(value.path)}}`;
-    case 'color':
-      return colorValue(value);
-    case 'dimension':
-      return dimensionValue(value);
-    case 'fontFamily':
-      return value.family;
-    case 'fontWeight':
-      return value.weight;
-    case 'number':
-      return value.number;
-    case 'strokeStyle':
-      return value.style;
-    case 'shadow':
-      return shadowValue(value);
-  }
-}
-
-function projectToken(token: IRToken): DtcgToken {
-  const out: DtcgToken = { $value: projectValue(token.value), $type: token.type };
-  if (token.description !== undefined) out.$description = token.description;
-  if (token.deprecated !== undefined) out.$deprecated = token.deprecated;
-  return out;
-}
+import { projectGroup } from './dtcg-project';
 
-function projectGroup(group: IRGroup): DtcgGroup {
-  const out: DtcgGroup = {};
-  for (const [key, node] of Object.entries(group)) {
-    out[kebab(key)] = isToken(node) ? projectToken(node) : projectGroup(node);
-  }
-  return out;
-}
+import type { IRDocument } from '../ir';
 
 export function renderJson(ir: IRDocument): string {
+  // `primitives` is keyed by namespace (`color` / `space` / `borderWidth`);
+  // each projects to a sibling top-level DTCG group, so reference paths like
+  // `{space.medium}` resolve at the document root.
   const doc = {
     $description: ir.description,
-    color: projectGroup(ir.primitives),
+    ...projectGroup(ir.primitives),
     ...projectGroup(ir.groups),
     $extensions: ir.extensions,
   };