Frontend Toolkit

Build forms with correct loading, success, and error UX using Server Actions + react-hook-form + Zod. Use when adding a new form, after QA reports form bugs, when errors aren't announced or input is lost on submit, or before shipping. Not for general state-store selection (use state-management-decisions) or non-form error/empty UI states (use async-ux-states).

Apply Next.js Metadata API per route — title template, og:image, generateMetadata for dynamic pages, JSON-LD structured data, robots, sitemap, canonical, hreflang. Use when adding a new route, when search visibility drops, when rich results are needed, or before shipping. Not for choosing a route's render mode (use render-strategy-decision); align generateMetadata with that route caching choice.

OWASP Top 10 audit for frontend — XSS via dangerouslySetInnerHTML, env-var leaks, token storage, CSRF, broken access control (IDOR), open redirect, CSP, Supabase RLS, CORS, Zod env validation. Use when adding auth, after handling external input, before shipping, or quarterly. Not for the initial env-validation setup (use developer-experience) or wiring npm audit / CSP regression tests into CI (use cicd-pipeline).

Ensure every async view handles loading, error, and empty states correctly with proper Suspense boundaries and custom 404/500 pages. Use when QA reports blank screens, infinite spinners, or undefined exposure, or before shipping. Not for choosing route render strategy (use render-strategy-decision) or form-specific error handling (use form-ux).

Refactor TypeScript/React code for readability and maintainability — remove `any`, name compound conditions, apply guard clauses, extract magic literals to constants, deduplicate shared logic. Use during PR review, before a feature touches a complex area, or on a weekly cadence. Not for component-level extraction (use component-quality) or cross-file/module restructuring (use architecture-improvement).

Write RFC and ADR documents to capture technical decisions (including rejected alternatives) — Context / Options / Decision / Consequences format. Use before a hard-to-reverse architecture decision, when designing a large feature, when technical choices spark debate, or when PR reviewers request rationale. Not for evaluating a library to adopt (use new-tech-evaluation) or prioritizing debt migrations (use tech-debt-management) — this records the resulting decision.

Audit and improve animations for 60fps, prefers-reduced-motion compliance, motion-feel (duration/easing), and accessibility. Use when jank appears in scroll/interaction, INP regresses, an animation auto-plays/loops or flashes, or before shipping. Not for diagnosing broad Core Web Vitals regressions (use rendering-performance) or full WCAG conformance auditing (use accessibility-audit).

Improve React component design — split Container/Presentational, add useEffect cleanup, extract custom hooks, apply cva + cn() consistently, decide extraction with explicit criteria. Use when a pattern repeats 2+ times, a file exceeds 500 LOC, or PR review flags component complexity. Not for non-component code changes (use code-refactoring) or extraction into the shared component library (use design-system-construction).

Set up or audit internationalization — message extraction, locale routing strategy, server/client message split, ICU plurals, date/number/currency formatting, RTL, missing-key fallback, pseudo-localization testing. Use when adding a second locale, when hardcoded strings accumulate, or before going multi-region. Not for emitting hreflang/per-locale canonical tags (use seo-metadata) or deciding static vs dynamic rendering of locale routes (use render-strategy-decision).

Build mobile-first responsive layouts — breakpoint strategy, fluid type/space with clamp(), container queries, mobile viewport units (dvh) + overflow robustness, touch-target testing, responsive images. Use when adding a layout, when mobile bugs appear, or before shipping a public page. Not for codifying breakpoint/fluid scales as design tokens (use design-system-construction) or auditing touch-target size and zoom against WCAG (use accessibility-audit).

WCAG 2.2 AA audit — semantic HTML, axe-core + eslint-plugin-jsx-a11y, keyboard navigation, ARIA, color contrast, target size, focus-not-obscured, prefers-reduced-motion. Use when completing a new component, after design system changes, or before shipping. Not for form label/aria-describedby patterns (use form-ux) or baking a11y into shared components from the start (use design-system-construction).

Reduce initial JS bundle size via Bundle Analyzer, optimizePackageImports, code splitting, and unused-dep removal. Use when bundle exceeds target, after adding a large dependency, when Lighthouse Performance drops, or before shipping. Not for diagnosing runtime Core Web Vitals (use rendering-performance) or evaluating a library's size before adopting it (use new-tech-evaluation).

Evaluate a new library, framework version, or AI integration with bundle size, TypeScript support, maintenance status, security/supply-chain, and migration + exit cost. POC + benchmark before adoption. Use at quarterly tech review, when a new library could solve a pain point, on a React/Next.js major version release, or on AI API major updates. Not for recording the resulting decision (use decision-records) or shrinking an already-adopted dependency (use bundle-optimization).

Audit and optimize third-party scripts — analytics, tag managers, chat widgets, embeds — with the right loading strategy, performance budget, facades, and CSP/consent controls. Use when adding a script, when TBT/INP regress, when a GDPR/CCPA consent requirement arises, or before shipping. Not for first-party bundle size (use bundle-optimization) or broad Core Web Vitals diagnosis (use rendering-performance).

Set up DX baseline — ESLint + Prettier + husky + lint-staged + commitlint, strict TypeScript, path alias, t3-env for typed env vars, Node/package-manager pinning, .editorconfig, .vscode/extensions.json, CONTRIBUTING.md. Use at project start, during team onboarding, when ESLint warnings pile up, or local builds slow down. Coordinates with cicd-pipeline (local pre-commit gating complements CI) and security-audit (typed env validation hardens the secret-leak surface).

Inventory and prioritize technical debt — TODO/FIXME/HACK, any usage, deprecated APIs, untested logic — with impact × effort matrix. Use at quarter start, before a refactoring sprint, when a new teammate joins, or when feature velocity slows. Not for actually paying down debt (use code-refactoring) or recording a migration approach (use decision-records) — this only inventories and prioritizes.

Diagnose and fix Core Web Vitals (LCP ≤ 2.5s, INP ≤ 200ms, CLS ≤ 0.1) with measurement-first methodology. Use when Lighthouse drops, CWV field data fails, users report slowness, or before shipping. Not for when JS payload is the bottleneck (use bundle-optimization) or moving work to the server (use render-strategy-decision).

Reduce duplicate/over-fetching requests, tune cache policies by freshness, invalidate caches after mutations, and shape queries. Use when duplicate API requests appear, stale data shows after a write, TTFB exceeds 500ms, or before shipping. Not for route-level rendering strategy (use render-strategy-decision) or Core Web Vitals tuning (use rendering-performance).

Choose the right rendering strategy per Next.js route — SSG / ISR / SSR / CSR / Streaming + Suspense — driven by data shape, not by page type. Use when adding a new route, when a route unexpectedly renders dynamically, when performance issues prompt re-evaluation, or when a code review flags inconsistency. Not for diagnosing Core Web Vitals regressions (use rendering-performance) or tuning fetch/cache policies (use api-caching-optimization).

Build or audit a Tailwind + cva + shadcn/ui design system with two-tier tokens, variants, theming, and 4-state Storybook stories. Use when starting a new project, addressing UI inconsistency, onboarding a designer, adding dark mode / theming, when arbitrary values (w-[347px]) accumulate, or when component patterns repeat across 2+ places. Not for component-level extraction decisions (use component-quality) or WCAG conformance auditing (use accessibility-audit).

Decision framework for choosing the right state location — URL, server cache, local component, or shared/global store. Use when state-sync bugs appear, prop drilling gets deep (3+ levels), filters/tabs lose state on reload, or quarterly review. Not for form state specifically (use form-ux) or when the state is actually server data (use api-caching-optimization).