assets/design_system_doc_template.md
Design System Documentation
System Info
| Field | Value | |-------|-------| | Name | [Design System Name] | | Version | [X.Y.Z] | | Owner | [Team/Person] | | Status | Active / Beta / Deprecated | | Last Updated | YYYY-MM-DD |
Design Principles
The following principles guide all design decisions in this system:
-
[Principle 1 Name] - [One sentence description. Example: "Clarity over cleverness - every element should have an obvious purpose."]
-
[Principle 2 Name] - [One sentence description. Example: "Consistency breeds confidence - similar actions should look and behave the same."]
-
[Principle 3 Name] - [One sentence description. Example: "Accessible by default - every component must meet WCAG 2.1 AA standards."]
-
[Principle 4 Name] - [One sentence description. Example: "Progressive disclosure - show only what is needed, reveal complexity on demand."]
Color Palette
Brand Colors
| Name | Hex | RGB | Usage | |------|-----|-----|-------| | Primary | #[XXXXXX] | rgb(X, X, X) | Primary actions, links, key UI elements | | Secondary | #[XXXXXX] | rgb(X, X, X) | Secondary actions, accents | | Accent | #[XXXXXX] | rgb(X, X, X) | Highlights, badges, notifications |
Neutral Colors
| Name | Hex | Usage | |------|-----|-------| | Gray-900 | #[XXXXXX] | Primary text | | Gray-700 | #[XXXXXX] | Secondary text | | Gray-500 | #[XXXXXX] | Placeholder text, disabled states | | Gray-300 | #[XXXXXX] | Borders, dividers | | Gray-100 | #[XXXXXX] | Backgrounds, hover states | | White | #FFFFFF | Page background, card background |
Semantic Colors
| Name | Hex | Usage | |------|-----|-------| | Success | #[XXXXXX] | Success messages, positive indicators | | Warning | #[XXXXXX] | Warning messages, caution indicators | | Error | #[XXXXXX] | Error messages, destructive actions | | Info | #[XXXXXX] | Informational messages, tips |
Accessibility
- All text colors must meet WCAG 2.1 AA contrast ratio (4.5:1 for normal text, 3:1 for large text)
- Test with color blindness simulators
- Never use color as the only indicator of state
Typography Scale
Font Family
- Primary: [Font Name] (headings and body)
- Monospace: [Font Name] (code blocks, technical content)
- Fallback Stack: [System font stack]
Type Scale
| Name | Size | Weight | Line Height | Usage | |------|------|--------|-------------|-------| | Display | 48px / 3rem | Bold (700) | 1.2 | Hero headings | | H1 | 36px / 2.25rem | Bold (700) | 1.25 | Page titles | | H2 | 28px / 1.75rem | Semibold (600) | 1.3 | Section headings | | H3 | 22px / 1.375rem | Semibold (600) | 1.35 | Subsection headings | | H4 | 18px / 1.125rem | Medium (500) | 1.4 | Card titles, labels | | Body Large | 18px / 1.125rem | Regular (400) | 1.6 | Lead paragraphs | | Body | 16px / 1rem | Regular (400) | 1.5 | Default body text | | Body Small | 14px / 0.875rem | Regular (400) | 1.5 | Secondary text, captions | | Caption | 12px / 0.75rem | Regular (400) | 1.4 | Labels, metadata |
Spacing System
Base Unit: 4px
| Token | Value | Usage | |-------|-------|-------| | space-1 | 4px | Tight spacing (icon padding) | | space-2 | 8px | Compact elements (inline items) | | space-3 | 12px | Related elements (form field gaps) | | space-4 | 16px | Default spacing (paragraph gaps) | | space-5 | 20px | Group spacing (card padding) | | space-6 | 24px | Section spacing | | space-8 | 32px | Large section gaps | | space-10 | 40px | Page section dividers | | space-12 | 48px | Major layout sections | | space-16 | 64px | Page-level spacing |
Layout Spacing
- Page margin: space-6 (mobile), space-8 (tablet), space-12 (desktop)
- Card padding: space-5
- Form field gap: space-3
- Section gap: space-10
Component Library
Component Status Legend
- Stable - Production ready, fully documented and tested
- Beta - Functional but may change, use with awareness
- Deprecated - Scheduled for removal, migrate to replacement
- Planned - On roadmap, not yet available
Components
| Component | Status | Description | Variants | |-----------|--------|-------------|----------| | Button | Stable | Primary action triggers | Primary, Secondary, Tertiary, Danger, Ghost | | Input | Stable | Text input fields | Default, Error, Disabled, With icon | | Select | Stable | Dropdown selection | Single, Multi, Searchable | | Checkbox | Stable | Multi-select toggle | Default, Indeterminate, Disabled | | Radio | Stable | Single-select option | Default, Disabled | | Toggle | Stable | Binary on/off switch | Default, With label | | Modal | Stable | Overlay dialog | Small, Medium, Large, Fullscreen | | Toast | Stable | Temporary notification | Success, Error, Warning, Info | | Card | Stable | Content container | Default, Interactive, Elevated | | Badge | Stable | Status indicator | Solid, Outline, Dot | | Avatar | Stable | User representation | Image, Initials, Icon | | Table | Beta | Data display grid | Default, Sortable, Selectable | | Tabs | Beta | Content organization | Default, Underline, Pill | | Tooltip | Stable | Contextual information | Default, Rich content | | [New Component] | Planned | [Description] | [Variants] |
Usage Guidelines
Do
- Use components as documented (do not override internal styles)
- Follow the spacing system for consistent layouts
- Test components across supported browsers and screen sizes
- Use semantic colors for their intended purpose
- Reference design tokens instead of hardcoded values
Do Not
- Modify component internals without contributing changes back
- Create one-off components when an existing component fits
- Use brand colors for semantic purposes (error, success)
- Skip accessibility requirements for "internal" tools
- Mix design system versions across a single application
Contribution Process
Proposing a New Component
- Check existing components - Verify no existing component solves the need
- Create proposal - Document use case, behavior, variants, accessibility requirements
- Design review - Present to design system team for feedback
- Build - Implement component following system patterns
- Review - Code review + design review + accessibility audit
- Document - Add to component library with usage guidelines
- Release - Publish in next minor version
Updating an Existing Component
- File issue - Describe the change and justification
- Impact assessment - Identify all instances of current usage
- Design + develop - Implement change with backward compatibility
- Migration guide - Document breaking changes if any
- Release - Publish with changelog entry
Reporting Issues
- File bug reports with reproduction steps and screenshots
- Tag with component name and severity
- Include browser/OS information for rendering issues