# Design System: [Project Name]

## 1. Visual Atmosphere

[Describe the mood, density, and aesthetic philosophy in 2-3 sentences. Be specific — never use "clean and modern". Reference the atmosphere type from design-vocabulary.md. Example: "A spacious, light-filled interface with generous whitespace that feels calm and unhurried. Elements float on a near-white canvas with subtle shadows providing depth. The overall impression is sophisticated simplicity — premium without being cold."]

## 2. Color System

### Primitives

```css
:root {
  --white: #ffffff;
  --black: #000000;

  --gray-50: #______;
  --gray-100: #______;
  --gray-200: #______;
  --gray-300: #______;
  --gray-400: #______;
  --gray-500: #______;
  --gray-600: #______;
  --gray-700: #______;
  --gray-800: #______;
  --gray-900: #______;
  --gray-950: #______;

  --accent-50: #______;
  --accent-100: #______;
  --accent-200: #______;
  --accent-300: #______;
  --accent-400: #______;
  --accent-500: #______;
  --accent-600: #______;
  --accent-700: #______;
  --accent-800: #______;
  --accent-900: #______;

  --red-500: #______;
  --red-600: #______;
  --green-500: #______;
  --green-600: #______;
  --amber-500: #______;
  --amber-600: #______;
}
```

### Semantic Tokens

```css
:root {
  --color-bg-primary: var(--gray-50);
  --color-bg-secondary: var(--gray-100);
  --color-bg-surface: var(--white);
  --color-bg-inverse: var(--gray-900);

  --color-text-primary: var(--gray-900);
  --color-text-secondary: var(--gray-500);
  --color-text-tertiary: var(--gray-400);
  --color-text-inverse: var(--white);
  --color-text-link: var(--accent-600);

  --color-accent: var(--accent-600);
  --color-accent-hover: var(--accent-700);
  --color-accent-light: var(--accent-50);

  --color-border: var(--gray-200);
  --color-border-strong: var(--gray-300);
  --color-divider: var(--gray-100);

  --color-error: var(--red-600);
  --color-error-light: var(--red-500);
  --color-success: var(--green-600);
  --color-success-light: var(--green-500);
  --color-warning: var(--amber-600);
  --color-warning-light: var(--amber-500);
}
```

### Component Tokens

```css
:root {
  --button-primary-bg: var(--color-accent);
  --button-primary-text: var(--color-text-inverse);
  --button-primary-hover: var(--color-accent-hover);
  --button-secondary-bg: transparent;
  --button-secondary-border: var(--color-border-strong);
  --button-secondary-text: var(--color-text-primary);

  --card-bg: var(--color-bg-surface);
  --card-border: var(--color-border);
  --card-shadow: 0 1px 3px rgba(0, 0, 0, 0.08);

  --input-bg: var(--color-bg-surface);
  --input-border: var(--color-border);
  --input-border-focus: var(--color-accent);
  --input-text: var(--color-text-primary);
  --input-placeholder: var(--color-text-tertiary);

  --nav-bg: var(--color-bg-surface);
  --nav-active-bg: var(--color-accent-light);
  --nav-active-text: var(--color-accent);
}
```

## 3. Typography

- **Font family**: [Specific font name], [fallback], system-ui, sans-serif
- **Font source**: Google Fonts link or system font

| Level | Element | Size | Weight | Line Height | Letter Spacing |
|-------|---------|------|--------|-------------|----------------|
| Display | Hero headlines | 3rem (48px) | 700 | 1.1 | -0.02em |
| H1 | Page title | 2.25rem (36px) | 700 | 1.2 | -0.01em |
| H2 | Section title | 1.5rem (24px) | 600 | 1.3 | 0 |
| H3 | Subsection | 1.25rem (20px) | 600 | 1.4 | 0 |
| H4 | Card/group title | 1.125rem (18px) | 600 | 1.4 | 0 |
| Body | Default text | 1rem (16px) | 400 | 1.5 | 0 |
| Small | Captions, meta | 0.875rem (14px) | 400 | 1.5 | 0.01em |
| XS | Labels, badges | 0.75rem (12px) | 500 | 1.4 | 0.02em |

## 4. Spacing & Layout

- **Base unit**: 4px (0.25rem)
- **Spacing scale**: 1 (4px), 2 (8px), 3 (12px), 4 (16px), 5 (20px), 6 (24px), 8 (32px), 10 (40px), 12 (48px), 16 (64px), 20 (80px), 24 (96px)
- **Content max-width**: [1200px / 1280px / 1440px]
- **Grid**: [12-column / auto-fit] with [16px / 24px] gap

| Breakpoint | Name | Min Width | Columns | Padding |
|------------|------|-----------|---------|---------|
| Mobile | sm | 0 | 1 | 16px |
| Tablet | md | 768px | 2 | 24px |
| Laptop | lg | 1024px | 3-4 | 32px |
| Desktop | xl | 1280px | 4+ | 32px |

## 5. Component Styling Defaults

### Buttons
- Border radius: [6px / 8px / full]
- Padding: 10px 20px (md), 8px 16px (sm), 12px 24px (lg)
- Font weight: 500
- Transition: background-color 150ms ease, box-shadow 150ms ease
- Focus: 2px ring with 2px offset using `--color-accent`
- Disabled: opacity 0.5, cursor not-allowed

### Cards
- Border radius: [8px / 12px]
- Border: 1px solid var(--card-border)
- Shadow: var(--card-shadow)
- Padding: 20-24px
- Hover (if interactive): shadow increase or border-color change

### Inputs
- Height: 40px (md), 36px (sm), 48px (lg)
- Border radius: 6px
- Border: 1px solid var(--input-border)
- Padding: 0 12px
- Focus: border-color var(--input-border-focus) + 2px ring
- Error: border-color var(--color-error) + error message below

### Navigation
- Item height: 40px
- Active: background var(--nav-active-bg), text var(--nav-active-text)
- Hover: background var(--color-bg-secondary)
- Transition: background-color 150ms ease

## 6. Interaction States (MANDATORY)

### Loading
- Use skeleton loaders matching content shape
- Pulse animation: opacity 0.4 → 1.0, duration 1.5s, ease-in-out
- Background: var(--color-bg-secondary)

### Error
- Inline message below the element
- Icon (circle-exclamation) + red text using var(--color-error)
- Border change on the input/container to var(--color-error)

### Empty
- Centered illustration or icon (64-96px)
- Heading: "No [items] yet" or similar
- Descriptive text: one sentence explaining what will appear
- Primary CTA button: "Create first...", "Add...", "Import..."

### Hover
- Interactive elements: subtle background shift or underline
- Cards: shadow increase or border-color change
- Transition: 150ms ease

### Focus
- Visible ring: 2px solid var(--color-accent), 2px offset
- Applied to all interactive elements (buttons, inputs, links, tabs)
- Never remove outline without providing alternative focus indicator

### Disabled
- Opacity: 0.5
- Cursor: not-allowed
- Title attribute explaining why the element is disabled