/visual-design-system

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:

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:

: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:

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):

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

Anti-Patterns

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