Sibling contract

Tokens

Token-format conformance is the foundation of portable design intelligence. If tokens are not structurally valid, every downstream tool inherits the rot.

Version 0.1.0 · provisional · machine export

Source authority

Primary standard

W3C Design Tokens Format Module 2025.10 (CG-FINAL, 2025-10-28)

JSON Schema

https://www.designtokens.org/schemas/2025.10/format.json

Reference validator

@terrazzo/parser 2.4.0

Conformance

Required token properties

$value (required) · $type (required, direct or inherited) · $description (recommended on semantic) · $extensions (optional, namespaced)

Standard DTCG types

color, dimension, fontFamily, duration, cubicBezier, number, boolean

Custom Designesy types

spring (via $extensions.designesy.spring) · sound (via $extensions.designesy.sound)

Color spaces

OKLCH mandatory for new tokens · Display-P3 permitted · sRGB bare hex legacy (SHOULD migrate)

Verification — 10 checks

01t01 · Every token has $type (direct or inherited)PASS: All tokens typed · FAIL: Any token missing type

02t02 · Every token has $valuePASS: All valued · FAIL: Any missing value

03t03 · Semantic tokens have $descriptionPASS: All described · WARN: Primitive missing description

04t04 · Color tokens use OKLCH or Display-P3PASS: New tokens OKLCH/P3 · FAIL: New semantic uses bare hex · WARN: Legacy hex in primitive

05t05 · Custom types namespaced under $extensions.designesy.*PASS: Namespaced · FAIL: Bare custom type

06t06 · Aliases resolve to valid typed tokensPASS: All resolve · FAIL: Dangling reference

07t07 · $schema property presentPASS: Present · WARN: Missing (no editor validation)

08t08 · DTCG 2025.10 schema validation passes (Terrazzo tz check)PASS: Passes · FAIL: Schema violation

09t09 · No type drift between themes (same token, different $type)PASS: Consistent · FAIL: Drift detected

10t10 · Dimension units are px or rem onlyPASS: Valid units · FAIL: Invalid unit

10 checks. PASS=1, WARN=0.5, FAIL=0. Score = (points/10) × 100. A≥90, B≥80, C≥70, D≥60, F<60.

Open questions

DTCG custom types proposal: should spring and sound be proposed to W3C DTCG?
Color migration timeline: when should §8.1 migrate from bare hex to structured OKLCH?
Resolver support: should Designesy adopt DTCG 2025.10 resolvers?
Multi-theme conformance: how should t09 handle intentional cross-theme type changes?
Style Dictionary integration: switch from Terrazzo when style-dictionary achieves full 2025.10 support?

Sibling contract to the design system v0.3.0. Machine export at /contracts/tokens.json.