rcr-frontend

# RCR Frontend

Supplements global `react-guidelines` and `frontend-html-css-guidelines` skills.

## Component Organization

- Reusable components: `src/app/components/` with kebab-case naming (includes all Shadcn-derived primitives)
- No separate `ui/` directory — everything lives directly under `src/app/components/`
- Page-specific components: `-components/` directory or `-component.tsx` suffix

## Styling

- **Tailwind CSS v4** with `c-*` design tokens from `src/app/styles/theme.css`
- Semantic color pattern: `c-main` / `c-main-contrast`, `c-destructive` / `c-destructive-contrast`. Never invent token names — check `src/app/styles/app.css` for the full list
- **Never** use legacy Shadcn theme variables (`bg-background`, `text-foreground`, etc.)
- **Detecting invalid classes**: Oxfmt sorts unknown classes to the front. If classes appear out of order after `bun check`, they're misspelled or missing from the theme

## Radix & Shadcn

- Always import Radix from the `radix-ui` package (`import { HoverCard as HoverCardPrimitive } from 'radix-ui'`), not from subpackages like `@radix-ui/react-hover-card`
- Use `asChild` to compose styling (e.g., dropdown trigger styled as Button) rather than duplicating inline styles
- Mark key DOM nodes with `data-slot` attributes for styling hooks

## Component Primitives

### Buttons

The `Button` component handles sizing, text, and icon dimensions internally. Never override these with utility classes.

- **Dimensions**: use the `size` prop (`default` | `sm` | `icon`), never manual `h-x w-x p-0`. For icon-only buttons, `size="icon"` gives `size-9`.
- **Text size**: baked into the base (`text-sm`). Never add `text-xs`, `text-sm`, etc. via `className`.
- **Icon size**: the base rule `[&_svg:not([class*='size-'])]:size-4` auto-sizes child SVGs. Never add `h-x w-x` or `size-x` to icons inside buttons — omit sizing entirely and let the button handle it.
- **Content over positioning**: put content (counts, badges) as regular children in flow — never absolutely-positioned overlays.

### Icons

- Lucide icons with `Icon` suffix: `HomeIcon`, not `Home`
- Icons inherit size from surrounding text automatically. `size-[1em]` is redundant — omit it.
- Only add explicit `size-*` when overriding the contextual size (e.g., a larger icon in small text).
- Use `<Spinner />` from `@/components/spinner` for loading states

## Tailwind Shorthand

- When width and height are equal, use `size-x` instead of `w-x h-x`
- No custom/arbitrary text sizes (`text-[10px]`, `text-[13px]`, etc.) — use design system tokens (`text-xs`, `text-sm`, etc.) unless there's a specific constraint preventing it

## Event Handlers

- No inline arrow functions in JSX `onClick`/`onChange` props — extract to a named handler or a component with its own handler

## Forms

- TanStack Forms + Zod schemas for form management and validation