| name | frontend-design |
| description | Create distinctive, production-grade frontend UI with a bold, intentional aesthetic direction, purposeful layouts, meaningful motion, and strong accessibility. Prefer React + Next.js (TypeScript), but support vanilla HTML/CSS/JS when appropriate. |
Frontend Design
Build memorable, functional interfaces with a clear point-of-view (no generic templates). Commit to one aesthetic direction, define tokens, ship accessible + responsive UI, and keep changes scoped.
Preferred Targets (choose the best fit)
- Next.js (TypeScript): preferred for production app/marketing routes and design system work.
- React (TypeScript): preferred for SPA/component libraries outside Next.js.
- Vanilla HTML/CSS/JS: great for static demos, prototypes, and standalone embeds.
Quick Start (do this first)
- Ask up to 4 questions:
- What user and job-to-be-done (what should feel “easy” after the change)?
- Where does it live (component/route) and what stack? Prefer Next.js/React; vanilla is fine for standalone pages or prototypes.
- In Next.js: assume App Router (
app/). Any server/client constraints?
- Any hard constraints (brand tokens, light/dark, motion limits, must-keep UI parts, perf budgets)?
- Pick an aesthetic direction + one signature move. If vague, propose 2–3 options from
references/aesthetic-playbook.md.
- Define tokens (type, palette, spacing, radius, shadows, motion). Keep accents to 1–2.
- Build structure first (semantic markup + layout), then motion, then polish + QA.
Guardrails (avoid footguns)
- Keep scope tight: redesign only what the user asked for.
- Reuse existing tokens/components if working in an existing repo; do not introduce a new global styling system unless requested.
- Match complexity to the vision: refined minimalism needs restraint; maximalism needs deliberate structure (not random decoration).
- Respect
prefers-reduced-motion for all animations.
- Avoid “AI slop” defaults. If the repo already uses a generic font, keep it unless the user explicitly wants new typography.
- Enforce token semantics: error/success/warning colors are for meaning, not decoration; keep contrast accessible in light/dark.
- Default to shipping code that is easy to maintain: small components, clear hierarchy, minimal dependencies.
- Don’t add new packages (animation libs, UI kits, icon sets) unless the user explicitly asks or the repo already uses them.
- Default to one primary CTA per view; demote the rest (secondary/tertiary) to avoid competing actions.
Workflow
1) Commit to a direction
- Declare: aesthetic direction, palette mood, type pairing, and the signature move.
- Write a 1–2 sentence design thesis that explains the hierarchy and vibe.
- Use
references/anti-patterns.md to avoid predictable layouts and cliched palettes.
1b) Design system rules (strict vs flexible)
- Strict: semantic color meaning, readable type ramp, reduced motion, visible focus, and “human-in-control” for AI actions (undo/apply/confirm).
- Flexible: brand accent hue, surface “temperature” in dark mode, and density preset (compact vs comfy).
- When to read more: load
references/tokens-and-semantics.md when defining tokens and references/ai-native-ui-patterns.md when adding AI surfaces.
1a) React/Next.js coding guidance (read when implementing)
- React fundamentals: keep components pure; prefer event handlers over Effects for user-driven work; follow the Rules of Hooks.
- Next.js App Router: keep Client Components small; use Server Components by default; mark
"use client" only where you need state, effects, or browser APIs.
- Data fetching: prefer server-side
fetch and explicit cache/revalidate controls; avoid unnecessary client-side effects for data.
- When to read more: load
references/react-next-best-practices.md before writing complex React logic or introducing new data fetching patterns.
2) Plan tokens and layout (before details)
- Define CSS variables (or a theme object) for:
- Color: background/surface/ink/muted/accent(+optional accent2)
- Type: display/body/mono, size scale, line-height
- Shape: radius scale and border rules
- Depth: shadow and outline rules
- Motion: durations + easing + reveal stagger step
- Lay out the page/component skeleton and content hierarchy.
- Reference
references/implementation-patterns.md for patterns and QA.
3) Implement (ship code, not moodboards)
- Start with semantic structure and accessible interactions (keyboard + focus states).
- Build macro layout with Grid; micro layout with Flexbox.
- For Next.js/React, keep components small and composable; prefer CSS Modules or the repo’s existing styling approach.
- Use “link for navigation, button for actions” to keep semantics and keyboard behavior correct.
- Apply the signature move sparingly but decisively (one memorable thing, not ten).
- Add motion as orchestration (one strong page-load + a few micro-interactions), not random flourishes.
3a) Next.js implementation notes (when applicable)
- App Router only: assume
app/ routing (not pages/).
- Server vs Client: default to Server Components; add
"use client" only for interactive islands.
- Data + state: keep data fetching on the server when possible; keep client state local and purposeful.
- Performance: avoid layout shift (stable heights, predictable grids); keep blur/shadows paint-friendly on mobile.
- Platform primitives: prefer
next/link for navigation and next/image for real images when available.
- Fonts: if changing typography in Next.js, prefer
next/font to avoid FOIT/FOUT surprises.
- Styling: keep it consistent—CSS Modules, Tailwind, or the existing system; don’t introduce a new one without asking.
3b) Content + states (don’t ship empty shells)
- Define loading, empty, and error states for any data-driven UI.
- Keep copy tight and purposeful; avoid placeholder lorem unless asked.
- Preserve existing product terminology unless the user requests copy changes.
4) Polish and QA
- Responsive pass: collapse grids, maintain padding, preserve CTA prominence on mobile.
- Accessibility pass: landmarks, one
h1, labels, contrast, focus order, skip link when relevant.
- Performance pass: avoid expensive shadows on mobile, keep animation paint-friendly, avoid large images.
Definition of Done
- Layout looks intentional at mobile + desktop breakpoints (no cramped type, no orphan CTAs).
- Focus states are visible, tab order is logical, and motion respects
prefers-reduced-motion.
- Tokens are centralized (CSS variables/theme), and the signature move is present but not overused.
Deliverables (how to present results)
- List files changed and what they do.
- Explain the aesthetic direction + signature move (1–2 sentences).
- Provide commands to validate (use the repo’s conventions; common ones include
npm run dev, npm run lint, npm test).
Bundled Resources
references/aesthetic-playbook.md: strong directions, type+color cues, signature moves.references/implementation-patterns.md: layout/motion/a11y patterns for vanilla + React.references/anti-patterns.md: quick “don’t do this” checklist to avoid generic output.references/react-next-best-practices.md: React + Next.js coding guidelines (hooks, effects, server/client, data fetching).references/tokens-and-semantics.md: token semantics, type ramp, dark mode, and density rules (strict vs flexible).references/ai-native-ui-patterns.md: copilot panels, citations, disclosures, and human-in-the-loop UI patterns.assets/vanilla-starter/: runnable vanilla starter you can copy + retheme via CSS variables.assets/react-component-starter/: small React component + CSS module skeleton to retheme.assets/nextjs-app-router-starter/: minimal Next.js App Router page + tokens you can copy and retheme.
