sdlc-kit / rules

---
description: Frontend standards for React + TypeScript + Tailwind CSS + shadcn/ui code.
globs: frontend/**/*.ts,frontend/**/*.tsx
paths: frontend/**/*.ts,frontend/**/*.tsx
alwaysApply: false
---
# Frontend standards (React + TypeScript + Tailwind + shadcn/ui)

## Layout (follow the existing layout if it differs)
| Path                                  | Contains                                              |
|---------------------------------------|-------------------------------------------------------|
| `src/components/ui/`                  | shadcn generated. Add with `npx shadcn@latest add <name>`. Don't hand-edit. |
| `src/features/<feature>/components/`  | One component per file, `PascalCase.tsx`              |
| `src/features/<feature>/hooks/`       | `useX.ts` hooks (UI logic)                            |
| `src/features/<feature>/api/`         | fetch functions, TanStack Query hooks, `queryKeys.ts` |
| `src/features/<feature>/schemas/`     | zod schemas; types via `z.infer`                      |
| `src/pages/` or `src/routes/`         | Thin route components that compose feature parts      |
| `src/lib/`                            | api client, `cn()` and shared utils                   |

## TypeScript
- Strict mode. No `any`, no `@ts-ignore`, no non-null `!`. `as` only for narrowing, with a comment.
- API types come from the generated `src/api/schema.d.ts` when it exists; never hand-write them. Without it, they
  must match the backend response schema exactly (names, nullability): open the backend schema and compare.
- No nested ternaries (in JSX too): use early returns or a small component.

## Components
- Function components. Props type named `<Component>Props`.
- Presentational components get data via props. Data fetching lives in `api/` hooks.
- Move logic over ~15 lines out of JSX into a hook or helper.
- Lists use a stable `key` (an id, never the array index).
- Never put user data into `dangerouslySetInnerHTML`; React escapes plain text for you.
- No direct DOM changes (`document.querySelector(...)`, `classList`): use state, props or refs.
- Props passed down more than 3 levels → context, or restructure the tree.
- No `useMemo`, `useCallback` or `React.memo` without a measured need.

## Data and forms
- Server data: TanStack Query only. Never `fetch` inside `useEffect`.
- Query keys come from `queryKeys.ts`. On mutation success, invalidate the affected keys.
- Forms: `react-hook-form` + `zodResolver` + shadcn `Form` components.
  Show each field's error; show server errors (409/422) on the form; disable submit while pending.
- Every data view handles 4 states: loading (`Skeleton`), error (message + retry), empty (helpful text), success.

## Styling
- Tailwind classes only; merge with `cn()`. No inline `style`, no new CSS files. No arbitrary values
  (`w-[317px]`, `text-[#3b82f6]`): use the scale and theme tokens.
- Images get `width` and `height`, so the layout doesn't jump.
- Use theme tokens (`bg-background`, `text-muted-foreground`, `border-input`), not raw colors like `bg-gray-500`.
- Mobile first: base classes for small screens, then `sm:`, `md:`, `lg:`.
- Use an existing shadcn component before writing a custom one. Check `src/components/ui/` first.

## Accessibility
- Semantic elements (`button`, `nav`, `main`, `table`). No clickable `div`.
- Every input has a label. Icon-only buttons have `aria-label`. Everything works with the keyboard.
- Never show state by colour alone: add text or an icon. Headings go in order, with no skipped level.

## Misc
- API base URL from `import.meta.env.VITE_*`. Never hardcode URLs.
- User-facing errors via toast or inline message. No `console.log`.