@apollion-dsi/tokens 4.0.0

package/src/renderers/json.ts

@@ -0,0 +1,81 @@
+/**
+ * JSON renderer — emit Foundation tokens as DTCG-compliant JSON.
+ *
+ * **Spec:** [Design Tokens Community Group Format Module](https://design-tokens.github.io/community-group/format/)
+ * (W3C draft track, mid-2024).
+ *
+ * Each token is a leaf with `$value` + `$type`. Groups nest naturally:
+ * ```json
+ * { "bg": { "primary": { "$value": "#003750", "$type": "color" } } }
+ * ```
+ *
+ * Enables interop with Tokens Studio (Figma), Style Dictionary downstream,
+ * Specify, and any tool consuming the DTCG spec.
+ *
+ * @see tech-radar R1 (DTCG compliance)
+ * @see ADR-006 §3.10 + PRD-002 §S5
+ */
+
+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;
+}
+
+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;
+}
+
+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,
+      },
+    },
+  };
+  return `${JSON.stringify(doc, null, 2)}\n`;
+}

package/src/renderers/ts.ts

@@ -0,0 +1,46 @@
+/**
+ * TypeScript renderer — emit Foundation tokens as `as const` literal.
+ *
+ * **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.
+ *
+ * @see tech-radar R4
+ * @see ADR-006 §3.10 + PRD-002 §S5
+ */
+
+import type { FoundationLayer } from '@apollion-dsi/core/themes/foundation';
+
+import type { Variant } from '../config-schema';
+
+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');
+}
+
+export function renderTs(foundation: FoundationLayer, variant: Variant): string {
+  return [
+    HEADER_LINE,
+    `// Variant: brand=${variant.brand} mode=${variant.mode} surface=${variant.surface} dimension=${variant.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');
+}

package/src/runtime/v1.ts

@@ -0,0 +1,40 @@
+/**
+ * `@apollion-dsi/tokens/runtime/v1` — Versioned API surface for v4+.
+ *
+ * **Status:** S4 Strangler Fig builders (ADR-006 §6 S4).
+ *
+ * This is the ONLY public entry of `@apollion-dsi/tokens`. Bumping to `/v2`
+ * adds new exports without breaking `/v1` (versioned API decoupling per
+ * ADR-006 §3.3). Consumers import:
+ *
+ * ```ts
+ * import {
+ *   mountSingleColor, mountGreyscaleColors, mountNeutralColors, getOppositeColor,
+ *   createSpacing,
+ *   createFoundation, invertForSurface,
+ *   TOKENS_RUNTIME_API_VERSION,
+ * } from '@apollion-dsi/tokens/runtime/v1';
+ * ```
+ *
+ * **Strangler Fig:** `colors` + `spacing` builders are DUPLICATES of core's
+ * implementation (validated bit-equivalent via parity tests). `foundation`
+ * + `surface` are re-exports from core via stable subpaths. Both classes
+ * coexist orthogonally — core remains SSOT until PRD-003 post-v4
+ * consolidation.
+ *
+ * @see ADR-006 §3.3 (versioned API + decoupling B2 mitigation)
+ * @see ADR-006 §6 S1 + §6 S4
+ * @see PRD-002 §S4
+ */
+
+export const TOKENS_RUNTIME_API_VERSION = 'v1' as const;
+
+// Strangler Fig duplicates (full implementation in tokens)
+export { getOppositeColor, mountGreyscaleColors, mountNeutralColors, mountSingleColor } from '../builders/colors';
+export { createSpacing } from '../builders/spacing';
+
+// Interim re-exports from core (consolidated in PRD-003 if needed)
+export { createFoundation } from '../builders/foundation';
+export type { FoundationLayer } from '../builders/foundation';
+export { invertForSurface } from '../builders/surface';
+export type { SurfaceMode } from '../builders/surface';

package/src/theme-factory.ts

@@ -0,0 +1,80 @@
+/**
+ * Build a `FoundationLayer` for a given `Variant` — the unit consumed by
+ * all renderers (CSS, JSON, TS).
+ *
+ * Pipeline:
+ * 1. Tokens builders → ColorsThemeInterface (OKLch lerp via culori).
+ * 2. Tokens builders → SpacingThemeInterface (Dimension override applied).
+ * 3. Core `createSemantic` (re-exported via tokens/builders/foundation
+ *    indirectly).
+ * 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.
+ *
+ * @see ADR-006 §3.6 (Surface-within-mode E6 — pending in S6)
+ * @see PRD-002 §S5
+ */
+
+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';
+import type { SpacingInput } from '@apollion-dsi/core/themes/spacing';
+import { defaultInputSpacing } from '@apollion-dsi/core/themes/spacing';
+import { invertForSurface } from '@apollion-dsi/core/themes/surface';
+
+import { mountGreyscaleColors, mountNeutralColors, mountSingleColor } from './builders/colors';
+import { createSpacing } from './builders/spacing';
+import type { Variant } from './config-schema';
+
+type ColorsThemeInterface = ReturnType<typeof composeColors>;
+
+function composeColors(input: Variant['colors']) {
+  return {
+    baseDark: input.baseDark,
+    baseLight: input.baseLight,
+    deepDark: input.deepDark,
+    deepLight: input.deepLight,
+    transparent: input.transparent ?? 'transparent',
+    neutral: mountNeutralColors(input),
+    grayscale: mountGreyscaleColors(input),
+    main: mountSingleColor(input.main!, input),
+    opposite: mountSingleColor(input.opposite!, input),
+    complementary: mountSingleColor(input.complementary!, input),
+    danger: mountSingleColor(input.danger!, input),
+    information: mountSingleColor(input.information!, input),
+    success: mountSingleColor(input.success!, input),
+    warning: mountSingleColor(input.warning!, input),
+    primary: mountSingleColor(input.primary!, input),
+    secondary: mountSingleColor(input.secondary!, input),
+    tertiary: mountSingleColor(input.tertiary!, input),
+  };
+}
+
+/**
+ * Build the Foundation layer for one variant. Pure function, deterministic.
+ */
+export function buildFoundationForVariant(
+  variant: Variant,
+  spacingInput: SpacingInput = defaultInputSpacing,
+): FoundationLayer {
+  const themeColors = composeColors(variant.colors) as unknown as ColorsThemeInterface;
+  const themeSpacing = createSpacing(spacingInput, variant.dimension);
+  const semantic = createSemantic({ colors: themeColors as never, spacing: themeSpacing as never });
+
+  const baseFoundation = createFoundation(semantic);
+
+  if (variant.surface === 'negative') {
+    // invertForSurface acts on the full Theme — assemble a minimal shim.
+    // S6 will refactor to accept (semantic, surface) directly.
+    const fullTheme = { semantic, colors: themeColors as never } as never;
+    const inverted = invertForSurface(fullTheme, 'negative');
+    return createFoundation(inverted.semantic);
+  }
+
+  return baseFoundation;
+}