[DRAFT RFC] Spectrum Design System Glossary

[GarthDB]

[DRAFT RFC] Spectrum Design System Glossary

Update (March 2026): The registry foundation (Phases 0–2) is complete. The package @adobe/design-system-registry is published, and the registry is live at Registry | Spectrum Design Data. This RFC is updated to reflect that foundation and to reframe the remaining work (glossary enrichment, viewer, MCP, QA) as the next layer building on top of it. Spec umbrella: RFC #714 — Spectrum Design Data Specification. Distributed architecture: RFC #715. Token format & cascade: RFC #646. Living outline: docs/rfc-coordination.md.

---

Problem Statement

The Spectrum Design System currently lacks a centralized, authoritative source for design terminology. This creates several challenges:

1. Inconsistent terminology across tokens, component schemas, documentation, and platforms
2. No validation for new terms being introduced
3. Platform fragmentation - each implementation (iOS, Qt, Web Components) may use different terms
4. AI integration gaps - chatbots and assistants lack structured access to Spectrum terminology
5. Content authoring friction - designers and content strategists have no clear process for defining and managing terms

Proposed Solution

Create a comprehensive Spectrum Design System Glossary with:

Core Components

1. Enhanced Registry (@adobe/design-system-registry) — Foundation complete

• Extend existing registry (PR feat(registry): add Design System Registry package #660) with rich definitions Done. Registry is published and includes optional glossary fields (definition, platforms, terminology, sources, governance, relatedTerms).
• Follow Spectrum Naming and Definition Writing Guide methodology
• Include superordinate, description, essential characteristics
• Multi-platform terminology support
• Governance metadata (owners, review dates, status)

Deliverables: npm package, Registry docs, 11 registry collections (179 values), 21 with full glossary definitions, platform extension system with 2 example extensions, AUTHORING.md.

2. Platform Extension System — Complete

• Allow platform teams to contribute platform-specific terminology
• Support both centralized contributions and plugin-based extensions
• Maintain single source of truth while enabling customization

Deliverables: platform-extension.json schema, example extensions (iOS states, Web Components states), PLATFORM_EXTENSIONS.md.

3. Web Viewer (GitHub Pages)

• Searchable, browsable glossary interface
• Category navigation, cross-references, export capabilities
• Mobile-responsive and accessible (WCAG 2.1 AA)
• Revised: Build on the existing docs site at Registry (no standalone app). Enhance registry pages to show full definitions, related terms, platform info; consider term detail pages and lightweight search.

4. LLM Integration

• Enhanced MCP server with glossary tools
• Static JSON HTTP API for chatbots (MrFluffyJaws, etc.) — or publish registry JSON as static assets on the docs site
• Enable AI assistants to understand and validate terminology

Content Sources

• Extract from Spectrum Naming Guide (methodology)
• Extract from App Frame (browsing) wiki (navigation terms)
• Extract from Spectrum Tokens wiki (token terminology)
• Existing registry data (sizes, states, components, etc.)

Connection to RFC #646: Token Schema Enums

Cascade & dimensions: RFC #646 now describes how multi-dimensional modes (e.g. color scheme, scale) appear in structured token names and how specificity is computed (non-default properties only). The registry / glossary should stay aligned with those dimensions where they represent controlled terminology (modes, themes, scale labels), so validation and authoring tools can share one vocabulary.

RFC #646 defines a structured token format with 12 enum schemas (800+ controlled vocabulary values) for token name parts: components, anatomy parts, states, sizes, properties, platforms, colors, etc. Many of these enums overlap with registry collections.

Proposal: The registry should be the canonical source for design system terminology. Token schema enums should consume the registry (or be validated against it). Glossary definitions written for registry terms then document both the glossary and the token schema’s controlled vocabularies.

Concept	Registry	Token schema (#646)	Relationship
Components	57 values	80 values	Overlapping
Anatomy	25 generic terms	249 component-specific parts	Registry = building blocks; token enums = compound terms
States	11 values	7 values	Reconcile (registry has active, pending, selected, etc.; token has error)
Platforms	5 values	5 values	Identical
Sizes	25 (t-shirt + numeric)	19 (numeric)	Different scope
Colors, themes, properties	Gaps	In token enums only	Consider new registry collections
Token dimensions (modes)	TBD collections	Structured name facets in #646	Registry can validate mode labels / defaults

Reconciling states, anatomy (generic vs compound), and any new registry collections (e.g. colors, themes) is part of the glossary content QA phase.

Architecture Overview

graph TB
    subgraph foundation [Registry Foundation — Completed]
        registryJSON["Registry JSON Files"]
        registrySchema["JSON Schema Validation"]
        registryPkg["@adobe/design-system-registry npm"]
        platformExt["Platform Extensions"]
        markdownGen["Markdown Generator"]
        docsSite["Docs Site — registry pages"]
    end

    subgraph glossaryLayer [Glossary Layer — Proposed]
        glossaryDefs["Enriched Definitions"]
        glossaryViewer["Enhanced Glossary Viewer"]
        glossaryMCP["Glossary MCP Tools"]
        contentQA["Content QA Process"]
        governance["Governance Workflow"]
    end

    subgraph consumers [Consumers]
        tokenSchemaEnums["Token Schema Enums — RFC #646"]
        mcpServer["MCP Server"]
        optionsEditor["Component Options Editor"]
        platformTeams["Platform Teams"]
        aiAssistants["AI Assistants"]
    end

    registryJSON --> registrySchema
    registryJSON --> registryPkg
    registryJSON --> markdownGen
    markdownGen --> docsSite
    registryJSON --> platformExt

    glossaryDefs --> registryJSON
    glossaryDefs --> glossaryViewer
    glossaryDefs --> glossaryMCP
    contentQA --> glossaryDefs
    governance --> glossaryDefs

    glossaryViewer --> docsSite
    glossaryMCP --> mcpServer
    registryPkg --> optionsEditor
    registryPkg --> tokenSchemaEnums
    platformExt --> platformTeams
    mcpServer --> aiAssistants

Loading

Benefits

1. Consistency: Single source of truth for all Spectrum terminology
2. Validation: Automated term validation in tools and schemas
3. Discoverability: Easy to find and understand Spectrum terms
4. AI-Ready: Structured data for chatbots and AI assistants
5. Extensible: Platform teams can customize without forking
6. Governed: Clear ownership and review processes

Open Questions

1. Authoring Workflow — Resolved

• Decision: GitHub JSON editing. AUTHORING.md documents the process. Evolve to a web interface later if needed.

2. Platform Extensions — Resolved

• Decision: Support both centralized and plugin patterns (Option C). Example extensions exist. Open question: which platform teams will contribute real extensions?

3. Maintenance & Governance — Open

• Who reviews and approves new terms?
• How often should terms be reviewed?
• What's the deprecation workflow for outdated terms?
• Should we establish a terminology working group?

4. Scope & Prioritization — Open

• Prioritized list for glossary definitions: (1) States, (2) Anatomy terms, (3) Variants, (4) existing glossary/navigation/token terms. Feedback welcome on ordering and whether to add new registry collections (e.g. colors, themes).

5. Registry / Token Enum Synchronization — New

• How should token schema enums (RFC [DRAFT RFC] Token Schema Structure and Validation System #646) consume or stay in sync with the registry? Generate from registry, validate against it, or document alignment process?

Implementation Plan

Phase 0: RFC and Community Feedback — Complete

• Gather feedback, refine approach, achieve consensus

Phase 1: Enhanced Schema & Content Migration — Complete

• Enhanced registry schema with definitions, platforms, governance
• Extracted content from wiki sources (glossary, navigation-terms, token-terminology, enhanced states)
• Created authoring documentation (AUTHORING.md)

Phase 2: Platform Extension System — Complete

• Extension schema and validation, helper functions, example extensions (iOS, Web Components), PLATFORM_EXTENSIONS.md

Phase 3: Glossary Web Experience

• Enhance existing registry docs pages to show full definitions, related terms, platform info
• Add term detail pages where glossary data exists
• Add cross-reference links; consider lightweight client-side search
• Deploy as part of Registry docs (no separate app)

Phase 4: LLM Integration

• Add registry/glossary tools to MCP server (list-registries, get-registry, lookup-term, get-term-definition, etc.)
• Static JSON: publish registry JSON as static assets on docs site, or separate API as needed

Phase 5: Content QA & Reconciliation with Token Enums

• Prioritized definition enrichment (states, anatomy terms, variants, existing terms)
• Reconcile with RFC [DRAFT RFC] Token Schema Structure and Validation System #646 token schema enums (align states, clarify anatomy generic vs compound, validate components)
• Review with content strategists; verify cross-references and platform terminology

Phase 6: Integration & Rollout

• Integrate glossary into component-options-editor, token validation tools
• Solicit platform team contributions; announce to community; establish maintenance cadence

Request for Feedback

We're seeking input on:

1. Does this solve the terminology challenges you've experienced?
2. Glossary viewer: Separate section vs. richer registry pages when glossary data is present?
3. Registry vs. token enum sync: How should RFC [DRAFT RFC] Token Schema Structure and Validation System #646 enums consume the registry?
4. What terminology domains should we prioritize next?
5. What concerns or blockers do you foresee?
6. Would you use this glossary in your work? How?

Please comment below with your feedback, questions, or concerns!

Related Links

• RFC #714: Spectrum Design Data Specification (umbrella)
• RFC #715: Distributed Design Data Architecture
• RFC coordination outline (docs/rfc-coordination.md)
• Registry | Spectrum Design Data
• @adobe/design-system-registry (npm)
• RFC #646: Token Schema Structure and Validation System
• PR feat(registry): add Design System Registry package #660: Design System Registry Foundation — feat(registry): add Design System Registry package #660
• Spectrum Naming and Definition Writing Guide
• Spectrum Tokens Wiki
• Issue [Discussion] Open Questions for Component Schema Authoring Tool #658: Component Schema Authoring Tool — [Discussion] Open Questions for Component Schema Authoring Tool #658

Success Metrics

If this RFC is approved and the glossary layer is implemented, we'll measure success by:

1. Completeness: Target coverage of key registries (e.g. 100% of states and anatomy terms with definitions); current: 21 terms with full definitions
2. Adoption: 3+ platform teams using extensions (current: 2 examples)
3. Usage: Regular traffic to Registry docs from Spectrum community
4. Integration: Tools consuming registry/glossary (e.g. MCP server, component-options-editor, token validation)
5. AI Access: MCP glossary tools used by AI assistants; chatbot integration as needed
6. Maintenance: Documented review cadence and ownership for term updates

---

Note: This is a DRAFT RFC. All aspects are open for discussion and refinement based on community feedback.

[GarthDB]

Implementation Update: Phases 0-2 Completed ✅

While gathering feedback on this RFC, we've completed the foundational work for Phases 0-2. Here's what's been implemented:

✅ Phase 1: Enhanced Schema & Content Migration

Enhanced Schema:

• Extended registry-value.json with glossary fields: definition, platforms, terminology, sources, governance, relatedTerms
• All existing registries remain backward compatible
• 36 tests passing, all validation passing

New Content (18 enhanced terms):

• glossary.json - 5 general design system terms (design-token, superordinate, multi-platform-design-system, etc.)
• navigation-terms.json - 7 navigation terms extracted from App Frame wiki
• token-terminology.json - 6 token concepts extracted from Tokens wiki
• Enhanced states.json - Added full definitions for default, hover, keyboard-focus states

Documentation:

• AUTHORING.md - Comprehensive guide for content strategists (350+ lines)
• Following Spectrum Naming and Definition Writing Guide methodology

✅ Phase 2: Platform Extension System

Implementation:

• Created platform-extension.json schema
• Built flexible extension system supporting both centralized and plugin approaches
• Example extensions: ios-states.json, web-components-states.json
• Helper functions: getTermForPlatform(), loadPlatformExtension(), etc.

Documentation:

• PLATFORM_EXTENSIONS.md - Complete guide for platform teams (450+ lines)
• Examples for iOS and Web Components

📊 Current Statistics

Metric	Count
Total registry values	179
Enhanced definitions	21
Registry files	11 (8 original + 3 new)
Platform extensions	2 (iOS, Web Components)
Documentation pages	3 (AUTHORING, PLATFORM_EXTENSIONS, README updates)

🔍 Ready for Review

The foundational work is ready for community review:

• All code in this branch: feat/add-design-system-registry
• Implementation status: GLOSSARY_IMPLEMENTATION_STATUS.md

🎯 Next Steps Based on Feedback

Remaining phases (3-6) will proceed based on RFC feedback:

• Phase 3: Web Viewer (GitHub Pages) - Searchable glossary interface
• Phase 4: LLM Integration - MCP tools + static JSON API
• Phase 5: Content QA - Review with content strategists
• Phase 6: Integration & Rollout - Tool integration, community announcement

💬 Specific Questions for Reviewers

1. Schema Design: Does the enhanced schema meet your needs? Any missing fields?
2. Platform Extensions: Would you prefer centralized contributions or plugin-based extensions for your platform?
3. Content Quality: Review the example definitions in states.json - is this the level of detail we want?
4. Priorities: Which remaining phases are most valuable to your team?

Please review the implementation and provide feedback on the approach before we proceed with the web viewer and broader rollout.

[GarthDB]

Update (March 2026): This discussion body was updated to reflect current state:

• Registry foundation (Phases 0–2) is complete. The @adobe/design-system-registry package and Registry docs are live.
• Phases 0–2 are marked complete with links to deliverables.
• Phases 3–6 are revised: glossary viewer builds on the existing registry docs site; MCP and static API options clarified; Phase 5 includes reconciliation with RFC #646 token schema enums; Phase 6 focuses on integration and rollout.
• New section added: "Connection to RFC [DRAFT RFC] Token Schema Structure and Validation System #646: Token Schema Enums" (registry as canonical source; token enums should consume or validate against it).
• Architecture diagram updated to show registry foundation, glossary layer, and token schema enums as a consumer.
• Open questions updated: authoring workflow and platform extensions resolved; governance, prioritization, and registry/enum sync still open.
• Success metrics updated with current state and targets.

[GarthDB]

Update (March 2026): Linked #714, #715, cascade/dimension alignment with #646, and the coordination doc.

[GarthDB]

Update (April 2026): Alignment with taxonomy naming framework (#806).

Three-registry proposal: The taxonomy work proposes splitting the current anatomy-terms.json (24 terms) into separate registries that serve different validation purposes:

Registry	Purpose	Validates name field
Component Anatomy	Visible named parts of components (from designer specs)	anatomy
Token Objects	Styling surfaces (background, border, edge, visual, content)	object
Taxonomy Categories	Allowed values within each concept category	structure, orientation, position, size, density, shape

Plus existing registries for component, variant, state (unchanged).

Updated RFC #646 connection: The overlap table in the "Connection to RFC #646" section references the original analytical model's 12 enum schemas (800+ values across 9 categories). The spec has since evolved: the name object now uses flat semantic fields aligned with the taxonomy concept categories (structure, substructure, component, anatomy, object, property, variant, state, orientation, position, size, density, shape). The registry reconciliation work (Phase 5) should target these new categories rather than the original analytical enums.

Phase 5 reframing: Content QA and Reconciliation with Token Enums is now shaped by the taxonomy work — specifically the component anatomy audit (133 terms from S2 docs) and the semantic/dimension field split. See spec/taxonomy.md.