Design System Documentation
Component library, design tokens, and usage guidelines
Color Tokens
All colors are defined as CSS custom properties. Use var(--token) syntax. Never hardcode hex values.
| Token | Preview | Usage |
|---|
Typography
Type scale and font families used across the system.
| Token | Value | Usage |
|---|
Heading 1 (28px/700)
Heading 2 (20px/700)
Heading 3 (16px/600)
Body text (14px/400)
Small text (12px/400)
Monospace: var(--mono)
Spacing & Radius
Consistent spacing tokens for margins, padding, and border radius.
| Token | Value | Usage |
|---|
Buttons
Button variants for different actions and contexts.
Standard Variants
Primary for main actions, secondary for alternatives, danger for destructive actions.
Sizes
Three size options: small (sm), default, and large (lg).
Inputs
Form input components with focus states.
Text Input
Standard text fields with border, focus ring using --circuit color.
Select & Textarea
Dropdown and multiline input components.
Badges
Status and label indicators.
Info
Success
Warning
Danger
Status Badges
Semantic badges using dim background with matching color text.
Alerts
Contextual feedback messages.
Info: This is an informational alert message.
Success: Operation completed successfully.
Warning: Please review before continuing.
Error: Something went wrong. Please try again.
Cards
Content container components.
Card Title
Cards use --bg-card background with --border and --shadow-sm for subtle elevation.
Stat Card
42.5%
Used for KPI and metric displays.
Accessibility Specs
WCAG 2.1 AA compliance guidelines for the design system.
Color Contrast
Minimum 4.5:1 for body text, 3:1 for large text (18px+ bold or 24px+ regular)
Focus Indicators
All interactive elements have visible focus rings using box-shadow: 0 0 0 3px var(--circuit-dim)
Touch Targets
Minimum 44x44px touch target for mobile. Buttons have minimum padding of 8px 16px.
Motion
Respect prefers-reduced-motion. All animations use var(--duration) for consistency.
Keyboard Navigation
All interactive elements are keyboard accessible with logical tab order.
ARIA Labels
Icon-only buttons require aria-label. Form inputs require associated labels.
Usage Guidelines
Best practices for using the design system components.
Do
Use CSS custom properties (var(--xxx)) for all colors and spacing. Keep components consistent across templates. Follow the established naming conventions for CSS classes. Test in both light and dark themes.
Do Not
Hardcode hex color values in component styles. Override theme tokens with inline styles. Use font-family declarations instead of var(--sans) or var(--mono). Skip mobile responsive breakpoints.