Frontend

---
name: frontend
description: Use when building React components, optimizing performance, analyzing bundle sizes, scaffolding projects, implementing accessibility, reviewing frontend code quality, performing visual overhauls, or designing UI/UX systems.
---

# Frontend Engineer

Frontend development patterns, performance optimization, accessibility, and distinctive UI design for any framework.

---

## Step 1: Detect the Stack

Before writing any code, identify the framework and tooling from project signals:

| Signal file / pattern | Stack |
|----------------------|-------|
| `next.config.*` | Next.js (React) |
| `nuxt.config.*` | Nuxt (Vue) |
| `svelte.config.*` | SvelteKit |
| `astro.config.*` | Astro |
| `remix.config.*` / `@remix-run` in package.json | Remix (React) |
| `angular.json` | Angular |
| `vite.config.*` + React | Vite + React |
| `vite.config.*` + Vue | Vite + Vue |
| `tailwind.config.*` | Tailwind CSS |
| `styled-components` / `emotion` in package.json | CSS-in-JS |

Check: `cat package.json`, `ls -la`, `cat vite.config.*` — whichever applies.

---

## Step 2: Research Current Practices

Once you know the stack, search before making framework-specific recommendations:

WebSearch: " component patterns best practices 2025"
WebSearch: " performance optimization 2025"
WebSearch: " bundle size optimization 2025"
WebSearch: " accessibility best practices 2025"
WebSearch: " best practices 2025"

---

## Step 3: Design Thinking

> **First Principles preamble**: before reaching for a library, framework, or component pattern, ask whether the choice solves *this* UI's specific constraint, or is a habit from larger apps. A landing page is not a dashboard; a settings panel is not a marketing site. Question the requirement before adopting the pattern; reject "we need X because everyone uses X" and reason from the actual user, content, and interaction model.

When building any UI — component, page, or application — commit to a bold aesthetic direction **before writing a line of code**:

- **Purpose**: What problem does this interface solve? Who uses it?
- **Tone**: Pick an extreme and own it. Brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art
deco/geometric, soft/pastel, industrial/utilitarian — commit to one direction and execute it with precision.
- **Differentiation**: What makes this unforgettable? What is the one thing someone will remember?
- **Constraints**: Framework, performance budget, accessibility requirements.

**The goal is intentionality, not intensity.** Refined minimalism and bold maximalism both work — generic middle ground does not.

### Typography

Choose fonts that are beautiful, unique, and characterful. Pair a distinctive display font with a refined body font.

- **Avoid**: Inter, Roboto, Arial, system fonts, Space Grotesk (overused)
- **Prefer**: Unexpected choices that elevate the aesthetic and feel designed for the context
- Every font decision should be documented with a reason

### Color and Theme

Commit to a cohesive aesthetic. Use CSS variables for consistency.

- Dominant colors with sharp accents outperform timid, evenly-distributed palettes
- Define tokens: primary, surface, text, error, border — never scatter raw hex values
- Vary between light and dark themes — do not default to one
- Check contrast ratios (4.5:1 for body text, 3:1 for large text)

### Motion

Use animation for effects and micro-interactions. Prioritize CSS-only for HTML; Motion library for React when available.

- One well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions
- Use scroll-triggering and hover states that surprise
- Match animation complexity to the aesthetic vision — maximalist designs need elaborate motion, refined designs need restraint

### Spatial Composition

- Unexpected layouts: asymmetry, overlap, diagonal flow, grid-breaking elements
- Generous negative space OR controlled density — not the muddled middle
- Visual hierarchy through size contrast, not just color

### Backgrounds and Visual Details

Create atmosphere and depth rather than defaulting to solid colors:

- Gradient meshes, noise textures, geometric patterns, layered transparencies
- Dramatic shadows, decorative borders, grain overlays
- Custom cursors, contextual effects that match the overall aesthetic

### Aesthetic Anti-Patterns

Never use generic AI-generated aesthetics:

- Overused fonts: Inter, Roboto, Arial, Space Grotesk, system fonts
- Purple gradients on white backgrounds
- Predictable layouts and cookie-cutter component patterns
- Design that lacks context-specific character
- Two consecutive generations that converge on the same choices

---

## Step 4: Universal Frontend Principles

These apply regardless of framework.

### Component Design

- **Single responsibility**: one component, one job — split when a component does two distinct things
- **Props as API**: treat component props like a public API — document what is required vs optional
- **Co-location**: keep styles, tests, and types next to the component they belong to
- **Composition over inheritance**: prefer passing children/slots over extending base components
- **Controlled vs uncontrolled**: be intentional — controlled for forms that need validation, uncontrolled for simple inputs

### Performance

- **Render budget**: components should render in under 16ms for 60fps; profile before optimizing
- **Lazy loading**: code-split at route boundaries; defer below-fold components
- **Image optimization**: use the framework image component or `<picture>` + `srcset`; never serve 2x the display size
- **Memoization**: only add when profiling shows a problem — premature memoization adds complexity for no gain
- **Bundle analysis**: regularly audit bundle size; flag dependencies over 50kb that can be replaced or lazy-loaded

### Accessibility (a11y)

- **Semantic HTML**: use the right element (`<button>` not `<div onClick>`, `<nav>` not `<div class="nav">`)
- **Focus management**: custom modals/drawers/dropdowns must trap focus and restore it on close
- **ARIA**: only use ARIA to extend semantics, not replace them; prefer native elements
- **Color contrast**: 4.5:1 for body text, 3:1 for large text (WCAG AA minimum)
- **Keyboard navigation**: every interactive element reachable and operable by keyboard
- **Screen reader testing**: test with NVDA+Firefox or VoiceOver+Safari before shipping

### State Management

- **Locality first**: co-locate state with the component that owns it; lift only when needed
- **Server state vs client state**: use a data-fetching library for server state (TanStack Query, SWR, Apollo) — do not store it in global store
- **Derived state**: compute from source of truth — do not sync two pieces of state
- **Global store**: only for genuinely cross-cutting state (auth user, theme, feature flags)

### Forms

- **Validation**: validate on blur for UX, on submit for correctness; show errors inline
- **Accessibility**: every input has a `<label>`; error messages referenced via `aria-describedby`
- **Loading states**: disable submit during async; show spinner or progress
- **Optimistic UI**: apply the mutation locally, rollback on error

### Security

- **XSS**: never set `innerHTML`/`dangerouslySetInnerHTML` from user input; sanitize if unavoidable
- **CSP**: Content-Security-Policy header; avoid `unsafe-inline`
- **Sensitive data**: never log tokens, passwords, or PII to the console
- **Third-party scripts**: audit before adding; every script is a supply chain risk
- **Dependency audit**: run `npm audit` regularly; keep dependencies current

---

## Review Checklist

Before any frontend PR:

- [ ] Aesthetic direction chosen and documented before any code was written
- [ ] Font choices are distinctive and context-appropriate (not Inter/Roboto/Arial/Space Grotesk)
- [ ] Color tokens defined; contrast ratios verified (WCAG AA)
- [ ] All component states handled — default, hover, focus, disabled, loading, error, empty
- [ ] Components have single, clear responsibility
- [ ] No `dangerouslySetInnerHTML` from unvalidated input
- [ ] Every interactive element is keyboard-accessible
- [ ] Every input has an associated `<label>`
- [ ] Images have meaningful `alt` text (or `alt=""` if decorative)
- [ ] Bundle impact assessed for new dependencies
- [ ] No console.log of tokens or PII
- [ ] Responsive at mobile, tablet, and desktop breakpoints