frontend

Files (1)

• SKILL.md

SKILL.md (first lines)

# Frontend Skill — Next.js 15, shadcn/ui & Tailwind CSS

> **Read `skills/design/SKILL.md` first.** That file decides what the UI should
> look like — screen structure, colour, type, icons, and the states every screen
> owes the user. This file covers the plumbing underneath it. Wiring a screen up
> correctly and still shipping a gradient hero with three emoji is a failure.

## 1. When to Use
Use this skill when building or editing Next.js UI pages, React client/server components, shadcn/ui styled primitives, Tailwind styling, TanStack Query hooks, or AuthContext integrations.

## 2. Route Groups & Layout Ownership

`apps/web/src/app/` is split into three groups. Route groups are parentheses —
they set layout, not URL, so `(app)/dashboard/page.tsx` still serves
`/dashboard`.

| Group | Layout owns | Put a screen here when |
|---|---|---|
| `(marketing)` | Public header, footer | It is public and sells the product |
| `(app)` | Sidebar, topbar, auth guard, page width | It requires a signed-in user |
| `(auth)` | Bare centred frame | It is credential entry |

**The `(app)` layout already guarantees a signed-in user.** A screen inside it
starts with `if (!user) return null;` and renders content — no `isLoading`
branch, no signed-out fallback, no `max-w-*`, no navigation. Those exist once,
in the layout. Duplicating them is how the four screens drifted apart before.

The root `app/layout.tsx` holds `<html>`, fonts, and `<Providers>` only. It
renders no chrome, because chrome differs per group.

## 3. Shell Components

In `components/app-shell/`:

- **`PageHeader`** — title, one-sentence description, up to two actions. Every
  `(app)` screen opens with exactly one.
- **`EmptyState`** — what a list renders when it has nothing. Reach for it before
  rendering records whose every field is blank.
- **`StatCard`** — label, one live number, caption, optional icon badge. Never
  a static string styled as a metric.
- **`StatusBadge`** — maps a status string (`ACTIVE`, `PENDING`, …) to the badge
  hue that means it everywhere. Add new states to its map; never colour a badge
  at the call site.
- **`Breadcrumbs`** — derived from the URL, mounted once in the `(app)` layout.
  Add a label to its `LABELS` map when you add a route.
- **`BulkActionBar`** / **`ViewToggle`** — selection toolbar and list/grid
  switcher for list screens.
- **`Shell`** — the signed-in frame (sidebar, topbar, breadcrumbs, content column, sign-in and permission gates). `(app)/layout.tsx` and `iam/(console)/layout.tsx` both render inside it and supply only brand, navigation and gate. Do not build a second frame.
- **`Sidebar`** / **`Topbar`** — primary nav and account menu. Adding a
  destination means adding it to `Sidebar`'s `sections`, not to a page.

In `components/auth/`: `AuthShell` (the split-screen credential frame) and `SignInForm` (shared by `/login` and `/iam/login`).

In `components/iam/`: `IamNav` and `InviteUserDialog`.

In `components/marketing/`: `SiteHeader` — public nav only.

### The `/iam` area
Access control is its own area at `/iam` (`app/iam/(console)/` behind a gate, `app/iam/login/` outside it). It was `/admin` inside the product; `next.config.mjs` redirects the old URLs. It admits the workspace ROOT and holders of `admin:access`. It is scoped to the signed-in user's workspace by the API, and `useAuth().tenant` names it on screen.

### Passwords and links
`lib/password.ts` mirrors the server rule and is tested against the real schema. `/reset-password` serves both reset and invitation links (`?invite=1` only changes wording).

## 4. Theming

`globals.css` and the font block in `app/layout.tsx` are **generated** from the
selected theme (`src/themes.ts` in the CLI). Each theme sets its own palette,
type pairing, and corner radius.

- Colour comes from CSS-variable tokens wired into `tailwind.config.ts`. Add a
  token before reaching for a literal Tailwind colour.
- The font block in `layout.tsx` sits between `FONTS:START` / `FONTS:END`
  markers. Edit freely — but keep the markers, or regenerating the theme stops
  working.
- Dark/light switching is `next-themes`. Everything must be legible in both.

## 5. Data Fetching & Session State
- **Client Components**: Declare `'use client'` at the very top of interactive components.
- **Data Fetching**: Use `@/lib/api-client` backed by TanStack Query hooks in `hooks/` with staleTime and refetch controls.
- **Session State**: Managed via `useAuth()` (`contexts/auth-context.tsx`) leveraging server-side HTTP-only session cookies (`credentials: 'include'`).
- **API base URL**: import `API_BASE_URL` from `@/lib/api-client`. Never hardcode `http://localhost:3001` — it ships to production and points at the developer's laptop.

## 6. shadcn/ui Component Suite & Radix Primitives
`apps/web/src/components/ui/` contains standard, composable, unstyled-primitive-backed UI components:
- **Button**: Powered by Radix `Slot` (`asChild`), `class-variance-authority` (`cva`), and responsive variants (`default`, `destructive`, `outline`, `secondary`, `ghost`, `link`).
- **Dialog / Modal**: Radix Dialog with backdrop overlay, animated transition, header, description, content, and close triggers.
- **DropdownMenu**: Radix DropdownMenu with trigger, submenus, radio groups, checkboxes, and keyboard shortcuts.
- **Form Controls**: Styled `Input`, `SearchInput` (leading icon), `PasswordInput` (show/hide), Radix `Label`, Radix `Select`, Radix `Switch`, `Checkbox`, `RequiredMark`, and `FieldHint` (the "?" tooltip — use it only on fields whose purpose is not obvious from the label). `useFormValidation` tracks values, touched fields, and errors so a message only appears after a field is blurred or submit is attempted.
- **Button `loading`**: `<Button loading={mutation.isPending}>` shows a spinner and disables the button — use it instead of swapping the label text and adding `disabled` by hand.
- **Feedback & State**: `Toaster` (`sonner`), `Badge` (`cva`, soft-tint variants: a wash of the hue plus a matching border, never a solid fill — `success` / `warning` / `error` for status), `Skeleton`, `Alert`, and `Tooltip`.

Status variants on `Badge` and `Alert` use the `success` / `warning` /
`destructive` tokens. They are for system state, not decoration.

## 7. Dynamic Permission-Aware UI
- Use `hasPermission(action)` from `useAuth()` to conditionally display admin navigation and action buttons.
- **Zero-Trust Invariant**: UI element hiding is an aesthetic convenience. All privileged backend API routes must strictly enforce server-side `requirePermission(...)`.
- `api-client.ts` uses `credentials: 'include'` on all `fetch` requests so HTTP-only session cookies are transmitted automatically.
- Do not render secrets or default credentials in UI that ships to production. Gate development helpers behind `process.env.NODE_ENV !== 'production'`.

## 8. Mandatory Testing Expectations
- Test client API interactions with unit tests for `@/lib/api-client`.
- Prioritize behavioral testing (auth state changes, error handling, session expiration recovery) over brittle full-page DOM snapshots.
- Ensure Next.js builds cleanly (`pnpm build`) with zero static generation errors across all routes.
- Run `pnpm --filter @app/web lint` — it is `--max-warnings 0`, so an unused import fails the build.

From Mihir-Rabari/create-odoo-app, MIT.

More from Mihir-Rabari/create-odoo-app