[Discussion] Open Questions for Component Schema Authoring Tool

[GarthDB]

Overview

Key questions that need team discussion and decision before/during implementation.

✅ DECISIONS MADE

1. Schema Versioning Strategy

Decision: Package.json semver is sufficient

• Use normal semver rules when profiles change
• No UUIDs needed at this time (revisit if Figma sync or external tool integration needed)
• Multiple versions not supported simultaneously, but users can reference older package versions if needed
• Primary users: Spectrum Designers authoring data + Spectrum website pulling from npm package

2. State Property Standardization

Decision: Global enum with component-specific subsets

• Create global state-values.json enum with all allowable states
• Create global size-values.json enum with all allowable size values
• Components define their own subset from the global enum
• No state/size profiles for schema structure - profiles only used for tokenNaming mappings
• Allows flexibility while ensuring naming consistency

Example:

// Global enum
{"enum": ["default", "hover", "down", "keyboard-focus", "pending"]}

// Component uses subset
{"state": {"enum": ["default", "hover", "down"]}}

3. Variant Property Semantics

Decision: Keep generic variant

• Maintain single variant property
• Options within variant must be mutually exclusive
• Document meaning per component
• No split into colorVariant, layoutVariant, etc.

4. Conditional Validation

Decision: Use descriptions for now, defer UI complexity

• Not blocking in v1
• Use clear descriptions to communicate rules (e.g., "Icon must be present if label is not defined")
• Authoring UI should display descriptions prominently
• Consider validation warnings in v2+ if needed

5. Shared Property Groups

Decision: Property registry for guidance, not enforcement

• Create property-registry.json with common properties
• Authoring tool suggests properties from registry
• Allow custom properties for component-specific needs
• Validation warnings (not blockers) for similar property names
• Future: Link to anatomy terms and token options

6. Performance Targets

Decision: Anything reasonable

• No strict targets for v1
• Monitor and optimize as needed

7. Browser Support

Decision: Chrome for now

• Focus on Chrome for initial release
• Expand browser support in later versions

8. Authentication Strategy

Decision: sessionStorage by default

• Use sessionStorage (cleared on tab close) for v1
• More secure, appropriate for work context
• Optional "remember me" with encrypted localStorage in v2 if requested

9. Merge Conflict Handling

Decision: Manual engineering process

• Engineers handle conflicts manually in GitHub repo
• Tool doesn't need automated conflict resolution for v1

10. Profile Approval Process

Decision: GitHub repo settings/permissions

• Use standard GitHub review process
• Configure via repo settings and branch protection

11. Breaking Change Policy

Decision: Standard semver major release

• Breaking changes trigger major version bump
• Include release notes describing what's breaking and migration path
• Follow standard semver practices

12. RFC #646 Token Validation

Decision: Not yet, keep in mind for future

• Not implementing in v1
• Consider when expanding to component anatomy editor
• Consider when building token editor/namer tool

13. RFC #624 Multi-Platform Timing

Decision: Not yet, keep in mind for future

• Not needed immediately
• Keep platform support in mind for future architecture

14. User Testing Timeline

Decision: Managed by Spectrum Design Team

• Team will coordinate user testing when ready
• No specific timeline set yet

15. Success Metrics Tracking

Decision: User testing feedback for now

• Rely on qualitative feedback from user testing
• No analytics implementation needed for v1

---

Implementation Impact

These decisions affect the following issues:

#647 - Schema Foundation

• Create size-values.json and state-values.json global enums
• Size profiles used ONLY for tokenNaming field (mapping schema values to token options)
• Components define their own subsets from global enums
• No UUIDs needed

#648 - Basic Mapping Editor Tool

• Create property registry for suggestions (not enforcement)
• Display component descriptions prominently in UI
• No conditional validation blocking in v1
• Chrome-only browser support
• sessionStorage authentication

#656 - Deployment & Documentation

• Chrome-only deployment target
• Document the global enum + subset pattern
• Document property registry usage

---

Related

• [META] Component Schema Authoring Tool - Project Tracking #657 (Meta tracking issue)
• All planning documents in .cursor/plans/