joshuadavidthomas/agent-skills/frontend-design-principles

Frontend Design Principles

Build frontend interfaces with craft and intention.

Scope & Routing

After this file, load the context-specific guide:

• `app.md` — dashboards, admin and settings panels, internal tools, SaaS products, data-heavy interfaces (tables, forms, lists), anything users work in repeatedly.
• `marketing.md` — landing pages, marketing sites, announcements, creative artifacts, anything where first impression matters most.

If unclear, ask. Blended projects need both: a SaaS marketing site uses marketing.md; its product dashboard uses app.md.

Why This Process Exists

You default to generic output — training patterns for dashboards and landing pages are strong. The process below helps, but process alone isn't craft: you have to catch yourself.

Where Defaults Hide

Defaults disguise themselves as infrastructure — the parts that feel like they just need to work, not be designed. There are no structural decisions. Everything is design.

• Typography isn't a container — it IS the design. A bakery tool and a trading terminal both want "clean, readable type," but warm-and-handmade is not cold-and-precise. Reaching for your usual font means you're not designing.
• Navigation isn't around the product — it IS the product. Where you are, where you can go, what matters most. A page floating in space is a component demo, not software.
• Data isn't presentation — it's meaning. A progress ring and a stacked label both show "3 of 10"; one tells a story, one fills space. Ask what the number means to the person looking at it.
• Token names are design decisions, not implementation detail. Someone reading only your CSS variables should be able to guess the product:

/* ❌ generic — could be any project */
--gray-700: …;  --surface-2: …;
/* ✅ domain — evokes this product's world */
--ink: …;  --parchment: …;

Required: Before Generating

Do not write code until these are done.

1. Answer the intent questions

Answer with specifics or ask the user — do not guess, do not default:

• [ ] Who is this human? Not "users." The actual person — where are they, what's on their mind, what did they do 5 minutes ago and 5 minutes after?
• [ ] What must they accomplish? The verb: grade these submissions, find the broken deployment, approve the payment.
• [ ] What should this feel like? Words that mean something. Not "clean and modern" (every AI says that) — warm like a notebook? cold like a terminal? dense like a trading floor?

2. Produce the four required outputs

• [ ] Domain: concepts, metaphors, vocabulary from this product's world — territory, not features. Min 5.
• [ ] Color world: colors that exist naturally in this domain. Go to the actual world, not "warm/cool." List 5+.
• [ ] Signature: one element — visual, structural, or interaction — that could only exist for THIS product.
• [ ] Defaults to reject: 3 obvious choices for this interface type, visual AND structural. You can't avoid patterns you haven't named.

3. Propose direction and confirm

Reference your domain concepts, colors, signature, and what replaces each rejected default.

Domain: [5+ concepts from the product's world]
Color world: [5+ colors that exist in this domain]
Signature: [one element unique to this product]
Rejecting: [default] → [alternative] ×3
 
Direction: [approach connecting the above]
 
Does that direction feel right?

Test: remove the product name from your proposal — could someone still identify what it's for? If not, explore deeper. Wait for confirmation before generating code.

Required: Before Showing

Your first output is probably generic; the work is catching it before the user has to. Look at what you made and ask "if they said this lacks craft, what would they mean?" — fix that first. Run these; iterate if any fails:

• [ ] Swap test: swap your typeface/layout for the usual one — would anyone notice? Where swapping wouldn't matter is where you defaulted.
• [ ] Squint test: blur your eyes. Is hierarchy still readable? Anything jumping out harshly? Craft whispers.
• [ ] Signature test: point to specific components where your signature appears. "The overall feel" doesn't count.
• [ ] Token test: read your CSS variables aloud. Do they belong to this product's world, or any project?

Principles

• Every choice must be a choice. For every decision — layout, color temperature, typeface, spacing scale, hierarchy — you can state WHY. "It's common / clean / it works" is a default, not a choice.
• Sameness is failure. If another AI given a similar prompt would produce substantially the same output, you failed. Design from intent and sameness is impossible — no two intents are identical. Linear's cards don't look like Notion's; Vercel's metrics don't look like Stripe's.
• Intent must be systemic. "Warm" then cold colors is not following through. If warm: surfaces, text, borders, accents, semantic colors, type — all warm. Check every token against the stated intent.
• Infinite expression. A metric can be a hero number, sparkline, gauge, delta, trend badge, or something new. Never ship the same sidebar width + card grid + icon-left-number-big every time — it reads as AI-generated instantly.

Craft Foundations

The quality floor, regardless of direction:

• Subtle layering. Surfaces barely different but distinguishable — whisper-quiet elevation shifts, not dramatic jumps (study Vercel, Supabase, Linear). Borders light enough to disappear until you look for structure; if they're the first thing you notice, they're too strong.
• Color lives somewhere. Spend time in the product's physical world before reaching for a palette — materials, light, objects. It should feel like it came FROM somewhere, not applied TO something. Gray builds structure; color carries meaning. One intentional accent beats five thoughtless ones.

Universal Anti-Patterns

Always wrong, regardless of context:

• Dramatic drop shadows — box-shadow: 0 25px 50px … looks cheap
• Arbitrary asymmetric padding — every value should be intentional
• Thick decorative borders — 2px+ for visual weight
• Multiple accent colors — one accent, used consistently
• Mixing depth strategies — borders OR shadows, not both randomly
• Inconsistent spacing — the clearest sign of no system

Communication

Be invisible. Don't announce modes or narrate process ("Let me explore the domain…", "Running the checks…"). Jump into the work; state suggestions with reasoning.

Deep Dives

• references/principles.md — spacing, depth, typography, color implementation, dark mode (concrete values and CSS)
• app.md — dashboards, admin panels, SaaS products
• marketing.md — landing pages, marketing sites, creative artifacts