frontend-dev

# Frontend Development Reference for the conventions a frontend change must follow. This is a reference skill, not a step sequence — read the relevant section before writing code, then verify against the checklist at the end. The frontend uses ra-core (react-admin headless) for data fetching, routing, and CRUD logic, with shadcn-admin-kit and shadcn/ui for the UI layer. ## When to Use - Creating or modifying React components, forms, list pages, or detail views. - Adding or changing filters, data fetching, or responsive (mobile/desktop) layouts. - Registering a new resource or reorganizing an existing resource folder. Not for backend/schema work — see `Skill({skill: "backend-dev"})`. Not for theming/colors — see `Skill({skill: "shadcn-customization"})`. ## Component architecture - Import form inputs (`TextInput`, `SelectInput`, `ReferenceInput`, etc.) from `@/components/admin/`, not from shadcn/ui directly. The admin layer wraps shadcn with ra-core integration (labels, validation, data binding). - Import pure UI components (`Card`, `Button`, `Badge`, `Sheet`, etc.) from `@/components/ui/`. - Domain configuration (deal stages, note statuses, task types, company sectors) comes from `useConfigurationContext()`, never hardcoded. ## Resource (CRUD) conventions Each resource follows this file structure (e.g. `contacts/`): - `ContactList.tsx` — list page (desktop + mobile variants) - `ContactShow.tsx` — detail view - `ContactEdit.tsx` / `ContactCreate.tsx` — form pages - `ContactInputs.tsx` — shared form fields reused between create and edit - `index.tsx` — exports `{ list, show, edit, create, recordRepresentation }` Resources are registered in `root/CRM.tsx` via `<Resource name="contacts" {...contacts} />`. ## Data fetching - For standard CRUD, use ra-core hooks: `useListContext()`, `useShowContext()`, `useGetList()`, `useGetOne()`, `useGetIdentity()`. - When a query or mutation isn't covered by ra-core hooks, add a custom dataProvider method and call it via `useQuery`/`useMutation` with `useDataProvider<CrmDataProvider>()` (e.g. `dataProvider.getActivityLog()` in `ActivityLog.tsx`, `dataProvider.salesCreate()` in `SalesCreate.tsx`). ## Forms - Forms use `Form` from ra-core + `FormToolbar` for submit/cancel actions. - Ra-core's `Form` uses React Hook Form under the hood. Use `useFormContext()` for imperative operations (`setValue`, `reset`, `getValues`). - Top-level resource forms use full-page `CreateBase`/`EditBase` with `Card` (e.g. contacts), or `Dialog` (e.g. deals). - On mobile, inline/sub-resource forms use `CreateSheet`/`EditSheet` from `misc/` (e.g. notes, tasks). - Split form fields into semantic sub-components (e.g. `ContactIdentityInputs`, `ContactPositionInputs`). ## Filters - Use `ToggleFilterButton` / `ActiveFilterButton` components for filter UI. - Filters apply immediately, no "apply" button. ## Responsive design - Major pages have desktop and mobile variants. Use `useIsMobile()` to branch. - Desktop: 2-column grid layouts. Mobile: single column with `MobileHeader`/`MobileContent`. - Mobile lists use `InfiniteListBase` for scroll pagination. ## Red Flags - Importing `TextInput`/`SelectInput`/etc. directly from `@/components/ui/` instead of `@/components/admin/`. - Hardcoding deal stages, note statuses, task types, or sectors instead of reading `useConfigurationContext()`. - A new resource folder missing one of the standard files, or not registered in `root/CRM.tsx`. - A bespoke fetch/axios call where a ra-core hook or a dataProvider method belongs. - A new top-level page with only a desktop layout and no `useIsMobile()` branch. - A form field component growing past the typical size instead of being split into semantic sub-components. ## Verification - [ ] Inputs imported from `@/components/admin/`, pure UI from `@/components/ui/`. - [ ] Domain options come from `useConfigurationContext()` — nothing hardcoded. - [ ] New resources follow the file structure and are registered in `root/CRM.tsx`. - [ ] Data access uses ra-core hooks, or a dataProvider method via react-query. - [ ] Pages touching major UI have both desktop and mobile variants. - [ ] If the change touches UI/forms/filters/interactions, an e2e test exists (see `Skill({skill: "e2e-conventions"})`).