beautify

What this skill does

# Beautify

Make web apps look intentionally designed rather than AI-generated. This skill covers the visual principles that separate premium-feeling apps (Stripe, Linear, Vercel) from generic template output. Apply these principles when building new UI or when the user says something "looks off" but can't articulate why.

Reference [AI-SLOP-FIXES.md](AI-SLOP-FIXES.md) for specific antipattern remediation. Reference [REFERENCE-TEARDOWNS.md](REFERENCE-TEARDOWNS.md) for concrete examples from production apps.

---

## Core Principles

1. **Restraint is the primary aesthetic.** Premium apps use fewer colors, fewer font weights, fewer borders, fewer shadows. When in doubt, remove rather than add.
2. **Every visual difference must communicate a difference in meaning.** If two elements look different, they should BE different. If they're the same type of thing, they must look identical.
3. **Hierarchy is not optional.** Every screen has exactly one primary focal point, 2-3 secondary elements, and everything else recedes. If everything is emphasized, nothing is.
4. **Whitespace is a design element, not empty space.** It creates grouping, hierarchy, and breathing room. Increasing whitespace almost always improves perceived quality.
5. **Color is information, not decoration.** Each color in the palette should have a job. If a color doesn't communicate status, action, or brand, remove it.
6. **Consistency compounds.** One slightly-off spacing value is invisible. Twenty slightly-off values make an app feel broken. Nail the system, not individual screens.
7. **The eye follows contrast.** The highest-contrast element on screen gets attention first. Use this deliberately — never accidentally.

---

## Visual Hierarchy

This is the single most impactful skill. A clear hierarchy makes any design feel professional; a muddled one makes even beautiful components feel amateurish.

### Tools for creating hierarchy (in order of impact):

**Size difference.** The primary element should be dramatically larger than secondary elements. Not 10% larger — 50-100% larger. A page heading at `text-3xl` with body at `text-sm` creates immediate hierarchy. A heading at `text-xl` with body at `text-lg` creates mush.

**Weight contrast.** Pair `font-bold` (700) headings with `font-normal` (400) body text. Never use `font-medium` (500) for both headings and body — the difference is invisible. Use at most 3 font weights per page: one for headings, one for body, one for de-emphasized text.

**Color contrast.** Primary content in `text-gray-900`, secondary in `text-gray-500`, tertiary in `text-gray-400`. Three levels is usually enough. Don't use `text-gray-700` and `text-gray-600` on the same page — the difference is imperceptible.

**Spatial hierarchy.** The most important element gets the most surrounding whitespace. A CTA button with `py-3 px-8` surrounded by `mt-8` commands more attention than one with `py-2 px-4` and `mt-4`.

### Common hierarchy failures:

- **Flat hierarchy:** Every text element is `text-base font-medium text-gray-700`. Fix: Pick ONE weight/size for body, make headings dramatically different.
- **Inverted hierarchy:** Navigation or header competes with page content. Fix: Nav should be quieter than content — use `text-sm font-normal text-gray-500` for nav items.
- **Competing CTAs:** Multiple buttons with equal visual weight. Fix: One `bg-primary text-white` button per section. Everything else is `text-gray-600 hover:text-gray-900` or a ghost/outline variant.

---

## Whitespace

### The core rule: space between groups > space within groups

If items inside a card are spaced with `gap-3` (12px), the gap between cards should be `gap-6` (24px) or more. If sections use `gap-6` internally, section gaps should be `py-16` or `py-20`. This ratio (2-3x) is the single most important spacing principle.

### Where to add whitespace:

- **Page margins.** `px-6` minimum on mobile, `px-8` to `px-12` on desktop. Cramped edges make everything feel cheap.
- **Above page headings.** `pt-8` to `pt-12` before the first heading. Content that starts immediately below the nav feels rushed.
- **Between sections.** `py-12` to `py-20` between major sections. This is almost always too small in AI-generated output.
- **Around CTAs.** Primary buttons need breathing room. `mt-6` to `mt-8` above a CTA gives it importance.
- **Inside cards.** `p-6` is the minimum for cards with content. `p-4` works for compact list items but feels cramped for standalone cards.

### Where density is correct:

- **Data tables.** Tight rows (`py-2` to `py-3`) with compact cells are fine — density is the point.
- **Navigation items.** `py-2 px-3` keeps nav compact and functional.
- **Form fields.** `gap-4` to `gap-5` between form fields is appropriate — too much space makes forms feel disconnected.
- **Inline elements.** Icon-to-text gap of `gap-1.5` to `gap-2`. Badge padding of `px-2 py-0.5`.

---

## Color Application

### The 60-30-10 rule

- **60% neutral.** Backgrounds, cards, body text. White/gray/off-white. This is the canvas.
- **30% secondary.** Borders, secondary text, dividers, subtle backgrounds. Gray-200 to gray-500 range.
- **10% accent.** Primary buttons, active states, links, key indicators. Your brand color.

Most AI-generated apps flip this ratio — too much accent color, not enough neutral space. If more than 10% of the visible pixels are your brand color, pull back.

### Saturation management

- **Interactive elements** (buttons, links, active tabs) use full-saturation brand color.
- **Backgrounds and containers** use desaturated, lightened variants: `bg-blue-50` not `bg-blue-500`.
- **Status colors** (success, error, warning) use medium saturation for backgrounds (`bg-green-50`, `bg-red-50`) with full saturation for text and icons (`text-green-700`, `text-red-700`).
- **Never use full-saturation color as a large background.** A `bg-blue-600` hero section screams template. Use `bg-white` or `bg-gray-50` with a blue accent element instead.

### When NOT to use color

- Section backgrounds — use whitespace or subtle borders to separate sections, not colored backgrounds.
- Every card having a colored accent — pick one or two cards to highlight, leave the rest neutral.
- Decorative color blocks with no information purpose.

---

## Typography in Practice

### Weight pairing

Use exactly two weights for most UI: `font-semibold` (600) for headings and labels, `font-normal` (400) for body and descriptions. Add `font-medium` (500) only if you genuinely need a third level (e.g., subheadings within a section). Never use `font-light` (300) — it's unreadable at small sizes on most screens.

### Size relationships

Maintain a clear step ratio between sizes. A practical scale:

| Role | Tailwind | Size |
|------|----------|------|
| Page title | `text-2xl` or `text-3xl` | 24-30px |
| Section heading | `text-xl` | 20px |
| Card title | `text-lg` or `text-base font-semibold` | 16-18px |
| Body | `text-sm` or `text-base` | 14-16px |
| Secondary/meta | `text-xs` or `text-sm` | 12-14px |

The key: adjacent levels in the hierarchy should be at least 2 Tailwind size steps apart. `text-base` heading with `text-sm` body works. `text-lg` heading with `text-base` body is too close.

### Line length

Body text should never exceed `max-w-prose` (~65ch). Text that stretches across a full-width container is the fastest way to look unprofessional. For headings, `max-w-2xl` keeps them from stretching too wide on large screens.

### Letter-spacing

- Large headings (`text-3xl` and up): add `tracking-tight` (-0.025em). Large text has too much natural spacing.
- Body text: leave default (no tracking class).
- All-caps labels or overlines: add `tracking-wide` or `tracking-wider`. Uppercase text without extra tracking looks cramped.

---

## Composition

### Alignment grids

Pick ONE alignment edge for content and stick to it across pages. Left-align is correct for 90% of SaaS UIs. Center-align only for: hero sections, empty states,