| name | frontend-design-principles |
| description | Use when building or reviewing frontend UI — dashboards, admin panels, landing pages, marketing sites, web apps. Drives domain-specific design decisions (typography, color world, layout, CSS token naming, depth and spacing systems) instead of generic AI defaults; routes to app.md (product/data UIs) or marketing.md (public/creative pages) by context. |
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:
--gray-700: …; --surface-2: …;
--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:
2. Produce the four required outputs
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:
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 productsmarketing.md — landing pages, marketing sites, creative artifacts
