[v1] Deployment to GitHub Pages & Documentation

[GarthDB]

Overview

Deploy the component schema authoring tool to GitHub Pages and create comprehensive documentation.

Context

Tool needs to be accessible to designers and developers without local setup. Static hosting on GitHub Pages is free and requires no infrastructure.

Decisions from #658

• ✅ Chrome-only browser support for v1
• ✅ sessionStorage authentication
• ✅ Document global enum + subset pattern
• ✅ Document property registry usage

Goals

1. Deploy tool to GitHub Pages
2. Automated deployment pipeline
3. Comprehensive documentation
4. User onboarding

Tasks

GitHub Pages Deployment

• Set up GitHub Pages

  • Configure gh-pages branch
  • Set up custom domain (optional)
  • Configure GitHub Pages settings
  • Test deployment
  • Add browser requirement notice (Chrome)

• Create deployment workflow

  • Add GitHub Actions workflow for auto-deployment
  • Build static bundle with Vite
  • Run tests before deployment
  • Deploy on push to main branch
  • Add deployment status badge

• Optimize for production

  • Minimize bundle size
  • Configure caching strategy
  • Add error tracking (Sentry or similar - optional)
  • Set up analytics (optional)

User Documentation

• Write getting started guide

  • System requirements (Chrome browser)
  • How to access the tool
  • Overview of features
  • Quick start tutorial

• Document the schema patterns

  • Explain global enums (size-values.json, state-values.json)
  • Explain component subsets
  • Explain size profiles (for token mapping only)
  • Explain tokenNaming field structure
  • Explain anatomy field

• Document property registry

  • How to use property suggestions
  • When to create custom properties
  • Common property patterns
  • Validation warnings

• Create step-by-step tutorials

  • Tutorial: Adding token mapping to a component
  • Tutorial: Defining component anatomy
  • Tutorial: Creating a new component schema
  • Tutorial: Editing size/state enums
  • Tutorial: Exporting changes and creating PR

• Add FAQ section

  • Common questions about schema structure
  • Troubleshooting validation errors
  • How to handle browser issues

• Create troubleshooting guide

  • Schema validation errors
  • Export issues
  • Browser compatibility (Chrome only for v1)

Developer Documentation

• Write architecture overview

  • Project structure
  • Key components
  • Data flow
  • Schema loading system

• Document schema structure

  • component.json schema
  • size-profiles.json structure
  • property-registry.json structure
  • Global enum files
  • tokenNaming field details

• Create contributing guide

  • How to set up dev environment
  • Coding standards
  • How to add new features
  • Testing requirements

• Write API documentation

  • Schema loader API
  • Validation API
  • Export API
  • Component loading functions from @packages/component-schemas/index.js

• Add testing guide

  • Running tests
  • Writing new tests
  • Test coverage expectations

• Create deployment guide

  • Manual deployment steps
  • GitHub Actions workflow
  • Rollback procedures

Schema Documentation

• Document global enum pattern

  • How global enums work
  • How components define subsets
  • Why this pattern (flexibility + consistency)
  • Examples

• Document size profiles

  • Purpose: token mapping ONLY, not schema structure
  • Available profiles (standard, compact, extended, typography)
  • When to use each profile
  • How to reference in tokenNaming

• Document tokenNaming field

  • Field structure
  • propertyToOptionMapping usage
  • Size profile references
  • Schema-to-token mapping examples

• Document anatomy field

  • Purpose and usage
  • Valid anatomy parts
  • How anatomy relates to tokens

• Provide examples

  • Button component (standard size profile)
  • Action button (extended size profile)
  • Heading (typography profile)
  • Custom size patterns

• Document property registry

  • Purpose (guidance, not enforcement)
  • Common properties
  • How tool uses registry for suggestions

In-App Help

• Add tooltips for all UI elements

  • Component list view
  • Property editor
  • Mapping editor
  • Validation messages
  • Export functionality

• Create contextual help panels

  • What are size profiles?
  • What is tokenNaming?
  • What is anatomy?
  • How to fix validation errors

• Link to documentation

  • Help icon in header
  • Links from validation messages
  • Links from tooltips

• Add keyboard shortcuts guide

  • Common actions
  • Navigation shortcuts

Onboarding Flow

• Create first-run tutorial

  • Welcome screen
  • Feature overview
  • Sample component walkthrough

• Build interactive walkthrough

  • Select a component
  • View properties
  • Edit mapping
  • View validation
  • Export changes

• Add sample components

  • Pre-loaded examples
  • Demonstrate different patterns
  • Show best practices

Testing

• Test deployment

  • Test on Chrome (primary target)
  • Test on slow connections
  • Test error scenarios
  • Verify documentation links work
  • Test GitHub Pages URL access

• Documentation review

  • Technical accuracy
  • Clarity for designers
  • Completeness
  • Working code examples

Success Criteria

• Tool accessible at GitHub Pages URL
• Deployment happens automatically on merge to main
• Documentation covers all major features
• New users can start using tool within 5 minutes
• Zero deployment downtime
• Clear browser requirement notice (Chrome)
• Global enum + subset pattern well documented
• Property registry usage explained

Browser Support

v1: Chrome only

• Focus on getting core functionality working
• Expand to other browsers in future versions

Dependencies

• [Epic] v1 MVP: Schema Foundation for Token Mapping #647 (Schema Foundation for documentation)
• [Epic] v1 MVP: Basic Mapping Editor Tool #648 (Basic tool must be complete)

Estimated Effort

1-2 weeks

Documentation Structure

docs/
├── user-guide/
│   ├── getting-started.md
│   ├── schema-patterns.md
│   ├── tutorials/
│   │   ├── adding-token-mapping.md
│   │   ├── defining-anatomy.md
│   │   └── creating-component.md
│   └── faq.md
├── developer-guide/
│   ├── architecture.md
│   ├── contributing.md
│   ├── api-reference.md
│   └── testing.md
└── schema-reference/
    ├── global-enums.md
    ├── size-profiles.md
    ├── tokenNaming-field.md
    ├── anatomy-field.md
    └── property-registry.md

Related

• [Epic] v1 MVP: Schema Foundation for Token Mapping #647 (Schema Foundation)
• [Epic] v1 MVP: Basic Mapping Editor Tool #648 (Basic Tool)
• [Discussion] Open Questions for Component Schema Authoring Tool #658 (Decisions)
• Deployment Architecture Analysis