design-system

Visual Design System

Typography Scale

Use a modular scale with 1.25 ratio for consistent visual rhythm:

Role	Tailwind Class	Size	Weight	Line Height
Display	text-5xl	48px	font-bold	leading-tight
H1	text-4xl	36px	font-bold	leading-tight
H2	text-2xl	24px	font-semibold	leading-tight
H3	text-xl	20px	font-semibold	leading-snug
H4	text-lg	18px	font-medium	leading-snug
Body	text-base	16px	font-normal	leading-relaxed
Small	text-sm	14px	font-normal	leading-normal
Caption	text-xs	12px	font-medium	leading-normal

Rules:

• Use tracking-tight on display and H1 headings for visual density
• Body text line length: 45-75 characters (use max-w-prose or max-w-2xl)
• Use text-muted-foreground for secondary/supporting text
• Weight hierarchy: bold → semibold → medium → normal (never skip two levels)

Spacing System

4px base unit. Every spacing value should be a multiple of 4:

Scale	Tailwind	Pixels	Usage
xs	gap-1 / p-1	4px	Tight spacing between inline elements
sm	gap-2 / p-2	8px	Related items within a group
md	gap-3 / p-3	12px	Default component internal padding
base	gap-4 / p-4	16px	Standard component padding, list item gaps
lg	gap-6 / p-6	24px	Section padding, card content padding
xl	gap-8 / p-8	32px	Major section gaps, page horizontal padding
2xl	gap-12 / p-12	48px	Between major page sections
3xl	gap-16 / p-16	64px	Page vertical padding, hero sections

Rules:

• Component internal padding: p-4 to p-6
• Gap between components in a grid/list: gap-4 to gap-6
• Page horizontal margins: px-6 to px-16
• Vertical space between page sections: py-12 to py-16
• Maintain consistent spacing rhythm — don't mix gap-5 and gap-6 in the same view

Color Theory

Semantic Color System (shadcn)

Use the semantic color tokens, not raw colors:

• Primary (bg-primary) — Brand color. Main CTAs, active navigation, selected states.
• Secondary (bg-secondary) — Supporting actions. Secondary buttons, hover backgrounds.
• Muted (bg-muted) — Subtle backgrounds. Sidebar, code blocks, disabled states.
• Accent (bg-accent) — Highlight color. Hover states, active rows, chips.
• Destructive (bg-destructive) — Danger/delete. Error states, destructive buttons, alerts.

Custom Palette Guidelines

When establishing a color direction for a project:

• Choose one primary hue and build variants using HSL (adjust lightness ±10-20%)
• Neutral grays for backgrounds: use 2-3 shades (white → very light gray → light gray)
• Text grays: high contrast for primary text (text-foreground), medium for secondary (text-muted-foreground)
• Semantic colors are non-negotiable: green=success, amber=warning, red=error, blue=info
• Contrast ratios: 4.5:1 minimum for normal text, 3:1 for large text (>18px bold)

Color Usage Patterns

• Backgrounds: Max 3 levels (page bg → card bg → nested element bg)
• Borders: Use sparingly. border-border at 1px for card boundaries. Use whitespace/shadow instead of borders when possible.
• Status indicators: Colored dot + text label (never color alone — accessibility)
• Charts/data viz: Use 5-7 distinct hues at similar saturation. Avoid red/green pairs for colorblind users.

Visual Hierarchy

Establish importance through these tools, in order of impact:

1. Size — Largest element draws the eye first. Page title > section title > body text.
2. Color/Contrast — High contrast elements read as more important. Primary color for CTAs.
3. Weight — Bolder text appears more important. Use weight to differentiate headings from body.
4. Position — Top-left reads first (F-pattern for content, Z-pattern for landing pages). Place primary actions at natural scan endpoints.
5. Whitespace — Elements surrounded by space feel more important. Don't crowd important elements.

Common hierarchies:

• Dashboard: KPI cards (largest, top) → Charts (medium) → Tables/lists (detailed, bottom)
• Settings: Navigation (sidebar, persistent) → Section heading → Form fields → Save button (bottom-right)
• Landing page: Hero (full-width, bold) → Features (grid) → Social proof → CTA

Elevation & Depth

Shadow scale creates visual layering:

Level	Tailwind	Usage
Flat	no shadow	Inline elements, backgrounds
Raised	shadow-sm	Cards, list items
Elevated	shadow-md	Dropdown menus, popovers
Floating	shadow-lg	Tooltips, floating action buttons
Overlay	shadow-xl	Modals, dialog boxes

Rules:

• Cards: shadow-sm default, shadow-md on hover for interactive cards
• Modals: shadow-xl + backdrop-blur-sm on the overlay background
• Focus rings: ring-2 ring-ring ring-offset-2 — visible, consistent, accessible
• Don't combine heavy shadows with heavy borders — choose one depth technique

Motion Principles

Animation durations and easing for Framer Motion and CSS transitions:

Interaction	Duration	Easing
Micro-interaction (hover, focus)	150-200ms	ease-out
Element enter/appear	200-300ms	ease-out / [0.16, 1, 0.3, 1]
Element exit/disappear	150-200ms	ease-in
Page transition	300-500ms	ease-in-out
Layout shift	200-400ms	spring (stiffness: 300, damping: 30)
Stagger delay (list items)	50-100ms per item	—

Rules:

• Entrances are slightly slower than exits (builds anticipation vs quick dismissal)
• Use spring physics for layout animations — feels more natural than linear easing
• Stagger children for lists/grids: creates a "cascade" effect that guides the eye
• Never animate more than 2 properties simultaneously on a single element
• Reduce motion for prefers-reduced-motion — use motion-safe: Tailwind modifier