Generic Design System

Design system reference adapting to any project's visual language.

Research First for New Systems

When creating a NEW design system (not following an existing one):

Skill(ui-research)  # Research modern patterns first

References:

• UI Inspiration Sources - Research sources
• Design Patterns - Visual tokens

When to Use This Skill

Use for:

• Implementing UI components
• Choosing colors or typography
• Creating animations or transitions
• Ensuring visual consistency
• Setting up design tokens
• Reviewing design system compliance

Don't use when:

• UX flow design → use generic-ux-designer
• Feature architecture → use generic-feature-developer
• Code quality review → use generic-code-reviewer

Design System Architecture

When to Build vs Reference

Situation	Action
Existing design system	Follow it strictly
No design system	Use this skill to establish foundations
Partial system	Identify gaps, extend consistently

Token Organization

Layer	Example	Purpose
Primitive	--color-blue-500	Raw values
Semantic	--color-primary	Meaning
Component	--button-background	Context

Decision: Use semantic tokens in code, primitive tokens as foundation only.

Consistency Decision Tree

1. Component exists? → Use existing pattern
2. Similar exists? → Adapt existing (don't create competing pattern)
3. New category? → Propose to user, document reasoning

Color System

Every project should define:

• Primary, Secondary, Accent
• Background, Foreground, Muted
• Destructive, Success, Warning

Contrast Requirements

Use Case	Minimum
Body text	4.5:1 (AA)
Large text	3:1 (AA)
UI components	3:1 (AA)

Typography

Font Stack

--font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
--font-mono: "SF Mono", Monaco, "Courier New", monospace;

Type Scale

Name	Size	Use
sm	14px	Secondary text
base	16px	Body text
lg	18px	Lead paragraphs
xl	20px	Section headers
2xl	24px	Page headers

Spacing System

Base unit: 4px or 8px

Token	4px Base	Use
1	4px	Tight spacing
2	8px	Default gap
4	16px	Card padding
6	24px	Page margins

Animation

GPU-Accelerated Only

DO animate: transform, opacity AVOID: width, height, top, left, margin, padding

Duration

Token	Duration	Use
fast	100ms	Micro-interactions
DEFAULT	200ms	Most transitions
slow	300ms	Complex animations

Timing

--ease-default: cubic-bezier(0.4, 0, 0.2, 1);
--ease-bounce: cubic-bezier(0.68, -0.55, 0.265, 1.55);

Components

Component States

State	Visual Treatment	Example
Default	Base styling	Normal button
Hover	Subtle feedback	Lighter/darker bg
Active	Pressed state	Scaled down slightly
Focus	Visible outline	2px ring, offset
Disabled	Reduced opacity	50% opacity, no pointer
Loading	Spinner/skeleton	Button with spinner
Error	Destructive color	Red border/text

Touch Targets

• Minimum: 44x44px (WCAG 2.1 AAA)
• Spacing: 8px between adjacent targets
• Mobile: Consider 48x48px for primary actions

Buttons

Variant	Use	Min Size
Primary	Main actions	44x44px
Secondary	Alternative actions	44x44px
Ghost	Subtle actions	44x44px
Destructive	Delete actions	44x44px

Form Inputs

• Clear focus states (2px visible ring)
• Error states with messages
• Label always visible
• Required indicator

Modals

• Focus trapped inside
• Escape to close
• Dark overlay (50-70% opacity)

Responsive Breakpoints

Token	Min Width
sm	640px
md	768px
lg	1024px
xl	1280px

Dark Mode

:root {
  --background: #ffffff;
  --foreground: #000000;
}
[data-theme="dark"] {
  --background: #000000;
  --foreground: #ffffff;
}

See Also

• Design Patterns - Atomic Design, tokens, component docs
• Code Review Standards - Accessibility checks
• generic-ux-designer - For UX flow and research decisions
• Project CLAUDE.md - Project-specific design constraints

READ references when:

• Setting up new design system → DESIGN_PATTERNS.md (full structure)
• Complex component patterns → DESIGN_PATTERNS.md (Atomic Design section)