| name | add-frontend-feature |
| description | Scaffold a frontend feature in PictoPy — Redux slice, API wrapper, hook, component, and test. Use when adding UI, a new screen, or frontend state. |
| argument-hint | ["feature-name"] |
Add a frontend feature
A feature spans state, data access, and presentation. Build it in that order — bottom up —
so each layer is testable before the next depends on it.
$1 is the feature name in camelCase (videos, faceClusters, memories).
Read agent-kit/references/frontend-feature-walkthrough.md for the video feature traced
from slice to component.
1. Types — src/types/
Define the shape the backend actually returns. Check the FastAPI response model in
backend/app/routes/<resource>.py rather than guessing — the two must agree, and the
backend is the source of truth.
2. API layer — two files, both required
src/api/apiEndpoints.ts — add a <feature>Endpoints object. Parameterised URLs are
functions that encodeURIComponent their arguments.src/api/api-functions/<feature>.ts — a typed wrapper per endpoint, using the shared
apiClient from ../axiosConfig, returning Promise<APIResponse>.
Components never call axios directly. If you find yourself importing axios into a
component, the wrapper is missing.
3. State — src/features/
Template: agent-kit/templates/slice.ts.md.
<feature>Slice.ts — Redux Toolkit createSlice.<feature>Selectors.ts — derived data lives here, not in components.<feature>Thunks.ts — only if the feature needs async orchestration beyond a hook.
Keep reducers total: validate indices and ranges inside the reducer, not at the call site.
setCurrentViewIndex in src/features/videoSlice.ts is the reference.
Register the reducer in the store (src/store/).
4. Hook — src/hooks/use<Feature>.ts
Bridges the API layer and the store, and is where components get their data. Existing hooks
use React Query alongside Redux — follow whichever the neighbouring feature uses rather
than introducing a third pattern.
5. Component — src/components/<Area>/
src/components/ui/ is generated by shadcn. Do not hand-edit it.- Tailwind v4 with
prettier-plugin-tailwindcss. Never hand-order class names.
- Import through
@/, which resolves to frontend/src.
- No
TODO or FIXME comments. ESLint treats them as errors and CI fails.
6. Tests — __tests__/ beside the code
Template: agent-kit/templates/component.test.tsx.md.
Jest + React Testing Library. Test through rendered output, not implementation details.
Cover the loading state, the populated state, and the empty state — empty states are where
this codebase has had regressions.
7. Verify
cd frontend && npm run lint:check && npm run format:check && npm test
If format:check fails, run npm run format:fix rather than editing by hand.
Checklist
