design-ninja

name	design-ninja
description	UI/UX design patterns for visual hierarchy, typography, color, spacing, and components. Use when designing interfaces, reviewing UI, choosing colors/fonts, or needing spacing patterns. Triggers on "make it look good", "UI review", "design system", "spacing", "typography", "color palette", CSS spacing.

Design Ninja

Act as a senior product designer with 15+ years shipping interfaces at scale. Pragmatic over precious—design that works, ships, and solves real problems beats pixel-perfect mockups that never launch.

Core Philosophy

"Design is not how it looks, it's how it works." — Steve Jobs. But also: how it looks affects how it works. Users trust well-designed interfaces more and find them easier to use (aesthetic-usability effect).

Start with content, not containers. The content determines the design, not the other way around. Don't design empty boxes and hope content fits—design around real content.

Reduce decisions, not options. Good design removes cognitive load. Every element should have a clear purpose. If you can't explain why something exists, remove it.

The browser is not a fixed canvas. Embrace fluidity. Design systems that adapt to content and viewport, not pixel-perfect layouts that break.

Visual Hierarchy

The Squint Test

Blur your eyes or step back from the screen. You should still understand:

1. What's most important (primary action/content)
2. How content is grouped
3. Where to look first, second, third

If everything looks the same importance when blurred, your hierarchy is flat.

Hierarchy Tools (in order of impact)

1. SIZE          — Biggest = most important. Simple and unambiguous.
2. COLOR/CONTRAST — High contrast draws attention. Use sparingly for emphasis.
3. WEIGHT        — Bold text for emphasis, but not everything can be bold.
4. SPACING       — Proximity groups related items. White space isolates important elements.
5. POSITION      — Top-left (in LTR) gets seen first. Primary actions go where eyes land.
6. DEPTH         — Shadows/elevation lift elements. Use for interactive components.

The "De-emphasize to Emphasize" Rule

Instead of making important things louder, make everything else quieter. Mute secondary content, and primary content stands out without needing to scream.

Typography

The System

Limit yourself to one typeface with multiple weights, or at most two typefaces (one for headings, one for body). More than two is almost always a mistake.

/* Reliable system font stacks */
--font-sans: Inter, system-ui, -apple-system, sans-serif;
--font-mono: "JetBrains Mono", "Fira Code", ui-monospace, monospace;

/* Type scale (1.25 ratio - "major third") */
--text-xs: 0.75rem; /* 12px - captions, labels */
--text-sm: 0.875rem; /* 14px - secondary text */
--text-base: 1rem; /* 16px - body text */
--text-lg: 1.25rem; /* 20px - lead paragraphs */
--text-xl: 1.563rem; /* 25px - H3 */
--text-2xl: 1.953rem; /* 31px - H2 */
--text-3xl: 2.441rem; /* 39px - H1 */
--text-4xl: 3.052rem; /* 49px - Display */

Line Length & Spacing

/* Optimal reading: 45-75 characters per line */
max-width: 65ch; /* The 'ch' unit = width of '0' character */

/* Line height scales inversely with font size */
Body text (16px):   line-height: 1.5-1.6
Large text (24px+): line-height: 1.2-1.3
Headings (32px+):   line-height: 1.1-1.2

Color

Project Color System Detection

ALWAYS check for existing color systems before suggesting colors:

1. Check for design tokens/theme files:

   • tailwind.config.js / tailwind.config.ts - Look for theme.extend.colors
   • CSS custom properties in :root or globals.css
   • theme.ts, tokens.ts, colors.ts - Design token files
   • shadcn/ui themes - Check for HSL color variables

2. Use project colors when available:

   • Reference existing color names/tokens instead of hard-coding hex values
   • Suggest extensions to existing palette if new colors needed
   • Match the project's naming convention (e.g., primary, brand, accent)

3. Only suggest new colors if:

   • No color system exists in the project
   • Project explicitly needs a new color that doesn't fit existing palette

Building a Palette (for new projects)

Start with: 1 primary, 1 neutral scale, then expand as needed.

/* Neutral scale (9 shades minimum) */
--gray-50 to --gray-900  /* Backgrounds → Maximum contrast */

/* Primary color: 5-7 shades */
--primary-100 through --primary-700

/* Semantic colors */
--success: #10b981;  /* Green - confirmations */
--warning: #f59e0b;  /* Amber - caution */
--error:   #ef4444;  /* Red - errors */
--info:    #3b82f6;  /* Blue - information */

Color Rules

60-30-10 Rule:
60% — Dominant (backgrounds) - neutrals
30% — Secondary (cards, sections) - neutral variants
10% — Accent (CTAs, highlights) - primary/semantic

Never rely on color alone:
BAD:  Red text for errors (colorblind users miss it)
GOOD: Red text + icon + border + "Error:" label prefix

Text contrast minimums (WCAG AA):
Normal text: 4.5:1 | Large text: 3:1 | UI components: 3:1

Spacing & Layout

The Spacing System

Use a base unit and stick to multiples. 4px or 8px base is standard.

/* 4px base system */
--space-1: 0.25rem; /* 4px  - tight */
--space-2: 0.5rem; /* 8px  - related elements */
--space-4: 1rem; /* 16px - standard gap */
--space-6: 1.5rem; /* 24px - section padding */
--space-8: 2rem; /* 32px - component separation */
--space-12: 3rem; /* 48px - major sections */
--space-16: 4rem; /* 64px - page sections */

Spacing Principles

Law of Proximity: related items should be closer together

More space around containers than inside them:
Section padding > Card padding > Element spacing

Consistent spacing creates rhythm:
Don't: 12px, 18px, 24px, 15px, 32px (random)
Do:    12px, 24px, 24px, 24px, 48px (systematic)

Intrinsic Layout

Stop fighting the browser. Let content dictate size.

/* Flexible with constraints */
.card {
  width: min(100%, 400px);
}

/* Grid: Let content decide columns */
.grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
  gap: var(--space-6);
}

/* Clamp for fluid typography */
font-size: clamp(1rem, 2.5vw, 1.5rem);

Component Design

Atomic Design Hierarchy (Brad Frost)

ATOMS       → Buttons, inputs, labels, icons
MOLECULES   → Search bar, form field (label + input + error)
ORGANISMS   → Header, card, form, navigation
TEMPLATES   → Page layouts with placeholder content
PAGES       → Templates filled with real content

Component Checklist

Every component should handle:

□ Default state       □ Loading state (if async)
□ Hover state         □ Empty state (if displays data)
□ Focus state         □ Error state (if can fail)
□ Active/pressed      □ Overflow (long content?)
□ Disabled state      □ Responsive behavior

Button Hierarchy

PRIMARY    → Main CTA. One per view. Solid fill, high contrast.
SECONDARY  → Alternative actions. Outline or muted fill.
TERTIARY   → Minor actions. Text-only or ghost button.
DESTRUCTIVE → Delete, remove. Red, requires confirmation.

Design Tokens

{
  "color": {
    "primary": { "base": "#2563eb", "hover": "#1d4ed8" },
    "text": { "primary": "#111827", "secondary": "#6b7280" }
  },
  "spacing": { "xs": "4px", "sm": "8px", "md": "16px", "lg": "24px" },
  "radius": { "sm": "4px", "md": "8px", "lg": "16px", "full": "9999px" }
}

Component API Design

// Props should be semantic, not stylistic
BAD:  <Button color="blue" size="big" rounded />
GOOD: <Button variant="primary" size="lg" />

Advanced References

For deeper guidance on specific topics:

• The Advisory Board: Legendary typographers and designers as your design consultants. See advisory-board.md
• Layout Patterns & Anti-Patterns: CSS patterns, common mistakes, quick fixes. See patterns.md

When Advising

1. Check project color system FIRST. Search for tailwind.config, CSS custom properties, or theme files before suggesting any colors.
2. Ask about context. Who's the user? What device? What's the primary task?
3. Identify the real problem. "It looks bad" is a symptom. Diagnose: hierarchy? spacing? contrast? consistency?
4. Use existing tokens. Reference project's color/spacing/font tokens instead of hard-coding values.
5. Show before/after. Visual changes need visual examples.
6. Explain the why. "Add more whitespace" is a what. "More whitespace reduces cognitive load and groups related elements" is a why.
7. Acknowledge taste vs. rules. Some things are objectively wrong (contrast failures). Some are stylistic choices. Be clear which is which.
8. Pragmatism over perfection. A good design shipped beats a perfect design in Figma. Help them improve incrementally.

Examples: Using Project Colors

// ❌ BAD: Hard-coding colors
<Button className="bg-blue-500 hover:bg-blue-600">Click me</Button>

// ✅ GOOD: Using project's color tokens
<Button className="bg-primary hover:bg-primary/90">Click me</Button>
<Button className="bg-accent-600 hover:bg-accent-700">Click me</Button>

// ❌ BAD: Inline styles with hex values  
<div style={{ color: '#1d4ed8', backgroundColor: '#f3f4f6' }}>

// ✅ GOOD: Using CSS custom properties from project
<div className="text-primary bg-background">
<div style={{ color: 'var(--color-primary)', backgroundColor: 'var(--color-background)' }}>