@apollion-dsi/tokens 5.5.0 → 5.7.0

package/src/ir.ts

@@ -265,6 +265,11 @@ function buildColorPrimitives(colors: ColorsThemeInterface): IRGroup {
   }
   out.grayscale = recordColorGroup(colors.grayscale);
   out.neutral = recordColorGroup(colors.neutral);
+  // ADR-023 — surface ladder roles (mode-aware grounds / inks / edges / washes).
+  out.surface = recordColorGroup(colors.surface as unknown as Record<string, string>);
+  out.ink = recordColorGroup(colors.ink as unknown as Record<string, string>);
+  out.edge = recordColorGroup(colors.edge as unknown as Record<string, string>);
+  out.wash = recordColorGroup(colors.wash as unknown as Record<string, string>);
   out.baseDark = colorToken(colors.baseDark ?? '#000000');
   out.baseLight = colorToken(colors.baseLight ?? '#ffffff');
   out.deepDark = colorToken(colors.deepDark ?? '#000000');
@@ -317,6 +322,11 @@ const BG_REF: Readonly<Record<string, string>> = {
   danger: 'color.danger.base',
   warning: 'color.warning.base',
   info: 'color.information.base',
+  canvas: 'color.surface.canvas',
+  sunken: 'color.surface.sunken',
+  paper: 'color.surface.paper',
+  raised: 'color.surface.raised',
+  overlay: 'color.surface.overlay',
 };
 
 const TEXT_REF: Readonly<Record<string, string>> = {
@@ -327,6 +337,17 @@ const TEXT_REF: Readonly<Record<string, string>> = {
   onDanger: 'color.baseLight',
   onWarning: 'color.baseDark',
   onInfo: 'color.baseLight',
+  primary: 'color.ink.primary',
+  secondary: 'color.ink.secondary',
+  muted: 'color.ink.muted',
+  disabled: 'color.ink.disabled',
+};
+
+/** Foundation `edge.*` → `color.edge.*` primitive (ADR-023 ink-alpha lines). */
+const EDGE_REF: Readonly<Record<string, string>> = {
+  hairline: 'color.edge.hairline',
+  border: 'color.edge.border',
+  strong: 'color.edge.strong',
 };
 
 /** Navigate the structural palette by IR path (`color.x.y`). */
@@ -691,6 +712,7 @@ export function buildColorIR(foundation: FoundationLayer, colors: ColorsThemeInt
       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),
+      edge: colorRefGroup(foundation.edge as unknown as Record<string, string>, colors, EDGE_REF),
       tx: buildReadableTextGroup(colors),
       shadow: buildShadow(colors),
     },
@@ -749,6 +771,7 @@ export function buildIR(foundation: FoundationLayer, colors: ColorsThemeInterfac
     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),
+      edge: colorRefGroup(foundation.edge as unknown as Record<string, string>, colors, EDGE_REF),
       tx: buildReadableTextGroup(colors),
       spacing: dimensionRefGroup(foundation.spacing as unknown as Record<string, string>, primitives, SPACE_REF),
       border: border.group,

package/src/renderers/css.ts

@@ -90,3 +90,51 @@ export function renderCss(ir: IRDocument, options: RenderCssOptions = {}): strin
 
   return lines.join('\n');
 }
+
+/** Options of {@link renderCssModes}. */
+export interface RenderCssModesOptions extends RenderCssOptions {
+  /** `<html>` attribute carrying the resolved mode (same default as the core mode engine). */
+  attribute?: string;
+}
+
+/**
+ * Mode-scoped CSS (APOLLION-DARK-MODE-ENGINE, ADR-024 — `output.cssModes`):
+ * ONE file per (brand × surface × dimension) carrying BOTH modes, scoped the
+ * way the core mode engine scopes them — `:root`/`[attr="light"]` for light,
+ * `[attr="dark"]` for dark, plus a `prefers-color-scheme` fallback for pages
+ * that never set the attribute. Consumers without React link this file and
+ * flip the mode with the attribute (`getModeScript` / `syncDocumentMode`)
+ * — the "CSS-only switch" of the docs, made real.
+ */
+export function renderCssModes(light: IRDocument, dark: IRDocument, options: RenderCssModesOptions = {}): string {
+  const { attribute = 'data-apollion-mode', rgbCompanions } = options;
+  const { brand, surface, dimension } = light.meta;
+  const lines: string[] = [HEADER_LINE, ''];
+
+  const block = (selector: string, ir: IRDocument, scheme: 'light' | 'dark'): void => {
+    lines.push(`${selector} {`, `  color-scheme: ${scheme};`);
+    emitVars(ir.groups, [], lines);
+    if (rgbCompanions) emitRgbVars(ir.groups, [], lines);
+    lines.push('}', '');
+  };
+
+  lines.push(
+    `/* Variant: brand=${brand} surface=${surface} dimension=${dimension} modes=light+dark (attribute ${attribute}) */`,
+    '',
+  );
+  block(`:root, html[${attribute}="light"]`, light, 'light');
+  block(`html[${attribute}="dark"]`, dark, 'dark');
+  lines.push('@media (prefers-color-scheme: dark) {');
+  lines.push(`  html:not([${attribute}]) {`, '    color-scheme: dark;');
+  const inner: string[] = [];
+  emitVars(dark.groups, [], inner);
+  if (rgbCompanions) emitRgbVars(dark.groups, [], inner);
+  for (const line of inner) lines.push(`  ${line}`);
+  lines.push('  }', '}', '');
+
+  lines.push('@supports (background: paint(squircle)) or (color: oklch(0% 0 0)) {');
+  emitProperties(light.groups, [], lines);
+  lines.push('}', '');
+
+  return lines.join('\n');
+}

package/src/renderers/tailwind.ts

@@ -91,13 +91,13 @@ interface ColorEntry {
 }
 
 /**
- * Colour entries for the preset's `colors` scale: the `bg`/`text`/`tx`
+ * Colour entries for the preset's `colors` scale: the `bg`/`text`/`edge`/`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 groupName of ['bg', 'text', 'edge', 'tx'] as const) {
     for (const [key, token] of flatTokens(groupAt(ir.groups, groupName), [groupName])) {
       const color = colorPayload(token);
       if (!color) continue;

package/src/theme-factory.ts

@@ -11,10 +11,11 @@
  * 5. If surface === 'negative': core `invertForSurface` applied.
  *
  * **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).
+ * the canonical-dark seed swap (`toDarkColors`, imported from the core — the
+ * single source of the swap, ADR-022) — 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.
  *
@@ -22,6 +23,7 @@
  * @see PRD-002 §S5 · docs/spikes/2026-08-13-dark-mode-real-parity.md
  */
 
+import { toDarkColors } from '@apollion-dsi/core/themes/colors';
 import type { FoundationLayer } from '@apollion-dsi/core/themes/foundation';
 import { createFoundation } from '@apollion-dsi/core/themes/foundation';
 import { createSemantic } from '@apollion-dsi/core/themes/semantic';
@@ -30,6 +32,7 @@ import { defaultInputSpacing } from '@apollion-dsi/core/themes/spacing';
 import { invertForSurface } from '@apollion-dsi/core/themes/surface';
 
 import { mountGreyscaleColors, mountNeutralColors, mountSingleColor } from './builders/colors';
+import { resolveSurfaceLadder } from './builders/ladder';
 import { createSpacing } from './builders/spacing';
 import type { Variant } from './config-schema';
 
@@ -42,33 +45,18 @@ 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']) {
+  const neutral = mountNeutralColors(input);
   return {
     baseDark: input.baseDark,
     baseLight: input.baseLight,
     deepDark: input.deepDark,
     deepLight: input.deepLight,
     transparent: input.transparent ?? 'transparent',
-    neutral: mountNeutralColors(input),
+    neutral,
     grayscale: mountGreyscaleColors(input),
+    // ADR-023 — surface ladder (mirror of core's createColors composition).
+    ...resolveSurfaceLadder({ ...input, neutral }, input.ladder),
     main: mountSingleColor(input.main!, input),
     opposite: mountSingleColor(input.opposite!, input),
     complementary: mountSingleColor(input.complementary!, input),
@@ -91,7 +79,7 @@ export function buildVariantThemes(variant: Variant, spacingInput: SpacingInput
   // 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 colorsInput = variant.mode === 'dark' ? toDarkColors(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 });

package/src/token-meta.ts

@@ -48,6 +48,15 @@ export const TOKEN_META: Readonly<Record<string, TokenMetaEntry>> = {
     deprecated: 'Use bg.information once the foundation role is renamed (tracked for S6).',
   },
 
+  // ── Surface ladder (ADR-023 — mode-aware grounds, inks, edges) ───────────
+  'bg.canvas': { description: 'Page ground — the theme canvas (never pure black in dark).' },
+  'bg.paper': { description: 'Component ground (cards, inputs, tables) — lighter than the canvas in both modes.' },
+  'bg.overlay': { description: 'Top of the elevation ladder — modal / dialog panels.' },
+  'text.primary': { description: 'Primary neutral ink — AA + APCA Lc ≥ 75 over bg.paper and bg.canvas.' },
+  'text.muted': { description: 'Muted neutral ink — AA + APCA Lc ≥ 45 over bg.paper.' },
+  'edge.border': { description: 'Default control outline — primary ink at 20 % alpha, legible on any ground.' },
+  'edge.hairline': { description: 'Dividers and card outlines — primary ink at 10 % alpha.' },
+
   // ── Foundation text-on roles ─────────────────────────────────────────────
   'text.on-primary': { description: 'Text/icon colour with guaranteed contrast over bg.primary.' },
   'text.on-danger': { description: 'Text/icon colour with guaranteed contrast over bg.danger.' },