@apollion-dsi/tokens 5.3.0 → 5.5.0

package/src/renderers/design-md.ts

@@ -0,0 +1,107 @@
+/**
+ * Design.md renderer — resolved-values AI context per brand.
+ *
+ * The rules layer (`llms.txt`) teaches *which* token to reach
+ * for; this emission supplies the *resolved values* those rules reference,
+ * generated from the consumer's own build so it can never drift from the
+ * shipped theme. YAML frontmatter for machines + a markdown body for humans.
+ *
+ * One document per brand, covering every (mode × surface × dimension) variant
+ * of that brand. Pure projection over per-variant `IRDocument`s — no value is
+ * computed here; a missing value is an IR gap by contract.
+ *
+ * @see ../../../../docs/references/design-md-decision.md (adoption decision)
+ * @see ../ir.ts (source of truth) · ./ts.ts (sibling resolved-surface renderer)
+ */
+
+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. -->';
+
+/** Flatten a resolved IR group into dot-path → raw value pairs. */
+function flatten(group: IRGroup, prefix: string, out: Array<[string, string | number]>): void {
+  for (const [key, node] of Object.entries(group)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    if (isToken(node)) {
+      out.push([path, rawValue(node.value) as string | number]);
+    } else {
+      flatten(node, path, out);
+    }
+  }
+}
+
+function yamlEscape(value: string | number): string {
+  if (typeof value === 'number') return String(value);
+  // hex colors and px/rem strings are safe unquoted except when starting with
+  // YAML-significant characters — quote everything for uniformity/safety.
+  return `'${String(value).replace(/'/g, "''")}'`;
+}
+
+function variantKey(ir: IRDocument): string {
+  const { mode, surface, dimension } = ir.meta;
+  return `${mode}.${surface}.${dimension}`;
+}
+
+/**
+ * Render one Design.md for a brand from its variant IRDocuments.
+ * Deterministic: variant order is the caller's (build order), path order is
+ * IR insertion order — both stable for a given config.
+ */
+export function renderDesignMd(brand: string, variants: readonly IRDocument[]): string {
+  if (variants.length === 0) {
+    throw new Error(`renderDesignMd: no variants for brand "${brand}"`);
+  }
+
+  // ── YAML frontmatter (machine surface) ────────────────────────────────────
+  const fm: string[] = ['---', `brand: '${brand}'`, 'generator: apollion-tokens', 'variants:'];
+  for (const ir of variants) {
+    const flat: Array<[string, string | number]> = [];
+    flatten(ir.groups, '', flat);
+    fm.push(`  ${variantKey(ir)}:`);
+    for (const [path, value] of flat) {
+      fm.push(`    ${path}: ${yamlEscape(value)}`);
+    }
+  }
+  fm.push('---');
+
+  // ── Markdown body (human surface) ─────────────────────────────────────────
+  const body: string[] = [
+    '',
+    HEADER_LINE,
+    '',
+    `# Design.md — ${brand}`,
+    '',
+    'Resolved design-token values for this brand, one section per variant.',
+    'Consumption rules (which token to reach for, layer boundaries) live in the',
+    'package `llms.txt`; this file carries the values those rules reference.',
+    'Regenerate with `apollion-tokens build` — never edit.',
+    '',
+  ];
+
+  for (const ir of variants) {
+    const { mode, surface, dimension } = ir.meta;
+    body.push(`## Variant \`${mode} · ${surface} · ${dimension}\``, '');
+    const flat: Array<[string, string | number]> = [];
+    flatten(ir.groups, '', flat);
+
+    // group rows by top-level namespace for readable tables
+    const byNs = new Map<string, Array<[string, string | number]>>();
+    for (const [path, value] of flat) {
+      const ns = path.split('.')[0] ?? path;
+      const rows = byNs.get(ns) ?? [];
+      rows.push([path, value]);
+      byNs.set(ns, rows);
+    }
+
+    for (const [ns, rows] of byNs) {
+      body.push(`### ${ns}`, '', '| Token | Value |', '| --- | --- |');
+      for (const [path, value] of rows) {
+        body.push(`| \`${path}\` | \`${value}\` |`);
+      }
+      body.push('');
+    }
+  }
+
+  return `${fm.join('\n')}\n${body.join('\n')}`;
+}

package/src/renderers/resolver.ts

@@ -10,9 +10,10 @@
  * manifest + O(brand·mode·surface + 2·dimension + 1) sets (spacing + font per
  * dimension).
  *
- * **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.
+ * **Mode modifier:** `mode` is emitted as a real modifier (values + default),
+ * and since ADR-019 the dark contexts carry real values — palette generation
+ * derives dark through the canonical seed swap in `theme-factory.ts` (the S5
+ * dark == light placeholder is retired).
  *
  * Set documents are projected from `IRSlice`s via the shared `dtcg-project`
  * mapping, so a composed (base + color + spacing + font) tree is byte-equivalent

package/src/renderers/tailwind.ts

@@ -0,0 +1,195 @@
+/**
+ * Tailwind renderer — project the token IR to a generated Tailwind preset +
+ * tailwind-merge extension (the Tailwind-consumer naming layer).
+ *
+ * The CSS surface already carries the values (`--apollion-*` custom
+ * properties); what a Tailwind stack lacks is the *naming layer* — theme keys
+ * pointing at those vars. Both modules are pure projections of the IR
+ * (generated, never hand-maintained), so preset keys cannot drift from the
+ * emitted CSS vars (differential-tested per group).
+ *
+ * **Alpha modifier (`/50` etc.):** Tailwind's `<alpha-value>` form needs raw
+ * channel triplets (`rgb(R G B / <alpha-value>)`), so opaque colour tokens map
+ * through `-rgb` companion vars (emitted by the CSS renderer under the same
+ * flag — see {@link rgbTriplet} / {@link isOpaqueColor}, the single source of
+ * that projection rule). Tokens that already carry alpha are excluded from the
+ * modifier form — mapping them through `rgb(… / <alpha-value>)` would silently
+ * drop their baked-in alpha (the surveyed source's silent-alpha-loss bug); the
+ * exclusion is noted as a comment in the emitted preset.
+ *
+ * **Scope (v1):** foundation groups only — `bg`/`text`/`tx` → `colors`,
+ * `spacing` → `spacing`, `border.radius`/`border.width` → `borderRadius`/
+ * `borderWidth`, `font.*` → `fontFamily`/`fontSize`/`fontWeight`/`lineHeight`,
+ * `shadow` → `boxShadow`. `border.style` has no Tailwind theme scale —
+ * deliberately unmapped. No dependency on the component-token tier.
+ *
+ * @see ../ir.ts (source of truth) · css.ts (`-rgb` companions) ·
+ *   docs/plans/tailwind-preset-renderer.md (divergence-matrix row 6)
+ */
+
+import { converter, parse } from 'culori';
+
+import type { IRColorValue, IRDocument, IRGroup, IRToken } from '../ir';
+import { isToken, kebab } from '../ir';
+
+const toRgb = converter('rgb');
+
+const HEADER_LINE = '// Generated by apollion-tokens build — DO NOT EDIT. See apollion.config.mjs.';
+
+/** Colour payload of a token, resolving references (else undefined). */
+export function colorPayload(token: IRToken): IRColorValue | undefined {
+  if (token.value.kind === 'color') return token.value;
+  if (token.value.kind === 'ref' && token.value.resolved.kind === 'color') return token.value.resolved;
+  return undefined;
+}
+
+/**
+ * Whether a colour token is opaque — eligible for the `<alpha-value>` modifier
+ * form via a `-rgb` companion var. Alpha-carrying tokens are excluded (the
+ * modifier form would silently drop their baked-in alpha).
+ */
+export function isOpaqueColor(color: IRColorValue): boolean {
+  return color.alpha === undefined;
+}
+
+/**
+ * `R G B` channel triplet (0–255, space-separated) for a `-rgb` companion var.
+ * Derived from the sRGB hex fallback — renderer-local via culori (no IR change).
+ */
+export function rgbTriplet(color: IRColorValue): string {
+  const rgb = toRgb(parse(color.hex));
+  if (!rgb) return '0 0 0';
+  const channel = (value: number): number => Math.min(255, Math.max(0, Math.round(value * 255)));
+  return `${channel(rgb.r)} ${channel(rgb.g)} ${channel(rgb.b)}`;
+}
+
+/** Flat `key → token` map of a group's tokens, kebab-dashed path keys. */
+function flatTokens(group: IRGroup, prefix: string[] = []): Map<string, IRToken> {
+  const out = new Map<string, IRToken>();
+  for (const [key, node] of Object.entries(group)) {
+    const path = [...prefix, kebab(key)];
+    if (isToken(node)) out.set(path.join('-'), node);
+    else for (const [k, v] of flatTokens(node, path)) out.set(k, v);
+  }
+  return out;
+}
+
+/** Narrow a root-level IR node to a group (missing → empty). */
+function groupAt(groups: IRGroup, ...path: string[]): IRGroup {
+  let node: IRToken | IRGroup | undefined = groups[path[0]];
+  for (const segment of path.slice(1)) {
+    if (!node || isToken(node)) return {};
+    node = node[segment];
+  }
+  return node && !isToken(node) ? node : {};
+}
+
+interface ColorEntry {
+  readonly key: string;
+  readonly cssVar: string;
+  readonly opaque: boolean;
+}
+
+/**
+ * Colour entries for the preset's `colors` scale: the `bg`/`text`/`tx`
+ * foundation groups, keyed `<group>-<path>` (the CSS var name minus the
+ * `--apollion-` prefix — one mental model across surfaces).
+ */
+function colorEntries(ir: IRDocument): ColorEntry[] {
+  const out: ColorEntry[] = [];
+  for (const groupName of ['bg', 'text', 'tx'] as const) {
+    for (const [key, token] of flatTokens(groupAt(ir.groups, groupName), [groupName])) {
+      const color = colorPayload(token);
+      if (!color) continue;
+      out.push({ key, cssVar: `--apollion-${key}`, opaque: isOpaqueColor(color) });
+    }
+  }
+  return out;
+}
+
+/** `key → var()` entries for a var-passthrough scale (spacing, radius, …). */
+function varEntries(group: IRGroup, cssPrefix: string[]): Array<readonly [string, string]> {
+  return [...flatTokens(group)].map(([key]) => [key, `var(--apollion-${[...cssPrefix, key].join('-')})`] as const);
+}
+
+function pushScale(out: string[], scale: string, entries: ReadonlyArray<readonly [string, string]>): void {
+  if (entries.length === 0) return;
+  out.push(`      ${scale}: {`);
+  for (const [key, value] of entries) out.push(`        ${JSON.stringify(key)}: ${JSON.stringify(value)},`);
+  out.push('      },');
+}
+
+/**
+ * Render the generated Tailwind preset module (`tailwind/preset.mjs`) —
+ * runtime-importable ESM, `theme.extend` only (never replaces Tailwind scales).
+ */
+export function renderTailwindPreset(ir: IRDocument): string {
+  const out: string[] = [
+    HEADER_LINE,
+    '// Tailwind preset over the Apollion foundation tokens — requires dist/css/ vars in scope.',
+    '',
+    'const preset = {',
+    '  theme: {',
+    '    extend: {',
+  ];
+
+  const colors = colorEntries(ir);
+  out.push('      colors: {');
+  for (const { key, cssVar, opaque } of colors) {
+    if (opaque) {
+      out.push(`        ${JSON.stringify(key)}: ${JSON.stringify(`rgb(var(${cssVar}-rgb) / <alpha-value>)`)},`);
+    } else {
+      out.push(`        // ${key} carries its own alpha — excluded from the <alpha-value> modifier form.`);
+      out.push(`        ${JSON.stringify(key)}: ${JSON.stringify(`var(${cssVar})`)},`);
+    }
+  }
+  out.push('      },');
+
+  pushScale(out, 'spacing', varEntries(groupAt(ir.groups, 'spacing'), ['spacing']));
+  pushScale(out, 'borderRadius', varEntries(groupAt(ir.groups, 'border', 'radius'), ['border', 'radius']));
+  pushScale(out, 'borderWidth', varEntries(groupAt(ir.groups, 'border', 'width'), ['border', 'width']));
+  pushScale(out, 'fontFamily', varEntries(groupAt(ir.groups, 'font', 'family'), ['font', 'family']));
+  pushScale(out, 'fontSize', varEntries(groupAt(ir.groups, 'font', 'size'), ['font', 'size']));
+  pushScale(out, 'fontWeight', varEntries(groupAt(ir.groups, 'font', 'weight'), ['font', 'weight']));
+  pushScale(out, 'lineHeight', varEntries(groupAt(ir.groups, 'font', 'lineHeight'), ['font', 'line-height']));
+  pushScale(out, 'boxShadow', varEntries(groupAt(ir.groups, 'shadow'), ['shadow']));
+
+  out.push('    },', '  },', '};', '', 'export default preset;', '');
+  return out.join('\n');
+}
+
+/**
+ * Render the tailwind-merge extension module (`tailwind/tw-merge.mjs`) —
+ * the config object for `extendTailwindMerge`, derived from the same IR as the
+ * preset so conflict resolution knows every generated key (one step better than
+ * the surveyed hand-maintained original).
+ */
+export function renderTwMergeExtension(ir: IRDocument): string {
+  const keys = (group: IRGroup): string[] => [...flatTokens(group).keys()];
+  const list = (values: string[]): string => `[${values.map((v) => JSON.stringify(v)).join(', ')}]`;
+
+  const out: string[] = [
+    HEADER_LINE,
+    '// tailwind-merge extension for the generated preset — pass to extendTailwindMerge().',
+    '',
+    'export const twMergeExtension = {',
+    '  extend: {',
+    '    theme: {',
+    `      colors: ${list(colorEntries(ir).map((entry) => entry.key))},`,
+    `      spacing: ${list(keys(groupAt(ir.groups, 'spacing')))},`,
+    `      borderRadius: ${list(keys(groupAt(ir.groups, 'border', 'radius')))},`,
+    `      borderWidth: ${list(keys(groupAt(ir.groups, 'border', 'width')))},`,
+    '    },',
+    '    classGroups: {',
+    `      'font-family': [{ font: ${list(keys(groupAt(ir.groups, 'font', 'family')))} }],`,
+    `      'font-size': [{ text: ${list(keys(groupAt(ir.groups, 'font', 'size')))} }],`,
+    `      'font-weight': [{ font: ${list(keys(groupAt(ir.groups, 'font', 'weight')))} }],`,
+    `      leading: [{ leading: ${list(keys(groupAt(ir.groups, 'font', 'lineHeight')))} }],`,
+    `      shadow: [{ shadow: ${list(keys(groupAt(ir.groups, 'shadow')))} }],`,
+    '    },',
+    '  },',
+    '};',
+    '',
+  ];
+  return out.join('\n');
+}

package/src/renderers/ts.ts

@@ -6,20 +6,34 @@
  * `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.
+ * nested objects. Documented tokens (`token-meta.ts`) carry their
+ * `$description`/`$deprecated` as JSDoc, so a deprecated token strikes through
+ * at the call site before any codemod runs.
  *
  * @see ../ir.ts (source of truth) · tech-radar R4 · ADR-006 §3.10
  */
 
-import type { IRDocument, IRGroup } from '../ir';
+import type { IRDocument, IRGroup, IRToken } from '../ir';
 import { isToken, rawValue } from '../ir';
 
 const HEADER_LINE = '// Generated by apollion-tokens build — DO NOT EDIT. See apollion.config.mjs.';
 
+function emitDoc(node: IRToken, pad: string, out: string[]): void {
+  const lines: string[] = [];
+  if (node.description !== undefined) lines.push(node.description);
+  if (node.deprecated === true) lines.push('@deprecated');
+  else if (typeof node.deprecated === 'string') lines.push(`@deprecated ${node.deprecated}`);
+  if (lines.length === 0) return;
+  out.push(`${pad}/**`);
+  for (const line of lines) out.push(`${pad} * ${line.replace(/\*\//g, '*\\/')}`);
+  out.push(`${pad} */`);
+}
+
 function emitGroup(group: IRGroup, depth: number, out: string[]): void {
   const pad = '  '.repeat(depth);
   for (const [key, node] of Object.entries(group)) {
     if (isToken(node)) {
+      emitDoc(node, pad, out);
       out.push(`${pad}${JSON.stringify(key)}: ${JSON.stringify(rawValue(node.value))},`);
     } else {
       out.push(`${pad}${key}: {`);

package/src/theme-factory.ts

@@ -10,14 +10,16 @@
  * 4. Core `createFoundation` → FoundationLayer.
  * 5. If surface === 'negative': core `invertForSurface` applied.
  *
- * **Mode handling (S5 limitation):** `mode` is currently a no-op placeholder
- * — palette generation does not differ per mode. ADR-006 E6 (in S6) wires
- * `themeMode` resolution into surface inversion. For S5, mode appears only
- * in the variant filename so the output topology is ready when S6 plugs in
- * real dark-mode logic.
+ * **Mode handling (ADR-019):** `mode === 'dark'` derives the palette through
+ * the canonical-dark seed swap (`toCanonicalDarkInput`) — the same convention
+ * the core invariant suite exercises as "canonical dark". Emitted dark equals
+ * the runtime canonical dark byte-exactly (parity by composition over the
+ * Strangler Fig builders; see `__tests__/parity.test.ts` canonical-dark rows).
+ * This retires the S5 placeholder (dark == light) and closes the ADR-006 E6/S6
+ * parking.
  *
- * @see ADR-006 §3.6 (Surface-within-mode E6 — pending in S6)
- * @see PRD-002 §S5
+ * @see ADR-019 (canonical-dark emission) · ADR-006 §3.6 (superseded parking)
+ * @see PRD-002 §S5 · docs/spikes/2026-08-13-dark-mode-real-parity.md
  */
 
 import type { FoundationLayer } from '@apollion-dsi/core/themes/foundation';
@@ -40,6 +42,24 @@ export interface VariantThemes {
   colors: ColorsThemeInterface;
 }
 
+/**
+ * Canonical dark input — the ADR-010 convention the core invariant suite calls
+ * "canonical dark": swap ONLY the contrast/deep axes (`baseLight↔baseDark`,
+ * `deepLight↔deepDark`); brand seeds stay fixed. The engine is mode-aware by
+ * construction (ADR-012 state floors, ADR-018 `onLight`, `isDarkSurface`), so
+ * every derived stop resolves correctly from the swapped seeds. See ADR-019 and
+ * `docs/spikes/2026-08-13-dark-mode-real-parity.md`.
+ */
+function toCanonicalDarkInput(input: Variant['colors']): Variant['colors'] {
+  return {
+    ...input,
+    baseDark: input.baseLight,
+    baseLight: input.baseDark,
+    deepDark: input.deepLight,
+    deepLight: input.deepDark,
+  };
+}
+
 function composeColors(input: Variant['colors']) {
   return {
     baseDark: input.baseDark,
@@ -68,7 +88,11 @@ function composeColors(input: Variant['colors']) {
  * deterministic.
  */
 export function buildVariantThemes(variant: Variant, spacingInput: SpacingInput = defaultInputSpacing): VariantThemes {
-  const themeColors = composeColors(variant.colors) as unknown as ColorsThemeInterface;
+  // ADR-019: dark stops being a placeholder — the palette derives from the
+  // canonical-dark seed swap. Emitted dark == runtime canonical dark, byte-exact
+  // (parity by composition over the Strangler Fig builders).
+  const colorsInput = variant.mode === 'dark' ? toCanonicalDarkInput(variant.colors) : variant.colors;
+  const themeColors = composeColors(colorsInput) as unknown as ColorsThemeInterface;
   const themeSpacing = createSpacing(spacingInput, variant.dimension);
   const semantic = createSemantic({ colors: themeColors as never, spacing: themeSpacing as never });