git:20251218.ec4a3fd to git:20260113.90b2d6e

82 added, 57 removed. Audit A to A.

---

name: generic-design-system

description: Complete design system reference for any project - colors, typography, spacing, components, animations. Adapts to project theme and tech stack. Use when implementing UI, choosing colors, creating animations, or ensuring brand consistency. For new design systems, use ui-research skill first.

---

# 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](../_shared/UI_INSPIRATION_SOURCES.md) - Research sources

- [Design Patterns](../_shared/DESIGN_PATTERNS.md) - 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 |

+ | 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 |

+ | 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) |

+ | Use Case | Minimum |

+ | ------------- | ---------- |

+ | Body text | 4.5:1 (AA) |

+ | Large text | 3:1 (AA) |

+ | UI components | 3:1 (AA) |

## Typography

### Font Stack

```css

- --font-sans: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;

- --font-mono: 'SF Mono', Monaco, 'Courier New', monospace;

+ --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 |

+ | 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 |

+ | 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 |

+ | Token | Duration | Use |

+ | ------- | -------- | ------------------ |

+ | fast | 100ms | Micro-interactions |

+ | DEFAULT | 200ms | Most transitions |

+ | slow | 300ms | Complex animations |

### Timing

```css

--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 |

+ | 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 |

+ | 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 |

+ | ----- | --------- |

+ | sm | 640px |

+ | md | 768px |

+ | lg | 1024px |

+ | xl | 1280px |

## Dark Mode

```css

- :root { --background: #ffffff; --foreground: #000000; }

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

+ :root {

+ --background: #ffffff;

+ --foreground: #000000;

+ }

+ [data-theme="dark"] {

+ --background: #000000;

+ --foreground: #ffffff;

+ }

```

## See Also

- [Design Patterns](./../_shared/DESIGN_PATTERNS.md) - Atomic Design, tokens, component docs

- [Code Review Standards](./../_shared/CODE_REVIEW_STANDARDS.md) - 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)