@apollion-dsi/tokens 7.3.0 → 7.5.0

package/src/ir.ts

@@ -36,10 +36,11 @@ import { createFont, 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 { DEFAULT_TEXT_SIZE, type TextSize } from '@apollion-dsi/core/themes/text-size';
 import { converter, formatHex, parse } from 'culori';
 
 import { breakpointEntries } from './builders/breakpoints';
-import { containerSizeEntries, layoutEntries } from './builders/layout';
+import { containerSizeEntries, layoutEntries, zIndexEntries } from './builders/layout';
 import {
   motionDurationEntries,
   motionEasingEntries,
@@ -518,14 +519,14 @@ function buildBorder(primitives: IRGroup): { group: IRGroup; extensions: Record<
  * Font scales: family/size/weight/lineHeight as DTCG types; non-DTCG bits
  * (letterSpacing/textTransform/fontStyle) go to `$extensions`.
  *
- * **ADR-011:** `size` is now density-aware. Built with the SAME `dimension` the
- * variant uses (`createFont`), so a `font.size.*` token emits the resolved `rem`
- * value for that density (e.g. `medium = 1.25rem` at normal, `1rem` at compact),
- * mirroring `buildSpacePrimitives`. `family/weight/lineHeight` stay axis-invariant
- * — they're identical across dimensions, just carried in each font set.
+ * **ADR-030:** `size` follows the `textSize` axis (independent of `dimension`),
+ * built with core's `createFont`, so a `font.size.*` token emits the resolved
+ * `rem` value for that level (e.g. `medium = 1.25rem` at md, `1.5625rem` at xl).
+ * `family/weight/lineHeight` stay axis-invariant — identical across levels, just
+ * carried in each font set.
  */
-function buildFont(dimension: Dimension): { group: IRGroup; extensions: Record<string, unknown> } {
-  const resolved = createFont(defaultInputFont, dimension);
+function buildFont(textSize: TextSize): { group: IRGroup; extensions: Record<string, unknown> } {
+  const resolved = createFont(defaultInputFont, { textSize });
   const family: Record<string, IRToken> = {};
   for (const [key, value] of Object.entries(defaultInputFont.fontFamily)) {
     const clean = value.replace(/;\s*$/, '').trim();
@@ -656,7 +657,7 @@ function decorateMeta(doc: IRDocument): IRDocument {
 // - base    → border (+ `border-width.*` it references)          [axis-invariant]
 // - color   → `color.*` primitives + bg/text (refs) + shadow     [brand×mode×surface]
 // - spacing → `space.*` primitives + spacing (refs)              [dimension]
-// - font    → font scale (size density-aware, ADR-011)           [dimension]
+// - font    → font scale (size per text-size level, ADR-030)      [textSize]
 // `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).
 // ───────────────────────────────────────────────────────────────────────────
@@ -731,6 +732,20 @@ function buildLayoutConstants(): IRGroup {
   return out;
 }
 
+/**
+ * Cross-component `z-index` stacking scale (APOLLION-ZINDEX-TOKENS, plan §5)
+ * — axis-invariant mirror of `theme.zIndex`. `number` tokens, not
+ * `dimension`: `z-index` is unitless by spec, the same shape `lineHeight`
+ * uses elsewhere in this file.
+ */
+function buildZIndex(): IRGroup {
+  const out: Record<string, IRToken> = {};
+  for (const [key, value] of zIndexEntries()) {
+    out[key] = { type: 'number', value: { kind: 'number', raw: `${value}`, number: value } };
+  }
+  return out;
+}
+
 /**
  * Motion scales (ADR-027) — axis-invariant mirror of `theme.motion` via the
  * Strangler Fig builder. Tier-1 `duration`/`easing` primitives, the
@@ -799,9 +814,9 @@ const BREAKPOINT_EXTENSION = {
  * 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}),
- * symmetric with spacing.
+ * **ADR-011 / ADR-030:** font is not in the base set — its `size` scale varies
+ * on the `textSize` axis, so it lives in per-level `font.<textSize>` sets
+ * ({@link buildFontIR}).
  */
 export function buildBaseIR(): IRSlice {
   const borderWidth = buildBorderWidthPrimitives();
@@ -821,6 +836,7 @@ export function buildBaseIR(): IRSlice {
       breakpoint: buildBreakpoints(),
       'container-size': buildContainerSizes(),
       layout: buildLayoutConstants(),
+      'z-index': buildZIndex(),
       motion: buildMotion(),
     },
     seen,
@@ -829,13 +845,13 @@ export function buildBaseIR(): IRSlice {
 }
 
 /**
- * Font slice for one dimension: the typographic scale built with that dimension's
- * multiplier (ADR-011). Mirrors {@link buildSpacingIR} — font joined the density
- * axis, so it is no longer part of the axis-invariant base set. The non-DTCG bits
- * (letterSpacing/textTransform/fontStyle) ride along in `$extensions`.
+ * Font slice for one text-size level (ADR-030): the typographic scale built with
+ * that level's ratio. Independent of `dimension` — density drives spacing only.
+ * The non-DTCG bits (letterSpacing/textTransform/fontStyle) ride along in
+ * `$extensions`.
  */
-export function buildFontIR(dimension: Dimension): IRSlice {
-  const font = buildFont(dimension);
+export function buildFontIR(textSize: TextSize): IRSlice {
+  const font = buildFont(textSize);
   const seen = new Set<string>();
   const groups = decorateSlice({ font: font.group }, seen);
   return { groups, extensions: { 'com.apollion.font': font.extensions } };
@@ -900,7 +916,9 @@ export function buildIR(foundation: FoundationLayer, colors: ColorsThemeInterfac
   };
   const primitives = buildPrimitives(colors, variant.dimension);
   const border = buildBorder(primitives);
-  const font = buildFont(variant.dimension);
+  // Per-variant documents (CSS/TS) carry the default `default` scale; the other
+  // levels ship in `font.<textSize>` sets and `css/font.css` (ADR-030).
+  const font = buildFont(DEFAULT_TEXT_SIZE);
 
   const extensions: Record<string, unknown> = {
     'com.apollion.variant': meta,
@@ -925,6 +943,7 @@ export function buildIR(foundation: FoundationLayer, colors: ColorsThemeInterfac
       breakpoint: buildBreakpoints(),
       'container-size': buildContainerSizes(),
       layout: buildLayoutConstants(),
+      'z-index': buildZIndex(),
       motion: buildMotion(),
       font: font.group,
       shadow: buildShadow(colors),

package/src/renderers/css.ts

@@ -13,9 +13,11 @@
  * @see ../ir.ts (source of truth) · ADR-006 §3.3 + §3.10 · tech-radar R3
  */
 
+import { DEFAULT_TEXT_SIZE, TEXT_SIZE_ATTRIBUTE } from '@apollion-dsi/core/themes/text-size';
+
 import { colorPayload, isOpaqueColor, rgbTriplet } from './tailwind';
 
-import type { IRDocument, IRGroup } from '../ir';
+import type { IRDocument, IRGroup, IRSlice } from '../ir';
 import { isToken, kebab, rawValue } from '../ir';
 
 const HEADER_LINE = '/* Generated by apollion-tokens build — DO NOT EDIT. See apollion.config.mjs. */';
@@ -138,3 +140,58 @@ export function renderCssModes(light: IRDocument, dark: IRDocument, options: Ren
 
   return lines.join('\n');
 }
+
+/** Options of {@link renderCssTextSize}. */
+export interface RenderCssTextSizeOptions {
+  /**
+   * Attribute carrying the active level, on `<html>` or any subtree root —
+   * core's `TEXT_SIZE_ATTRIBUTE`, the one `ApollionProvider` writes.
+   *
+   * @default 'data-apollion-text-size'
+   */
+  attribute?: string;
+  /**
+   * Level emitted on the bare `:root` block.
+   *
+   * @default 'default'
+   */
+  defaultLevel?: string;
+}
+
+/**
+ * `css/font.css` — the text-size axis (ADR-030) as CSS custom properties.
+ *
+ * Only `--apollion-font-size-*` vary between levels (family/weight/line-height
+ * are level-invariant and already live in the per-variant files). The default
+ * level sits on `:root`; every level also gets
+ * `:root[attr="<level>"], [attr="<level>"]`: the `:root[…]` form (specificity
+ * 0,2,0) beats the plain `:root` block of a per-variant file regardless of load
+ * order, and the bare `[…]` form rescales a subtree. Switch at runtime by
+ * setting the attribute — no rebuild, no reload.
+ */
+export function renderCssTextSize(
+  levels: ReadonlyArray<readonly [string, IRSlice]>,
+  options: RenderCssTextSizeOptions = {},
+): string {
+  const { attribute = TEXT_SIZE_ATTRIBUTE, defaultLevel = DEFAULT_TEXT_SIZE } = options;
+  const lines: string[] = [HEADER_LINE, ''];
+  lines.push(
+    `/* Text size (ADR-030): levels=${levels.map(([level]) => level).join('+')} default=${defaultLevel} (attribute ${attribute}) */`,
+    '',
+  );
+
+  const block = (selector: string, slice: IRSlice): void => {
+    lines.push(`${selector} {`);
+    const font = slice.groups.font as IRGroup;
+    emitVars(font.size as IRGroup, ['font', 'size'], lines);
+    lines.push('}', '');
+  };
+
+  const fallback = levels.find(([level]) => level === defaultLevel);
+  if (fallback) block(':root', fallback[1]);
+  for (const [level, slice] of levels) {
+    block(`:root[${attribute}="${level}"],\n[${attribute}="${level}"]`, slice);
+  }
+
+  return lines.join('\n');
+}

package/src/renderers/resolver.ts

@@ -7,8 +7,8 @@
  * 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 + 2·dimension + 1) sets (spacing + font per
- * dimension).
+ * manifest + O(brand·mode·surface + dimension + textSize + 1) sets (spacing per
+ * dimension, font per text-size level — ADR-030).
  *
  * **Mode modifier:** `mode` is emitted as a real modifier (values + default),
  * and since ADR-019 the dark contexts carry real values — palette generation
@@ -23,11 +23,13 @@
  * @see https://www.designtokens.org/TR/ (Resolver draft)
  */
 
+import { DEFAULT_TEXT_SIZE } from '@apollion-dsi/core/themes/text-size';
+
 import { projectGroup } from './dtcg-project';
 
 import type { ApollionConfig } from '../config-schema';
 import type { IRSlice } from '../ir';
-import type { SetPlan } from '../set-plan';
+import type { FontSetPlan, SetPlan } from '../set-plan';
 
 /** A DTCG modifier: an enumerated axis with a default value. */
 interface ResolverModifier {
@@ -51,10 +53,15 @@ interface ResolverManifest {
 }
 
 /** Render one IR slice (base/color/spacing) to a DTCG set JSON document. */
-function renderSet(slice: IRSlice, description: string): string {
+function renderSet(slice: IRSlice, description: string, deprecated?: string): string {
+  const groups = projectGroup(slice.groups) as Record<string, Record<string, unknown>>;
+  // DTCG `$deprecated` on each top-level group, so DTCG-only tooling sees it too.
+  if (deprecated) {
+    for (const key of Object.keys(groups)) groups[key] = { $deprecated: deprecated, ...groups[key] };
+  }
   const doc: Record<string, unknown> = {
     $description: description,
-    ...projectGroup(slice.groups),
+    ...groups,
   };
   if (Object.keys(slice.extensions).length > 0) doc.$extensions = slice.extensions;
   return `${JSON.stringify(doc, null, 2)}\n`;
@@ -78,16 +85,24 @@ export function renderSpacingSet(slice: IRSlice, dimension: string): string {
   return renderSet(slice, `Apollion DS — spacing set. dimension=${dimension}. DTCG 2025.10.`);
 }
 
-/** Font set for one dimension (size density-aware, ADR-011). */
-export function renderFontSet(slice: IRSlice, dimension: string): string {
-  return renderSet(slice, `Apollion DS — font set. dimension=${dimension}. DTCG 2025.10.`);
+/** Font set for one text-size level (ADR-030), or a deprecated `font.<dimension>` alias. */
+export function renderFontSet(slice: IRSlice, set: Pick<FontSetPlan, 'textSize' | 'deprecatedDimension'>): string {
+  if (set.deprecatedDimension) {
+    return renderSet(
+      slice,
+      `Apollion DS — font set. DEPRECATED alias of font.${set.textSize} (dimension=${set.deprecatedDimension} no longer scales type, ADR-030; removed at the next major). DTCG 2025.10.`,
+      `Alias of font.${set.textSize} — dimension no longer scales type (ADR-030). Use font.<textSize>.`,
+    );
+  }
+  return renderSet(slice, `Apollion DS — font set. textSize=${set.textSize}. 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.
+ * Modifiers enumerate the five axes (brand/mode/surface/dimension/textSize)
+ * with the first encountered value as `default` (`textSize` always defaults to
+ * `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
@@ -101,7 +116,14 @@ export function renderResolver(config: ApollionConfig, plan: SetPlan): string {
     { 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] },
+    {
+      name: 'textSize',
+      values: [...modifiers.textSize],
+      // `resolveTextSizes` guarantees `default` is present.
+      default: DEFAULT_TEXT_SIZE,
+    },
   ];
+  const deprecatedFontSets = plan.font.filter((f) => f.deprecatedDimension);
 
   const sets: ResolverSet[] = [
     { name: plan.base.name, source: plan.base.file },
@@ -114,8 +136,8 @@ export function renderResolver(config: ApollionConfig, plan: SetPlan): string {
     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 + font sets ' +
-      'for the chosen dimension. NOTE: mode is a topology placeholder in this ' +
+      'colour set for the chosen brand/mode/surface, the spacing set for the chosen ' +
+      'dimension and the font set for the chosen textSize. NOTE: mode is a topology placeholder in this ' +
       'release (dark resolves identically to light until S6).',
     sets,
     modifiers: modifierList,
@@ -129,10 +151,13 @@ export function renderResolver(config: ApollionConfig, plan: SetPlan): string {
             color: '${brand}.color.${mode}.${surface}',
             // spacing set name = `spacing.<dimension>`
             spacing: 'spacing.${dimension}',
-            // font set name = `font.<dimension>` (size density-aware, ADR-011)
-            font: 'font.${dimension}',
+            // font set name = `font.<textSize>` (ADR-030 — independent of dimension)
+            font: 'font.${textSize}',
           },
         },
+        // `font.<dimension>` sets still ship as aliases of `font.default` (ADR-030
+        // compatibility); removed at the next major.
+        deprecatedSets: Object.fromEntries(deprecatedFontSets.map((f) => [f.name, `font.${f.textSize}`])),
         modeIsPlaceholder: true,
       },
     },

package/src/set-plan.ts

@@ -9,7 +9,9 @@
  * **Set topology** (each set is reference-closed, see `ir.ts` slices):
  * - `base` — 1 file, axis-invariant (border).
  * - `spacing.<dimension>` — one per dimension.
- * - `font.<dimension>` — one per dimension (size density-aware, ADR-011).
+ * - `font.<textSize>` — one per text-size level (ADR-030).
+ * - `font.<dimension>` — DEPRECATED aliases of `font.default` (same content), kept so
+ *   pinned set paths still resolve after ADR-030; removed at the next major.
  * - `<brand>.color.<mode>.<surface>` — one per (brand × mode × surface).
  *
  * @see ir.ts (`buildBaseIR` / `buildColorIR` / `buildSpacingIR` / `buildFontIR`)
@@ -17,9 +19,10 @@
  */
 
 import type { Dimension } from '@apollion-dsi/core/themes/dimension';
+import { DEFAULT_TEXT_SIZE, type TextSize } from '@apollion-dsi/core/themes/text-size';
 
 import type { ApollionConfig, Mode, Surface } from './config-schema';
-import { expandVariants } from './config-schema';
+import { expandVariants, resolveTextSizes } from './config-schema';
 
 /** Directory (relative to dist root) holding the emitted set files. */
 export const SETS_DIR = 'json/sets';
@@ -44,12 +47,17 @@ export interface SpacingSetPlan {
   readonly dimension: Dimension;
 }
 
-/** A font set keyed by its dimension (size density-aware, ADR-011). */
+/** A font set keyed by its text-size level (ADR-030). */
 export interface FontSetPlan {
   readonly kind: 'font';
   readonly name: string;
   readonly file: string;
-  readonly dimension: Dimension;
+  readonly textSize: TextSize;
+  /**
+   * Set only on the deprecated `font.<dimension>` aliases: the dimension the
+   * legacy name carried. Content is `font.default` — dimension no longer scales type.
+   */
+  readonly deprecatedDimension?: Dimension;
 }
 
 /** The axis-invariant base set. */
@@ -70,6 +78,7 @@ export interface SetPlan {
     readonly mode: readonly Mode[];
     readonly surface: readonly Surface[];
     readonly dimension: readonly Dimension[];
+    readonly textSize: readonly TextSize[];
   };
 }
 
@@ -88,8 +97,13 @@ export function spacingSetName(dimension: Dimension): string {
   return `spacing.${dimension}`;
 }
 
-/** Stable font-set name for a dimension: `font.<dimension>`. */
-export function fontSetName(dimension: Dimension): string {
+/** Stable font-set name for a text-size level: `font.<textSize>`. */
+export function fontSetName(textSize: TextSize): string {
+  return `font.${textSize}`;
+}
+
+/** @deprecated Legacy per-dimension font-set name (`font.<dimension>`, alias of `font.default`). */
+export function legacyFontSetName(dimension: Dimension): string {
   return `font.${dimension}`;
 }
 
@@ -115,8 +129,11 @@ export function planSets(config: ApollionConfig): SetPlan {
   const color: ColorSetPlan[] = [];
   const spacingSeen = new Set<string>();
   const spacing: SpacingSetPlan[] = [];
-  const fontSeen = new Set<string>();
-  const font: FontSetPlan[] = [];
+  const textSizes = [...resolveTextSizes(config)];
+  const font: FontSetPlan[] = textSizes.map((textSize) => {
+    const name = fontSetName(textSize);
+    return { kind: 'font', name, file: setFile(name), textSize };
+  });
 
   for (const v of variants) {
     pushUnique(brands, v.brand);
@@ -142,12 +159,19 @@ export function planSets(config: ApollionConfig): SetPlan {
       spacingSeen.add(sName);
       spacing.push({ kind: 'spacing', name: sName, file: setFile(sName), dimension: v.dimension });
     }
+  }
 
-    const fName = fontSetName(v.dimension);
-    if (!fontSeen.has(fName)) {
-      fontSeen.add(fName);
-      font.push({ kind: 'font', name: fName, file: setFile(fName), dimension: v.dimension });
-    }
+  // Deprecated `font.<dimension>` aliases (ADR-030 compatibility, removed at the
+  // next major): same content as `font.default`, after the real sets.
+  for (const dimension of dimensions) {
+    const name = legacyFontSetName(dimension);
+    font.push({
+      kind: 'font',
+      name,
+      file: setFile(name),
+      textSize: DEFAULT_TEXT_SIZE,
+      deprecatedDimension: dimension,
+    });
   }
 
   return {
@@ -155,6 +179,6 @@ export function planSets(config: ApollionConfig): SetPlan {
     spacing,
     font,
     color,
-    modifiers: { brand: brands, mode: modes, surface: surfaces, dimension: dimensions },
+    modifiers: { brand: brands, mode: modes, surface: surfaces, dimension: dimensions, textSize: textSizes },
   };
 }