Formalize DTCG 2025.10 type vocabulary alignment

[ryandmonk]

Background

The W3C Design Tokens Community Group (DTCG) Format Module 2025.10 reached stable status in October 2025. dspack-export already supports DTCG as an input format. The dspack spec should formalize the relationship between the two type vocabularies at the spec level.

Open question 16.4 in the v0.2 spec now acknowledges the relationship, but the question of what to do about it remains open.

Current Type Alignment

Shared types (8) — same name, same semantics

dspack type	DTCG type	Notes
color	color	Aligned
dimension	dimension	Aligned
fontFamily	fontFamily	Aligned
fontWeight	fontWeight	Aligned
duration	duration	Aligned
cubicBezier	cubicBezier	Aligned
number	number	Aligned
shadow	shadow	Aligned

dspack-only types (6) — finer-grained than DTCG

dspack type	DTCG equivalent	Why dspack is finer-grained
fontSize	dimension	Agents benefit from knowing a dimension is specifically a font size
lineHeight	dimension or number	Distinguishes typographic vertical rhythm from general spacing
letterSpacing	dimension	Distinguishes tracking from general spacing
borderRadius	dimension	Distinguishes corner rounding from general sizing
opacity	number	Distinguishes transparency from arbitrary numbers
string	(none)	Catch-all for non-numeric values; DTCG has no equivalent

DTCG-only types (5) — composite types dspack doesn't define

DTCG type	Description	dspack implication
strokeStyle	Line/border styling	Could be useful for component-level tokens
border	Composite: color + width + style	dspack tokens are atomic resolved values, not composites
transition	Composite: duration + delay + timing	Same — dspack would represent these as separate tokens
gradient	Color gradient definition	Not currently in dspack's recommended types
typography	Composite: font family + size + weight + etc.	Same — dspack would represent these as separate tokens

Design Questions

A future dspack version could address this alignment in several ways:

1. Accept DTCG type names as aliases — e.g., a token with "type": "dimension" is valid even though dspack recommends fontSize/borderRadius/etc. for finer granularity. This preserves backward compatibility and eases DTCG-to-dspack conversion.

2. Document the mapping without changing the schema — a normative "DTCG Compatibility" subsection in the token types section that defines the exact mapping. No schema change, but consumers get a reference table.

3. Add DTCG composite types — gradient is arguably useful as an atomic dspack type. The true composites (border, transition, typography) are less natural for dspack's resolved-value model where each token is a single value.

These are not mutually exclusive.

Non-Goals

• Adopting DTCG's $-prefix syntax ($value, $type, $description)
• Adopting DTCG's unresolved reference model ({color.primary} in values)
• Adopting DTCG's structured value format (e.g., {"value": 16, "unit": "px"} vs. dspack's "16px")
• Replacing dspack's token model — dspack remains a resolved-value, generation-optimized format

References

• DTCG Format Module 2025.10
• dspack spec section 5.3 — Token Types
• dspack spec section 16.4 — Token Type Taxonomy (open question)
• dspack-export DTCG support