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

File	Read When
`references/color-and-theming.md`	Choosing colors, building palettes, implementing dark/light mode
`references/typography-and-spacing.md`	Setting type scales, font choices, spacing systems
`references/layout-and-responsiveness.md`	Building layouts with flexbox/grid, making designs responsive
`references/depth-and-visual-hierarchy.md`	Adding shadows, depth, borders, establishing visual hierarchy
`references/animation-and-motion.md`	Adding transitions, animations, scroll effects, SVG animation
`references/ux-and-components.md`	Designing user flows, building dashboards, planning interaction states (empty/loading/error), building reusable components, onboarding patterns, choosing native HTML elements

Task Sizing

Before starting, classify the task to avoid over-engineering:

Patch (single element change, bug fix, style tweak): Apply only the directly relevant principle. Skip phases, skip audit. Don't load reference files.
Component (new button, card, form, modal): Phases 1-5 only. Load 1-2 reference files max.
Page/Feature (new page, multi-component feature, dashboard): Full workflow. Load references as needed per phase.
Audit (reviewing existing code): Use the audit checklist. Load references for failing items only.

Always match the scope of your design work to the scope of the user's request. A request to modify one component does not warrant project-wide changes to color systems, spacing tokens, or theme infrastructure. If the project has an existing design system, follow it. These guidelines apply when building from scratch or when the project has no established patterns.

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. Design Before Code

Always sketch or plan the UI before coding, even if rough. Gather inspiration from real sites, Figma Community, Dribbble, or Mobbin. Identify the repeated patterns — most sites use only 2-3 core component types with variations.

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?

Generic AI-generated frontends have tells: perfectly centered layouts, blue-to-purple gradients, identical card grids, rounded-everything, stock illustrations, polished but soulless. The antidote is intentional character — expressed through color boldness, type choices, copy tone, spacing rhythm, and interaction style.

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.

Build Workflow

When creating new frontend interfaces, follow this sequence. Load relevant reference files based on which phases apply to your task.

Phase 0: User Flows    → Map core journeys, identify edge cases, document in project
Phase 1: Structure     → Identify components, sketch layout hierarchy
Phase 2: Layout        → Build with flexbox/grid, plan responsive behavior
Phase 3: Typography    → Set type scale, font family, line heights
Phase 4: Color         → Apply palette, ensure contrast, handle dark/light mode
Phase 5: Spacing       → Apply consistent spacing system (multiples of 4)
Phase 6: Depth         → Add shadows, borders, elevation where needed
Phase 7: Hierarchy     → Verify visual hierarchy — zoom out, check scanning
Phase 8: Animation     → Add transitions and motion where they aid UX
Phase 9: Polish        → Responsive testing, native HTML elements, image optimization

Not every task requires all phases. A small component may only need phases 1-5. A full page build benefits from the complete sequence.

Phase 0: User Flows

Before building any UI, map the user's journey through the feature or page.

Create or update docs/user-flows.md documenting each core user flow as a numbered step sequence (entry point → intermediate steps → goal achieved)
For each step, note: what the user sees, what actions are available, what data is needed, what happens next
Identify edge cases at every step: empty states, error states, loading states, unauthorized states
Present flows to the user for review before coding
After building, verify the implemented UI matches the documented flows
Update the doc whenever flows change

Load references/ux-and-components.md for detailed user flow guidance.

Skip Phase 0 for isolated component changes, targeted fixes, or tasks where the user flow is self-evident. Only create docs/user-flows.md when building a new feature with multiple screens or a multi-step interaction. For smaller tasks, describe flows in your response rather than creating files.

Phase 1: Structure

Before writing HTML, create a mental model of the component tree. Every element is a box — responsive design is dynamically moving boxes into rows and columns. Identify repeated patterns and build them as reusable components. Most well-designed sites use surprisingly few unique component types — often just 2-3 core patterns with different props.

Phase 2-9: Reference Files

Load only the reference files relevant to your current phase:

Phase	Reference File
2. Layout	`references/layout-and-responsiveness.md`
3. Typography	`references/typography-and-spacing.md`
4. Color	`references/color-and-theming.md`
5. Spacing	`references/typography-and-spacing.md`
6. Depth	`references/depth-and-visual-hierarchy.md`
7. Hierarchy	`references/depth-and-visual-hierarchy.md`
8. Animation	`references/animation-and-motion.md`
9. Polish	`references/layout-and-responsiveness.md` + `references/ux-and-components.md`

Audit Checklist

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

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 ratios meet WCAG AA: 4.5:1 for normal text, 3:1 for large text (18px+ bold or 24px+)
Dark mode support (if applicable) uses proper shade inversion

Typography & Spacing

Consistent type scale (not arbitrary font sizes)
Single font family (or deliberate pairing with clear roles)
Line height inversely proportional to font size
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

Transitions use appropriate timing functions (not all linear)
Animations serve UX purpose (feedback, orientation, delight) not just decoration
Motion respects prefers-reduced-motion media query
Hover animations wrapped in @media (hover: hover)

UX & Accessibility

Core user flow achievable in minimum clicks
Native HTML elements used where appropriate (dialog, details, datalist)
Images optimized (WebP, appropriate sizing)
SVGs used for icons instead of raster images

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

Anti-Patterns

Avoid	Do Instead
Hardcoded hex colors scattered throughout	Define color tokens as CSS variables
Random spacing values (13px, 17px, 22px)	Use multiples of 4: 12px, 16px, 24px
Multiple font families without clear purpose	One family, vary weight and size
Pure white (#fff) text on dark backgrounds	Slightly off-white (95-97% lightness)
Center-aligned body text	Left-align paragraphs, center only short headings
`position: absolute` for layout	Flexbox or Grid for layout, absolute only for overlays
Uniform shadows on every element	3 shadow levels (sm, md, lg) applied by context
Animations on everything	Animate only what aids comprehension or feedback
Custom JS for modals, accordions, tooltips	Native `<dialog>`, `<details>`, `<datalist>` first
Serving full-size images to mobile	`<picture>` + `<source>` with media queries
Ignoring touch devices	`@media (hover: hover)` for hover-dependent interactions
Over-designing	The simplest solution that works is the best solution
Designing only the happy path	Map user flows first; design for empty, error, loading, and unauthorized states
Inconsistent terminology ("Delete" vs "Remove")	Standardize action labels and button names project-wide
Mixing icon styles (fill + outline + varying weights)	Use one icon library consistently (Lucide, Phosphor, etc.)
Stacking multiple effects (gradient + shadow + glow)	Pick one subtle effect or none; less is almost always better
No feedback after user actions	Gray out buttons on click, show loading indicators, use toasts for confirmation
Over-designed charts (rounded bars, missing axes)	Simple charts with clear axes, labels, and hover states showing values
No empty state design	Design intentional empty states with guidance on what to do next
Using Lorem Ipsum in prototypes	Use real or realistic content to catch layout and flow issues early

Related Skills

For frontend code architecture decisions (rendering strategies, state management, component file organization, MVC/MVVM patterns), see the architecting-frontend skill (if available). This skill focuses on visual design and UX — how the interface looks, feels, and behaves.

designing-frontend