[DRAFT RFC] Spectrum Design System Glossary

[GarthDB]

[DRAFT RFC] Spectrum Design System Glossary

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)

• Extend existing registry (PR feat(registry): add Design System Registry package #660) with rich definitions
• Follow Spectrum Naming and Definition Writing Guide methodology
• Include superordinate, description, essential characteristics
• Multi-platform terminology support
• Governance metadata (owners, review dates, status)

2. Platform Extension System

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

3. Web Viewer (GitHub Pages)

• Searchable, browsable glossary interface
• Category navigation, cross-references, export capabilities
• Mobile-responsive and accessible (WCAG 2.1 AA)
• Deployed to: https://adobe.github.io/spectrum-design-data/glossary/

4. LLM Integration

• Enhanced MCP server with glossary tools
• Static JSON HTTP API for chatbots (MrFluffyJaws, etc.)
• 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.)

Architecture Overview

graph TB
    subgraph authoring [Content Authoring Layer]
        github[GitHub JSON/MD Files]
        future[Future: Web CMS]
    end
    
    subgraph core [Core Data Layer]
        registry[Design System Registry]
        glossary[Glossary Definitions]
        platform[Platform Extensions]
    end
    
    subgraph consumption [Consumption Layer]
        viewer[Web Viewer GitHub Pages]
        mcp[MCP Server Tools]
        json[Static JSON HTTP API]
        validation[Validation Tools]
    end
    
    subgraph platforms [Platform Teams]
        ios[Spectrum iOS]
        qt[Spectrum Qt]
        web[Web Components]
        react[React Spectrum]
    end
    
    github --> registry
    github --> glossary
    platforms --> platform
    
    registry --> viewer
    registry --> mcp
    registry --> json
    registry --> validation
    
    glossary --> viewer
    glossary --> mcp
    glossary --> json
    
    platform --> viewer
    platform --> mcp
    
    future -.future.-> glossary

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

• Option A: Start with GitHub JSON editing (simple, immediate)
• Option B: Build web CMS from the start (user-friendly, requires development)
• Recommendation: Hybrid approach - start with GitHub, evolve to web interface later

2. Platform Extensions

• Option A: Platforms contribute to central registry (single source of truth)
• Option B: Separate extension packages (decentralized, platform autonomy)
• Option C: Support both patterns
• Question: What would platform teams prefer?

3. Maintenance & Governance

• 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

• Start with design tokens and component terminology?
• Include anatomy terms immediately?
• Add product-specific terminology later?
• What domains should we prioritize first?

Implementation Plan

Phase 0: RFC and Community Feedback

You are here - Gather feedback, refine approach, achieve consensus

Phase 1: Enhanced Schema & Content Migration

• Enhance registry schema with definitions, platforms, governance
• Extract content from wiki sources
• Create authoring documentation

Phase 2: Platform Extension System

• Design extension schema and validation
• Create helper functions and documentation
• Build example extensions

Phase 3: Web Viewer

• Build searchable glossary interface
• Deploy to GitHub Pages
• Integrate with existing docs

Phase 4: LLM Integration

• Add glossary tools to MCP server
• Create static JSON API
• Enable AI assistant access

Phase 5: Content QA

• Review with content strategists
• Verify cross-references and accuracy

Phase 6: Integration & Rollout

• Integrate with existing tools
• Announce to community
• Establish maintenance workflow

Request for Feedback

We're seeking input on:

1. Does this solve the terminology challenges you've experienced?
2. What are your preferences for authoring workflow (GitHub vs. web interface)?
3. How would you like platform extensions to work?
4. What terminology domains should we prioritize first?
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

• 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 implemented, we'll measure success by:

1. Completeness: 100+ terms with full definitions
2. Adoption: 3+ platform teams using extensions
3. Usage: Regular web viewer traffic from Spectrum community
4. Integration: 5+ tools consuming glossary programmatically
5. AI Access: MCP tools used by AI assistants, chatbot integration verified
6. Maintenance: Monthly content review by content strategists

---

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.