[META] Component Schema Authoring Tool - Project Tracking

[GarthDB]

Project Overview

Build a web-based authoring tool for component schemas that addresses the critical gap between component schema enum values and token option names.

Problem Statement

• Component schemas use abbreviated values: s, m, l, xl
• Token names use full words: small, medium, large, extra-large
• No explicit mapping exists between these values
• 26 components duplicate identical size patterns
• Manual JSON editing is error-prone and inconsistent

Solution

A web-based authoring tool that:

1. Establishes explicit schema-to-token mappings
2. Creates reusable size profiles for consistency
3. Provides validation and consolidation features
4. Enables automated GitHub PR workflow
5. Runs entirely in browser (zero infrastructure cost)

Architecture

• Frontend: React + TypeScript + Vite
• UI: Spectrum Web Components
• Git: isomorphic-git (browser-based)
• API: @octokit/rest (GitHub API)
• Deployment: Static GitHub Pages
• Authentication: GitHub OAuth Device Flow

Implementation Plan

Planning & Discussion

• [Discussion] Open Questions for Component Schema Authoring Tool #658

v1 MVP (Must Have) - 4-6 weeks

• [Epic] v1 MVP: Schema Foundation for Token Mapping #647
• [Epic] v1 MVP: Basic Mapping Editor Tool #648
• [v1] Deployment to GitHub Pages & Documentation #656

v2 (Should Have) - 10-14 weeks

• [v2] Full Validation Dashboard #649
• [v2] Consolidation Features #650
• [v2] Anatomy Editor #651
• [v2] Automated GitHub PR Creation Workflow #652

v3+ (Nice to Have) - Future

• [v3] Figma Plugin Companion Tool #653
• [v3] Platform-Specific Size Profiles #654
• [v3] Advanced Batch Operations & Analytics #655

Success Metrics

1. Completeness: 100% of components have explicit schema-to-token mappings
2. Consolidation: 26+ components use shared size profiles (reduce duplication)
3. Adoption: 80%+ of schema changes made via tool (vs manual editing)
4. Quality: 95%+ validation pass rate for all components
5. Efficiency: 80%+ time saved vs manual JSON editing
6. Cost: Zero infrastructure costs (static hosting)

Strategic Alignment

• RFC [DRAFT RFC] Token Schema Structure and Validation System #646: Fills the schema-to-token mapping gap
• RFC [DRAFT RFC] Token Authoring Workflow and Process #625: Enables structured authoring workflow
• RFC [DRAFT RFC] Component Schema Feedback Automation Pipeline #642: Provides maintenance process for component schemas
• RFC [DRAFT RFC] Token Structure Changes for Multi-Platform Support #624: Prepares for multi-platform support

User Personas

• Designers: Need simple UI to author component options (Figma plugin in v3)
• Developers: Need full control, validation, GitHub integration (web tool)
• Token Maintainers: Need schema-token consistency (validation features)

Dependencies

• React, Vite, TypeScript
• Spectrum Web Components
• isomorphic-git + Lightning FS
• @octokit/rest
• Ajv (JSON Schema validation)
• diff2html

Risks & Mitigations

Risk	Likelihood	Impact	Mitigation
Browser storage limits	Medium	Medium	Monitor usage, clear old clones, repo is only ~10MB
Git operations fail	High	High	Comprehensive error handling, fallback export
User adoption low	Medium	High	User testing, clear docs, designer outreach
Merge conflicts	Medium	Medium	Auto-sync, clear error messages
OAuth complexity	Low	Medium	Clear UI, good error messages

Related Documents

• Main Plan: .cursor/plans/figma_plugin_poc_for_token_spec_authoring_067bdbb4.plan.md
• Component Schema Analysis: .cursor/plans/component-schema-analysis.md
• GitHub PR Workflow: .cursor/plans/github-pr-workflow-design.md
• Deployment Architecture: .cursor/plans/deployment-architecture-analysis.md
• RFC Context: .cursor/plans/rfc-context-summary.md
• POC Analysis: .cursor/plans/figma-plugin-poc-analysis.md

Status

🟡 Planning Complete - Ready to begin implementation with #647

[GarthDB]

Created Issues

All sub-issues have been created and organized by priority:

📋 Planning & Discussion

• [Discussion] Open Questions for Component Schema Authoring Tool #658 - Open Questions for Team Discussion

🎯 v1 MVP (Must Have) - 4-6 weeks

Critical foundation and basic functionality:

1. [Epic] v1 MVP: Schema Foundation for Token Mapping #647 - Schema Foundation for Token Mapping (1-2 weeks)

   • Complete component-options.json enum
   • Create size-profiles.json
   • Extend component.json schema
   • Update example components

2. [Epic] v1 MVP: Basic Mapping Editor Tool #648 - Basic Mapping Editor Tool (2-3 weeks)

   • Set up web tool project
   • Load and display schemas
   • Edit mappings and profiles
   • Export functionality

3. [v1] Deployment to GitHub Pages & Documentation #656 - Deployment & Documentation (1-2 weeks)

   • Deploy to GitHub Pages
   • User and developer docs
   • Onboarding flow

🚀 v2 (Should Have) - 10-14 weeks

Advanced features for power users:

4. [v2] Full Validation Dashboard #649 - Full Validation Dashboard (2-3 weeks)

   • Comprehensive validation
   • Quick fixes
   • Validation reports

5. [v2] Consolidation Features #650 - Consolidation Features (3-4 weeks)

   • Detect duplicate patterns
   • Bulk operations
   • Consolidation recommendations

6. [v2] Anatomy Editor #651 - Anatomy Editor (2-3 weeks)

   • Edit anatomy parts
   • Validate against global enum
   • Usage tracking

7. [v2] Automated GitHub PR Creation Workflow #652 - Automated GitHub PR Creation (3-4 weeks)

   • Browser-based git operations
   • GitHub OAuth
   • Automated commits and PRs

✨ v3+ (Nice to Have) - Future

Polish and advanced features:

8. [v3] Figma Plugin Companion Tool #653 - Figma Plugin Companion (3-4 weeks)

   • Lightweight plugin for designers
   • Export to web tool

9. [v3] Platform-Specific Size Profiles #654 - Platform-Specific Profiles (3-4 weeks)

   • Support RFC [DRAFT RFC] Token Structure Changes for Multi-Platform Support #624 multi-platform
   • Platform-specific overrides

10. [v3] Advanced Batch Operations & Analytics #655 - Advanced Batch Operations & Analytics (4-5 weeks)

    • Batch operations
    • Analytics dashboard
    • Historical tracking

---

Recommended Implementation Order

Phase 1 (Start Now):

1. Review [Discussion] Open Questions for Component Schema Authoring Tool #658 questions with team → Make decisions
2. Begin [Epic] v1 MVP: Schema Foundation for Token Mapping #647 (Schema Foundation)

Phase 2 (After Schema Foundation):
3. Start #648 (Basic Tool)
4. Parallel: #656 (Deployment setup)

Phase 3 (After Basic Tool):
5. Choose 2-3 v2 features based on priority and feedback

---

Quick Links

• 📝 Planning docs: .cursor/plans/
• 🎯 Start here: [Epic] v1 MVP: Schema Foundation for Token Mapping #647
• ❓ Discuss: [Discussion] Open Questions for Component Schema Authoring Tool #658

[GarthDB]

✅ Decisions Finalized

All key decisions from #658 have been made and documented. Key issues have been updated:

Updated Issues

• [Discussion] Open Questions for Component Schema Authoring Tool #658 - All 15 questions answered and decisions documented

• [Epic] v1 MVP: Schema Foundation for Token Mapping #647 - Schema Foundation updated with new approach:

  • Global enums (size-values.json, state-values.json)
  • Size profiles for tokenNaming only (not schema structure)
  • Components define their own subsets from global enums
  • Property registry created

• [Epic] v1 MVP: Basic Mapping Editor Tool #648 - Basic Tool updated with:

  • Property registry for suggestions (not enforcement)
  • Prominent description display
  • Chrome-only support
  • sessionStorage authentication

• [v1] Deployment to GitHub Pages & Documentation #656 - Deployment updated with:

  • Chrome-only target
  • Documentation of new patterns

Key Architecture Decisions

1. Global Enums + Component Subsets: Components choose their enum values from global size-values.json and state-values.json, ensuring naming consistency while maintaining flexibility

2. Size Profiles for Token Mapping Only: Profiles like standard, compact, extended are used ONLY in the tokenNaming field to map schema values to token options, NOT for defining component schema structure

3. Property Registry: Guidance system that suggests common properties without enforcing them, reducing property proliferation while allowing component-specific needs

4. Descriptions for Conditional Logic: Use clear descriptions (e.g., "Icon must be present if label is not defined") displayed prominently in UI, deferring complex validation to v2

Ready to Begin

✅ #647 (Schema Foundation) has no blockers and can begin immediately

Example Pattern

// button.json showing the new pattern
{
  "properties": {
    "size": {
      "enum": ["s", "m", "l", "xl"],  // Subset from global size-values.json
      "default": "m"
    }
  },
  "anatomy": ["button-control", "icon", "label"],
  "tokenNaming": {
    "propertyToOptionMapping": {
      "size": {
        "sizeProfile": "standard",  // References size-profiles.json
        "schemaToToken": {
          "s": "small",
          "m": "medium",
          "l": "large",
          "xl": "extra-large"
        }
      }
    }
  }
}