@apollion-dsi/tokens 5.6.0 → 5.8.0

package/src/builders/layout.ts

@@ -0,0 +1,24 @@
+/**
+ * Layout builder — **Strangler Fig duplicate** of
+ * `@apollion-dsi/core/themes/layout` (ADR-025 invariant 5).
+ *
+ * Mirrors the container-size scale (the `cq` channel thresholds — px, slot
+ * widths, NOT viewport breakpoints) and the page-layout constants
+ * (`pageMaxWidth`). Axis-invariant.
+ *
+ * @see ./colors.ts (Strangler Fig contract notes)
+ */
+import type { ContainerSizesInput, LayoutInput } from '@apollion-dsi/core/themes/layout';
+import { defaultInputContainerSizes, defaultInputLayout } from '@apollion-dsi/core/themes/layout';
+
+/** Resolved `[key, '<value>px']` pairs of the container-size scale, ascending. */
+export function containerSizeEntries(
+  input: ContainerSizesInput = defaultInputContainerSizes,
+): ReadonlyArray<readonly [string, string]> {
+  return Object.entries(input.values).map(([key, value]) => [key, `${value}px`] as const);
+}
+
+/** Resolved `[key, '<value>px']` pairs of the page-layout constants. */
+export function layoutEntries(input: LayoutInput = defaultInputLayout): ReadonlyArray<readonly [string, string]> {
+  return [['page-max-width', `${input.pageMaxWidth}px`] as const];
+}

package/src/config-schema-runtime.ts

@@ -59,6 +59,7 @@ export const ApollionConfigSchema = z
         ts: z.boolean().optional(),
         designMd: z.boolean().optional(),
         tailwind: z.boolean().optional(),
+        cssModes: z.boolean().optional(),
       })
       .passthrough()
       .optional(),

package/src/config-schema.ts

@@ -45,6 +45,11 @@ export interface ApollionOutputFlags {
    * channel-triplet companion vars to `dist/css/` so opaque colour tokens
    * support Tailwind's alpha modifier. See `renderers/tailwind.ts`. */
   tailwind?: boolean;
+  /** `dist/css/<brand>.<surface>.<dimension>.modes.css` — both modes in ONE file,
+   * scoped by `html[data-apollion-mode]` (+ `prefers-color-scheme` fallback) the
+   * way the core mode engine scopes them (ADR-024). Requires `modes` to include
+   * both `light` and `dark`. See `renderers/css.ts` (`renderCssModes`). */
+  cssModes?: boolean;
 }
 
 export interface ApollionConfig {

package/src/ir.ts

@@ -38,6 +38,8 @@ import type { SpacingAlias } from '@apollion-dsi/core/themes/spacing';
 import { defaultInputSpacing } from '@apollion-dsi/core/themes/spacing';
 import { converter, formatHex, parse } from 'culori';
 
+import { breakpointEntries } from './builders/breakpoints';
+import { containerSizeEntries, layoutEntries } from './builders/layout';
 import { createSpacing } from './builders/spacing';
 import type { Variant } from './config-schema';
 import type { ColorsThemeInterface } from './theme-factory';
@@ -265,6 +267,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 +324,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 +339,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`). */
@@ -640,10 +663,52 @@ export function assertSlicesMetaComplete(slices: readonly IRSlice[]): void {
 }
 
 /**
- * Axis-invariant base slice: border (radius/width/style). `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.
+ * Viewport breakpoint scale (APOLLION-BREAKPOINT-TOKENS) — axis-invariant,
+ * px by contract, half-open `[value, next)` bands over `min-width` sets.
+ * Values mirror `@apollion-dsi/core/themes/breakpoints` via the Strangler Fig
+ * builder; the parity suite pins the mirror.
+ *
+ * CSS emission (`--apollion-breakpoint-*`) is **informational only**: `var()`
+ * is invalid inside a `@media` prelude, so those custom properties serve JS
+ * `getComputedStyle` readers, never media queries. Query-capable surfaces are
+ * the TS record and the Tailwind `screens` scale (literal px).
+ */
+function buildBreakpoints(): IRGroup {
+  const out: Record<string, IRToken> = {};
+  for (const [key, px] of breakpointEntries()) out[key] = { type: 'dimension', value: toDimensionValue(px) };
+  return out;
+}
+
+/**
+ * Container-size scale + page-layout constants (ADR-025 invariant 5) —
+ * axis-invariant mirrors of `theme.containerSizes` / `theme.layout`.
+ * `container-size.*` are the `cq` channel thresholds (slot widths, a
+ * deliberately separate scale from `breakpoint.*`).
+ */
+function buildContainerSizes(): IRGroup {
+  const out: Record<string, IRToken> = {};
+  for (const [key, px] of containerSizeEntries()) out[key] = { type: 'dimension', value: toDimensionValue(px) };
+  return out;
+}
+
+function buildLayoutConstants(): IRGroup {
+  const out: Record<string, IRToken> = {};
+  for (const [key, px] of layoutEntries()) out[key] = { type: 'dimension', value: toDimensionValue(px) };
+  return out;
+}
+
+/** `$extensions` payload documenting the breakpoint interval contract. */
+const BREAKPOINT_EXTENSION = {
+  unit: 'px',
+  interval: 'half-open [value, next) — min-width sets, ascending',
+  cssVarsUsage: 'informational only — var() is invalid inside a @media prelude',
+} as const;
+
+/**
+ * Axis-invariant base slice: border (radius/width/style) + the viewport
+ * `breakpoint.*` scale. `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.
  *
  * **ADR-011:** font left the base set — its `size` scale is now density-aware,
  * so it lives in per-dimension `font.<dimension>` sets ({@link buildFontIR}),
@@ -654,13 +719,22 @@ export function buildBaseIR(): IRSlice {
   const primitives: IRGroup = { borderWidth };
   const border = buildBorder(primitives);
 
-  const extensions: Record<string, unknown> = {};
+  const extensions: Record<string, unknown> = { 'com.apollion.breakpoint': BREAKPOINT_EXTENSION };
   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 }, seen);
+  const groups = decorateSlice(
+    {
+      'border-width': borderWidth,
+      border: border.group,
+      breakpoint: buildBreakpoints(),
+      'container-size': buildContainerSizes(),
+      layout: buildLayoutConstants(),
+    },
+    seen,
+  );
   return { groups, extensions };
 }
 
@@ -691,6 +765,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),
     },
@@ -737,7 +812,11 @@ export function buildIR(foundation: FoundationLayer, colors: ColorsThemeInterfac
   const border = buildBorder(primitives);
   const font = buildFont(variant.dimension);
 
-  const extensions: Record<string, unknown> = { 'com.apollion.variant': meta, 'com.apollion.font': font.extensions };
+  const extensions: Record<string, unknown> = {
+    'com.apollion.variant': meta,
+    'com.apollion.font': font.extensions,
+    'com.apollion.breakpoint': BREAKPOINT_EXTENSION,
+  };
   if (Object.keys(border.extensions).length > 0) {
     extensions['com.apollion.border'] = { radius: border.extensions };
   }
@@ -749,9 +828,13 @@ 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,
+      breakpoint: buildBreakpoints(),
+      'container-size': buildContainerSizes(),
+      layout: buildLayoutConstants(),
       font: font.group,
       shadow: buildShadow(colors),
     },

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

@@ -30,7 +30,7 @@
 import { converter, parse } from 'culori';
 
 import type { IRColorValue, IRDocument, IRGroup, IRToken } from '../ir';
-import { isToken, kebab } from '../ir';
+import { isToken, kebab, rawValue } from '../ir';
 
 const toRgb = converter('rgb');
 
@@ -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;
@@ -145,6 +145,17 @@ export function renderTailwindPreset(ir: IRDocument): string {
   }
   out.push('      },');
 
+  // `screens` takes LITERAL px, never `var()` — custom properties are invalid
+  // inside a `@media` prelude. `xs` (0) is the unprefixed base band, omitted by
+  // Tailwind convention. APOLLION-BREAKPOINT-TOKENS.
+  pushScale(
+    out,
+    'screens',
+    [...flatTokens(groupAt(ir.groups, 'breakpoint'))]
+      .filter(([key]) => key !== 'xs')
+      .map(([key, token]) => [key, rawValue(token.value)] as const),
+  );
+
   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']));

package/src/theme-factory.ts

@@ -32,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';
 
@@ -45,14 +46,17 @@ export interface VariantThemes {
 }
 
 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),

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.' },