ui-design-system

What this skill does

# UI Design System

## When to Use

Activate this skill when:
- Creating new UI components that must follow a design system
- Building page layouts with consistent spacing and structure
- Setting up or extending design tokens (colors, typography, spacing)
- Choosing colors, fonts, or spacing values for a project
- Reviewing UI code for design consistency and accessibility
- Integrating shadcn/ui components into existing layouts

Do NOT use this skill for:
- Backend API implementation (use `python-backend-expert`)
- Component or hook testing (use `react-testing-patterns`)
- E2E browser testing (use `e2e-testing`)
- General React patterns unrelated to design system (use `react-frontend-expert`)
- Deployment or CI/CD (use `deployment-pipeline`)

## Instructions

### Step 0: Read Existing Design Tokens

Before generating any UI code, check the project for existing tokens:

1. Read `tailwind.config.ts` (or `.js`) for custom theme extensions
2. Read `src/styles/globals.css` or `app/globals.css` for CSS custom properties
3. Read `components.json` if shadcn/ui is configured

If no design tokens exist, generate a starter set and ask the user to confirm before proceeding (see Edge Cases).

### Design Tokens

#### Color Tokens

Define colors as CSS custom properties consumed by Tailwind. Never use hardcoded hex/rgb values in components.

**CSS custom properties (HSL format for shadcn/ui compatibility):**

```css
/* globals.css */
@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 222 47% 11%;
    --primary: 221 83% 53%;
    --primary-foreground: 210 40% 98%;
    --secondary: 210 40% 96%;
    --secondary-foreground: 222 47% 11%;
    --muted: 210 40% 96%;
    --muted-foreground: 215 16% 47%;
    --accent: 210 40% 96%;
    --accent-foreground: 222 47% 11%;
    --destructive: 0 84% 60%;
    --destructive-foreground: 210 40% 98%;
    --border: 214 32% 91%;
    --input: 214 32% 91%;
    --ring: 221 83% 53%;
    --radius: 0.5rem;
  }

  .dark {
    --background: 222 47% 11%;
    --foreground: 210 40% 98%;
    --primary: 217 91% 60%;
    --primary-foreground: 222 47% 11%;
    --secondary: 217 33% 17%;
    --secondary-foreground: 210 40% 98%;
    --muted: 217 33% 17%;
    --muted-foreground: 215 20% 65%;
    --accent: 217 33% 17%;
    --accent-foreground: 210 40% 98%;
    --destructive: 0 63% 31%;
    --destructive-foreground: 210 40% 98%;
    --border: 217 33% 17%;
    --input: 217 33% 17%;
    --ring: 224 76% 48%;
  }
}
```

**Tailwind config mapping:**

```ts
// tailwind.config.ts
export default {
  theme: {
    extend: {
      colors: {
        background: "hsl(var(--background))",
        foreground: "hsl(var(--foreground))",
        primary: {
          DEFAULT: "hsl(var(--primary))",
          foreground: "hsl(var(--primary-foreground))",
        },
        secondary: {
          DEFAULT: "hsl(var(--secondary))",
          foreground: "hsl(var(--secondary-foreground))",
        },
        muted: {
          DEFAULT: "hsl(var(--muted))",
          foreground: "hsl(var(--muted-foreground))",
        },
        accent: {
          DEFAULT: "hsl(var(--accent))",
          foreground: "hsl(var(--accent-foreground))",
        },
        destructive: {
          DEFAULT: "hsl(var(--destructive))",
          foreground: "hsl(var(--destructive-foreground))",
        },
        border: "hsl(var(--border))",
        input: "hsl(var(--input))",
        ring: "hsl(var(--ring))",
      },
    },
  },
} satisfies Config;
```

**Color usage rules:**
- Always use semantic token classes: `bg-primary`, `text-foreground`, `border-border`
- Never use raw Tailwind palette colors (`bg-blue-500`) in component code
- Every color must have a dark mode variant defined
- Use `foreground` variants for text on colored backgrounds

#### Typography Scale

Define a typographic scale using Tailwind's font-size utilities:

| Token | Size | Line Height | Usage |
|-------|------|-------------|-------|
| `text-xs` | 12px | 16px | Captions, helper text |
| `text-sm` | 14px | 20px | Secondary text, labels |
| `text-base` | 16px | 24px | Body text (default) |
| `text-lg` | 18px | 28px | Subheadings |
| `text-xl` | 20px | 28px | Section headings |
| `text-2xl` | 24px | 32px | Page headings |
| `text-3xl` | 30px | 36px | Hero headings |

**Typography rules:**
- Set a base font in `tailwind.config.ts`: `fontFamily: { sans: ["Inter", "system-ui", "sans-serif"] }`
- Use `font-medium` (500) for headings and labels, `font-normal` (400) for body
- Use `tracking-tight` for headings `text-2xl` and above
- Limit line length with `max-w-prose` (65ch) for readability

#### Spacing (8pt Grid)

All spacing values follow an 8pt base grid:

| Tailwind Class | Value | Use Case |
|---------------|-------|----------|
| `p-1` / `gap-1` | 4px | Inline icon padding, tight gaps |
| `p-2` / `gap-2` | 8px | Compact element spacing |
| `p-3` / `gap-3` | 12px | Input padding, small card padding |
| `p-4` / `gap-4` | 16px | Standard component padding |
| `p-6` / `gap-6` | 24px | Card padding, section gaps |
| `p-8` / `gap-8` | 32px | Section padding |
| `p-12` / `gap-12` | 48px | Page section spacing |
| `p-16` / `gap-16` | 64px | Major layout spacing |

**Spacing rules:**
- Use `gap-*` for flex/grid children instead of individual margins
- Prefer `space-y-*` for vertical stacking of sibling elements
- Cards: `p-6` padding with `gap-4` between internal elements
- Page sections: `py-12` or `py-16` vertical padding
- Never mix spacing systems (no `margin: 13px`)

### Component Structure

#### Hierarchy: Container > Layout > Content

Every component follows a three-layer structure:

```tsx
// Container: outer wrapper with spacing, background, border
<Card className="p-6">
  {/* Layout: flex/grid arrangement */}
  <div className="flex items-center gap-4">
    {/* Content: actual UI elements */}
    <Avatar src={user.avatar} alt={user.name} />
    <div className="space-y-1">
      <h3 className="text-sm font-medium">{user.name}</h3>
      <p className="text-sm text-muted-foreground">{user.role}</p>
    </div>
  </div>
</Card>
```

#### Semantic HTML

Use the correct HTML element for every purpose:

| Element | Use For | Not |
|---------|---------|-----|
| `<button>` | Clickable actions | `<div onClick>` |
| `<a>` | Navigation links | `<button>` for links |
| `<nav>` | Navigation regions | `<div>` |
| `<main>` | Primary page content | `<div>` |
| `<article>` | Self-contained content (card, post) | `<div>` |
| `<section>` | Thematic grouping with heading | `<div>` |
| `<aside>` | Sidebar or tangential content | `<div>` |
| `<header>` | Introductory content for a section | `<div>` |
| `<footer>` | Footer content for a section | `<div>` |
| `<ul>` / `<ol>` | Lists of items | `<div>` for each item |

#### shadcn/ui Primitives

Prefer shadcn/ui components over custom implementations:

| Need | Use | Not |
|------|-----|-----|
| Buttons | `<Button>` | Custom `<button>` with styles |
| Modals | `<Dialog>` | Custom modal with portal |
| Dropdowns | `<DropdownMenu>` | Custom dropdown |
| Cards | `<Card>` | Styled `<div>` |
| Inputs | `<Input>` | Styled `<input>` |
| Selects | `<Select>` | Native `<select>` |
| Tooltips | `<Tooltip>` | Custom tooltip |
| Tabs | `<Tabs>` | Custom tab component |
| Tables | `<Table>` | Plain `<table>` |
| Alerts | `<Alert>` | Custom banner div |

If shadcn/ui is not installed, fall back to plain Tailwind with equivalent patterns and consistent class ordering.

### TypeScript Component Interfaces

Export props as TypeScript interfaces with JSDoc descriptions:

```tsx
/** Props for the UserProfileCard component. */
interface UserProfileCardProps {
  /** User data to display. */
  user: User;
  /** Called when the edit button is clicked. */
  onEdit?: (userId: string) => void;
  /** Visual variant of the card. */
  variant?: "default" | "compact";
  /** Additional CSS classes applied to the root element. */
  className?: string;
}

export function UserProfileCard({
  user,
  onEdit,
  variant = "