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.2 · provisional · machine export

View as Markdown

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. PASS=1, WARN=0.5, FAIL=0; SKIP is not scored. Score = ((PASS + 0.5 × WARN) / scored checks) × 100, where a scored check returned PASS, WARN or FAIL (until v0.1.1 a SKIP counted in the denominator, so a clean file with no custom types scored 90; until v0.1.2 a WARN counted 0, where the motion contract, the score engine and the npm validator count it half). A {group.token} alias is a reference: t08 checks the dimension it resolves to, and a $root token is checked like any other. A≥90, B≥80, C≥70, D≥60, F<60.

01 t01 · $schema declaration present and pointing at designtokens.org Pass Present, designtokens.org Warn Present but non-canonical Fail Missing (no editor validation)

02 t02 · Token groups present (top-level non-$ keys) Pass Groups found Fail No token groups

03 t03 · Every token has $type (direct or inherited) Pass All tokens typed Warn Partial typing Fail Any token missing type

04 t04 · Every token has $value Pass All valued Fail Any missing value

05 t05 · Color tokens use structured {colorSpace, components} format instead of bare hex Pass No bare hex Warn Mixed structured and bare hex Fail All bare hex

06 t06 · $type values are DTCG 2025.10 standard types Pass All standard Warn Non-standard types present (custom (see t07)) Fail No tokens typed

07 t07 · Custom types namespaced (dot-prefix, e.g. designesy.spring via $extensions.designesy.*) Pass All namespaced Warn Bare custom type names Fail n/a

08 t08 · Dimension units are valid CSS length units (px, rem preferred) Pass All valid Warn Partial Fail Invalid units

09 t09 · Token naming hierarchy: tokens organized into nested groups Pass Groups with hierarchy Warn Flat token set Fail No tokens

10 t10 · No deprecated pre-2025.10 patterns (bare hex colors, bare number dimensions, $ref syntax) Pass Clean Warn Deprecated patterns found Fail n/a

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.4.6. Machine export at /contracts/tokens.json. The live DTCG export (/export/dtcg) scores 100, grade A, on the 10 conformance checks: 9 pass, and t07 does not apply because the export declares no custom types (designesy_tokens_score, 2026-10-11).