---
name: visual-design-system
description: |
  Enforces professional visual design standards — typography, color systems,
  layout hierarchy, components, and animations — on every UI task.
  TRIGGER when: user asks to style a component, design a page, pick fonts or
  colors, build a navbar/card/button/modal/form, says "make it look good",
  "improve the design", "style this", "it looks generic", or starts building
  any visible UI element.
  TRIGGER also when: user asks about spacing, layout, animations, or
  micro-interactions on any web interface.
  DO NOT TRIGGER when: user is working on backend logic, database schemas,
  API routes, or any non-visual server-side task.
---

# Visual Design System

Enforces premium, non-generic visual design across every UI element — from
typography and color to layout hierarchy, component polish, and animations.
Primary constraint: every visual decision must be intentional and mapped to
the global CSS variable system — no hardcoded values, no default framework
aesthetics, no AI-slop styling.

## Core Rules

Rule: Eliminate default system fonts. Why: system fonts and template defaults
signal unpolished, low-effort development instantly. Select intentional
typefaces — Inter or Poppins for body/UI, Everett 700 for hero headings.

Rule: Declare all colors as CSS root variables before using them anywhere.
Why: hardcoded hex values inside components destroy global theming — a brand
color change requires editing 50+ files instead of one variable.

Rule: Whitespace is not empty space — it is a design asset. Why: cramped
layouts look cheap and amateur. Generous padding and margin create the
"breathing room" that makes interfaces feel premium and expensive.

Rule: Never style all cards or tiers equally on a pricing or feature page.
Why: equal visual weight gives the user no guidance. Differentiate with size,
gradient borders, glow shadows, and accent banners to guide the eye to the
most important CTA.

Rule: Never use linear transitions on any UI animation. Why: linear motion
looks mechanical. Always use `ease-in-out` with `duration-300` minimum —
this simulates physical velocity and makes motion feel natural.

Rule: Always declare `cursor: pointer` on custom clickable elements. Why:
missing pointer cursor is the clearest marker of AI-generated UI — it makes
custom buttons feel broken and unfinished.

## Typography System

**Font Selection by Role:**
- Hero headers / brand taglines: Everett 700 (editorial, high-impact)
- UI body / dashboards / labels: Inter or Poppins (legible, professional)
- Never use: default browser fonts, Comic Sans, or unverified Google Fonts

**Font Weight Scale:**
| Weight | Use case |
|--------|----------|
| 900 | Massive hero headings only — maximum visual impact |
| 700 | Section headings, primary labels, button text |
| 600 | Sub-headings, card titles, form labels |
| 400 | Body copy, paragraphs, secondary descriptions |
| 100–200 | Pricing display numbers, premium minimal accents only — never in dense content |

**Research Rule:** Use ColorZilla browser extension to sample exact hex codes
from competitor UIs. Use WhatFont extension to identify exact font family and
weight. Never copy colors from screenshots — compression distorts them.

## Color System

**Five required categories — define all before writing any CSS:**
- `--primary`: dominant brand identifier (e.g., royal purple, deep navy)
- `--primary-hover`: slightly lighter/darker variant of primary for hover state
- `--accent`: vibrant contrasting CTA color (electric green, bright blue, yellow)
- `--background` / `--surface`: page and card backgrounds
- `--foreground` / `--muted`: primary and secondary text

**global.css root variable structure:**
```css
:root {
  --primary:       #[hex];
  --primary-hover: #[hex];
  --accent:        #[hex];
  --background:    #[hex];
  --surface:       #[hex];
  --border:        #[hex];
  --foreground:    #[hex];
  --muted:         #[hex];
  --danger:        #ef4444;
  --success:       #22c55e;
  --radius-sm:     8px;
  --radius-md:     12px;
  --radius-lg:     20px;
}
```

## Layout & Spacing

**Visual Hierarchy Rule:** Size, contrast, color, and spacing must guide the
user's eye to what matters most first. Never treat all elements as equal weight.

**Bento Grid:** Use for feature lists, dashboards, and data-heavy views.
Varied card sizes packed into a cohesive grid feel designed — equal-size
grids feel templated.

**Z-Axis Management:** Manage z-index actively. Floating elements, popups,
and hover shadows must sit on explicitly higher z-index layers — never let
them bleed beneath neighboring containers.

**Pricing Page Rule:**
- Free / basic tier → flat card, minimal styling
- Premium / "Most Popular" tier → larger card, gradient border, shadow glow,
  accent banner ("Best Value" / "30% Off") — this directs the user to the
  highest-value CTA automatically

## Component Standards

**Button Variants — define all four before using any:**
| Variant | Style | Use case |
|---------|-------|----------|
| Primary | Solid `--primary` bg, `rounded-xl`, no border | Main CTA action |
| Secondary | Subtle bg + thin `--primary` border | Supporting action |
| Ghost | Transparent bg, border appears on hover only | Tertiary / nav actions |
| Danger | Solid `--danger` bg | Destructive actions only (delete, remove) |

**Input Fields:**
- Soft light-grey border at rest
- Smooth `ease-in-out` transition on focus
- Glowing `--primary` colored outline on focus state
- Never use sharp default browser input styling

**Icons:** Replace text labels ("Edit", "Delete") with SVG icons from Lucide
Icons or Remix Icons. Why: icon-based UI is cleaner, faster to scan, and
feels more professional than raw text labels.

**Sidebar / Panel Layout:**
- Left sidebar: fixed height, non-scrollable
- Right content area: scrollable only
- On mobile: sidebar collapses to a drawer — never shrinks inline

## Animation Standards

**Micro-interactions on buttons:**
- Hover: `hover:-translate-y-0.5 transition-all duration-300 ease-in-out`
- Shadow glow expands on hover
- Never use sudden color snaps — always transition

**Modals and Drawers:**
- Enter: slide in from right, `ease-out duration-300`
- Overlay: background fades to dark smoothly — never snaps black
- Exit: slide out with `ease-in` — never disappears instantly
- Close icon: positioned visually near the action text, not in a corner alone

**Glassmorphism (sticky navbars / floating panels):**
```css
backdrop-filter: blur(12px);
background: rgba(255,255,255,0.7);
```
Why: creates a premium translucent layer that lets page content scroll
beneath without losing the nav — used by Stripe, Linear, Vercel.

## Design-to-Code Pipeline

Follow this order. Do not skip steps. Coding before mockup produces AI slop.

1. **Wireframe** — grayscale layout only. No colors, no fonts, no icons.
   Tools: Excalidraw, Balsamiq, or Claude Design.
2. **Mockup** — pixel-perfect static design with exact colors, fonts, spacing.
   Tools: Figma. Lock the `Design.md` variables here.
3. **Prototype** — connect mockup screens into a clickable flow.
   Tools: Google Stitch. Validate routing and modal behavior before coding.
4. **UI Code** — translate confirmed prototype into React/Next.js + Tailwind.

**Design.md:** Create a `Design.md` at project root documenting exact layout
widths, border-radii, color hex codes, font names, and padding targets. This
is the master spec for the AI when generating UI code.

## Decision Guide

| Situation | Correct action |
|-----------|---------------|
| Site looks generic after coding | Root cause: no wireframe/mockup was built first — restart with design step |
| Client wants to change brand color | Update one CSS root variable — done globally |
| Two buttons look identical in priority | Apply hierarchy: one Primary, one Ghost or Secondary |
| Animation feels jarring or robotic | Replace `linear` with `ease-in-out duration-300` |
| Mobile layout is broken/cramped | Sidebar must collapse to drawer — never inline-shrink |

## Anti-Patterns

| ❌ Never do this | ✅ Do this instead |
|-----------------|------------------|
| Hardcode hex values in component files | Map all colors to `global.css` root variables |
| Use default framework button/input styling | Define all 4 button variants and input focus states |
| Use linear transitions | Use `ease-in-out duration-300` minimum on all animations |
| Style all pricing cards identically | Apply visual hierarchy — differentiate premium tier |
| Copy colors from competitor screenshots | Use ColorZilla extension to sample from live DOM |
| Skip wireframe, design in code directly | Always wireframe → mockup → prototype → code |

## Gotchas

- Glassmorphism and micro-interactions are finish work — apply them after
  layout, spacing, and component architecture are solid.

- A design that looks good on desktop but breaks on mobile is not done.
  Every component must have responsive behavior planned from the start.

- Everett 700 is not on Google Fonts — it must be purchased or sourced
  separately and placed in `public/fonts/`. Always verify font licensing.

- The `Design.md` file is consumed by the AI IDE — the more specific its
  values, the more accurate the generated UI will be.

---

**Handoff**
```
Skill: visual-design-system
Type: Reference
Trigger phrases covered: "style this", "make it look good", "it looks generic",
  "build a navbar/card/button", "pick fonts or colors", "improve the design"
DO NOT TRIGGER for: backend logic, API routes, database work, server-side tasks
Test prompts to verify:
  1. "Build me a pricing page with three tiers" → Should trigger; hierarchy rules applied,
     premium card differentiated with gradient border and accent banner
  2. "This looks too generic, fix the design" → Should trigger; root cause traced to
     missing wireframe/mockup; design pipeline enforced
  3. "Write an Express middleware for auth" → Should NOT trigger; backend task, no UI involved
Pass/fail rubric score: 5/5
Suggested next iteration: add dark mode variable rules if user's projects
  frequently require dark/light theme switching
```