/beautify

name: beautify
description: "Use this skill when the user wants to make their app look better, says it looks like a template, asks how to achieve Stripe/Linear quality, or says something looks off. Covers visual hierarchy, whitespace, composition, color application, and typography in practice."

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 s