create-freakpunch 0.0.0-stage → 0.2.0

package/template/CLAUDE.md

@@ -0,0 +1,297 @@
+# freakpunch admin panel
+
+A reusable admin panel, installed into a project's `fp-admin/` folder with `npm create freakpunch@latest`.
+New features are **modules** that look and behave exactly like the rest of the panel. Never invent a new
+look, layout or component style: reuse what exists and follow `design/`.
+
+
+A new panel is deliberately empty: no modules, no sample data, and optional built-in pages switched off in
+`src/app.config.ts` → `features`. On first open, a setup wizard (`/setup`) creates the company and the Owner.
+Until a backend is connected, data stays in the browser: see `BACKEND.md`.
+
+## Rules for AI agents
+
+1. Read this file and `design/` before changing anything.
+2. New feature = new module: `npm run new-module -- <id> --en "Label" --tr "Etiket"`, then replace its sample
+   fields. The generated list, detail and form pages are the reference for new pages.
+3. **Only change project files:** `src/modules/**`, `src/app.config.ts`, `src/app.roles.ts`, `public/**`.
+   Everything else (`src/core`, `src/pages`, `src/components/ui`, `src/locales`, `src/index.css`, `design/`,
+   `tools/`) belongs to freakpunch and is replaced by updates. If something is missing there, say so to the user
+   instead of editing or copying it.
+4. Every string in both EN and TR. Tokens only. Shared components first (`design/COMPONENTS.md`).
+5. Gate every route and action with a permission; add project-specific ones in `src/app.roles.ts`.
+6. Never add sample or placeholder data to a panel unless the user asks for it.
+7. `npm run check` must pass before you finish.
+
+## Commands
+
+```bash
+npm run dev      # Vite dev server
+npm run build    # tsc -b && vite build (must pass with no errors)
+npm run lint     # oxlint (must pass with no errors or warnings)
+npm run check    # design rules + lint + build: run this before finishing any change
+npm run new-module -- orders --en "Orders" --tr "Siparişler" [--group content]
+npm run fp:update  # installed copies: refresh freakpunch's files (add -- --dry-run to preview)
+docker build -t freakpunch . && docker run --rm -p 8080:80 freakpunch
+```
+
+## Stack
+
+Vite · React 19 · TypeScript (strict) · Tailwind CSS v4 · React Router v8 (data router, `react-router`) ·
+TanStack Query v5 · TanStack Table **v9** (`useTable` + `tableFeatures`, not the v8 `useReactTable` API) ·
+React Hook Form + Zod v4 · Recharts (through SortUI `chart`) · Sonner toasts.
+
+UI components: **SortUI first** (shadcn-compatible, built on Base UI). **Component source order:** SortUI
+first; if SortUI doesn't have it, the official shadcn/ui component (`npx shadcn@latest add <name>`);
+always adapted to our tokens, never two versions of the same component. No other component libraries.
+- Install: `npx shadcn@latest add @sortui/<name> -y` (component list: https://sortui.dev/docs/components).
+- Files land in `src/components/ui/` and are vendored: avoid editing them; style via `className`
+  or tokens. Lint ignores them. The one exception: hard-coded screen-reader/default strings are
+  translated in place with `useTranslation()` (dialog, sheet, sidebar, spinner, breadcrumb,
+  pagination; keys in `common:a11y`, `common:actions.close`, `common:shell.*`). Re-adding one of those
+  with the CLI overwrites the file: reapply the translation.
+- The CLI writes `import { cn } from "cn"`. Rewrite it to `@/lib/utils` after adding:
+  `sed -i 's|from "cn"|from "@/lib/utils"|' src/components/ui/*.tsx`
+- Base UI uses `render` instead of `asChild`. A Button rendering a link needs `nativeButton={false}`;
+  use `ButtonLink` (`src/core/components/button-link.tsx`) for router links.
+- Theme: we use our own `ThemeProvider` (`src/core/theme/theme-context.tsx`), not `next-themes`.
+  `next-themes` stays installed only because the vendored `sonner.tsx` imports it.
+
+## Folder structure
+
+```
+src/
+  app.config.ts            ← per-project config: name, brand, currency, workspaces, nav groups, modules
+  index.css                ← THE design-token source (colors, radius, shadows, layout spacing)
+  main.tsx  providers.tsx  router.tsx
+  locales/                 ← translations: {en,tr}/<namespace>.ts + index.ts (registers every namespace)
+  components/ui/           ← SortUI components (vendored, CLI-managed)
+  core/                    ← identical in every project
+    api/        http.ts (fetch client, ApiError, bearer/cookie auth), rest.ts (createRestService,
+                toPaginated), mock.ts (delay, paginate, createMockCollection, createMockDocument),
+                types.ts (ListParams, Paginated)
+    auth/       auth-store (session in localStorage), auth.service (mock, swappable), use-auth,
+                require-auth (→ /login?redirect=…), roles, permissions (role → permission map),
+                can (Can, useCan, usePermissions), require-permission (route guard), dev-role-switcher
+    users/      user model, mock team (one demo user per role), users.service, hooks
+    setup/      first-run wizard service (local or POST /setup) + SetupGate
+    company/    company settings (general, branding, security policies), password-policy, hooks
+    audit/      audit.service (record + list), hooks
+    notifications/ event catalog + types, notifications.service (feed + settings, mock, per user),
+                hooks (polling, optimistic mark-read), notification-center (top-bar bell + panel)
+    preferences/ preferences-store (time zone, date format, sidebar default)
+    i18n/       i18n init + language detection, keys (I18nKey, useAnyT, vmsg), use-format,
+                language-switcher, types (Messages<T>), i18next.d.ts (typed keys)
+    components/ page (Page, Panel), states (Loading/Empty/ErrorState), form-page (FormLayout,
+                FormSection), form-error, confirm-dialog (useConfirm, typed confirm), status-badge,
+                segmented, button-link, user-avatar, image-upload, phone-input, date-picker,
+                search-select, file-attachments,
+                data-table/ (DataTable, TableHeaderCell, features, toolbar, use-list-url-state)
+    layout/     app-shell (canvas + inset panel), app-sidebar, top-bar (breadcrumbs), command-menu (⌘K)
+    config/     types (AppConfig, FeatureId, AuthMode), runtime (isFeatureOn, authMode, showLanding)
+    modules/    types (AppModule, NavItem…), navigation (nav built from config + modules), lazy-page
+    theme/      theme-context (light/dark/system), brand (presets), brand-context, theme-toggle
+    lib/        storage (namespaced localStorage), format (createFormatters, initials), phone, csv
+  modules/
+    registry.ts            ← every available module; app.config.ts decides which are on
+    locales.ts             ← registers each module's translations
+    orders/                ← what `npm run new-module` generates
+      index.ts             module definition: nav, routes, quick actions (labels = i18n keys, permissions)
+      locales/             en.ts + tr.ts (namespace = module id)
+      types.ts             entity types + Zod form schema
+      api/                 orders.service.ts (interface + mock impl), orders.mock.ts (seed)
+      hooks.ts             TanStack Query keys + hooks
+      components/  pages/
+  pages/                   core pages: setup, login, dashboard/, not-found, no-access
+    settings/              settings-routes, settings-nav, settings-layout (left sub-nav),
+                           account/ (profile, security, notifications, preferences),
+                           company/ (general, branding, users, roles, security policies, modules,
+                           integrations/, audit log, danger zone)
+```
+
+## Architecture rules
+
+- **Screens never call fetch or mocks directly.** Data flows: page → module `hooks.ts` (TanStack Query)
+  → `*.service.ts` (typed interface) → mock today / `http` tomorrow.
+- **Swapping to a real API** = implement the service interface with `http` from `@/core/api/http` and
+  change the one `export const xService = …` line. Map backend responses into `Paginated<T>` /
+  entity types inside the service so screens don't change. Set `VITE_API_URL` for the base URL.
+- **Real JWT auth** = reimplement `AuthService` in `core/auth/auth.service.ts` (call the login
+  endpoint, then `authStore.set(session)`). `http` already sends `Authorization: Bearer <token>` and
+  clears the session on 401. `RequireAuth` and the screens stay as they are.
+- Mock services use `createMockCollection(name, seed)` so data persists in localStorage
+  (`fp:mock:<name>`) and survives reloads. Clear site data to reset.
+- Lists keep state in the URL via `useListUrlState` (`?page=&size=&sort=field.dir&q=&<filter>=`) and
+  use **server-side** pagination/sorting (`manualPagination`, `manualSorting`): the service does the
+  work, as a backend would.
+- Keep TanStack Table `columns` stable (`useMemo` with stable deps, `mutateAsync` instead of the
+  mutation object). Build columns with `createColumnHelper<DataTableFeatures, Row>()`.
+- Forms: React Hook Form + `zodResolver`, SortUI `Field`/`FieldLabel` + `FormFieldError` (translates
+  `vmsg` keys), default `onSubmit` validation mode (`onTouched` races with autofocus+submit and drops
+  errors). Use `useWatch`, not `watch` (React Compiler lint). Settings forms use
+  `FormLayout saveBar="dirty"` (save bar only when dirty).
+- Feedback: `toast` from `sonner`; destructive confirmations via `useConfirm()`; query errors via
+  `ErrorState` (404 `ApiError` renders "Not found" with `notFoundAction`).
+- Every page wraps content in `<Page title description actions>` (sets the document title).
+  Breadcrumbs come from route `handle: { crumb: 'ns:key' }`; access from `handle.permission`.
+- Toasts appear bottom-center everywhere (`providers.tsx`).
+- Mock services record audit entries (`auditService.record`) when company settings, users or
+  integrations change; a real backend writes the audit log server-side.
+- Accessibility: real links for navigation (`Link`/`ButtonLink`), `aria-label` on icon buttons,
+  visible focus rings (brand-colored `--ring`), keyboard paths for everything (⌘K, ⌘B sidebar).
+
+## Design system
+
+**`design/` is the official design system: read it before building any screen.**
+`design/DESIGN.md` (principles, layout, type, spacing, radius, shadows, color tokens, accent/semantic
+rules), `design/COMPONENTS.md` (which SortUI + shared component for what), `design/PATTERNS.md`
+(list/form/detail/settings page patterns, do's and don'ts).
+- Every new screen must follow `design/` and reuse existing tokens and shared components.
+- Never introduce new colors, radii, shadows or fonts outside the token system in `src/index.css`.
+  If something is truly missing, add a token there (light + dark) and document it in `design/DESIGN.md`.
+- Other components may be added following the component source order (SortUI → official shadcn/ui);
+  no other component libraries.
+
+Minimal, Apple/Revolut-like. No glassmorphism (overlays dim, never blur).
+- **Tokens only.** All colors, radius, shadows and layout spacing are CSS variables in `src/index.css`
+  (`:root` + `.dark`), mapped to Tailwind in `@theme inline`. Never hard-code colors in components;
+  use `bg-card`, `text-muted-foreground`, `border`, `bg-fill-1/2`, `bg-raised`, `bg-canvas`,
+  `text-success/warning/danger/info`, `shadow-(--shadow-card)` etc.
+- Palette: black/white/warm grays + **one brand accent** (`--brand`, default indigo). `--primary`,
+  `--ring`, sidebar active icon and chart series 1 all derive from it. Semantic colors only where they
+  carry meaning (status dots/badges, deltas).
+- Type: **Inter is the only font.** Small uppercase labels use the `label-caps` utility; aligned numbers
+  use `tabular-nums`. There is no monospace font (`font-mono` is disabled).
+- 1px hairline borders, very soft shadows (`--shadow-card`, `--shadow-raised`, `--shadow-panel`),
+  12px radius for cards/controls (`rounded-xl`), 16px for the floating panel (`--radius-panel`).
+- Layout: warm off-white canvas (`--canvas`) with the sidebar directly on it; content in a floating
+  white panel (`--background`) inset by `--panel-inset` (matches SortUI inset sidebar `m-2`).
+  The active nav item is a raised bordered pill (`bg-raised` + ring + `--shadow-raised`).
+
+## Roles & permissions
+
+Four built-in roles (`core/auth/roles.ts`), plus project-defined ones from `src/app.roles.ts`: **owner** (everything; exactly one; can't be removed or
+demoted, only transfer ownership), **admin** (everything except the danger zone; can't edit the Owner),
+**editor** (create/edit/delete in modules, no company settings), **viewer** (read-only).
+- `core/auth/permissions.ts` is the single role → permission map. Permission strings are
+  `<resource>.<action>` (`orders.delete`, `settings.company.edit`, `users.manage`,
+  `company.transfer`) and are meant to be reused 1:1 as Spring Security authorities. Every registered
+  module automatically gets `<id>.view|create|edit|delete`.
+- UI: `useCan('x')` / `usePermissions().can` / `<Can permission="x">` (hide, or render-prop to
+  disable). Nav items, quick actions and settings nav take `permission`. Routes take
+  `handle.permission`; `RequirePermissions` in the shell redirects to `/app/no-access`.
+  Owner rules for user management: `canManageUser(actor, target)`.
+- **UI checks are not security.** The backend must enforce every permission (the mock services
+  enforce the Owner rules the same way a backend should).
+- In `npm run dev` the top
+  bar has a role switcher (`DevRoleSwitcher`, code-split behind `import.meta.env.DEV`, absent from
+  production builds).
+
+## Settings
+
+`/app/settings` has a left sub-navigation inside the panel (horizontal scroller on mobile).
+"My account" (profile, security, notifications, preferences) is for everyone; the "Company" group needs
+`settings.company.view` (Owner/Admin) and the danger zone `company.delete` (Owner). Add a page: a
+route in `settings-routes.tsx` (crumb + permission) and an item in `settings-nav.ts` (same permission).
+Company forms are read-only (`FormLayout readOnly`) without `settings.company.edit`.
+
+## Internationalization (EN + TR)
+
+react-i18next. English is the default and fallback; Turkish is a full second language.
+**Every feature ships with both EN and TR strings in the same change. No user-facing text in
+components**: page titles, labels, `aria-label`, `placeholder`, toasts, empty states, validation.
+- Files: `src/locales/{en,tr}/<namespace>.ts` (common, auth, landing, errors, dashboard, settings,
+  account, company, notifications), registered in `src/locales/index.ts`, and module-owned
+  `src/modules/<module>/locales/{en,tr}.ts`, registered in `src/modules/locales.ts`.
+- Locale files are TS objects. `tr` files are typed `Messages<typeof en>`, so a missing/extra Turkish
+  key fails `npm run build`. Keys are typed (`src/core/i18n/i18next.d.ts`): `t('typo')` doesn't compile.
+- Add a string: add the key to `en/<ns>.ts`, then the same key to `tr/<ns>.ts` (correct Turkish
+  characters: ç ğ ı İ ö ş ü). Use `{{name}}` interpolation, `_one`/`_other` plurals with `count`,
+  `<b>…</b>` + `<Trans components>` for inline markup. Never concatenate translated fragments.
+- Add a namespace: create `en/<ns>.ts` + `tr/<ns>.ts` and register both in `src/locales/index.ts`
+  (modules: `locales/` and `src/modules/locales.ts`), use `useTranslation(['<ns>', 'common'])` and `t('common:actions.save')`
+  for shared strings.
+- Config-like data (nav labels, crumbs, quick actions, nav groups, workspace plans) stores
+  `I18nKey` values (`'orders:nav'`) and is translated with `useAnyT()`.
+- Zod messages are keys: `vmsg('validation.minChars', { min: 2 })`; render errors with
+  `FormFieldError` (translates at render time).
+- Formatting: `const fmt = useFormat()` → `fmt.currency/number/date/dateTime/relative/…` (Intl with the
+  active locale, user timezone/date format, company currency). Pass `fmt` and `t` as `useMemo` deps
+  of table columns.
+- Language: `LanguageSwitcher` (landing, login, top bar) and Settings → Preferences. Stored in
+  `localStorage` `fp:lang`; first visit uses TR if the browser language is Turkish, else EN.
+  `<html lang>` follows the active language.
+- Vendored SortUI screen-reader strings (dialog/sheet "Close", mobile sidebar title, "Toggle sidebar",
+  spinner "Loading", pagination) are translated in the vendored files (see Stack). Our dialogs still use
+  `showCloseButton={false}` + a footer Cancel.
+
+## Notifications
+
+Top-bar bell (`core/notifications/notification-center.tsx`): unread badge (brand color, hidden at 0,
+"9+" above 9) and a panel (popover on desktop, bottom sheet on mobile) with All / Unread tabs, Today /
+Earlier groups, mark one / all as read, and a link to Settings → Notifications.
+- One event catalog (`core/notifications/types.ts` → `notificationEvents`) drives both the settings
+  toggles and the feed. Every notification has an `event`; events with in-app off are not returned.
+  Add an event there + its label in `account:notifications.events` (EN + TR).
+- The API sends `template` + `params`, never rendered text; the client renders
+  `notifications:templates.<template>.title|body` in the active language (roles, money and numbers are
+  localized at render time). Add a template to `notificationTemplates` and both locale files.
+- Data: `notificationsService` (per signed-in user; the mock seeds a different feed per role and
+  occasionally adds a new notification) → `useNotifications()` polls every 30 s. For a real backend
+  implement the interface with `http` (`GET /me/notifications`, `POST …/{id}/read`, `POST …/read-all`,
+  `GET|PUT /me/notification-settings`) and optionally `subscribe()` for SSE/WebSocket push; the hooks
+  already invalidate on pushed events and keep polling as a fallback.
+
+## How to add a module
+
+`npm run new-module -- orders --en "Orders" --tr "Siparişler"` creates `src/modules/orders` (list with search,
+filters, bulk delete and CSV export; create/edit form; mock data; REST switch; EN + TR) and registers it in
+`registry.ts`, `locales.ts` and `app.config.ts`. Replace the sample fields. It leaves the `// fp:*` marker
+comments in those files in place; keep them. What it sets up, if you need to do it by hand:
+
+1. Module folder with types, service, hooks, pages and `locales/`.
+2. `<name>/locales/en.ts` + `tr.ts` registered in `src/modules/locales.ts` as namespace `<name>`.
+3. In `<name>/index.ts` export an `AppModule` (labels/crumbs are translation keys):
+   ```ts
+   export const ordersModule: AppModule = {
+     id: 'orders',
+     nav: [{ label: 'orders:nav', path: '/app/orders', icon: ShoppingCart, group: 'catalog',
+             useBadge: usePendingCount, permission: 'orders.view' }],
+     quickActions: [{ label: 'orders:quickActions.new', path: '/app/orders/new', icon: Plus, permission: 'orders.create' }],
+     routes: [{ path: 'orders', handle: { crumb: 'orders:crumbs.list', permission: 'orders.view' }, children: [
+       { index: true, lazy: lazyPage(() => import('./pages/orders-list-page')) },
+       { path: 'new', handle: { crumb: 'orders:crumbs.new', permission: 'orders.create' }, lazy: … },
+     ] }],
+   }
+   ```
+   Routes are relative to `/app` and render inside the shell; pages are default exports, lazy-loaded.
+   Gate buttons with `<Can permission="orders.delete">`.
+4. Register it in `src/modules/registry.ts` (`orders: ordersModule`); this also creates the
+   `orders.view|create|edit|delete` permissions and their row in the roles matrix.
+5. Enable it in `src/app.config.ts` → `modules: { orders: true }`. Nav groups come from
+   `appConfig.navGroups` (`group` must match an id); empty groups are hidden.
+6. The sidebar, ⌘K menu, dashboard quick actions, routes and Settings → Modules pick it up automatically.
+
+Extras: `dashboardWidgets: [Component]` on the module adds cards to the dashboard. Extra permissions
+(`orders.refund`) and extra roles (`hr`) go in `src/app.roles.ts`, with their EN + TR labels.
+
+## How to change the brand color
+
+- Per project: set `brand` in `src/app.config.ts` to a preset key from `src/core/theme/brand.ts`
+  (`indigo`, `blue`, `violet`, `emerald`, `orange`, `rose`, `graphite`) or a custom
+  `{ color: 'oklch(…)', foreground: 'oklch(1 0 0)' }`. Also update the `--brand` default in
+  `src/index.css` to the same value so the first paint matches.
+- Add presets in `brandPresets` (`brand.ts`) and a label in `company:branding.presets` (EN + TR); they appear in Settings → Company → Branding.
+- Settings → Company → Branding previews the brand live (`previewBrand`) and saves it for the company (cached in localStorage `fp:brand` for first paint).
+
+## Deployment & indexing
+
+Backend connection, auth modes and serving under `/admin` (`VITE_BASE_PATH`) are in `BACKEND.md`.
+
+- `Dockerfile`: node:24-alpine build → nginx:alpine on port 80 with `nginx.conf`.
+- `nginx.conf`: SPA fallback (`try_files … /index.html`) so deep links work on refresh; immutable cache
+  for `/assets/`, `no-cache` for `index.html`; `X-Robots-Tag: noindex, nofollow` on every response
+  (repeated inside locations that set their own headers).
+- Search engines must not index the site: keep the `robots` meta tag in `index.html`,
+  `public/robots.txt` (`Disallow: /`) and the nginx header.
+- `assets/` holds design reference screenshots (not part of the build).

package/template/Dockerfile

@@ -0,0 +1,19 @@
+# syntax=docker/dockerfile:1
+
+# ---- Build stage ----
+FROM node:24-alpine AS build
+WORKDIR /app
+
+COPY package.json package-lock.json ./
+RUN npm ci
+
+COPY . .
+RUN npm run build
+
+# ---- Serve stage ----
+FROM nginx:alpine
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+COPY --from=build /app/dist /usr/share/nginx/html
+
+EXPOSE 80
+CMD ["nginx", "-g", "daemon off;"]

package/template/_gitignore

@@ -0,0 +1,26 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+packages/create-freakpunch/template
+*.tgz
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

package/template/components.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "base-nova",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/index.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "lucide",
+  "rtl": false,
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "menuColor": "default",
+  "menuAccent": "subtle",
+  "registries": {
+    "@sortui": "https://sortui.dev/r/{name}.json"
+  }
+}

package/template/design/COMPONENTS.md

@@ -0,0 +1,145 @@
+# Components
+
+## Component source order
+
+1. **SortUI** first (`npx shadcn@latest add @sortui/<name> -y`).
+2. If SortUI doesn't have it, the **official shadcn/ui** component (`npx shadcn@latest add <name>`).
+3. Either way it is adapted to our tokens (no raw colors, radii, shadows or fonts) and there is
+   **never more than one version of the same component**: don't add a shadcn/ui component SortUI
+   already provides, and don't keep two variants side by side.
+
+Two layers: **SortUI** primitives (vendored in `src/components/ui/`, CLI-managed, never edited) and our
+**shared components** (`src/core/components/`, `src/core/layout/`, …) that compose them into the
+design language. Screens use shared components first and SortUI primitives second. No other UI
+library is allowed.
+
+## SortUI components we use
+
+Add more with `npx shadcn@latest add @sortui/<name> -y`, then rewrite the `cn` import (see CLAUDE.md).
+
+| Component | Use it for | Notes |
+| --- | --- | --- |
+| `button` | every action | One `default` (brand) button per view = the primary action. Others: `outline` (secondary), `ghost` (tertiary / toolbar / icon buttons), `destructive` (delete, irreversible), `link`. Sizes: `default` in pages, `sm` in dense toolbars and cards, `lg`/`xl` on login/landing, `icon-sm` for row/toolbar icons. Use `data-icon="inline-start"` on leading icons. |
+| `input`, `textarea`, `input-group` | text entry | `InputGroup` for prefixes (currency symbol, search icon, country code). |
+| `field` | every form control | `Field` + `FieldLabel` + control + `FieldDescription` + `FormFieldError`. `data-invalid` + `aria-invalid` when invalid. `orientation="horizontal"` for switch/checkbox rows. |
+| `select` | single choice from a list | Always pass `items` so the trigger shows the label. Filters use `FilterSelect`. |
+| `calendar`, `combobox` | via `DatePicker` / `SearchSelect` | Don't use them raw. |
+| `checkbox`, `switch`, `radio-group` | booleans / small exclusive choices | Switch = takes effect (setting); checkbox = part of a form or selection. Radio cards (`FieldLabel` wrapping `Field`) for visual choices like theme. |
+| `toggle-group` | via `Segmented` only | Don't use raw toggle groups for view switches. |
+| `tabs` | switching between sibling views of one object | Not for top-level navigation (use routes). |
+| `dropdown-menu` | row actions, account menu, theme/language menus | Destructive items last, separated, `variant="destructive"`. |
+| `dialog` | short focused tasks (invite user, create API key, 2FA setup) | Title + description + body + footer (cancel left of primary). |
+| `alert-dialog` | via `useConfirm()` only | Confirmations, including typed confirmations. |
+| `sheet` | mobile sidebar (managed by `sidebar`), mobile notification panel (`side="bottom"`) | Use where a desktop popover would be too small on a phone. |
+| `popover` | non-modal panels anchored to a trigger (notification panel) | `p-0` + own header/body/footer for list panels. |
+| `sidebar` | app shell only | `variant="inset"`, `collapsible="icon"`. |
+| `table` | via `DataTable` | Use raw `Table` only for small static tables inside a card (e.g. login history, roles matrix), always with `TableHeaderCell` for headers. |
+| `badge` | counts, role labels, "Current", "New" | Status uses `StatusBadge`, not colored badges. Role uses `variant="secondary"`. |
+| `avatar` | people | `rounded-lg` square-ish avatars in lists and the sidebar; initials fallback on `bg-fill-2`. |
+| `breadcrumb` | top bar only | Driven by route `handle.crumb`. |
+| `command` | ⌘K menu only | |
+| `empty` | via `EmptyState` / `ErrorState` | |
+| `skeleton`, `spinner` | loading | Skeletons for known layouts (tables, KPI cards); `LoadingState` spinner for whole pages. |
+| `tooltip` | icon-only buttons in collapsed sidebar, truncated text | Never put essential information only in a tooltip. |
+| `kbd` | keyboard shortcuts | |
+| `separator` | vertical separators in toolbars | Use `divide-y`/`border` for horizontal lines. |
+| `chart` | all charts (Recharts inside `ChartContainer`) | Colors via `var(--chart-n)`. |
+| `sonner` | toasts via `toast()` | Mounted once in `providers.tsx`, bottom-center. |
+
+## Shared components
+
+### Page frame — `core/components/page.tsx`
+
+- **`<Page title description actions leading documentTitle>`**: every routed screen's root. Renders the
+  h1, description, right-aligned actions (primary action last) and sets `document.title`.
+  `title`/`description` are translated strings.
+- **`<Panel label actions>`**: bordered card with a `label-caps` header row. Use for dashboard cards,
+  detail summaries and any titled group of content.
+
+### Forms — `core/components/form-page.tsx`, `core/components/form-error.tsx`
+
+- **`<FormLayout onSubmit submitLabel isSubmitting isDirty onCancel extraActions saveBar>`**: a form
+  card with sections divided by hairlines and a sticky action bar. `saveBar="dirty"` hides the bar
+  until the form has unsaved changes (settings pages); default `"always"` (create/edit pages).
+- **`<FormSection title description>`**: two-column section (label column + fields) inside a
+  `FormLayout` or any `divide-y` card.
+- **`<FormFieldError error={errors.x} />`**: translated replacement for SortUI `FieldError`. Zod
+  messages are translation keys (`vmsg('validation.required')`), translated at render time so they
+  switch language instantly.
+
+### Lists — `core/components/data-table/`
+
+- **`<DataTable>`**: server-driven table (TanStack Table v9) with toolbar slot, skeleton rows,
+  error/empty states, footer counter, page size and paging. Columns from
+  `createColumnHelper<DataTableFeatures, Row>()`, memoized.
+- **`useListUrlState`**: keeps page/size/sort/search/filters in the URL.
+- **`selection` prop**: row checkboxes and a bar with bulk actions. Bulk deletes go through `useConfirm`.
+- **`downloadCsv`** (`core/lib/csv.ts`): CSV export with Excel-safe encoding and escaped formulas.
+- **`TableSearch`** (debounced), **`FilterSelect`** ("All …" clears), **`ClearFiltersButton`**.
+- **`TableHeaderCell`**: the shared header cell style. `DataTable` uses it; small static tables must
+  too (never copy the header classes by hand).
+
+### States — `core/components/states.tsx`
+
+- **`LoadingState`**: centered spinner + label for whole-page loading.
+- **`EmptyState`**: icon tile + title + description + optional action. Two flavours per list:
+  "nothing yet" (with a create action) and "no matches" (with clear filters).
+- **`ErrorState`**: query errors with retry; a 404 `ApiError` renders "Not found" with
+  `notFoundAction`.
+
+### Feedback
+
+- **`useConfirm()`** (`core/components/confirm-dialog.tsx`): promise-based confirm.
+  `destructive: true` for irreversible actions, `typeToConfirm: companyName` to require typing a value
+  (danger zone).
+- **`toast`** from `sonner`: success after a save, error with the message on failure,
+  `toast.promise` for row actions. Messages are translated.
+
+### Status and small pieces
+
+- **`StatusBadge tone`** / **`StatusDot tone`**: neutral outline pill + semantic dot.
+- **`Segmented`**: iOS-style segmented control for 2–4 short options (date ranges, role picker).
+- **`ButtonLink`**: a `Button` that is a router link.
+- **`LanguageSwitcher`** (`core/i18n/language-switcher.tsx`) and **`ThemeToggle`**
+  (`core/theme/theme-toggle.tsx`): ghost icon-button menus, used together in headers.
+- **`Can`** / **`useCan`** (`core/auth/can.tsx`): permission-gated UI (hide or disable).
+- **`UserAvatar`** (`core/components/user-avatar.tsx`): avatar image or initials.
+- **`ImageUpload`** (`core/components/image-upload.tsx`): file picker with preview tile, used for
+  avatars, logos and favicons.
+- **`DatePicker`** (`core/components/date-picker.tsx`): date-only field, value is `YYYY-MM-DD`.
+- **`SearchSelect`** (`core/components/search-select.tsx`): single choice from a long list with type-to-search.
+  Short lists use `select`.
+- **`FileAttachments`** (`core/components/file-attachments.tsx`): pick and list files; the service uploads
+  them with `http.post(path, formData)`.
+- **`PhoneInput`** (`core/components/phone-input.tsx`): country calling code (localized names) +
+  national number; validate with `isValidPhone`, store with `toE164` (`core/lib/phone.ts`).
+- **`ReadOnlyNotice`** (`pages/settings/company/components`): muted bar above company forms the
+  current role can view but not edit.
+- **`DevRoleSwitcher`** (`core/auth/dev-role-switcher.tsx`): development-only top-bar control.
+
+### Layout — `core/layout/`
+
+`AppShell` (canvas + inset panel, auth + permission guard), `AppSidebar` (workspace switcher, search,
+nav groups, user card with profile + sign out), `TopBar` (sidebar toggle, breadcrumbs, dev role
+switcher, language, clock, notifications, theme), `CommandMenu` (⌘K).
+
+### Notifications — `core/notifications/notification-center.tsx`
+
+**`NotificationBell`**: ghost icon button with a brand-colored unread badge; opens the
+notification panel in a `popover` (desktop) or bottom `sheet` (mobile). Items: type icon tile
+(semantic color + translated type for screen readers), title, body, relative time, unread dot;
+items with a link are real links. Settings has its own sub-navigation (`pages/settings/settings-layout.tsx`).
+
+## Usage rules
+
+1. Reach for a shared component before composing primitives. If you compose the same primitives twice,
+   promote them to `src/core/components/`.
+2. Never edit `src/components/ui/*`. Style through `className` with tokens, or with unlayered
+   attribute selectors in `index.css` (see the overlay rule). Only exception: translating hard-coded
+   screen-reader strings with `useTranslation()` (see CLAUDE.md).
+3. Never pass raw colors, shadows or radii in `className` (`bg-[#…]`, `shadow-[…]`, `rounded-[…]`).
+4. Every visible string, `aria-label`, `placeholder` and `title` comes from `t()`.
+5. Icon-only buttons: `variant="ghost" size="icon-sm"` + translated `aria-label`.
+6. Destructive actions always go through `useConfirm({ destructive: true })`.
+7. Permission-dependent controls use `Can`/`useCan`: hide what the user can never do; disable (with a
+   reason) what they can't do in this context, e.g. editing the Owner.