git:20260404.656d1be to git:20260408.c85708c
1 added, 93 removed. Audit A to B.
- # CLAUDE.md - Frontend
-
- This file provides guidance to Claude Code when working with the frontend.
-
- ## Essential Commands
-
- ```bash
- # Install dependencies
- pnpm i
-
- # Generate API client from OpenAPI spec
- pnpm generate:api
-
- # Start development server
- pnpm dev
-
- # Run E2E tests
- pnpm test
-
- # Run Storybook for component development
- pnpm storybook
-
- # Build production
- pnpm build
-
- # Format and lint
- pnpm format
-
- # Type checking
- pnpm types
- ```
-
- ### Pre-completion Checks (MANDATORY)
-
- After making **any** code changes in the frontend, you MUST run the following commands **in order** before reporting work as done, creating commits, or opening PRs:
-
- 1. `pnpm format` — auto-fix formatting issues
- 2. `pnpm lint` — check for lint errors; fix any that appear
- 3. `pnpm types` — check for type errors; fix any that appear
-
- Do NOT skip these steps. If any command reports errors, fix them and re-run until clean. Only then may you consider the task complete. If typing keeps failing, stop and ask the user.
-
- ### Code Style
-
- - Fully capitalize acronyms in symbols, e.g. `graphID`, `useBackendAPI`
- - Use function declarations (not arrow functions) for components/handlers
- - No `dark:` Tailwind classes — the design system handles dark mode
- - Use Next.js `<Link>` for internal navigation — never raw `<a>` tags
- - No `any` types unless the value genuinely can be anything
- - No linter suppressors (`// @ts-ignore`, `// eslint-disable`) — fix the actual issue
- - **File length** — keep files under ~200 lines; extract sub-components or hooks into their own files when a file grows beyond this
- - **Function/component length** — keep render functions and hooks under ~50 lines; extract named helpers or sub-components when they grow longer
-
- ## Architecture
-
- - **Framework**: Next.js 15 App Router (client-first approach)
- - **Data Fetching**: Type-safe generated API hooks via Orval + React Query
- - **State Management**: React Query for server state, co-located UI state in components/hooks
- - **Component Structure**: Separate render logic (`.tsx`) from business logic (`use*.ts` hooks)
- - **Workflow Builder**: Visual graph editor using @xyflow/react
- - **UI Components**: shadcn/ui (Radix UI primitives) with Tailwind CSS styling
- - **Icons**: Phosphor Icons only
- - **Feature Flags**: LaunchDarkly integration
- - **Error Handling**: ErrorCard for render errors, toast for mutations, Sentry for exceptions
- - **Testing**: Playwright for E2E, Storybook for component development
-
- ## Environment Configuration
-
- `.env.default` (defaults) → `.env` (user overrides)
-
- ## Feature Development
-
- See @CONTRIBUTING.md for complete patterns. Quick reference:
-
- 1. **Pages**: Create in `src/app/(platform)/feature-name/page.tsx`
- - Extract component logic into custom hooks grouped by concern, not by component. Each hook should represent a cohesive domain of functionality (e.g., useSearch, useFilters, usePagination) rather than bundling all state into one useComponentState hook.
- - Put each hook in its own `.ts` file
- - Put sub-components in local `components/` folder
- - Component props should be `type Props = { ... }` (not exported) unless it needs to be used outside the component
- 2. **Components**: Structure as `ComponentName/ComponentName.tsx` + `useComponentName.ts` + `helpers.ts`
- - Use design system components from `src/components/` (atoms, molecules, organisms)
- - Never use `src/components/__legacy__/*`
- 3. **Data fetching**: Use generated API hooks from `@/app/api/__generated__/endpoints/`
- - Regenerate with `pnpm generate:api`
- - Pattern: `use{Method}{Version}{OperationName}`
- 4. **Styling**: Tailwind CSS only, use design tokens, Phosphor Icons only
- 5. **Testing**: Add Storybook stories for new components, Playwright for E2E. When fixing a bug, write a failing Playwright test first (use `.fixme` annotation), implement the fix, then remove the annotation.
- 6. **Code conventions**:
- - Use function declarations (not arrow functions) for components/handlers
- - Do not use `useCallback` or `useMemo` unless asked to optimise a given function
- - Do not type hook returns, let Typescript infer as much as possible
- - Never type with `any` unless a variable/attribute can ACTUALLY be of any type
- - avoid index and barrel files
+ @AGENTS.md