Dtcg 2025 10

Use each *.normative.json as an index. Confirm final conformance behavior against the linked TR section text.

Version freshness (mandatory)

Before starting conformance work, check:

• https://www.designtokens.org/technical-reports/

If a newer stable TR exists, update references, requirement indexes, and schema mirrors first. Do not mix versions in one conformance run.

Repository alignment (mandatory)

When this skill, its references, or DTCG conformance behavior changes, update these repository documents in the same change:

• ARCHITECTURE.md
• AGEND.md
• .agents/skills/README.md (if discovery layout or compatibility links changed)

Default workflow (checklist)

• Identify scope: format, color, resolver, or a combination.
• Validate structure with the corresponding schema mirror(s).
• Apply semantic checks not expressible in JSON Schema.
• Resolve references/ordering with module-specific rules.
• Re-run validation until all checks pass.
• Produce conformance report from assets/conformance-report-template.md.

Critical requirements by module

Format essentials

• Detect token vs group by $value presence.
• Enforce names: no leading $, no {, }, or ..
• Support both reference syntaxes: curly aliases and JSON Pointer $ref.
• Resolve root-token aliases consistently: {group.$root} and #/group/$root must target the same token.
• Enforce type determination order exactly: explicit $type -> referenced token type -> nearest parent group $type -> invalid.
• Never infer token type by value shape alone.
• Implement chaining and cycle detection across aliases, $extends, and $ref.
• Preserve unknown $extensions data during read/write.

Color essentials

• $type must be color.
• $value must include colorSpace and components.
• Each component must be a number or "none".
• alpha is optional; default is 1.
• hex is optional fallback and must be 6-digit CSS hex.
• Enforce component bounds and structure by color space.

Resolver essentials

• Root version must exist and equal 2025.10.
• Root resolutionOrder is required.
• Sets must define ordered sources (last conflict wins).
• Modifiers must define non-empty contexts.
• Modifiers may reference sets, never modifiers.
• Only resolutionOrder may reference #/modifiers/....
• Nothing may reference #/resolutionOrder/....
• Apply stages in order: input validation -> flattening -> alias resolution -> final output.

Gotchas

• Do not silently coerce invalid values unless the spec defines fallback behavior.
• Keep normative requirements separate from non-normative guidance.
• Non-normative sections: Format section 2; Color sections 5-7; Resolver sections 1, 2.1, and 7.
• Preserve additional token properties (including $extensions) through transforms and resolution.

Validation loop

1. Make implementation or data changes.
2. Validate with schema mirror(s).
3. Validate semantics with references/requirements/*.normative.json plus TR section text.
4. If anything fails, fix and repeat from step 2.
5. Finalize only when all schema and semantic checks pass.

Output requirement

Final conformance output must include section-anchor-level pass/fail status plus rationale, using assets/conformance-report-template.md.