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

Component exists? → Use existing pattern
Similar exists? → Adapt existing (don't create competing pattern)
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;
}

generic-design-system

Safety Notice

Copy this and send it to your AI assistant to learn