adobe / adobe/spectrum-design-data
Glossary/Taxonomy Backbone — name-object refactor + registry split
- Dominant language
- Rust
- Stars
- 153
- Forks
- 35
- Avg merge
- 7h 54m
- Merged PRs (30d)
- 111
Description
## Overview
This epic tracks the Glossary/Taxonomy Backbone initiative — a structural refactoring of how token names are defined, validated, and extended across the spec. Approved 2026-04-02 following Nate's naming-convention onsite.
**Problem:** The spec's `name` object `property` field is overloaded (mixes component anatomy, CSS properties, and styling surfaces). `anatomy-terms.json` conflates designer anatomy with token styling surfaces. Platforms (iOS, etc.) have no formal way to own their dimensions/modes.
**Goal:** Three distinct registries + a restructured `name` object that separates concerns clearly, enabling platform autonomy and reliable cross-reference validation.
## Phases
- [x] **Phase 1 — Anatomy audit**: Expand `anatomy-terms.json` from 43 → ~133 terms by mining S2 component docs (`tools/s2-docs-mcp/data/components/`). Completed 2026-05-15: registry at **122 terms** (PRs #915 + #927; acceptance ≥120 met; zero SPEC-020/023/024/025 anatomy errors on `packages/tokens/src`). Tracked by #912 (closed).
- [ ] **Phase 2 — Name object restructuring**: Introduce new fields (`structure`, `substructure`, `anatomy`, `object`, `orientation`, `position`, `size`, `density`, `shape`). Retire the overloaded `property` field. **Status:** New fields already declared in spec (`taxonomy.md` field catalog); remaining work is `property`-field migration path and retirement. Tracked by RFC #806 open questions (#941 critical-path, #942, #943).
- [ ] **Phase 3 — Formatting / serialization**: Separate output-layer formatting rules from semantic naming. Formatting is purely serialization; it does not affect the name object schema.
- [ ] **Phase 4 — Platform autonomy**: Formal mechanism for platforms (iOS, Android, etc.) to own their dimensions and modes without conflating with web naming.
- [ ] **Phase 5 — Validation bridge**: Legacy tokens and component-schema tests must stay stable while spec and registry can evolve freely. Wire up SPEC-020/023/024/025 validators to the new schema.
## Dependencies / related
- RFC #661 (glossary phases overview): #662 (web viewer), #663 (MCP+static API), #664 (content QA), #665 (integration + rollout)
- RFC #806 (taxonomy / anatomy naming): open questions #941, #942, #943
- RFC #714 (anatomy audit): closed as done — see #912 for scope and acceptance criteria
- **Revive trigger for Phase 4 (Generate + Author) and Phase 5 (Platform SDKs)**: Both are deferred until Backbone Phases 1–3 are complete and the name-object schema is stable (#732, #731).
## Key files
- `packages/design-system-registry/registry/anatomy-terms.json` (122 terms — Phase 1 complete)
- `packages/design-data-spec/spec/` — spec source
- `tools/s2-docs-mcp/data/components/` — S2 docs anatomy source
- `sdk/core/src/validate/rules/spec020.rs`, `spec023.rs`, `spec024.rs`, `spec025.rs`
Contributor guide
Research direction
Start with the field catalog in packages/design-data-spec/spec/taxonomy.md and the open questions in RFC #941, then trace the property-field migration. Review sdk/core/src/validate/rules/spec020.rs, spec023.rs, spec024.rs, and spec025.rs alongside the existing registry. Done means the migration path and retirement are defined while legacy tokens and component-schema tests remain stable.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- tooling
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100