assets/design_system_doc_template.md
A supporting file of the ui-design-system skill.
| Field | Value |
|---|
| Name | [Design System Name] |
| Version | [X.Y.Z] |
| Owner | [Team/Person] |
| Status | Active / Beta / Deprecated |
| Last Updated | YYYY-MM-DD |
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."]
| 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 |
| 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 |
| 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 |
- 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
- Primary: [Font Name] (headings and body)
- Monospace: [Font Name] (code blocks, technical content)
- Fallback Stack: [System font stack]
| 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 |
| 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 |
- Page margin: space-6 (mobile), space-8 (tablet), space-12 (desktop)
- Card padding: space-5
- Form field gap: space-3
- Section gap: space-10
- 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
| 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] |
- 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
- 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
- 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
- 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
- File bug reports with reproduction steps and screenshots
- Tag with component name and severity
- Include browser/OS information for rendering issues