[Epic] v1 MVP: Schema Foundation for Token Mapping

[GarthDB]

Overview

Establish the schema foundation that enables explicit schema-to-token mapping, addressing the critical gap identified in RFC #646.

Context

• 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 share identical size patterns but each defines them separately

Decisions from #658

• ✅ Global enums for size and state values (not profiles for schema structure)
• ✅ Size profiles used ONLY for tokenNaming field mappings
• ✅ Components define their own subsets from global enums
• ✅ No UUIDs needed
• ✅ Package.json semver is sufficient

Goals

1. Create global enums for size and state values
2. Create size profiles for token mapping (NOT schema structure)
3. Extend component schema structure
4. Update example components

Tasks

Global Enums

• Create packages/structured-tokens/schemas/enums/size-values.json

  • Define all allowable size values: xs, s, m, l, xl, xxl, xxxl
  • Add description and documentation
  • Add regex pattern if needed for validation

• Create packages/component-schemas/schemas/enums/state-values.json

  • Define all allowable state values
  • Include: default, hover, down, keyboard-focus, focus-hover, focus-not-hover, pending
  • Add description and documentation
  • Remove spaces from multi-word states (use kebab-case)

• Update component-options.json

  • Add extra-small (for xs)
  • Add extra-extra-large (for xxl)
  • Add extra-extra-extra-large (for xxxl)
  • Validate against existing token usage

Size Profiles (Token Mapping Only)

• Create packages/component-schemas/schemas/size-profiles.json
  • Define standard profile mapping: {"s": "small", "m": "medium", "l": "large", "xl": "extra-large"}
  • Define compact profile mapping: {"s": "small", "m": "medium", "l": "large"}
  • Define extended profile mapping: {"xs": "extra-small", "s": "small", "m": "medium", "l": "large", "xl": "extra-large"}
  • Define typography profile mapping: {"xs": "extra-small", ..., "xxxl": "extra-extra-extra-large"}
  • Add usedBy tracking arrays
  • Note: Profiles are for tokenNaming field only, NOT for defining component schema structure

Base Component Schema

• Extend packages/component-schemas/schemas/component.json

  • Add tokenNaming field structure:

    "tokenNaming": {
      "type": "object",
      "properties": {
        "propertyToOptionMapping": {
          "type": "object",
          "description": "Maps component schema enum values to token option names"
        }
      }
    }

  • Add anatomy array field
  • Make fields optional for backward compatibility
  • Document usage and examples

• Create packages/component-schemas/schemas/property-registry.json

  • Define common properties (label, size, state, etc.)
  • Link to global enums where applicable
  • Add descriptions and common usage patterns
  • Note: This is for tooling guidance, not enforcement

Example Component Updates

• Update button.json

  • Size enum uses subset from global: ["s", "m", "l", "xl"]
  • Add tokenNaming with size profile reference: {"size": {"sizeProfile": "standard"}}
  • Add anatomy array: ["button-control", "icon", "label"]
  • State enum uses subset from global

• Update text-field.json

  • Same pattern as button
  • Reference standard size profile

• Update menu.json

  • Same pattern as button
  • Reference standard size profile

• Update checkbox.json

  • Same pattern as button
  • Reference standard size profile

• Update action-button.json

  • Size enum: ["xs", "s", "m", "l", "xl"]
  • Reference extended size profile

• Update heading.json

  • Size enum: ["xs", "s", "m", "l", "xl", "xxl", "xxxl"]
  • Reference typography size profile

Validation & Testing

• Add validation tests

  • Test that component size enums are subsets of global enum
  • Test that component state enums are subsets of global enum
  • Test size profile mappings are valid
  • Test tokenNaming structure validation
  • Test backward compatibility (components without new fields)

• Update package exports

  • Ensure index.js can load new files
  • Export helper functions for validation

Success Criteria

• Global size-values.json and state-values.json enums created
• All 26 components with standard size pattern reference standard profile in tokenNaming
• Complete component-options.json includes all size values
• 6 example components demonstrate the new structure
• All tests pass with backward compatibility maintained
• Components define their own size/state subsets (NOT referencing profiles for schema structure)

Example Structure

// button.json
{
  "properties": {
    "size": {
      "type": "string",
      "enum": ["s", "m", "l", "xl"],  // Subset from global size-values.json
      "default": "m"
    },
    "state": {
      "type": "string",
      "enum": ["default", "hover", "down", "keyboard-focus"],  // Subset from global state-values.json
      "default": "default"
    }
  },
  "anatomy": ["button-control", "icon", "label"],
  "tokenNaming": {
    "propertyToOptionMapping": {
      "size": {
        "sizeProfile": "standard",  // References size-profiles.json for token mapping
        "schemaToToken": {
          "s": "small",
          "m": "medium",
          "l": "large",
          "xl": "extra-large"
        }
      }
    }
  }
}

Dependencies

• None (foundational work)

Estimated Effort

1-2 weeks

Related

• [Discussion] Open Questions for Component Schema Authoring Tool #658 (Decisions documented)
• [Epic] v1 MVP: Basic Mapping Editor Tool #648 (Tool will use these schemas)
• RFC [DRAFT RFC] Token Schema Structure and Validation System #646: Token Schema Structure
• Component Schema Analysis document