@apollion-dsi/tokens 4.0.0 → 4.2.0

package/src/renderers/css.ts

@@ -1,64 +1,56 @@
 /**
- * CSS renderer — emit Foundation tokens as CSS custom properties.
+ * CSS renderer — project the token IR to CSS custom properties (the resolved
+ * consumer surface).
  *
- * Format: `--apollion-{layer}-{role}-{variant}` per ADR-006 §3.3.
+ * Format: `--apollion-{group}-{...path}-{token}` per ADR-006 §3.3. References
+ * are resolved to literal values and the primitives layer is omitted — CSS
+ * stays fully resolved (JSON is the SSOT surface). Nested groups (border/font/
+ * shadow) flatten into dashed paths. Color tokens additionally get `@property`
+ * declarations (tech-radar R3) wrapped in `@supports`.
  *
- * **tech-radar R3:** also emits `@property` declarations for typed tokens
- * (color/length) — enables native CSS transitions (View Transitions API
- * friendly). `@property` is browser-supported 84%+ mid-2024; wrapped in
- * `@supports` for graceful degradation.
+ * Output is deterministic: groups/tokens iterate in IR insertion order.
  *
- * Output is deterministic: keys iterated in insertion order from the
- * FoundationLayer object; no timestamps, no run-id.
- *
- * @see ADR-006 §3.3 + §3.10 + tech-radar R3
- * @see PRD-002 §S5
+ * @see ../ir.ts (source of truth) · ADR-006 §3.3 + §3.10 · tech-radar R3
  */
 
-import type { FoundationLayer } from '@apollion-dsi/core/themes/foundation';
-
-import type { Variant } from '../config-schema';
+import type { IRDocument, IRGroup } from '../ir';
+import { isToken, kebab, rawValue } from '../ir';
 
 const HEADER_LINE = '/* Generated by apollion-tokens build — DO NOT EDIT. See apollion.config.mjs. */';
 
-export function renderCss(foundation: FoundationLayer, variant: Variant): string {
-  const lines: string[] = [HEADER_LINE, ''];
-
-  // Variant marker as a comment (NOT a var — keep cascade clean).
-  lines.push(
-    `/* Variant: brand=${variant.brand} mode=${variant.mode} surface=${variant.surface} dimension=${variant.dimension} */`,
-    '',
-    ':root {',
-  );
-
-  // bg layer
-  for (const [key, value] of Object.entries(foundation.bg)) {
-    lines.push(`  --apollion-bg-${key}: ${value};`);
+function emitVars(group: IRGroup, prefix: string[], lines: string[]): void {
+  for (const [key, node] of Object.entries(group)) {
+    const path = [...prefix, kebab(key)];
+    if (isToken(node)) lines.push(`  --apollion-${path.join('-')}: ${rawValue(node.value)};`);
+    else emitVars(node, path, lines);
   }
+}
 
-  // text layer
-  for (const [key, value] of Object.entries(foundation.text)) {
-    const kebab = key.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
-    lines.push(`  --apollion-text-${kebab}: ${value};`);
+function emitProperties(group: IRGroup, prefix: string[], lines: string[]): void {
+  for (const [key, node] of Object.entries(group)) {
+    const path = [...prefix, kebab(key)];
+    if (!isToken(node)) {
+      emitProperties(node, path, lines);
+    } else if (node.type === 'color') {
+      lines.push(
+        `  @property --apollion-${path.join('-')} { syntax: '<color>'; inherits: true; initial-value: ${rawValue(node.value)}; }`,
+      );
+    }
   }
+}
 
-  // spacing layer
-  for (const [key, value] of Object.entries(foundation.spacing)) {
-    lines.push(`  --apollion-spacing-${key}: ${value};`);
-  }
+export function renderCss(ir: IRDocument): string {
+  const { brand, mode, surface, dimension } = ir.meta;
+  const lines: string[] = [HEADER_LINE, ''];
 
+  // Variant marker as a comment (NOT a var — keep cascade clean).
+  lines.push(`/* Variant: brand=${brand} mode=${mode} surface=${surface} dimension=${dimension} */`, '', ':root {');
+  emitVars(ir.groups, [], lines);
   lines.push('}', '');
 
-  // @property declarations for color tokens — opt-in via @supports
+  // @property declarations for color tokens — opt-in via @supports.
   lines.push('@supports (background: paint(squircle)) or (color: oklch(0% 0 0)) {');
-  for (const [key, value] of Object.entries(foundation.bg)) {
-    lines.push(`  @property --apollion-bg-${key} { syntax: '<color>'; inherits: true; initial-value: ${value}; }`);
-  }
-  for (const key of Object.keys(foundation.text)) {
-    const kebab = key.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
-    const value = (foundation.text as unknown as Record<string, string>)[key];
-    lines.push(`  @property --apollion-text-${kebab} { syntax: '<color>'; inherits: true; initial-value: ${value}; }`);
-  }
+  emitProperties(ir.groups, [], lines);
   lines.push('}', '');
 
   return lines.join('\n');

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,81 +1,41 @@
 /**
- * JSON renderer — emit Foundation tokens as 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 Community Group Format Module](https://design-tokens.github.io/community-group/format/)
- * (W3C draft track, mid-2024).
+ * **Spec:** [Design Tokens Format Module 2025.10](https://www.designtokens.org/TR/drafts/format/)
+ * (DTCG / W3C Community Group draft track).
  *
- * Each token is a leaf with `$value` + `$type`. Groups nest naturally:
- * ```json
- * { "bg": { "primary": { "$value": "#003750", "$type": "color" } } }
- * ```
+ * 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`
+ *   primitives and the `shadow` composite `{ color, offsetX, offsetY, blur, spread, inset? }`.
  *
- * Enables interop with Tokens Studio (Figma), Style Dictionary downstream,
- * Specify, and any tool consuming the DTCG spec.
+ * Non-DTCG values travel in the document `$extensions` (`com.apollion.*`).
  *
- * @see tech-radar R1 (DTCG compliance)
- * @see ADR-006 §3.10 + PRD-002 §S5
+ * **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 { FoundationLayer } from '@apollion-dsi/core/themes/foundation';
-
-import type { Variant } from '../config-schema';
-
-interface DtcgToken<T extends string = string> {
-  $value: string;
-  $type: T;
-}
-
-interface DtcgGroup {
-  [key: string]: DtcgToken | DtcgGroup;
-}
-
-export interface DtcgDocument {
-  $description: string;
-  bg: DtcgGroup;
-  text: DtcgGroup;
-  spacing: DtcgGroup;
-  /** Variant metadata — non-standard extension under DTCG `$extensions` namespace. */
-  $extensions: {
-    'com.apollion.variant': {
-      brand: string;
-      mode: string;
-      surface: string;
-      dimension: string;
-    };
-  };
-}
-
-function toColorGroup(layer: Record<string, string>): DtcgGroup {
-  const out: DtcgGroup = {};
-  for (const [key, value] of Object.entries(layer)) {
-    const kebab = key.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
-    out[kebab] = { $value: value, $type: 'color' };
-  }
-  return out;
-}
+import { projectGroup } from './dtcg-project';
 
-function toDimensionGroup(layer: Record<string, string>): DtcgGroup {
-  const out: DtcgGroup = {};
-  for (const [key, value] of Object.entries(layer)) {
-    out[key] = { $value: value, $type: 'dimension' };
-  }
-  return out;
-}
+import type { IRDocument } from '../ir';
 
-export function renderJson(foundation: FoundationLayer, variant: Variant): string {
-  const doc: DtcgDocument = {
-    $description: `Apollion DS tokens — DTCG v1. Variant: ${variant.brand}/${variant.mode}/${variant.surface}/${variant.dimension}.`,
-    bg: toColorGroup(foundation.bg as unknown as Record<string, string>),
-    text: toColorGroup(foundation.text as unknown as Record<string, string>),
-    spacing: toDimensionGroup(foundation.spacing as unknown as Record<string, string>),
-    $extensions: {
-      'com.apollion.variant': {
-        brand: variant.brand,
-        mode: variant.mode,
-        surface: variant.surface,
-        dimension: variant.dimension,
-      },
-    },
+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,
+    ...projectGroup(ir.primitives),
+    ...projectGroup(ir.groups),
+    $extensions: ir.extensions,
   };
   return `${JSON.stringify(doc, null, 2)}\n`;
 }

package/src/renderers/resolver.ts

@@ -0,0 +1,129 @@
+/**
+ * Resolver renderer (R5) — project the IR slices to a DTCG **Resolver** manifest
+ * plus the reference-closed set documents it points at.
+ *
+ * **Spec:** DTCG Resolver draft (Design Tokens Community Group — Resolver /
+ * "modes" module on the 2025.10 draft track). A resolver names a set of token
+ * files (`sets`) and a set of `modifiers` (enumerated axes with a `default`); a
+ * consumer composes the chosen modifier values into a single resolved token
+ * tree. This replaces the old N-file per-variant JSON explosion with one
+ * manifest + O(brand·mode·surface + dimension + 1) sets.
+ *
+ * **S5 mode caveat:** `mode` is emitted as a real modifier (values + default)
+ * even though palette generation is currently mode-agnostic (dark == light).
+ * The topology is therefore correct ahead of S6 wiring real dark-mode logic.
+ *
+ * Set documents are projected from `IRSlice`s via the shared `dtcg-project`
+ * mapping, so a composed (base + color + spacing) tree is byte-equivalent to the
+ * old full per-variant document (asserted in `resolver.test.ts`).
+ *
+ * @see ../ir.ts (slices) · ./dtcg-project.ts · ../set-plan.ts
+ * @see https://www.designtokens.org/TR/ (Resolver draft)
+ */
+
+import { projectGroup } from './dtcg-project';
+
+import type { ApollionConfig } from '../config-schema';
+import type { IRSlice } from '../ir';
+import type { SetPlan } from '../set-plan';
+
+/** A DTCG modifier: an enumerated axis with a default value. */
+interface ResolverModifier {
+  name: string;
+  values: string[];
+  default: string;
+}
+
+/** A DTCG set reference: a named token document at `source`. */
+interface ResolverSet {
+  name: string;
+  source: string;
+}
+
+interface ResolverManifest {
+  name: string;
+  description: string;
+  sets: ResolverSet[];
+  modifiers: ResolverModifier[];
+  $extensions: Record<string, unknown>;
+}
+
+/** Render one IR slice (base/color/spacing) to a DTCG set JSON document. */
+function renderSet(slice: IRSlice, description: string): string {
+  const doc: Record<string, unknown> = {
+    $description: description,
+    ...projectGroup(slice.groups),
+  };
+  if (Object.keys(slice.extensions).length > 0) doc.$extensions = slice.extensions;
+  return `${JSON.stringify(doc, null, 2)}\n`;
+}
+
+/** Axis-invariant base set (border + font). */
+export function renderBaseSet(slice: IRSlice): string {
+  return renderSet(slice, 'Apollion DS — base set (axis-invariant: border + font). DTCG 2025.10.');
+}
+
+/** Colour set for one (brand × mode × surface). */
+export function renderColorSet(slice: IRSlice, brand: string, mode: string, surface: string): string {
+  return renderSet(slice, `Apollion DS — colour set. brand=${brand} mode=${mode} surface=${surface}. DTCG 2025.10.`);
+}
+
+/** Spacing set for one dimension. */
+export function renderSpacingSet(slice: IRSlice, dimension: string): string {
+  return renderSet(slice, `Apollion DS — spacing set. dimension=${dimension}. DTCG 2025.10.`);
+}
+
+/**
+ * Render the Resolver manifest (`resolver.json`).
+ *
+ * Modifiers enumerate the four axes (brand/mode/surface/dimension) with the
+ * first encountered value as `default`. `sets` lists every concrete set file.
+ * The `$extensions['com.apollion.resolver']` block documents the composition
+ * rule — which sets to merge for a chosen modifier tuple — since the draft's
+ * apply-by-modifier binding is still settling; this keeps the manifest
+ * self-describing for our own consumers.
+ */
+export function renderResolver(config: ApollionConfig, plan: SetPlan): string {
+  const { modifiers } = plan;
+
+  const modifierList: ResolverModifier[] = [
+    { name: 'brand', values: [...modifiers.brand], default: modifiers.brand[0] },
+    { name: 'mode', values: [...modifiers.mode], default: modifiers.mode[0] },
+    { name: 'surface', values: [...modifiers.surface], default: modifiers.surface[0] },
+    { name: 'dimension', values: [...modifiers.dimension], default: modifiers.dimension[0] },
+  ];
+
+  const sets: ResolverSet[] = [
+    { name: plan.base.name, source: plan.base.file },
+    ...plan.spacing.map((s) => ({ name: s.name, source: s.file })),
+    ...plan.color.map((c) => ({ name: c.name, source: c.file })),
+  ];
+
+  const manifest: ResolverManifest = {
+    name: 'apollion-tokens',
+    description:
+      'Apollion DS token resolver — DTCG 2025.10. Compose the base set with the ' +
+      'colour set for the chosen brand/mode/surface and the spacing set for the ' +
+      'chosen dimension. NOTE: mode is a topology placeholder in this release ' +
+      '(dark resolves identically to light until S6).',
+    sets,
+    modifiers: modifierList,
+    $extensions: {
+      'com.apollion.resolver': {
+        // How to compose a final token tree for a chosen modifier tuple.
+        composition: {
+          always: [plan.base.name],
+          byModifier: {
+            // colour set name = `<brand>.color.<mode>.<surface>`
+            color: '${brand}.color.${mode}.${surface}',
+            // spacing set name = `spacing.<dimension>`
+            spacing: 'spacing.${dimension}',
+          },
+        },
+        modeIsPlaceholder: true,
+      },
+    },
+  };
+
+  return `${JSON.stringify(manifest, null, 2)}\n`;
+}

package/src/renderers/ts.ts

@@ -1,46 +1,45 @@
 /**
- * TypeScript renderer — emit Foundation tokens as `as const` literal.
+ * TypeScript renderer — project the token IR to an `as const` literal (the
+ * resolved consumer surface).
  *
- * **tech-radar R4:** consumer importing the generated `.d.ts` gets literal
- * types (e.g. `tokens.bg.primary: 'oklch(...)'` not `string`) — autocomplete
- * + compile-time invariant checks.
+ * Consumers importing the generated `.d.ts` get literal types (e.g.
+ * `tokens.bg.primary: '#003750'` not `string`) — autocomplete + compile-time
+ * invariant checks (tech-radar R4). References resolve to literal values, the
+ * primitives layer is omitted, and nested groups (border/font/shadow) nest as
+ * nested objects.
  *
- * @see tech-radar R4
- * @see ADR-006 §3.10 + PRD-002 §S5
+ * @see ../ir.ts (source of truth) · tech-radar R4 · ADR-006 §3.10
  */
 
-import type { FoundationLayer } from '@apollion-dsi/core/themes/foundation';
-
-import type { Variant } from '../config-schema';
+import type { IRDocument, IRGroup } from '../ir';
+import { isToken, rawValue } from '../ir';
 
 const HEADER_LINE = '// Generated by apollion-tokens build — DO NOT EDIT. See apollion.config.mjs.';
 
-function serializeRecord(record: Record<string, string>, indent: number): string {
-  const pad = ' '.repeat(indent);
-  const entries = Object.entries(record).map(
-    ([key, value]) => `${pad}${JSON.stringify(key)}: ${JSON.stringify(value)},`,
-  );
-  return entries.join('\n');
+function emitGroup(group: IRGroup, depth: number, out: string[]): void {
+  const pad = '  '.repeat(depth);
+  for (const [key, node] of Object.entries(group)) {
+    if (isToken(node)) {
+      out.push(`${pad}${JSON.stringify(key)}: ${JSON.stringify(rawValue(node.value))},`);
+    } else {
+      out.push(`${pad}${key}: {`);
+      emitGroup(node, depth + 1, out);
+      out.push(`${pad}},`);
+    }
+  }
 }
 
-export function renderTs(foundation: FoundationLayer, variant: Variant): string {
-  return [
+export function renderTs(ir: IRDocument): string {
+  const { brand, mode, surface, dimension } = ir.meta;
+  const out: string[] = [
     HEADER_LINE,
-    `// Variant: brand=${variant.brand} mode=${variant.mode} surface=${variant.surface} dimension=${variant.dimension}`,
+    `// Variant: brand=${brand} mode=${mode} surface=${surface} dimension=${dimension}`,
     '',
     'export const tokens = {',
-    '  bg: {',
-    serializeRecord(foundation.bg as unknown as Record<string, string>, 4),
-    '  },',
-    '  text: {',
-    serializeRecord(foundation.text as unknown as Record<string, string>, 4),
-    '  },',
-    '  spacing: {',
-    serializeRecord(foundation.spacing as unknown as Record<string, string>, 4),
-    '  },',
-    '} as const;',
-    '',
-    'export type Tokens = typeof tokens;',
-    '',
-  ].join('\n');
+  ];
+
+  emitGroup(ir.groups, 1, out);
+
+  out.push('} as const;', '', 'export type Tokens = typeof tokens;', '');
+  return out.join('\n');
 }

package/src/set-plan.ts

@@ -0,0 +1,136 @@
+/**
+ * Set topology planner (R5) — the single source of truth for which Resolver
+ * sets exist, their file paths, and the modifier enumerations.
+ *
+ * Both `build.ts` (which writes the set files) and `resolver.ts` (which writes
+ * the manifest pointing at them) derive from this plan, so set names can never
+ * drift between the two. Derived purely from the expanded variants of a config.
+ *
+ * **Set topology** (each set is reference-closed, see `ir.ts` slices):
+ * - `base` — 1 file, axis-invariant (border + font).
+ * - `spacing.<dimension>` — one per dimension.
+ * - `<brand>.color.<mode>.<surface>` — one per (brand × mode × surface).
+ *
+ * @see ir.ts (`buildBaseIR` / `buildColorIR` / `buildSpacingIR`)
+ * @see renderers/resolver.ts (manifest) · build.ts (set emission)
+ */
+
+import type { Dimension } from '@apollion-dsi/core/themes/dimension';
+
+import type { ApollionConfig, Mode, Surface } from './config-schema';
+import { expandVariants } from './config-schema';
+
+/** Directory (relative to dist root) holding the emitted set files. */
+export const SETS_DIR = 'json/sets';
+/** Resolver manifest path (relative to dist root). */
+export const RESOLVER_PATH = 'json/resolver.json';
+
+/** A colour set keyed by its (brand × mode × surface) coordinate. */
+export interface ColorSetPlan {
+  readonly kind: 'color';
+  readonly name: string;
+  readonly file: string;
+  readonly brand: string;
+  readonly mode: Mode;
+  readonly surface: Surface;
+}
+
+/** A spacing set keyed by its dimension. */
+export interface SpacingSetPlan {
+  readonly kind: 'spacing';
+  readonly name: string;
+  readonly file: string;
+  readonly dimension: Dimension;
+}
+
+/** The axis-invariant base set. */
+export interface BaseSetPlan {
+  readonly kind: 'base';
+  readonly name: string;
+  readonly file: string;
+}
+
+export interface SetPlan {
+  readonly base: BaseSetPlan;
+  readonly spacing: readonly SpacingSetPlan[];
+  readonly color: readonly ColorSetPlan[];
+  /** Distinct modifier values (declaration/encounter order), for the manifest. */
+  readonly modifiers: {
+    readonly brand: readonly string[];
+    readonly mode: readonly Mode[];
+    readonly surface: readonly Surface[];
+    readonly dimension: readonly Dimension[];
+  };
+}
+
+/** Set source path relative to the dist root (used by the resolver manifest). */
+function setFile(name: string): string {
+  return `${SETS_DIR}/${name}.json`;
+}
+
+/** Stable colour-set name for a coordinate: `<brand>.color.<mode>.<surface>`. */
+export function colorSetName(brand: string, mode: Mode, surface: Surface): string {
+  return `${brand}.color.${mode}.${surface}`;
+}
+
+/** Stable spacing-set name for a dimension: `spacing.<dimension>`. */
+export function spacingSetName(dimension: Dimension): string {
+  return `spacing.${dimension}`;
+}
+
+/** Push `value` onto `list` if absent — preserves first-encounter order. */
+function pushUnique<T>(list: T[], value: T): void {
+  if (!list.includes(value)) list.push(value);
+}
+
+/**
+ * Derive the full set topology from a config. Deterministic: ordering follows
+ * `expandVariants` (brands alphabetical → declaration order for the rest), so
+ * the emitted manifest + files are byte-stable across runs.
+ */
+export function planSets(config: ApollionConfig): SetPlan {
+  const variants = expandVariants(config);
+
+  const brands: string[] = [];
+  const modes: Mode[] = [];
+  const surfaces: Surface[] = [];
+  const dimensions: Dimension[] = [];
+
+  const colorSeen = new Set<string>();
+  const color: ColorSetPlan[] = [];
+  const spacingSeen = new Set<string>();
+  const spacing: SpacingSetPlan[] = [];
+
+  for (const v of variants) {
+    pushUnique(brands, v.brand);
+    pushUnique(modes, v.mode);
+    pushUnique(surfaces, v.surface);
+    pushUnique(dimensions, v.dimension);
+
+    const cName = colorSetName(v.brand, v.mode, v.surface);
+    if (!colorSeen.has(cName)) {
+      colorSeen.add(cName);
+      color.push({
+        kind: 'color',
+        name: cName,
+        file: setFile(cName),
+        brand: v.brand,
+        mode: v.mode,
+        surface: v.surface,
+      });
+    }
+
+    const sName = spacingSetName(v.dimension);
+    if (!spacingSeen.has(sName)) {
+      spacingSeen.add(sName);
+      spacing.push({ kind: 'spacing', name: sName, file: setFile(sName), dimension: v.dimension });
+    }
+  }
+
+  return {
+    base: { kind: 'base', name: 'base', file: setFile('base') },
+    spacing,
+    color,
+    modifiers: { brand: brands, mode: modes, surface: surfaces, dimension: dimensions },
+  };
+}