@apollion-dsi/tokens

Framework-agnostic design tokens for Apollion Design System v4+.

Status: ✅ GA desde 4.2.0 — v4 epic shipped 2026-05-25 (ADR-006). Atual 4.5.0, lockstep com @apollion-dsi/[email protected].

Versioned API

Single public entry: @apollion-dsi/tokens/runtime/v1.

Future major surface changes go to runtime/v2, runtime/v3, etc. — v1 is preserved indefinitely (Strangler Fig per ADR-006 §3.3).

import { TOKENS_RUNTIME_API_VERSION } from '@apollion-dsi/tokens/runtime/v1';

Scope

• In: OKLch palette derivation (S2/S4), Dimension axis (S3), Foundation/Surface builders (S4), build-time CSS/JSON/TS variant emission (S5), Config-First loader (S6).
• Out: Runtime React components (lives in @apollion-dsi/core), framework adapters (Vue/Flutter consumers consume dist/json/*.json directly).

JSON output (dist/json/*.json)

Tokens em JSON estruturado — values are structured objects, not shorthand strings:

• color → { "colorSpace": "oklch", "components": [L, C, H], "hex": "#rrggbb" } — OKLch working space + sRGB hex fallback. alpha emitted only when below 1.
• dimension → { "value": <number>, "unit": "rem" }.

dist/css/*.css and dist/ts/*.d.ts stay string-based (hex / rem) — JSON is the interop surface; CSS/TS are the resolved consumer surfaces.

Coupling to @apollion-dsi/core

Hard rule per ADR-006 §3.1:

• core declares @apollion-dsi/tokens in optionalDependencies (NOT dependencies).
• Consumer that does not opt into apollion.config.mjs#output.runtime: true never installs tokens.
• Lockstep version enforced via .changeset/config.json#fixed array from 4.0.0 (PRD-002 §S7).

Slicing (ADR-006 §6)

| 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

• ADR-006 — v4 epic
• PRD-002 — v4 epic execution
• packages/core/docs/v4-baseline-review.md