[Epic] v1 MVP: Basic Mapping Editor Tool

[GarthDB]

Overview

Build a web-based tool to view and edit schema-to-token mappings with basic validation.

Context

After establishing the schema foundation (#647), we need a tool for designers and developers to author and maintain these mappings without manual JSON editing.

Decisions from #658

• ✅ Property registry for suggestions (not enforcement)
• ✅ Display descriptions prominently (no conditional validation blocking)
• ✅ Chrome-only browser support for v1
• ✅ sessionStorage authentication
• ✅ Component defines size/state subsets from global enums

Goals

1. Create basic web tool infrastructure
2. Load and display component schemas
3. Enable mapping editing
4. Validate mappings

Tasks

Project Setup

• Create tools/component-schema-authoring/ directory
• Initialize with React + TypeScript + Vite
• Add Spectrum Web Components
• Create package.json
  • Set up dependencies
  • Add scripts for dev, build, test
  • Target Chrome browser only
• Create moon.yml for task definitions
• Add ava.config.js for testing
• Set up ESLint and TypeScript config
• Add .gitignore

Schema Loader

• Build schema loading infrastructure

  • Load all component schemas from packages/component-schemas/
  • Parse tokenNaming fields
  • Load size-profiles.json
  • Load global size-values.json and state-values.json enums
  • Load property-registry.json
  • Load enum schemas for validation
  • Add error handling for missing/invalid schemas

• Add Ajv for JSON Schema validation

  • Set up Ajv instance
  • Load component.json schema
  • Validate loaded components against schema

Component List View

• Display list of all components

  • Show component name, category
  • Show mapping status (complete/incomplete/missing)
  • Show anatomy status (defined/missing)
  • Add filtering by category
  • Add search functionality
  • Add sorting options (name, category, status)
  • Show mapping completeness indicator

• Component selection

  • Click to select and view details
  • Highlight selected component
  • Show component count

Property Mapping Editor

• Display component details

  • Show component title and description
  • Show documentation URL link
  • Display all properties

• Property editor interface

  • List all properties with types
  • Show current enum values (e.g., size: ["s", "m", "l", "xl"])
  • Display property descriptions prominently (main way to communicate conditional logic)
  • Show default values

• Add/Edit properties

  • Suggest properties from property-registry.json
  • Allow custom properties
  • Warn (don't block) if property name similar to existing
  • Validate enum values against global enums where applicable

• Size/State enum editor

  • Show global enum values available
  • Allow selecting subset for component
  • Validate selections are from global enum
  • Show validation feedback

• Token mapping editor

  • Display current schema-to-token mappings
  • Allow assigning size profile (standard, compact, extended, typography)
  • Show profile mapping details when selected
  • Allow editing individual mappings
  • Show validation feedback inline
  • Support undo/redo

• Anatomy editor

  • Display current anatomy parts
  • Add/remove anatomy parts
  • Validate against global anatomy-parts.json (if exists)
  • Reorder parts

Validation

• JSON syntax validation

  • Validate JSON structure
  • Show syntax errors

• Schema validation (using Ajv)

  • Validate against component.json schema
  • Check required fields
  • Validate property types

• Custom validation rules

  • Check size enum values are subset of global size-values.json
  • Check state enum values are subset of global state-values.json
  • Check for missing token mappings
  • Validate size profile references exist
  • Check anatomy parts against global enum (warning only)

• Validation UI

  • Show errors prominently (must fix)
  • Show warnings (review but not blocking)
  • Display validation messages with context
  • Link to relevant documentation

Export Functionality

• Generate changed files

  • Create JSON for each modified component
  • Format with proper indentation (2 spaces)
  • Include all required fields

• File diff generation

  • Show before/after for each file
  • Use diff library to generate unified diff
  • Display diff in readable format

• Export package

  • Create downloadable zip of all changes
  • Include directory structure
  • Include README with instructions for manual PR creation
  • List all changed files

• Manual PR instructions

  • Generate step-by-step guide
  • Include branch naming suggestion
  • Include commit message template (conventional commits)
  • Include changeset template

Testing

• Unit tests for schema loader

  • Test loading valid schemas
  • Test error handling for invalid schemas
  • Test parsing tokenNaming fields

• Unit tests for validation logic

  • Test enum subset validation
  • Test schema validation
  • Test mapping validation

• Component tests for UI

  • Test component list rendering
  • Test property editor
  • Test mapping editor
  • Test export functionality

• Integration tests

  • Test full workflow: load → edit → validate → export
  • Test with real component schemas

Success Criteria

• Tool loads all 85 component schemas successfully
• Users can view and edit schema-to-token mappings
• Users can assign size profiles to components
• Users can edit component properties with suggestions from registry
• Property descriptions displayed prominently
• Basic validation catches errors before export
• Users can export changes as zip file for manual PR creation
• Works in Chrome

Dependencies

• [Epic] v1 MVP: Schema Foundation for Token Mapping #647 (Schema Foundation must be complete)
• React
• Vite
• TypeScript
• Spectrum Web Components
• Ajv (JSON Schema validation)

Estimated Effort

2-3 weeks

UI Mockup Concept

┌────────────────────────────────────────────────────┐
│  Component Schema Authoring Tool                   │
├─────────────┬──────────────────────────────────────┤
│ Components  │  Component: button                   │
│             │                                      │
│ [Search]    │  Properties                          │
│             │  ┌───────────────────────────────┐   │
│ ☑ button    │  │ size: ["s","m","l","xl"]       │   │
│ ☐ text-field│  │ From global: [xs,s,m,l,xl,xxl,xxxl]│   │
│ ☐ checkbox  │  │                               │   │
│             │  │ Token Mapping:                │   │
│             │  │ Profile: [standard ▼]         │   │
│             │  │ s → small                     │   │
│             │  │ m → medium                    │   │
│             │  │ l → large                     │   │
│             │  │ xl → extra-large              │   │
│             │  └───────────────────────────────┘   │
│             │                                      │
│             │  Anatomy                             │
│             │  • button-control                    │
│             │  • icon                              │
│             │  • label                             │
│             │  [+ Add Part]                        │
│             │                                      │
│             │  [Export Changes]                    │
└─────────────┴──────────────────────────────────────┘

Related

• [Epic] v1 MVP: Schema Foundation for Token Mapping #647 (Schema Foundation)
• [Discussion] Open Questions for Component Schema Authoring Tool #658 (Decisions)
• Figma Plugin POC Analysis (reuse patterns)
• Component Schema Analysis