@apollion-dsi/tokens 4.2.0 → 4.3.0

package/CHANGELOG.md

@@ -0,0 +1,112 @@
+# @apollion-dsi/tokens
+
+## 4.3.0
+
+## 4.2.0
+
+### Minor Changes
+
+- 12ae4e0: feat(tokens): DTCG 2025.10 remainders — dimension references, per-token metadata, and Resolver (R5)
+  - **Spacing + composite sub-value references**: `spacing` and `border.width`
+    now reference primitive scales (`{space.*}`, `{border-width.*}`) instead of
+    inlining literals. The `space` primitives are built per density via
+    `createSpacing`, so references resolve correctly under compact/normal/spacious.
+  - **`$deprecated` + `$description` per token**: populated from a `TOKEN_META`
+    registry through the IR into the JSON output (a stale-key guard fails the
+    build if a meta entry points at a non-existent token).
+  - **DTCG Resolver (R5)**: the JSON surface now emits a single `resolver.json`
+    plus composable `sets/` (axis-invariant `base` + per-axis colour/spacing sets)
+    instead of one fully-resolved document per variant — a hard cutover, made
+    pre-GA. A composition-equivalence test proves `base + colour + spacing`
+    reproduces the old per-variant document exactly. The CSS and TS surfaces are
+    unchanged: still per-variant, fully resolved, byte-identical.
+
+## 4.1.0
+
+### Minor Changes
+
+- 063e0e9: Align `@apollion-dsi/tokens` DTCG output with the Design Tokens Format Module 2025.10.
+  - **Structured values:** `color` `$value` is now an OKLch object `{ colorSpace, components, hex, alpha? }` and `dimension` is `{ value, unit }` (was bare hex / length strings).
+  - **Typed IR:** a single intermediate representation (`src/ir.ts`) drives the JSON/CSS/TS renderers as pure projections.
+  - **Reference graph:** JSON emits a `color` primitives layer (structural SSOT) and foundation `bg`/`text` colours reference it via DTCG aliases (`{color.primary.base}`), with inline fallback when a resolved value diverges (e.g. surface inversion).
+  - **Composite tokens:** `border` (dimension / strokeStyle), `typography` (fontFamily / fontWeight / number + dimension) and `shadow` (DTCG shadow composite) now ship; values DTCG cannot model (em `letterSpacing`, `textTransform`, `fontStyle`, `100%` radius) travel in `$extensions` under `com.apollion.*`.
+
+  `@apollion-dsi/core` now exports the `themes/{border,depth,font}` subpaths so tokens consumes them as the single source of truth.
+
+  CSS/TS outputs for the existing `bg`/`text`/`spacing` layers are byte-identical; JSON is the spec-interop surface.
+
+## 4.0.0
+
+### Major Changes
+
+- bd7d6cb: # v4.0.0 — OKLch + Dimension + Token Split
+
+  The v4 epic per [ADR-006](../packages/core/docs/adr/ADR-006-v4-oklch-dimension-token-split.md) + [PRD-002](../packages/core/docs/prd/PRD-002-v4-epic-execution.md). DS-from-scratch (Q-G grilling 2026-05-24); no consumer migration. Greenfield adoption via [MIGRATION-v4.md](../packages/core/docs/migration/MIGRATION-v4.md).
+
+  ## Breaking — `@apollion-dsi/core@4.0.0`
+  - **Root barrel removed.** `import { Button } from '@apollion-dsi/core'` no longer works. Use granular subpaths (`@apollion-dsi/core/elements/button`). ESLint rule flips warn → error. ADR-001 Slice 6 finalized here. ADR-006 §3.7 E7.
+  - **OKLch palette derivation.** All `mount*Colors` helpers + `getOppositeColor` migrated from `color@5` RGB lerp to `culori@4` OKLch lerp. Validated by `spike/culori-oklch-lerp-parity` (0 unexpected regressions; greyscale 19× more uniform in OKLAB L). ADR-006 §2 B1 + §6 S2.
+  - **`defaultInputColors.opposite` token value changed.** OKLch hue rotation differs from HSL rotation (the OKLch is the perceptually correct opposite). Audit `theme.colors.opposite.*` consumers.
+  - **Dimension axis added.** `<ApollionProvider dimension="compact|normal|spacious">` is a new prop; default `normal` preserves v3.x spacing byte-exact. ADR-006 §6 S3.
+  - **`vendors/Color` eliminated.** Internal `color@5` vendor deleted (zero call-sites after S6 migration). `color` + `@types/color` removed from `package.json#dependencies`. WCAG functions migrated to `culori.wcagContrast` + `culori.wcagLuminance` (100% bit-exact parity per `spike/culori-wcag-parity`).
+  - **`invertForSurface(theme, surface, mode)` 3-arg signature.** `mode` is additive optional — existing 2-arg calls continue to work; `mode` is a placeholder for future PRD-003 mode-aware inversion. ADR-006 §6 S6.
+
+  ## Minor — `@apollion-dsi/eslint-config`
+  - `culori` + `zod` added to `VENDORED_V4_LIBS` — must import via `vendors/Culori|Zod`.
+  - `color` removed from `VENDORED_T2_LIBS` (eliminated).
+  - `no-restricted-imports` for `'@apollion-dsi/core'` root: `warn` → `error` (per v4 barrel removal above).
+
+  ## Major — `@apollion-dsi/tokens@4.0.0` (first release)
+
+  New package — framework-agnostic design tokens consumed via `runtime/v1` versioned API + `apollion-tokens build` CLI.
+  - **Strangler Fig builders** duplicated from core (`colors.ts`, `spacing.ts`); Foundation + Surface re-exported. Parity enforced by `__tests__/parity.test.ts`. ADR-006 §3.1 + §6 S4.
+  - **Atomic + idempotent build CLI.** `apollion-tokens build [--check] [--verbose] --config <path> [--out <dir>]`. Emits `dist/{css,json,ts}/*` + `dist/manifest.json` with sha256 audit trail. Rerun byte-identical. `--check` mode for CI gate. ADR-006 §3.5 + §6 S5.
+  - **DTCG-compliant JSON output** (tech-radar R1).
+  - **`as const` TypeScript output** (tech-radar R4).
+  - **CSS `@property` declarations** (tech-radar R3) + custom properties `--apollion-{layer}-{role}-{variant}`.
+  - **Sandboxed `apollion.config.mjs` loader** (`node:vm` + zod schema) — threat-model T2+E1 mitigation. ADR-006 §3.8 B3 + §6 S6.
+  - **Lockstep version** with `@apollion-dsi/core` via `.changeset/config.json#fixed`.
+
+  ## Minor — `@apollion-dsi/scripts`
+  - `codemods/v4-migrate.mjs` — one-way codemod (Q-G10: no `--revert`; DEX/Jovian/Fanaticofc don't consume v3.x, no legacy to revert). Transforms `invertForSurface` to 3-arg, flags `createTheme` for manual hoist to `apollion.config.mjs`. Transcript JSONL audit log.
+  - `verify-no-install-scripts.js` — supply-chain hardening; blocks `preinstall`/`install`/`postinstall` in `@apollion-dsi/*` workspaces (threat-model E2 mitigation).
+
+  ## Spike validation (preserved local, NOT merged to main)
+  - `spike/culori-wcag-parity` — 100.0000% bit-exact culori vs color@5 (262 measurements / 10 palettes). `vendors/Color` elimination LOCKED.
+  - `spike/culori-oklch-lerp-parity` — 0 unexpected regressions in 68 deltas; greyscale ramp 19× more uniform in OKLAB L. DECISION ✅ PROCEED.
+
+### Patch Changes
+
+- Updated dependencies [032f81c]
+- Updated dependencies [32f7a1d]
+- Updated dependencies [2dadba5]
+- Updated dependencies [820a612]
+- Updated dependencies [c056ee3]
+- Updated dependencies [d032437]
+- Updated dependencies [00e0525]
+- Updated dependencies [1c87be8]
+- Updated dependencies [d1192da]
+- Updated dependencies [3194fba]
+- Updated dependencies [f359982]
+- Updated dependencies [5d17ebc]
+- Updated dependencies [bd7d6cb]
+- Updated dependencies [6545751]
+- Updated dependencies [36eaf4a]
+- Updated dependencies [802828f]
+- Updated dependencies [e14469c]
+- Updated dependencies [81cd55b]
+- Updated dependencies [c57c548]
+- Updated dependencies [879eedd]
+- Updated dependencies [e2abc9c]
+- Updated dependencies [75961a1]
+- Updated dependencies [e55019a]
+- Updated dependencies [fba9a41]
+- Updated dependencies [3a90653]
+- Updated dependencies [5fca933]
+- Updated dependencies [ea3dc3a]
+- Updated dependencies [51f71f6]
+- Updated dependencies [0a1baeb]
+- Updated dependencies [6d1371e]
+- Updated dependencies [e55019a]
+- Updated dependencies [29081ae]
+  - @apollion-dsi/core@4.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 Framework-agnostic design tokens for Apollion Design System v4+.
 
-**Status:** 🟡 `0.0.0-alpha.0` — S1 scaffold. Public surface stabilizes at `4.0.0` GA.
+**Status:** ✅ **GA @ 4.2.0** — v4 epic shipped 2026-05-25 (ADR-006). Lockstep com `@apollion-dsi/core@4.2.0`.
 
 ## Versioned API
 
@@ -38,15 +38,15 @@ Hard rule per ADR-006 §3.1:
 
 ## Slicing (ADR-006 §6)
 
-| Slice                                           | Status         | Deliverable                                                    |
-| ----------------------------------------------- | -------------- | -------------------------------------------------------------- |
-| S1 — scaffold + versioned API                   | ✅ this commit | `runtime/v1` namespace, esbuild ESM/CJS dual emit, smoke test  |
-| S2 — culori vendor + OKLch lerp (in core)       | pending        | spike `spike/culori-oklch-lerp-parity` validated 0 regressions |
-| S3 — Dimension axis                             | pending        | `compact/normal/spacious` multipliers                          |
-| S4 — builders duplicated here via Strangler Fig | pending        | parity tests vs core                                           |
-| S5 — atomic+idempotent build CLI                | pending        | `apollion-tokens build` + `dist/manifest.json`                 |
-| S6 — Config-First + sandboxed loader            | pending        | `node:vm` + zod schema                                         |
-| S7 — release `4.0.0`                            | pending        | first major + lockstep changesets                              |
+| Slice                                | Status     | Deliverable                                       |
+| ------------------------------------ | ---------- | ------------------------------------------------- |
+| S1 — scaffold + versioned API        | ✅ shipped | `runtime/v1` namespace, esbuild ESM/CJS dual emit |
+| S2 — culori vendor + OKLch lerp      | ✅ shipped | `vendors/Culori` in core; OKLch palette           |
+| S3 — Dimension axis                  | ✅ shipped | `compact/normal/spacious` multipliers             |
+| S4 — Foundation/Surface builders     | ✅ shipped | Strangler Fig parity with core                    |
+| S5 — atomic+idempotent build CLI     | ✅ shipped | `apollion-tokens build` + `dist/manifest.json`    |
+| S6 — Config-First + sandboxed loader | ✅ shipped | `apollion.config.mjs` + zod schema                |
+| S7 — release `4.0.0`                 | ✅ shipped | lockstep changesets with core                     |
 
 ## Refs
 

package/lib/builders/colors.d.ts

@@ -0,0 +1,35 @@
+/**
+ * OKLch palette builders — **Strangler Fig duplicate** of
+ * `@apollion-dsi/core/themes/colors` (ADR-006 §6 S4, PRD-002 §S4).
+ *
+ * **Strangler Fig contract:** this file DUPLICATES the implementation from
+ * `packages/core/src/themes/Colors/Colors.helpers.ts` (S2 OKLch migration).
+ * It does NOT delegate to core. Rationale:
+ *
+ * - Core remains SSOT for v4.x release line.
+ * - Tokens v4.0.0 ships standalone — consumer that opts into
+ *   `@apollion-dsi/tokens` (via `optionalDependencies` in core) gets a
+ *   self-contained palette derivation without runtime dep on core internals.
+ * - Future PRD-003 (post-v4) consolidates by deleting either copy after
+ *   real consumer adoption validates the API surface.
+ *
+ * Parity is enforced via `__tests__/parity.test.ts`: given identical input,
+ * `core.mountSingleColor(...) === tokens.mountSingleColor(...)` for every
+ * exported function. Drift = build fail.
+ *
+ * Types are imported from core via the stable subpath
+ * `@apollion-dsi/core/themes/colors` (NOT the root barrel that gets removed
+ * in E7) — types ARE shared SSOT; only logic is duplicated.
+ *
+ * @see ../../docs/adr/ADR-006-v4-oklch-dimension-token-split.md §3.1 §6 S4
+ * @see ../../docs/prd/PRD-002-v4-epic-execution.md §S4
+ */
+import type { AcceptColorType, ColorPalleteInterface, ColorsInput, GrayscaleColorsType, NeutralColorsType } from '@apollion-dsi/core/themes/colors';
+/** Rotate hue 180° in OKLch space. Semantic shift vs HSL — see core for details. */
+export declare function getOppositeColor(color: AcceptColorType): string;
+/** Derive `{ base, dark, action, active, light }` via OKLch lerp. */
+export declare function mountSingleColor(color: AcceptColorType, colors: ColorsInput): ColorPalleteInterface;
+/** 12-step greyscale ramp — perceptually uniform via OKLch lerp. */
+export declare function mountGreyscaleColors(colors: ColorsInput): Record<GrayscaleColorsType, string>;
+/** 20-step neutral ramp anchored at n170 (primary mixed with darker). */
+export declare function mountNeutralColors(colors: ColorsInput): Record<NeutralColorsType, string>;

package/lib/builders/foundation.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Foundation builder — **interim re-export** from
+ * `@apollion-dsi/core/themes/foundation` (ADR-006 §6 S4, PRD-002 §S4).
+ *
+ * **Interim contract:** Foundation is complex (ADR-002 §3) and ships
+ * unchanged in v4. Tokens re-exports `createFoundation` from core via the
+ * stable subpath. Strangler Fig consolidation to standalone implementation
+ * is deferred to PRD-003 post-v4 if/when real consumer adoption justifies
+ * the duplication cost.
+ *
+ * Unlike `./colors.ts` and `./spacing.ts` (full duplicates because v4 logic
+ * is new), Foundation logic exists pre-v4 and parity is enforced trivially
+ * by re-export identity.
+ *
+ * @see ./colors.ts (Strangler Fig contract notes)
+ * @see ../../docs/adr/ADR-002-layered-theme-aliases-and-surface.md §3
+ */
+export { createFoundation } from '@apollion-dsi/core/themes/foundation';
+export type { FoundationLayer } from '@apollion-dsi/core/themes/foundation';

package/lib/builders/spacing.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Spacing builder — **Strangler Fig duplicate** of
+ * `@apollion-dsi/core/themes/spacing` (ADR-006 §6 S4).
+ *
+ * Same dimension override semantics as core: when `dimension` arg
+ * provided, its calibrated multiplier wins over `input.multiplier`.
+ *
+ * @see ./colors.ts (Strangler Fig contract notes)
+ */
+import type { Dimension } from '@apollion-dsi/core/themes/dimension';
+import type { SpacingInput, SpacingThemeInterface } from '@apollion-dsi/core/themes/spacing';
+export declare function createSpacing({ multiplier, alias }: SpacingInput, dimension?: Dimension): SpacingThemeInterface;

package/lib/builders/surface.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Surface builder — **interim re-export** from
+ * `@apollion-dsi/core/themes/surface` (ADR-006 §6 S4, PRD-002 §S4).
+ *
+ * **Interim contract:** Surface ships unchanged in v4 S4. Tokens re-exports
+ * `invertForSurface` from core via the stable subpath. Surface-within-mode
+ * extension (E6 in S6) will REPLACE the signature to
+ * `invertForSurface(theme, surface, mode)`; tokens will update its re-export
+ * accordingly in S6.
+ *
+ * @see ./colors.ts (Strangler Fig contract notes)
+ * @see ../../docs/adr/ADR-002-layered-theme-aliases-and-surface.md §3
+ * @see ../../docs/adr/ADR-006-v4-oklch-dimension-token-split.md §3.6 (E6 in S6)
+ */
+export { invertForSurface } from '@apollion-dsi/core/themes/surface';
+export type { SurfaceMode } from '@apollion-dsi/core/themes/surface';

package/lib/runtime/v1.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `@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 declare const TOKENS_RUNTIME_API_VERSION: "v1";
+export { getOppositeColor, mountGreyscaleColors, mountNeutralColors, mountSingleColor } from '../builders/colors';
+export { createSpacing } from '../builders/spacing';
+export { createFoundation } from '../builders/foundation';
+export type { FoundationLayer } from '../builders/foundation';
+export { invertForSurface } from '../builders/surface';
+export type { SurfaceMode } from '../builders/surface';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apollion-dsi/tokens",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "description": "Apollion Design System — Framework-agnostic design tokens",
   "homepage": "https://github.com/apollion-ds/apollion",
   "license": "MIT",
@@ -61,7 +61,7 @@
     "test": "jest --passWithNoTests",
     "coverage": "jest --coverage --passWithNoTests",
     "validate": "./scripts/validate.sh",
-    "release": "yarn build && changeset publish"
+    "release": "yarn build && yarn run -T changeset publish"
   },
   "peerDependencies": {
     "@apollion-dsi/core": ">=4.0.0"
@@ -71,7 +71,7 @@
     "zod": "4.4.3"
   },
   "devDependencies": {
-    "@apollion-dsi/core": "workspace:*",
+    "@apollion-dsi/core": "4.3.0",
     "@apollion-dsi/eslint-config": "0.8.0",
     "@types/culori": "4.0.1",
     "@types/jest": "30.0.0",
@@ -83,4 +83,4 @@
     "ts-jest": "^29.4.11",
     "typescript": "6.0.3"
   }
-}
+}