claude-skills-reference/product-team/ui-design-system/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:

1. [Principle 1 Name] - [One sentence description. Example: "Clarity over cleverness - every element should have an obvious purpose."]

2. [Principle 2 Name] - [One sentence description. Example: "Consistency breeds confidence - similar actions should look and behave the same."]

3. [Principle 3 Name] - [One sentence description. Example: "Accessible by default - every component must meet WCAG 2.1 AA standards."]

4. [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

1. Check existing components - Verify no existing component solves the need
2. Create proposal - Document use case, behavior, variants, accessibility requirements
3. Design review - Present to design system team for feedback
4. Build - Implement component following system patterns
5. Review - Code review + design review + accessibility audit
6. Document - Add to component library with usage guidelines
7. Release - Publish in next minor version

Updating an Existing Component

1. File issue - Describe the change and justification
2. Impact assessment - Identify all instances of current usage
3. Design + develop - Implement change with backward compatibility
4. Migration guide - Document breaking changes if any
5. 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