You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
⚠️ DRAFT STATUS: This RFC documents the token schema structure implemented in PR #644 and proposes it as the standard for future token work. Open for feedback and review.
This RFC proposes a comprehensive schema structure for all Spectrum design tokens, transforming hyphen-delimited token names into structured JSON objects with full validation capabilities. This provides the foundation for advanced tooling including token recommendations, automated documentation, and cross-platform transformation.
Problem: Current token structure uses hyphen-delimited names with implicit meaning, no validation of naming conventions, and limited ability to query or analyze tokens systematically. This makes it difficult to build tooling, enforce governance, or provide semantic guidance.
Solution: Implement structured token format with JSON Schema validation, controlled vocabularies (enums), semantic analysis capabilities, and perfect round-trip conversion. Complete implementation provided in PR #644.
Results: All 2,338 tokens across 8 files successfully parsed and validated with 100% regeneration rate and 82% schema validation coverage.
Background & Context
Origin
DNA-1485: Initiative to improve and expand design data schemas
August 2025 Onsite: Discussion of data system improvements and tooling needs
Token Recommendation Requirements: Need structured data for semantic token suggestions
Documentation Generation: Need queryable token structure for automated docs
Total controlled vocabulary: 800+ values ensuring consistency
Semantic Complexity Metric
Measures how much semantic context a token provides (0-3+):
// Calculated based on semantic fields in name.structuresemanticComplexity=countOf([component,property,anatomyPart,spaceBetween,referencedToken,options,state,calculation,platform])
Examples:
gray-100: complexity 0 (base palette, no semantic context)
background-color-default: complexity 1 (semantic alias with property)
constspacingTokens=tokens.filter(t=>t.name.structure.category==='spacing');// Returns: All 461 spacing tokens
Find High-Complexity Tokens
constsemanticTokens=tokens.filter(t=>t.name.semanticComplexity>=2);// Returns: Tokens with strong semantic context for recommendations
Track Token References
constaliases=tokens.filter(t=>t.name.structure.category==='semantic-alias'&&t.name.structure.referencedToken==='blue-800');// Returns: All tokens that reference blue-800
Validate Token Names
constinvalid=tokens.filter(t=>!t.validation.isValid);// Returns: Tokens that don't match schemas (need attention)
Benefits & Use Cases
1. Token Recommendation Systems
Enabled by semantic complexity metric and reference tracking
Use Case: IDE plugin suggests semantic alternatives
Enabled by schema validation and controlled vocabularies
Use Case: CI/CD validation of token PRs
$ pnpm validate-tokens
✓ All token names follow conventions
✗ Error: "button-height-350" - index 350 not in allowed sizes
✗ Error: "unknow-component-size" - component not in allowed list
4. Cross-Platform Token Transformation
Enabled by structured format and perfect round-trip
Use Case: Transform tokens for different platforms
// Web: --spectrum-button-background-default// iOS: ButtonBackgroundDefault// Android: button_background_default// All from same structured source
5. Token Migration & Deprecation
Enabled by reference tracking and semantic analysis
Use Case: Identify tokens to migrate
// Find all tokens referencing deprecated blue-800constaffectedTokens=findReferences('blue-800');// Plan migration path: blue-800 → blue-900// Update all 23 semantic aliases automatically
Pros: No change, existing tooling works Cons: Can't build advanced tooling, no governance, limited querying Decision: Rejected - doesn't meet future needs
Alternative 2: Use DTCG Format Directly
Pros: Standard format, external tool support Cons: Doesn't capture Spectrum-specific semantics (anatomy, space-between), loses semantic complexity Decision: Considered for future (RFC #627 proposes DTCG as additional output)
Alternative 3: Object with Names as Keys
Pros: Familiar structure, easy lookup by name Cons: Can't have duplicate names across themes, harder round-trip Decision: Rejected - anonymous array provides more flexibility
Alternative 4: AI/LLM-Based Parsing
Pros: Could handle more edge cases Cons: Non-deterministic, harder to validate, slower Decision: Rejected - rule-based parsing with schemas is more reliable
Migration & Adoption
Phase 1: Non-Breaking Addition (Complete in PR #644)
✅ Structured tokens live alongside original tokens
✅ No changes to existing token files in packages/tokens/src/
reacted with thumbs up emoji reacted with thumbs down emoji reacted with laugh emoji reacted with hooray emoji reacted with confused emoji reacted with heart emoji reacted with rocket emoji reacted with eyes emoji
Uh oh!
There was an error while loading. Please reload this page.
-
RFC: Token Schema Structure and Validation System
Status: Draft - Implementation Complete
Author: Garth Braithwaite
DACI: [To be assigned]
Implementation: PR #644
Related: DNA-1485, RFC #624, RFC #625, RFC #626
Executive Summary
This RFC proposes a comprehensive schema structure for all Spectrum design tokens, transforming hyphen-delimited token names into structured JSON objects with full validation capabilities. This provides the foundation for advanced tooling including token recommendations, automated documentation, and cross-platform transformation.
Problem: Current token structure uses hyphen-delimited names with implicit meaning, no validation of naming conventions, and limited ability to query or analyze tokens systematically. This makes it difficult to build tooling, enforce governance, or provide semantic guidance.
Solution: Implement structured token format with JSON Schema validation, controlled vocabularies (enums), semantic analysis capabilities, and perfect round-trip conversion. Complete implementation provided in PR #644.
Results: All 2,338 tokens across 8 files successfully parsed and validated with 100% regeneration rate and 82% schema validation coverage.
Background & Context
Origin
Current Token Format
{ "text-to-visual-50": { "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/dimension.json", "value": "4px", "uuid": "f1bc4c85-c0dc-44bf-a156-54707f3626e9" } }Limitations:
Design Data System Vision
From your onsite presentation:
Proposal
Structured Token Format
Transform token names into structured objects with full semantic information:
{ "id": "f1bc4c85-c0dc-44bf-a156-54707f3626e9", "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/dimension.json", "value": "4px", "name": { "original": "text-to-visual-50", "structure": { "category": "spacing", "property": "spacing", "spaceBetween": { "from": "text", "to": "visual" }, "index": "50" }, "semanticComplexity": 1 }, "validation": { "isValid": true, "errors": [] } }Token Categories
Nine primary token categories identified across all tokens:
text-to-visual-50)button-height-100)corner-radius-100)accent-color-100→{blue-800})blue-800)blue-800,transparent-blue-800)gradient-stop-1-red)bold-font-weight,sans-font-family)Schema Architecture
Base Schema Hierarchy
Enum Schemas (Controlled Vocabularies)
12 enum schemas define allowed values for token name parts:
Total controlled vocabulary: 800+ values ensuring consistency
Semantic Complexity Metric
Measures how much semantic context a token provides (0-3+):
Examples:
gray-100: complexity 0 (base palette, no semantic context)background-color-default: complexity 1 (semantic alias with property)button-background-color-default: complexity 2 (component + property + alias)button-control-background-color-hover: complexity 3+ (component + anatomy + property + state)Use Case: Token recommendation systems can suggest more semantically specific tokens:
blue-800, consideraccent-color-100(more semantic)"button-background-color-default(most specific for this use case)"Validation Strategy
Schema-Driven Validation
Validation Levels
Current Validation Results
Anonymous Token Array Structure
Tokens stored as array of objects (not keyed by name):
Why:
Before (keyed by name):
{ "blue-800": { "value": "#1473E6", "uuid": "..." } }After (anonymous array):
[ { "id": "550e8400-e29b-41d4-a716-446655440000", "value": "#1473E6", "name": { "original": "blue-800", "structure": { "category": "color-base", "color": "blue", "index": "800" }, "semanticComplexity": 0 } } ]Round-Trip Verification
Critical Requirement: Structured format must perfectly regenerate original token names.
Implementation:
Results: 100% match rate (2,338/2,338 tokens) - zero data loss
Example Template (spacing-token.hbs):
Implementation
Complete Implementation: PR #644
Package 1:
packages/structured-tokens/Package 2:
tools/token-name-parser/Parser Capabilities
Pattern Detection:
Example Parsing:
Input:
checkbox-control-size-small{ "category": "component-property", "component": "checkbox", "anatomyPart": "control", "property": "size", "options": ["small"] }Input:
text-to-visual-compact-medium{ "category": "spacing", "property": "spacing", "spaceBetween": { "from": "text", "to": "visual" }, "options": ["compact", "medium"] }Input:
accent-color-100(references{blue-800}){ "category": "semantic-alias", "property": "accent-color-100", "referencedToken": "blue-800", "notes": "Semantic alias providing contextual naming" }Usage Examples
Query Tokens by Category
Find High-Complexity Tokens
Track Token References
Validate Token Names
Benefits & Use Cases
1. Token Recommendation Systems
Enabled by semantic complexity metric and reference tracking
Use Case: IDE plugin suggests semantic alternatives
2. Automated Documentation Generation
Enabled by structured data and queryable format
Use Case: Generate token catalog by category
3. Design System Governance
Enabled by schema validation and controlled vocabularies
Use Case: CI/CD validation of token PRs
4. Cross-Platform Token Transformation
Enabled by structured format and perfect round-trip
Use Case: Transform tokens for different platforms
5. Token Migration & Deprecation
Enabled by reference tracking and semantic analysis
Use Case: Identify tokens to migrate
6. Foundation for Future RFCs
Directly enables other proposed RFCs
Alternatives Considered
Alternative 1: Keep Hyphenated Names Only
Pros: No change, existing tooling works
Cons: Can't build advanced tooling, no governance, limited querying
Decision: Rejected - doesn't meet future needs
Alternative 2: Use DTCG Format Directly
Pros: Standard format, external tool support
Cons: Doesn't capture Spectrum-specific semantics (anatomy, space-between), loses semantic complexity
Decision: Considered for future (RFC #627 proposes DTCG as additional output)
Alternative 3: Object with Names as Keys
Pros: Familiar structure, easy lookup by name
Cons: Can't have duplicate names across themes, harder round-trip
Decision: Rejected - anonymous array provides more flexibility
Alternative 4: AI/LLM-Based Parsing
Pros: Could handle more edge cases
Cons: Non-deterministic, harder to validate, slower
Decision: Rejected - rule-based parsing with schemas is more reliable
Migration & Adoption
Phase 1: Non-Breaking Addition (Complete in PR #644)
packages/tokens/src/packages/structured-tokens/tools/token-name-parser/Phase 2: Tooling Integration (Next)
Phase 3: Authoring Workflow (Future)
Phase 4: Platform Transformation (Future)
No breaking changes to existing token consumers.
Success Metrics
Achieved in PR #644:
Future Success Metrics:
Known Limitations & Future Work
455 Special Tokens (19.5%)
Tokens that regenerate correctly but need additional schemas:
Categories:
component-xs-regularbundles multiple font propertiesdrop-shadow-emphasizedhas complex structureswatch-border-opacitydirect opacity valuesbutton-minimum-width-multipliercalculation-basedandroid-elevationneeds platform schemaFuture Schemas Needed:
typography-composite-token.jsondrop-shadow-composite-token.jsonmultiplier-token.jsonImpact: These tokens work correctly (100% regeneration) but show as "special" in validation reports.
Edge Cases
focus-indicator,side-label-character-count)compact-extra-large)Performance Considerations
Open Questions
Related Work & References
GitHub Discussions
Jira Tickets
Implementation
Documentation (in PR #644)
FINAL_PROJECT_SUMMARY.md- Complete project overviewICONS_RESULTS.md- Icons parsing results (100% validation)TYPOGRAPHY_RESULTS.md- Typography parsing results (95.2% validation)LAYOUT_COMPONENT_RESULTS.md- Layout component results (70.3% validation)COLOR_FINAL_RESULTS.md- All color files summarySEMANTIC_COMPLEXITY.md- Semantic complexity metric documentationROUND_TRIP_VERIFICATION.md- Round-trip conversion verificationDecision Points
For Approval
For Discussion
Next Steps
Immediate (Post-Approval)
Short-term (1-2 months)
Medium-term (3-6 months)
Long-term (6-12 months)
Appendix
Appendix A: Complete Token Category Definitions
See full documentation in PR #644:
packages/structured-tokens/schemas/- All schema definitionspackages/structured-tokens/schemas/enums/- All enum definitionstools/token-name-parser/templates/- Regeneration templatesAppendix B: Validation Reports
Complete validation reports available in PR #644:
tools/token-name-parser/output/[filename]-validation-report.jsonAppendix C: Parser Implementation
Full parser source:
tools/token-name-parser/src/parser.js- Token name parsing logic (838 lines)tools/token-name-parser/src/validator.js- Schema validation (242 lines)tools/token-name-parser/src/name-regenerator.js- Name regeneration (98 lines)Appendix D: Test Coverage
All tests passing:
tools/token-name-parser/test/parser.test.jstools/token-name-parser/test/name-regenerator.test.jstools/token-name-parser/test/name-comparator.test.jstools/token-name-parser/test/semantic-complexity.test.jsFeedback & Discussion
Please provide feedback on:
This RFC is open for discussion and feedback before moving to approval.
Beta Was this translation helpful? Give feedback.
All reactions