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.3 · 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. Since v0.1.3 the type of a token is its own $type, else the type of the token it references, else the closest group $type above it ($extends included), and a token written { $type, $ref } is counted, with t04 checking that its JSON Pointer names a location in the file. A≥90, B≥80, C≥70, D≥60, F<60.

01 t01 · $schema declaration present and pointing at designtokens.org (a Designesy policy: DTCG does not require $schema) Pass Present, designtokens.org Warn Missing (no editor validation), or present but non-canonical Fail n/a

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 exactly one of $value and $ref, and a JSON Pointer $ref names a location in the file Pass All valued Fail A token with no value, with both $value and $ref, or with a $ref that names nothing or loops

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 · Dimensions use the 2025.10 form { value, unit } in px or rem Pass All in that form Warn Legacy strings such as "16px", or some invalid values Fail No usable dimension value

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, string or bare number dimensions, a $ref that is not a JSON Pointer) 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.7. 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).