Designing Frontend

A comprehensive design knowledge base for building polished, professional frontends. Apply these principles when creating new interfaces or auditing existing ones. Framework-agnostic: the principles work with any CSS approach (vanilla, Tailwind, CSS modules, etc.).

Reference Files

Scope

Match the scope of the design work to the scope of the request. A change to one component does not warrant project-wide changes to color systems, spacing tokens, or theme infrastructure. A small fix needs one relevant principle, not a reference file.

If the project already has a design system, follow it. Everything here applies when building from scratch, or where the project has no established pattern for what you are about to build.

Core Principles

These cross-cutting principles apply to every frontend task. Reference files contain the specific techniques and values.

1. Simple Over Clever

Good design is as little design as possible. More design almost always results in uglier design. Simple does not mean minimal to the point of uselessness — all essential elements must be present. The biggest visual payoff comes from taking an average design to "good" — pushing from good to great yields diminishing returns.

2. Hierarchy Is Everything

Users scan, they don't read. Emphasize what users look for first using size, weight, and color. De-emphasizing secondary elements is often more effective than making the primary element bigger or bolder. Always zoom out to verify scannability.

3. Spacing Makes or Breaks a Design

All spacing, sizing, padding, and margin values should be divisible by 4 (converted to rem by dividing by 16). Elements need more spacing than you think — start generous, reduce until it feels right when viewed as a whole. Use Gestalt proximity: spacing between elements signals grouping.

4. Limit Your Palette

A complete UI needs only: neutral background/text shades, a brand/primary color, and a few semantic state colors. Use HSL or OKLCH (not hex/RGB) — they map directly to design decisions. Create 3-4 shades per color by adjusting lightness in consistent increments.

5. Follow Conventions

Users should understand what to do instantly without thinking. Stick to established UI patterns (nav at top, buttons look like buttons, magnifying glass = search). Deviating from conventions forces thought. Following conventions is good design, not boring design.

6. Show, Don't Tell

Every section should be mostly something to look at, with text as its caption — not mostly prose with a decorative icon on top.

A wall of feature cards, each a heading and two sentences explaining a benefit, is the most common way a well-tokenized page still reads as machine-made. Replace the explanation with the thing it describes: a claim about speed becomes a real chart, a three-step setup becomes three visual panels, a feature becomes a mockup of that feature.

Before writing a paragraph to explain something, ask whether a visual could carry it with a caption instead. Default to the visual. Load references/page-composition.md for the full conversion table and the higher floor that proof sections carry.

7. Design With Character

Every product has a personality — discover it before building. A financial dashboard feels different from a creative portfolio, which feels different from a developer tool. Ask: if this product were a person, how would they dress? How would they speak? Ask: what makes this design unforgettable? What's the one thing someone will remember after closing the tab?

Commit to a clear aesthetic direction. Some flavors to consider: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian. These are starting points — the right direction comes from the product's purpose and audience. Several of them (editorial, retro-futuristic, brutalist) are also where generated interfaces already cluster, so choose one only when the brief points there, never as the safe pick.

Generated frontends converge on a few looks regardless of subject; the current clusters and older tells are listed in references/ux-and-components.md under "Avoiding the AI Look". The durable test: if someone could guess the aesthetic from the product category alone, rework it. Any cluster is legitimate when the brief asks for it; landing in one when the aesthetic was free means the choice was never made. The antidote is intentional character — expressed through color boldness, type choices, copy tone, spacing rhythm, and interaction style.

Character is scaled by the surface's mode (see Order of Decisions). On a Persuade or Experience surface it can own the page. On an Operate surface the product's world lends only four things: type, palette, density, and one signature move. It never supplies the layout, the navigation model, or the controls, and an instrument aesthetic (terminal, cockpit, control panel) on a working screen is a costume, not character. On a Read surface character lives in reading comfort.

Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations, textures, and effects. Minimalist designs need restraint, precision, and careful attention to spacing and typography. Bold maximalism and refined minimalism both work — the key is intentionality, not intensity.

Don't limit character to color and typography. Consider spatial composition (asymmetry, overlap, diagonal flow, grid-breaking elements) and atmospheric details (noise textures, gradient meshes, grain overlays, layered transparencies, custom cursors). These are tools, not requirements — use them when they serve the vision.

Before building, identify at least one distinguishing trait: a bold color, an unusual type pairing, a distinctive interaction pattern, a specific tone of voice, or a deliberate layout choice that makes this product feel like this product and not a template. Load references/ux-and-components.md for detailed guidance on design personality.

8. Motion Is a Budget, Not a Garnish

Before animating anything, ask how often a user will see it. An action performed a hundred times a day gets no animation ever; an action performed once gets room for delight. An animation on a high-frequency interaction charges its attention cost on every single trigger.

Motion is also never the only feedback channel. Every state change an animation communicates must stay visible when the animation does not run — a color, an icon, a label.

9. Sameness Lives in the Page Shape

Two sites with different palettes and the same skeleton are the same site twice. The generic rhythm — hero, three feature cards, testimonial, call to action, footer — is the strongest machine-made signal at the page level, and it survives a perfect palette.

Two habits break it. Pick the page shape by name before building, and say which one and why — an unstated decision reverts to the most common option every time. And find the one intentional rule-break: a design where everything sits on the grid, evenly spaced and perfectly safe, reads as generated even when every token is right. One deliberate break is the budget, not a licence to stack decorative gestures.

10. The Unseen Details Compound

Nobody reports that an inner radius is off by 4px or that an icon is two pixels from optical center. They report that the product feels cheap, or they say nothing and trust it less. Concentric radii, optical alignment, matched icon weights, and correct image edges are individually invisible and collectively decisive.

Load references/surface-craft.md when building or reviewing any component surface.

House Values

Where sources disagree, these are the calls. Use them unless the project has already standardised on something else — an established project convention always wins over this list.

Never approximate a specified curve or scale value with a similar-looking one. cubic-bezier(0.2, 0, 0, 1) is not cubic-bezier(0.4, 0, 0.2, 1), and 0.96 is not 0.95.

Order of Decisions

Some decisions constrain the ones after them, so their order is not arbitrary:

1. What the thing is, and its mode — a marketing page, an app shell, a form, a data view, an editor, a state screen. This governs density, motion, and component choice more than anything else. A marketing page can teach through scroll; a tool earns trust by getting out of the way. Name the mode, and say which and why, as with the page shape (principle 9). The mode comes from the requested surface, not the product: a dev tool's landing page is Persuade, a docs index is Read, and one surface has one mode.

   	Persuade	Operate	Read	Experience
   Examples	Landing, pricing, campaign	App UI, dashboard, editor, settings	Docs, articles, help, changelog	Portfolio, gallery, showcase
   Success means	The visitor understands the offer and acts	The task gets done	The reader understands	The visitor is inside the work
   Character lives in	The whole page	Type, palette, density, one signature move	Reading comfort and structure	The work itself; the interface recedes
   Layout and controls	Expressive where it serves the argument	Standard and conventional	Structure and wayfinding first	Led by the work
   Motion	Authored, scoped to the argument	Feedback and state changes only	Near zero	Whatever the work needs
   Go deeper	page-composition.md	App shells in page-composition.md	Measure and type in typography-and-spacing.md	page-composition.md, animation-and-motion.md

   Every mode stays behind the motion frequency gate (principle 8).

2. What the argument or task is — for a page, the beats it needs; for a screen, the one job it does.
3. Shape — the page shape or shell frame that carries it, picked by name.
4. Layout, type, color — the token layer. Color last of the three, because it is chosen against real type and real surfaces.
5. Spacing, depth, hierarchy — verified by zooming out, not by reading the values.
6. Motion — only where it earns its place.
7. The craft pass — radius, optical alignment, states, keyboard access, overflow, locale, and the words themselves.

Not every piece of work touches all seven. A single component starts at step 4.

Audit Checklist

When reviewing existing frontend code, check these areas. Load the relevant reference file for detailed criteria on any failing item.

Composition

• Each section is mostly something to look at, with text as caption — not prose with a decorative icon
• The page shape is a named, deliberate choice, not the reflexive hero → three cards → CTA → footer
• No two sections on the page use the same archetype
• Reading top to bottom, each section has a job in the argument; at least four distinct beats
• Section padding is weighted by role, not flattened to one value
• One section-separation mechanism used consistently at every boundary
• Two-column sections have a deliberate balance treatment, not a column trailing into empty space
• One intentional rule-break exists; the page is not uniformly safe
• No hand-built fake browser, phone, or IDE chrome
• Every metric, quote, and logo is real, or honestly marked as a placeholder
• No eyebrow label above a heading unless it adds context the heading cannot; never one repeated above every section
• No section numbers (01 / 02 / 03) unless the sequence itself carries information

Color & Theming

• Colors defined as CSS variables or design tokens, not hardcoded
• Using HSL or OKLCH format for easy palette manipulation
• Limited palette: primary + secondary + accent + neutrals + semantic states
• Contrast checked for every pairing the build introduced, not only body text on background
• Button label against its fill verified separately; a fill that passes as a swatch can fail as a button
• No dark panel left with dark text; lightness inversion carries to nested children
• Accent stays an accent, roughly 5% of a viewport or less
• Dark mode support (if applicable) uses proper shade inversion
• Light or dark chosen from the physical use scene, not from the product category
• No gradient text

Typography & Spacing

• Consistent type scale (not arbitrary font sizes)
• Single font family (or deliberate pairing with clear roles); at most three families on a page
• Line height inversely proportional to font size, with 1.0 as the floor on display type
• No italic headings; emphasis carried by weight, color, or an underline
• Monospace only for code, data, and measurements; never body copy or a "technical" costume on headings and labels
• No small all-caps, letter-spaced labels; labels and metadata in sentence case
• Typeface chosen for the product's feel, named in a few words before picking
• Long-form text capped at 60-75 characters per line
• Nothing below 18px set lighter than weight 400
• Anything wrapping to three or more lines has line-height 1.4 or more
• text-wrap: balance on headings, pretty on descriptions
• Truncated content stays reachable somewhere
• No center-aligned paragraphs (only short headings/labels)
• All spacing values divisible by 4 (in px) or clean rem values
• Gestalt proximity: related items close, unrelated items far

Layout & Responsiveness

• Flexbox as default, Grid only for structured/uniform layouts
• Dynamic sizing (viewport units, clamp(), flex ratios) over hardcoded pixels
• Responsive behavior planned and tested, not just "it doesn't break"
• Hover effects wrapped in @media (hover: hover) for touch safety
• Images served responsively with <picture> or srcset where appropriate

Depth & Hierarchy

• Visual hierarchy clear when zoomed out (primary > secondary > tertiary)
• Shadow system consistent (not random box-shadow values per element)
• Secondary content de-emphasized rather than primary over-emphasized
• Interactive elements have clear hover/focus/active states

Animation

• Every animation passes the frequency gate — nothing animates on a high-frequency or keyboard-initiated action
• No ease-in on UI; exits are ease-out and shorter than enters
• No transition: all — exact properties named
• Nothing enters from scale(0); entrances start at 0.9-0.95 with opacity
• Anchored surfaces (popovers, dropdowns, tooltips) scale from their trigger, not center
• Rapidly re-triggerable elements use transitions, not keyframes
• Every animated state change also has a static cue (color, icon, label)
• Motion respects prefers-reduced-motion media query
• Hover animations wrapped in @media (hover: hover)
• Theme switching does not smear (transitions suppressed for the swap)

Surface Craft

• Nested rounded elements are concentric (outer = inner + padding)
• Icons optically centered, not just geometrically
• Borders used for structure, shadows for depth — not interchangeably
• Images carry a pure black/white 10% outline, never a tinted one
• Icon stroke weight matches adjacent text weight; one icon library per surface
• Icons still legible at their smallest render size
• No colored border-left/border-right above 1px as a card, callout, or list-item accent
• Browser-drawn surfaces themed from the palette: selection, caret, scrollbars, focus ring, underline offset, tabular numerals

Internationalization & Device

• Direction-dependent CSS uses logical properties, not left/right
• No fixed widths or heights on text containers (strings grow when translated)
• Edge-pinned elements account for env(safe-area-inset-*)
• Breakpoints chosen from where content breaks, not device presets
• Off-screen or collapsed content has a visible affordance
• Layout survives 200% zoom with no horizontal page scroll

UX & Accessibility

• Core user flow achievable in minimum clicks
• Native HTML elements used where appropriate (dialog, details, datalist)
• Images optimized (WebP, appropriate sizing) with explicit dimensions
• SVGs used for icons instead of raster images
• Every interactive element reachable and operable from the keyboard, with a visible focus ring that never fades in
• Icon-only buttons and every form control carry an accessible name
• Paste is never blocked; inputs carry autocomplete and the right type
• Filters, tabs, and pagination are reflected in the URL
• Dates and numbers formatted through the platform's locale APIs, never hardcoded
• Text containers handle overflow; copy tested short, long, and translated
• Custom widgets implement their role's full keyboard model; no positive tabindex
• Modals trap focus, return it to the trigger on close, and close on Escape
• Decorative overlays carry pointer-events: none so they don't swallow clicks
• Hit areas meet the 24px floor, and extended hit areas never overlap
• Submit is never disabled until valid; the first invalid field takes focus
• Alt text chosen by purpose; a missing alt is worse than an empty one
• Layout reflows at 320px equivalent with vertical scrolling alone

Copy

• Button labels start with a verb and name the outcome
• Confirmation buttons repeat the consequence, so the dialog is answerable without reading the body
• Link text makes sense out of context; no bare "Learn more" appearing twice
• One capitalization policy per element type
• Errors state the fix, sit beside the field that failed, and carry no blame
• Empty states say what goes here and offer one next action
• Placeholders are examples, never the only label
• Toggles are labeled for their on state
• No sentence assembled by concatenating fragments around a variable

Interaction States

• Empty states designed (not blank screens) with clear next-action guidance
• Loading states use skeleton screens or spinners, not blank areas
• Error states are informative and offer recovery actions
• Destructive actions have confirmation dialogs
• Post-action feedback provided (toasts, button state changes, completion indicators)
• Interaction pattern choices appropriate (popover vs modal vs new page)
• Icon library consistent (one set, with labels/tooltips for non-obvious icons)
• Action terminology consistent across all screens

Before You Finish

Score the work 1-5 on each of six axes before handing it back, judged against the bar of the surface's mode: an Operate screen scores high on Philosophy and Specificity through precise details and one signature move, not through a reinvented layout. Anything below 3 gets a revision pass — catching a weakness here is far cheaper than catching it in a full review. Two passes is normal. A third usually means the brief is underspecified, not the design.

Audit Output

An audit is not a list of ticked boxes. It ends with a verdict and an honest statement of what was not checked.

Severity. HIGH breaks an interaction, blocks content or an action at a supported viewport, or leaves a state change visible only while an animation runs. MEDIUM is a visible inconsistency in layout, surfaces, or motion, or harms hierarchy and reading order. LOW is isolated polish.

Verification. Say what you actually checked. Without a browser, that means: every state the component defines (hover, focus, active, disabled, loading, empty), plus durations, easings, and logical-property usage read from the code. With a browser: walk each state, check every supported width, 200% zoom, and the RTL mirror, and replay motion at 10% speed. Report anything you could not run as Not verified.

Format. Group findings under the principle each violates, ordered by severity, one row per root cause listing every location it appears in.

Location is path/to/file:line. Why names the principle and the user impact, not just the rule.

End with Block when any HIGH remains, Approve otherwise, leaving the rest in the table as work to do. Never approve coverage you did not inspect. With nothing to report, say so explicitly and still report what was verified.

Anti-Patterns

Scope of This Skill

This is a knowledge base about finished interfaces: what they should look like, how they should behave, and why. It is deliberately not a process.

It does not cover how to run a design project, how to produce mockups or variant pickers, how to organize component files, which framework to pick, or what to write into project documentation. For frontend code architecture — rendering strategies, state management, file organization — see the architecting-frontend skill if available.