frontend-aesthetics

When to Use

Triggers: When building UI, a landing page, dashboard, settings panel, or any user-facing interface — before writing markup or choosing fonts, colors, or motion.

Load when: starting a UI from scratch, redesigning a generic-looking interface, or when the output "looks like every other AI-generated site." This skill governs VISUAL CRITERION, not technical correctness — pair it with react-19 / tailwind-4 / nextjs-15 for the implementation layer.

Core problem it solves: without explicit guidance, generation converges toward "on-distribution" defaults — generic, safe, forgettable. This skill forces distinctiveness.

The Direction-First Process

NEVER open a UI task by writing markup. Lock these five decisions FIRST, state them explicitly, then generate code constrained by them:

1. Aesthetic direction — name it concretely: brutalist, editorial, retro-futuristic, solarpunk, luxury, terminal/IDE, playful, Swiss-minimal. "Modern and clean" is NOT a direction — it's the absence of one.
2. Font pairing — one distinctive pairing with high contrast (see Pattern 1).
3. Constrained color system — one dominant + sharp accents, as CSS variables (see Pattern 2).
4. Motion focus point — ONE orchestrated moment, not scattered micro-interactions (see Pattern 3).
5. Background/depth treatment — atmosphere over flat solid color (see Pattern 4).

Interpret creatively. Make unexpected choices that feel genuinely designed for THIS context. Vary between light/dark, different fonts, different aesthetics across projects — do not converge on one house style.

Critical Patterns

Pattern 1: Typography — high contrast, not defaults

Overused defaults to AVOID: Inter, Roboto, Arial, system fonts. Reach for a distinctive pairing instead:

Code / terminal aesthetic  → JetBrains Mono, Fira Code, Space Grotesk
Editorial / publication    → Playfair Display, Crimson Pro, Fraunces
Startup / product          → Clash Display, Satoshi, Cabinet Grotesk
Technical / systems        → IBM Plex family, Source Sans 3
Distinctive / expressive   → Bricolage Grotesque, Obviously, Newsreader

Contrast rules:

• Pair across categories: display + monospace, serif + geometric sans, or one variable font across extreme weights.
• Use extreme weight jumps (100/200 vs 800/900), not adjacent weights.
• Use size jumps of 3x+, not timid 1.5x steps.

Pattern 2: Color — dominant + sharp accents

Dominant colors with sharp accents outperform timid, evenly-distributed palettes. Draw from IDE themes and cultural aesthetics, NOT generic SaaS palettes.

/* ✅ Constrained system: one dominant, sharp accents, as CSS variables */
:root {
  --color-primary:   #FF6B35; /* dominant */
  --color-secondary: #004E89;
  --color-accent:    #FFD23F; /* sharp accent — used sparingly */
}

❌ Purple/violet gradient on white background   → the #1 AI-slop tell
❌ Evenly-distributed 6-color palette            → reads as timid
✅ One dominant carrying 70%+, accent for punch

Pattern 3: Motion — one orchestrated moment

One well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions everywhere.

/* ✅ Staggered reveal on load — CSS-only for plain HTML */
@keyframes rise { from { opacity: 0; transform: translateY(1rem); } to { opacity: 1; transform: none; } }
.reveal { animation: rise 0.6s ease-out both; }
.reveal:nth-child(1) { animation-delay: 0.05s; }
.reveal:nth-child(2) { animation-delay: 0.15s; }
.reveal:nth-child(3) { animation-delay: 0.25s; }

• Plain HTML → CSS-only (animation-delay staggering).
• React → the Motion library (motion) when available.
• Focus effort on ONE high-impact moment, not decorative flourishes throughout.

Pattern 4: Spatial depth — atmosphere over flat

Create atmosphere and depth instead of defaulting to a solid background color. Layer gradients, geometric patterns, or contextual effects that match the aesthetic.

/* ✅ Layered radial gradients for depth */
body {
  background:
    radial-gradient(60rem 40rem at 15% -10%, color-mix(in oklab, var(--color-secondary) 25%, transparent), transparent),
    radial-gradient(50rem 30rem at 110% 20%, color-mix(in oklab, var(--color-primary) 20%, transparent), transparent),
    #0d0d0f;
}

Also valid: asymmetry, grid-breaking elements, contextual textures. Avoid perfectly centered, evenly-spaced, symmetric-everything layouts — they read as cookie-cutter.

Complete Example

Prompt: "Build a landing page for an AI security startup"

Direction-first decisions, stated before any code:

1. Direction:  terminal/IDE aesthetic — the product IS technical, lean into it
2. Fonts:      Space Grotesk (display, 800) + JetBrains Mono (body/labels) — 3.5x size jump on hero
3. Color:      dominant near-black IDE bg; accent terminal-green (#00FF9C); one warning-amber accent
4. Motion:     single staggered hero reveal (headline → subhead → CTA), CSS animation-delay
5. Depth:      layered radial gradients (green glow top-left) + faint monospace grid texture

Then generate markup constrained by exactly those five — never the reverse.

Quick Reference

Decision	AI-slop default (avoid)	Distinctive choice
Font	Inter / Roboto / system	Cross-category pairing (Pattern 1)
Color	Purple gradient on white	One dominant + sharp accent (Pattern 2)
Weight contrast	400 vs 600	200 vs 900
Size scale	1.5x steps	3x+ jumps
Motion	Scattered hover micro-effects	One orchestrated load (Pattern 3)
Background	Solid flat color	Layered gradients / texture (Pattern 4)
Layout	Centered, symmetric, even	Asymmetry, grid-breaking

Rules

• Lock the five direction-first decisions and state them EXPLICITLY before writing any markup — generating code first and styling after is the failure mode this skill exists to prevent
• Never ship Inter, Roboto, Arial, or system fonts as the primary typeface unless the user explicitly requests them
• Never ship a purple/violet gradient on a white background — it is the canonical AI-slop signature
• One dominant color carries the palette; accents are sharp and used sparingly — reject evenly-distributed multi-color palettes
• Concentrate motion into ONE orchestrated moment (typically page load with staggered reveals); do not scatter micro-interactions across the page
• Prefer CSS-only motion for plain HTML; use the Motion library for React when available
• This skill governs visual criterion ONLY — it does not replace react-19/tailwind-4/nextjs-15 for implementation correctness; load both layers together
• A named aesthetic direction is mandatory; "modern", "clean", and "minimal" are not directions unless paired with a concrete style (e.g. "Swiss-minimal")