implement-frontend

• 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.

• 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.

• 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).

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

• 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.

• 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.

• 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.

• 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).

• 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.

```

components//

*.tsx

hooks/ # feature hooks only

types/ # schemas + UI types

utils/

proto-mappers.ts # proto -> UI transforms

constants.ts

```

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

Every file should be ready to ship.