Tokens

Token Categories

/* Color tokens */
--color-gray-{50-900}    /* Neutral scale */
--color-primary          /* Brand action */
--color-success          /* Positive feedback */
--color-warning          /* Caution */
--color-error            /* Negative feedback */

/* Spacing tokens */
--space-{1-12}           /* 4px base: 4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80, 96 */

/* Typography tokens */
--font-family-{sans,mono}
--font-size-{xs,sm,base,lg,xl,2xl,3xl,4xl}
--font-weight-{normal,medium,semibold,bold}
--line-height-{tight,normal,relaxed}

/* Border tokens */
--radius-{sm,md,lg,xl,full}
--border-width-{1,2}

/* Shadow tokens */
--shadow-{sm,md,lg,xl}

/* Motion tokens */
--duration-{instant,fast,normal,slow}
--ease-{in,out,in-out}

Token File Format

// tokens.json (source of truth)
{
  "color": {
    "primary": {
      "value": "#3b82f6",
      "description": "Primary brand color for actions",
      "type": "color"
    }
  },
  "space": {
    "4": {
      "value": "16px",
      "description": "Standard component spacing",
      "type": "dimension"
    }
  }
}

Documentation Structure

Component Documentation

Every component needs:

# Button

Primary action element.

## Usage

Use buttons to trigger actions. One primary button per view.

## Variants

| Variant | Use Case |
|---------|----------|
| Primary | Main action |
| Secondary | Alternate action |
| Ghost | Subtle action |
| Destructive | Delete/remove |

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| label | string | required | Button text |
| variant | enum | primary | Visual style |
| disabled | boolean | false | Disables interaction |

## States

- Default
- Hover
- Active
- Focus
- Disabled
- Loading

## Accessibility

- Requires visible focus state
- Use `aria-disabled` over `disabled` attribute
- Loading state needs `aria-busy="true"`

## Examples

[Live examples with code]

## Changelog

- 2.1.0: Added loading state
- 2.0.0: Breaking - removed `size` prop (use CSS)
- 1.0.0: Initial release

System Documentation

docs/
├── getting-started/
│   ├── installation.md
│   ├── quick-start.md
│   └── migration.md
├── foundations/
│   ├── color.md
│   ├── typography.md
│   ├── spacing.md
│   └── motion.md
├── components/
│   ├── atoms/
│   ├── molecules/
│   └── organisms/
├── patterns/
│   ├── forms.md
│   ├── navigation.md
│   └── data-display.md
└── contributing/
    ├── proposing-changes.md
    ├── component-checklist.md
    └── release-process.md

Versioning

Semantic Versioning

MAJOR.MINOR.PATCH

1.0.0 → 1.0.1  PATCH: Bug fix, no API change
1.0.0 → 1.1.0  MINOR: New feature, backward compatible
1.0.0 → 2.0.0  MAJOR: Breaking change

Breaking Changes

Breaking:

• Removing a component
• Removing a prop
• Changing prop type
• Renaming a token
• Changing token value significantly

Not Breaking:

• Adding a component
• Adding a prop with default
• Bug fixes
• Adding a token

Deprecation Path

<!-- Phase 1: Warn -->
<Button size="large">  <!-- Console warning: size prop deprecated, use CSS -->

<!-- Phase 2: Document alternative -->
Before: <Button size="large">
After:  <Button className="btn-lg">

<!-- Phase 3: Remove in next major -->
v2.0.0: size prop removed

Release Process

Checklist

## Release Checklist

### Pre-release
- [ ] All changes documented
- [ ] Breaking changes identified
- [ ] Migration guide written (if major)
- [ ] Visual regression tests pass
- [ ] Accessibility audit complete
- [ ] Token changes reviewed

### Release
- [ ] Version bumped
- [ ] Changelog updated
- [ ] Package published
- [ ] Documentation updated
- [ ] Announcement sent

### Post-release
- [ ] Monitor for issues
- [ ] Respond to feedback
- [ ] Track adoption metrics

Contribution Process

Proposing Changes

## Component Proposal

### Problem
[What problem does this solve?]

### Solution
[Proposed component/change]

### Scope
- [ ] New component
- [ ] Component modification
- [ ] Token change
- [ ] Documentation only

### Impact
- Teams affected:
- Breaking changes: Yes/No
- Migration required: Yes/No

### Alternatives Considered
[Other approaches and why rejected]

Review Criteria

## Component Review Checklist

### Design
- [ ] Follows design system patterns
- [ ] Uses existing tokens
- [ ] Has documented variants and states
- [ ] Responsive behavior defined

### Development
- [ ] Accessible (WCAG 2.1 AA)
- [ ] Tested in target browsers
- [ ] No external dependencies
- [ ] Follows naming conventions

### Documentation
- [ ] Usage guidelines
- [ ] Props documented
- [ ] Examples provided
- [ ] Changelog entry

Metrics

Track system health:

Anti-Patterns

Curtis Score

Integration

Combine with:

• /components - Component structure this governs
• /handoff - Handoff process this documents
• All other UI skills - This governs their output