name: implement-frontend
description: Implementation standards for React/TypeScript/Next.js. Use when writing or reviewing frontend code, especially forms, state, hooks/components, and type safety.

Implement Frontend

Use this as the baseline for all frontend code. Fix violations.

Core rules

• Keep a single source of truth for any data or state.
• Enforce type safety: no any, no as casting, no ts-ignore.
• Use React Hook Form for every form. No manual form state.
• Use proto types as the contract; do not duplicate API types.
• Components render; hooks own data fetching and business logic.

Code quality (baseline)

• Use active verb names; use one word per concept.
• Keep functions small, do one thing, and stay at one abstraction level.
• Minimize arguments; avoid boolean flags; avoid negative conditionals.
• Use else-if for multi-way decisions.
• Replace magic numbers with named constants.
• Comment intent, warnings, examples, or TODOs; never contradict code.
• Remove commented-out or unused code.
• Guard against hidden side effects.

Critical anti-patterns

• Duplicate state or syncing state via useEffect.
• API calls or business logic inside components.
• zodResolver(schema as any) or other type escapes.
• Form object in dependency arrays (use only formState fields).

References

• See typescript-patterns.md for TypeScript and proto guidance.
• See react-patterns.md for forms, hooks, and state.

Quick checks

• Remove console.*, debugger, commented code, unused imports.
• Use useId for IDs; avoid hardcoded IDs.
• Zod v4 + createZodResolver.
• React Query/Connect Query owns server state; RHF owns form state; useState only for UI.

Reliability & data fetching (required)

• Optimistic updates must snapshot previous cache state and rollback on error.
• Only optimistic-update for operations with a safe rollback; avoid for destructive actions unless server supports undo.
• Retries are only for idempotent requests. Use exponential backoff with full jitter and cap attempts/time.
• Always use AbortController for in-flight requests to prevent race conditions on unmount or rapid input.

Cache & invalidation (required)

• React Query/Connect Query is the source of truth for server state; never copy server data into useState.
• Mutations must invalidate or update only the affected queries; do not refetch everything.
• setQueryData is allowed only for optimistic updates or small, scoped edits.

Performance & UX (required)

• Follow audit-ui for accessibility and UX checklist items; use ui-animation for motion.
• Lazy-load heavy UI (charts, editors, modals) with dynamic import and suspense fallback.
• Reserve image sizes to avoid layout shift; use next/image when applicable.
• Enforce bundle budgets in CI (document the budgets in the repo).

Observability (required)

• Add error boundaries at route/layout level; report exceptions to Sentry (or project standard).
• Tag client errors with userId/orgId and release (commit/semantic version), scrub PII.

Required structure (per feature)

components/<feature>/
  *.tsx
  hooks/                 # feature hooks only
  types/                 # schemas + UI types
  utils/
    proto-mappers.ts     # proto -> UI transforms
  constants.ts

Naming

• Files: kebab-case. Components: PascalCase. Functions: camelCase. Constants: UPPER_SNAKE_CASE.

Every file should be ready to ship.