loader/.cursor/skills/ui-design/templates/design-system.md

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

: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

: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

: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