Frontend Design

---
name: frontend-design
description: Use when building web components, pages, or applications with distinctive, production-grade design quality — color, typography, layout, interaction states, and platform conventions. Triggers on "frontend", "UI design", "design", "组件设计", "界面设计", "前端设计", "视觉风格".
---

# Frontend Design

Build distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics.
The method: pick a bold aesthetic direction, apply a color formula, pair typography deliberately,
specify interaction states, and execute with precision. Bold maximalism and refined minimalism both
work — the key is intentionality, not intensity.

## When to use

- Building web components, pages, or applications (HTML/CSS/JS, React, Vue, Svelte, etc.)
- Choosing a design direction, color palette, or typography system for a project
- Reviewing UI for visual quality, accessibility, or interaction polish
- Implementing responsive layouts, dark mode, or platform-specific conventions (Apple HIG, Material)
- Triggers on "frontend", "UI design", "组件设计", "界面设计", "前端设计", "视觉风格"

**Not for:** pure data visualization (use dataviz); backend logic with no visual surface;
API contract design (use api-design). Visually important web work where image-first is preferred
(use `image-to-code`).

## Steps

### 1. Define the element and project context

Before coding, commit to a bold aesthetic direction. Answer:

- **Element**: What are you building? (button, card, modal, navbar, page, full app)
- **Purpose**: What problem does this interface solve? Who uses it?
- **Tone**: Pick an extreme — brutally minimal, maximalist, retro-futuristic, organic, luxury, playful, editorial, brutalist, art deco, industrial. Commit fully; never default to "safe."
- **Differentiation**: What makes this UNFORGETTABLE? The one thing someone will remember.

Match implementation complexity to the vision: maximalist designs need elaborate code; minimalist
designs need restraint and precision. NEVER use generic AI aesthetics — overused fonts (Inter,
Roboto, Arial), purple gradients on white, rounded-2xl everything, stock card grids, lorem ipsum.

- Load [references/brief-inference.md](references/brief-inference.md) for the design-read protocol (infer page kind, audience, vibe, constraints before coding) and the three dials (DESIGN_VARIANCE, MOTION_INTENSITY, VISUAL_DENSITY) that gate layout, motion, and density
- Load [references/design-foundations.md](references/design-foundations.md) §Perception & Gestalt and §Hierarchy & Layout for the visual-organization principles beneath layout — Gestalt laws, the four hierarchy techniques, F/Z reading patterns, the squint and 5-second tests, CRAP expanded
- Load [references/design-foundations.md](references/design-foundations.md) §Cognitive Laws for the psychology laws that constrain layout — Hick's, Fitts's, Miller's 7±2, Tesler, Von Restorff, cognitive load types, progressive disclosure
- Load [references/ux-research.md](references/ux-research.md) when the user or context is unknown — interviews, personas, journey maps, empathy maps, usability testing (run discovery before visual design)
- Load [references/design-foundations.md](references/design-foundations.md) §Information Architecture when organizing content — the four IA elements, tree vs network, card sorting, navigation depth, labeling systems

### 2. Pick a style

If `docs/design/references.md` exists (produced by `design-research`), load it first — ground the
style choice in what real market references actually ship, not internal catalogs alone.
Choose a concrete visual style that fits the product type and tone. Consistency across all pages is
non-negotiable — don't mix flat and skeuomorphic randomly. Use SVG icons (Lucide, Heroicons), never
emoji as structural icons. Effects (shadows, blur, radius) must align with the chosen style.

- Load [references/styles.md](references/styles.md) for the style catalog (glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, skeuomorphism, flat design, and more) with characteristics, when-to-use, and effects
- Load [references/apple-hig.md](references/apple-hig.md) when designing for Apple platforms (iOS, iPadOS, macOS, tvOS, visionOS, watchOS) — HIG specs, routing table, critical design rules
- Load [references/material-design.md](references/material-design.md) when designing for Android or Google-ecosystem products — Material 3 color/type/elevation/state-layer roles, M3 vs M2, when Material vs HIG vs custom

### 3. Apply the color formula

Use a dominant-surface-accent distribution, not timid even palettes. Define semantic tokens
(never raw hex in components), meet WCAG contrast, and design light/dark variants together.

- Load [references/palettes.md](references/palettes.md) for the 60/30/10 formula, semantic token table, contrast ratios, dark-mode rules, and palette selection by product type
- Load [references/design-foundations.md](references/design-foundations.md) §Color for the theory beneath the formula — HSB model, five color schemes, 70:25:5 proportion, color psychology, cultural variance, the gray-test

### 4. Typography pairing

Pair a distinctive display font with a refined body font. Avoid generic defaults. Vary between
generations — never converge on the same choice every time.

- Load [references/font-pairings.md](references/font-pairings.md) for the type scale, weight hierarchy, line-height/line-length targets, tabular figures, and pairing catalog by personality
- Load [references/design-foundations.md](references/design-foundations.md) §Typography for the theory — font anatomy (x-height, counters, contrast), optical sizing, vertical rhythm, modular scale ratios, rendering

### 5. Specify interaction states and mark specs

Every interactive element needs all states: default, hover, focus, pressed, disabled, loading.
Use consistent scales for spacing, radius, elevation, and icons — not arbitrary values. Every
view must also handle the four user-side states — design them explicitly, don't leave them to chance:

| State | Design job |
|---|---|
| **Loading** | Show structure (skeleton screen), not a bare spinner |
| **Error** | Explain what happened in plain language + a concrete next step |
| **Empty** | Explain why it's empty + guide the user to a first action |
| **Partial** | Make loaded parts interactive; don't block the whole view on one fetch |

Load for depth (the essentials above are enough to specify the step; load these when the corresponding concern is in play):

- [references/ux-guidelines.md](references/ux-guidelines.md) — touch-target sizes, focus rings, reduced-motion, spacing scale, pre-delivery checklist
- [references/motion-system.md](references/motion-system.md) — motion token scale (duration, easing, distance), choreography patterns (stagger, shared-element, cross-fade), scroll-animation skeletons
- [references/design-tokens.md](references/design-tokens.md) — token tiers (global → semantic → component), naming convention, scales (spacing, radius, elevation, z-index)
- [references/component-anatomy.md](references/component-anatomy.md) — part-based design (compound components, slots), variant axes mapped to tokens (load when building component systems)
- [references/design-foundations.md](references/design-foundations.md) §Usability Heuristics — Nielsen's 10, Heuristic Evaluation, Norman, Rams (load when evaluating)
- [references/state-design.md](references/state-design.md) — skeleton-screen patterns, empty-state copy, error-recovery flows beyond the table above
- [references/state-management.md](references/state-management.md) — load only when the UI has complex data-flow (client/server state, cache strategy, optimistic updates); that's an architecture concern, not a state-spec one

### 6. Implement and verify

Implement working code (HTML/CSS/JS, React, Vue, etc.) that is production-grade, functional,
visually striking, and meticulously refined.

**Output:**
- Designing UI from scratch → `docs/design/DESIGN.md` — the UIUX design report: design system, information architecture, interaction patterns, component plan.
- Auditing an existing frontend → `docs/design/frontend-audit.md` — findings and optimization suggestions for current layout/components/typography/styles.
- User research before design → `docs/research/ux-research.md` — personas, journey maps, empathy maps, usability-test findings (produced when the user/context is unknown; load references/ux-research.md).

Then run the verification below.

## Verify

- [ ] Aesthetic direction is bold and intentional — not generic AI slop (no purple-on-white, no rounded-2xl everything, no stock card grids)
- [ ] Color formula applied: dominant/surface/accent distribution, semantic tokens, 4.5:1 contrast
- [ ] Typography: distinctive display + refined body, consistent type scale, no skipped heading levels
- [ ] Interaction states: every interactive element has default/hover/focus/pressed/disabled
- [ ] Touch targets ≥44pt; spacing on 4/8dp scale; consistent radius and elevation scales
- [ ] Responsive: works at 320px, 768px, 1024px, 1440px; no horizontal scroll on mobile
- [ ] Dark mode designed alongside light mode, not bolted on
- [ ] Accessibility: keyboard navigation, ARIA labels, focus management, reduced-motion support
- [ ] No emoji as icons; SVG icons from one consistent family

**Red flags:** purple/indigo everything; excessive gradients; rounded-2xl on everything; lorem
ipsum copy; oversized uniform padding; stock card grids; shadow-heavy layering; hardcoded hex in
components; text under 12px; gray-on-gray; color as sole state indicator.

- Load [references/anti-tells.md](references/anti-tells.md) for the full forbidden-patterns list and the pre-flight check matrix — run every box before delivering

## References

- [${CLAUDE_PLUGIN_ROOT}/references/engineering-principles.md](${CLAUDE_PLUGIN_ROOT}/references/engineering-principles.md) — shared discipline (surface assumptions, push back, verify don't assume)
- [${CLAUDE_PLUGIN_ROOT}/references/design-principles.md](${CLAUDE_PLUGIN_ROOT}/references/design-principles.md) — design discipline (CRAP, hierarchy before decoration, minimize cognitive load, design every state, accessibility non-optional, consistency from systems)
- [${CLAUDE_PLUGIN_ROOT}/references/product-icon.md](${CLAUDE_PLUGIN_ROOT}/references/product-icon.md) — generating a product icon / favicon as SVG (study OSS icon systems; not simple shapes + simple colors)
- [references/styles.md](references/styles.md) — 21 UI styles with effect specs (shadows, blur, radius)
- [references/palettes.md](references/palettes.md) — 12 palette directions by product type
- [references/font-pairings.md](references/font-pairings.md) — 31 font pairings across 10 personality categories
- [references/ux-guidelines.md](references/ux-guidelines.md) — 232 UX guidelines across 10 priority categories + pre-delivery checklist
- [references/apple-hig.md](references/apple-hig.md) — Apple HIG routing table + quick-reference specs
- [references/brief-inference.md](references/brief-inference.md) — design-read protocol + 3 dials (variance, motion, density) + design-system selection map
- [references/anti-tells.md](references/anti-tells.md) — forbidden AI patterns + pre-flight check matrix
- [references/motion-system.md](references/motion-system.md) — motion token scale, easing catalog, choreography patterns, scroll-animation skeletons
- [references/design-tokens.md](references/design-tokens.md) — token tiers, naming convention, scales (spacing, radius, elevation, z-index)
- [references/component-anatomy.md](references/component-anatomy.md) — compound components, slot architecture, variant axes, composition patterns
- [references/state-management.md](references/state-management.md) — client vs server state, store/cache selection, state machines, optimistic updates, derived state, normalization
- [references/design-foundations.md](references/design-foundations.md) — design theory in one place: Perception & Gestalt, Cognitive Laws (Hick's, Fitts's, Miller, Tesler, Von Restorff), Color (HSB, schemes, 70:25:5), Typography (anatomy, rhythm, scale), Hierarchy & Layout (F/Z patterns, squint/5-second tests, CRAP), Usability Heuristics (Nielsen 10, Norman, Rams), Information Architecture (4 elements, card sorting, labeling)
- [references/state-design.md](references/state-design.md) — four states (loading/error/empty/partial), skeleton screens, empty-state design, error recovery
- [references/material-design.md](references/material-design.md) — Material 3 color/type/elevation/state-layer roles, M3 vs M2, when Material vs HIG vs custom
- [references/ux-research.md](references/ux-research.md) — user interviews, personas, journey maps, empathy maps, usability testing (5-user rule, think-aloud)
- [references/visual-direction.md](references/visual-direction.md) — shared web visual-direction engine for imagegen (web mode) and image-to-code (variation axes, hero scale, composition anchors, anti-slop)
- [references/design-system-audit.md](references/design-system-audit.md) — token coverage vs hardcoded values audit, component variant/state/a11y documentation, systematic extension patterns