Beautify

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 for specific antipattern remediation. Reference 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:

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, and confirmation dialogs. Never center body text, form fields, or data.

Visual rhythm

Repeating elements (cards, list items, table rows) must be identical in structure. Same padding, same text sizes, same spacing between elements within each item. Variation in repeating elements creates visual noise — the eye constantly readjusts instead of scanning smoothly.

Page-level balance

• F-pattern for content pages: Primary content left, secondary content right. The eye naturally scans left-to-right, top-to-bottom.
• Single-column for focused tasks: Forms, checkout flows, onboarding steps. Max-width max-w-lg to max-w-xl, centered.
• Sidebar + content for dashboards: Fixed-width sidebar (w-64), fluid content area. Content area should have its own internal max-width for readability.

Asymmetry that works

Not everything needs to be perfectly centered or symmetrical. A page with a large content area and a narrow sidebar is asymmetric but balanced because the content has visual weight. A card grid with 3 columns where the first card is double-width creates intentional asymmetry that draws the eye.

---

Consistency

Cross-page coherence

Every page in the app should share:

• Identical header/nav height and style
• Same page padding and max-width
• Same heading hierarchy (h1 = page title at same size everywhere)
• Same card style (if pages use cards)
• Same button variants (primary/secondary/ghost look identical on every page)

Pattern reuse

When building a new page, explicitly reuse patterns from existing pages. Don't invent a new card style when one exists. Don't create a new button variant when primary/secondary/ghost covers the need. Every unique visual pattern adds cognitive load.

The "same but different" problem

Lists of items (pricing plans, feature comparisons, team members) should use identical visual structure with only content changing. When one pricing card has an icon and another doesn't, or one has a colored background and others don't, it creates unintentional hierarchy. If you need to highlight one option, do it with a single differentiator: a border color, a "Popular" badge, or a slight size increase — not three differences at once.

---

Auditing

For structured audit checklists (60-second scan and comprehensive), use the design-review skill. The principles in this skill inform what to look for; design-review provides the systematic checklist.

AI Slop Fixes

Specific antipatterns that appear in AI-generated UI and how to fix them. When auditing or improving a user's app, check for each of these patterns and apply the fix directly.

---

Too Many Borders

Symptom: Every element — cards, inputs, sections, containers, headers, footers — has a visible border. The page looks like a wireframe or a spreadsheet.

Why AI does this: Borders are the safest way to create visual separation. AI defaults to explicit containment because it never has to "see" the result and judge whether separation is already achieved through spacing or background contrast.

Fix: Remove borders from cards and use shadow-sm or background contrast (bg-white on bg-gray-50) instead. Keep borders only on inputs, tables, and explicit dividers. A card on a gray background needs no border at all — the background contrast creates the boundary.

Before: border border-gray-200 rounded-lg p-4 (on every card, on a white background)
After:  bg-white rounded-lg p-6 shadow-sm (on a bg-gray-50 page)
  or:   bg-white rounded-lg p-6 (on a bg-gray-100 page — no shadow needed)

---

Overuse of Cards

Symptom: Every piece of content is wrapped in a card container — single stats, labels, individual form fields, paragraphs of text. Cards nested inside cards.

Why AI does this: Cards are the default "container" pattern. AI wraps content in cards as a structural reflex, especially for dashboard layouts and data display.

Fix: Cards are for grouping related content that could plausibly be rearranged or compared. A single metric doesn't need a card — it needs a heading and a value. A form doesn't need each field in a card. Remove card wrappers from: individual stats (use a grid with shared background), form sections (use spacing and headings), single paragraphs, and any content that's already inside a card.

Before: 4 stat cards, each with border + shadow + padding, each containing one number
After:  One stats row with grid-cols-4, shared background, dividers between items
  or:   Simple flex row with gap-8, each stat is just a label + value, no container

---

Everything the Same Size

Symptom: Page title, section headings, card titles, and body text are all within 2-4px of each other. Nothing jumps out. The page reads as a wall of text.

Why AI does this: AI generates structurally correct HTML (h1, h2, h3, p) but applies timid size differences. It avoids dramatic sizing because extreme differences feel "risky."

Fix: Force dramatic size contrast. Page title should be at least 2x the body text size. Apply this rule: if two adjacent heading levels don't look obviously different at arm's length, the difference isn't big enough. Use text-3xl font-bold for page titles, text-lg font-semibold for section heads, text-sm for body. Skip intermediate sizes.

---

Rainbow Soup

Symptom: Multiple saturated colors on one screen — blue buttons, green badges, orange alerts, purple tags, red notifications, teal links. Every element has its own color.

Why AI does this: AI assigns semantically "appropriate" colors to each element independently without considering the aggregate effect. Green for success, blue for primary, orange for warning — individually reasonable, collectively chaotic.

Fix: Enforce the 60-30-10 rule. The fix is usually: make most things gray. Tags and badges that don't indicate status should be bg-gray-100 text-gray-700, not colored. Links should match the primary color, not be a separate blue. Limit the entire page to: one brand accent, one success green, one error red, and gray for everything else. Remove any color that doesn't answer the question "what status or action does this color communicate?"

Before: Blue button, green badge, orange tag, purple category, teal link
After:  Blue button, gray badge, gray tag, gray category, blue link
  (add color ONLY to badges that indicate live status: green=active, red=failed)

---

Generic Spacing

Symptom: Everything is spaced with gap-4 or p-4. Cards, sections, form fields, page margins — all use the same spacing value. The page feels monotonous and flat.

Why AI does this: Uniform spacing is safe. AI picks one comfortable value and applies it everywhere because varying spacing requires understanding visual grouping.

Fix: Apply the 2-3x rule. Space within groups should be smaller than space between groups. Within a card: gap-2 to gap-3. Between cards: gap-6. Between sections: py-12 to py-16. Page top padding: pt-8. This creates rhythm — the spacing itself communicates structure.

Before: Everything gap-4 p-4 space-y-4
After:  Card internal gap-3, between cards gap-6, between sections py-16, page px-8

---

Centered Everything

Symptom: Body text, form fields, card content, descriptions, and lists are all text-center. The page looks like a presentation slide, not an application.

Why AI does this: Center alignment feels "designed" and "balanced." AI defaults to center because it works for marketing hero sections, and it overapplies the pattern.

Fix: Left-align everything except: hero headlines, empty state messages, and confirmation dialogs. Forms should always be left-aligned. Card content should be left-aligned. Data and descriptions should be left-aligned. Numbers in tables should be right-aligned. Apply text-left as the default and explicitly justify center-alignment for the rare cases where it belongs.

---

Cluttered Headers

Symptom: The page header contains the logo, navigation, search bar, notification bell, user avatar, dropdown menu, breadcrumbs, and a CTA button — all fighting for attention in a 64px strip.

Why AI does this: AI includes every standard header element it's been trained on. Each element is individually reasonable, but combined they create visual overload.

Fix: Headers should contain at most: logo/name (left), primary nav (center or left), and 2-3 utility items (right). Move breadcrumbs below the header into the content area. Move search into the main content area or behind a toggle. Reduce icon sizes to 18-20px. Use text-gray-500 for utility icons, not text-gray-900. The header's job is navigation, not information display.

Before: Logo | Nav | Search bar | Bell | Messages | Help | Avatar | CTA | Breadcrumbs
After:  Logo | Nav (3-5 items) | Search icon | Bell | Avatar
  (breadcrumbs go below header, search opens on click, help moves to a menu)

---

Identical Page Layouts

Symptom: Every page is a carbon copy — same header, same single-column layout, same card grid, same spacing. The settings page looks like the dashboard which looks like the user list.

Why AI does this: It reuses the last successful layout. Once a page works, every subsequent page gets the same structure because deviation requires understanding what each page uniquely needs.

Fix: Match layout to purpose. Dashboards use multi-column grids with metric cards. Detail pages use a wide content area with a narrow sidebar for metadata. Settings pages use a left nav with a content panel. Form pages use single-column centered layout at max-w-lg. The layout communicates what type of page you're on before reading a single word.

---

Overly Rounded Corners

Symptom: Buttons are pills (rounded-full). Cards have rounded-2xl or rounded-3xl. Inputs match. Everything looks like a children's app or a medical device UI.

Why AI does this: High border-radius feels "modern" and "friendly." AI overindexes on roundness because it's a visible design choice that seems intentional.

Fix: For most SaaS apps, rounded-md (6px) to rounded-lg (8px) is correct for cards, buttons, and inputs. Reserve rounded-full exclusively for avatars, small status indicators, and pill-shaped tags. Match radius to element size — small elements (badges) can be rounder, large elements (cards, modals) should be less round. A good test: if the radius is visible as an obvious curve rather than a subtle softening, it's probably too much.

Before: rounded-full on buttons, rounded-3xl on cards, rounded-2xl on inputs
After:  rounded-md on buttons, rounded-lg on cards, rounded-md on inputs

---

Gratuitous Shadows

Symptom: Every card, button, input, badge, and container has a shadow. The page looks like a pile of floating Post-it notes.

Why AI does this: Shadows create perceived depth and "polish." AI adds them to make elements feel finished, but when everything is elevated, nothing is.

Fix: Shadows should indicate interactive elevation — elements that float above the page (dropdowns, modals, tooltips, popovers). Static content cards on a bg-gray-50 background don't need shadows — background contrast is sufficient. Remove shadows from: cards that aren't hoverable, badges, static containers, and inputs (use border instead). Keep shadows on: dropdowns, modals, floating toolbars, and hover states on clickable cards.

---

Placeholder-Quality Images and Icons

Symptom: Hero sections with unsplash stock photos. Feature sections with generic outline icons that don't match the app's style. Illustrations that look like they came from a different product.

Why AI does this: AI fills image placeholders with the most generic appropriate content. It selects icons individually without considering whether the set is visually cohesive.

Fix: Remove decorative images entirely rather than using stock photos — whitespace is better than a generic image. For icons, use a single icon library (Lucide, Heroicons, or Phosphor) at consistent sizes and stroke widths. Never mix libraries. For empty states and illustrations, use simple abstract shapes or the product's own UI elements as illustrations rather than stock illustrations. If the product doesn't have custom illustrations, a well-styled text block is better than a generic SVG illustration.

---

Inconsistent Alignment Between Sections

Symptom: The hero section has content at max-w-4xl, the features section stretches full-width, the pricing cards use max-w-6xl, and the footer uses max-w-5xl. Each section starts at a different horizontal position.

Why AI does this: Each section is generated as an independent unit. AI optimizes each section for its own content without maintaining a shared alignment grid across the page.

Fix: Define one max-w container and use it for every section's content. The background can be full-width, but the content within must align to the same grid. Typically max-w-6xl mx-auto px-6 for the outer container, with inner content using grid or flex for narrower columns where needed. Every section's left edge of content should align with every other section's left edge.

Before: Section 1 max-w-4xl, Section 2 max-w-full, Section 3 max-w-5xl
After:  All sections use max-w-6xl mx-auto px-6, inner content varies width as needed

Reference Teardowns

What makes premium apps look premium. Not surface-level observations ("Stripe uses purple") — specific techniques that can be transferred to any app.

---

Stripe (Dashboard)

Category: Financial data, API management, payments

Key aesthetic moves:

• Extreme typographic hierarchy on data. Revenue numbers are displayed at text-4xl font-semibold while their labels are text-xs font-medium text-gray-500 uppercase tracking-wider. The ratio between data and label is roughly 4:1 in visual weight. This makes numbers scannable from across a room — you absorb the data before you read the label.

• Restrained color on a neutral canvas. The dashboard is 95% white and gray. Color appears only for: the brand purple (CTAs and active nav), semantic status (green for succeeded, red for failed, yellow for pending), and charts. No colored section backgrounds, no colored card headers, no decorative color. This makes the colors that DO appear extremely meaningful.

• Information density without clutter. Tables show 8-10 columns with text-sm, tight row padding (py-3), and no row borders — only a subtle hover:bg-gray-50. The density is high but readable because typography does the separation work, not borders. Column headers are text-xs text-gray-500 uppercase tracking-wide — a completely different visual register from cell content, so headers never compete with data.

• Progressive disclosure through surface levels. The main view shows summary cards. Clicking into a card reveals a detail view with its own hierarchy. Each level uses whitespace and typography scale to indicate depth — drill-down pages have slightly less page padding and denser layouts than the overview, subtly signaling "you're one level deeper."

What to steal: Use dramatically different typographic treatments for data vs. labels (4:1 size ratio, different weights, different colors). Make the data the hero, make the label quiet. Apply this to any dashboard metric, stat card, or summary view.

---

Linear

Category: Project management, issue tracking

Key aesthetic moves:

• Monochrome with surgical accent color. The dark interface is built from 3-4 shades of dark gray (#1a1a1a to #2a2a2a to #3a3a3a). The only color comes from status indicators (purple, yellow, green, red dots — each 8px) and the currently active item's highlight. This extreme restraint makes every colored pixel meaningful. When you see purple, it means "in progress" — not decoration.

• Speed as aesthetic. Animations are 100-150ms (most apps use 200-300ms). Transitions use ease-out curves that start fast. Keyboard shortcuts are shown inline next to menu items in text-xs text-gray-500 font-mono. The visual language communicates "this tool is fast" through timing, not through marketing copy about speed.

• Flat hierarchy with hover-reveal. List items show only the essential info (title, status dot, assignee avatar) at rest. Actions (priority selector, label picker, due date) appear on hover. This keeps the default view clean and scannable while maintaining full functionality. The hover state uses a subtle bg-gray-800/50 to indicate interactivity without disrupting the visual flow.

• Typographic minimalism. One font (Inter), two weights (400 and 500), three sizes. Issue titles are text-sm font-medium, descriptions are text-sm font-normal text-gray-400, metadata is text-xs text-gray-500. The hierarchy is created entirely through color value (white vs. gray-400 vs. gray-500) rather than size differences.

What to steal: Create hierarchy through color value (brightness) instead of size. Three levels of gray on the same font size creates a clean, dense interface that doesn't sacrifice scanability. This works exceptionally well for list-heavy interfaces.

---

Vercel

Category: Deployment platform, developer tools

Key aesthetic moves:

• Typographic confidence at scale. Landing page headings use text-6xl to text-8xl with font-bold tracking-tighter. The letter-spacing is noticeably tight — -0.04em to -0.05em — which makes large text feel precise and engineered rather than generic. Body text is comparatively small (text-base or text-sm), creating a dramatic hierarchy. The heading IS the design — no supporting imagery needed.

• Black and white as a power move. The palette is essentially black (#000), white (#fafafa), and one accent (the triangle gradient for the logo). This isn't laziness — it's confidence. By removing all color decisions, every element is defined by typography, spacing, and composition alone. This forces the typography and layout to be excellent because there's nothing else to lean on.

• Generous vertical rhythm. Sections are separated by py-24 to py-32 — far more than most apps. Each section feels like a distinct "room" you scroll into. Within sections, content groups use gap-6 to gap-8. The contrast between tight internal spacing and expansive section gaps creates a breathing rhythm that feels premium.

• Geometric precision. Elements snap to an obvious grid. Card corners are consistently rounded-lg. Code blocks use rounded-md with a monospace font at exactly the right size to feel native to the surrounding type. Nothing is decorative — every element earns its space.

What to steal: Use tight letter-spacing (tracking-tight or tracking-tighter) on large headings. It immediately elevates typography from default to intentional. Pair with generous section spacing (py-20 to py-32) to create the "rooms" effect.

---

Notion

Category: Knowledge management, documents, wikis

Key aesthetic moves:

• Content-first by subtraction. The UI chrome is nearly invisible. The sidebar is plain text with small icons — no backgrounds on nav items, no borders, minimal hover states (just a bg-gray-100 rectangle). The toolbar appears only on hover or selection. This aggressively removes everything that isn't your content, making the content itself feel important.

• Warm neutrals instead of cool grays. Notion's grays have a slight warm tint — they lean toward #37352f instead of #374151. This makes the interface feel like paper rather than a screen. The background isn't #ffffff but a slightly warm off-white. The difference is subtle but cumulative: the entire app feels calm and approachable rather than clinical.

• Spacious line-height and wide content. Body text uses line-height: 1.7 to 1.8 — significantly more than the typical 1.5. Content blocks have generous vertical margins. The editing area is max-w-3xl centered, which keeps text readable without feeling cramped. This spaciousness is the core brand — it says "you have room to think here."

• Type as UI. Page titles, headings, toggles, callouts — almost every UI element is primarily a typographic choice rather than a component with borders and backgrounds. A "callout" is just an emoji + indented text with a light background. A "toggle" is a triangle icon + text. By building UI from typography rather than from boxes, the interface feels lightweight and flexible.

What to steal: Increase line-height to 1.7 for content-heavy apps. Switch from cool grays to warm grays (add a hint of brown/amber to your gray scale). These two changes make any content-focused app feel calmer and more readable.

---

Mercury

Category: Business banking, financial dashboard

Key aesthetic moves:

• Trust through restraint. The color palette is almost entirely gray-blue neutrals (#f8fafc, #e2e8f0, #64748b) with money amounts in near-black. The only deliberate color is a muted green for positive values and muted red for negative. No bright blues, no gradients, no visual excitement. Financial apps earn trust by being boring — visual restraint communicates "we take your money seriously."

• Premium whitespace ratios. Account balance is displayed with text-3xl font-light (note: light weight, not bold — this is unusual and distinctive) with mb-1 to a text-sm text-gray-500 label below. The entire balance section sits in py-8 of whitespace before the transaction list begins. The transaction list then uses tight spacing (py-3 per row). This contrast — expansive space around the hero data, dense space for the detail — communicates "the balance is what matters, transactions are supporting detail."

• Horizontal line as design element. Sections are separated by a single border-b border-gray-200 with generous margins above and below (my-8). No cards, no shadows, no background changes. Just a thin gray line and whitespace. This minimal separation technique feels more premium than cards because it implies the content is important enough to stand on its own without containment.

• Type weight inversion. Where most apps use bold for important numbers, Mercury uses font-light for the primary balance and font-medium for smaller amounts in the transaction list. This counterintuitive choice works because the large size already creates hierarchy — adding bold would be redundant. The light weight feels elegant and confident, like a luxury brand that doesn't need to shout.

What to steal: Try font-light on your largest, most important number. When an element is already the largest thing on screen, light weight adds elegance while bold adds nothing. Use thin horizontal rules (border-b border-gray-200) instead of cards to separate sections — it's the more confident choice.