create-freakpunch 0.0.0-stage → 0.2.0

package/template/design/DESIGN.md

@@ -0,0 +1,212 @@
+# Design system
+
+The official design language of this admin panel. Every screen in every project built
+from this template follows it. Components and patterns live in [COMPONENTS.md](COMPONENTS.md) and
+[PATTERNS.md](PATTERNS.md). The single source of truth for values is `src/index.css`.
+
+## Principles
+
+1. **Minimal, Apple/Revolut-like.** Calm surfaces, generous whitespace, few lines. Remove before adding.
+2. **Black, white, warm grays + one accent.** The brand color is the only hue that decorates. Every
+   other color must carry meaning (status, delta, danger).
+3. **No glassmorphism.** No blur, no translucent cards, no gradients on surfaces. Overlays dim the page
+   with a flat tint; they never blur it.
+4. **Tokens only.** Colors, radii, shadows, fonts and layout spacing come from CSS variables. A
+   component never contains a hex/oklch value, an arbitrary shadow, or a new font.
+5. **Quiet hierarchy.** Hierarchy comes from size, weight and muted text, not from color or borders.
+6. **Same in both themes and both languages.** Every screen works in light and dark, in English and
+   Turkish, and from 360px wide up.
+
+## Layout: canvas + floating panel
+
+```
+┌ canvas (--canvas, warm off-white) ───────────────────────────────┐
+│ sidebar          ┌ panel (--background, radius-panel, shadow-panel)┐
+│ (on the canvas)  │ top bar: sidebar toggle · breadcrumbs · tools  │
+│                  │────────────────────────────────────────────────│
+│  ▢ Dashboard     │  Page title                       [actions]    │
+│  ▣ Orders   ←pill│  description                                   │
+│                  │  ┌ card ┐ ┌ card ┐                             │
+│                  │  └──────┘ └──────┘                             │
+│  [user card]     └────────────────────────────────────────────────┘
+└──────────────────────────────────────────────────────────────────┘
+```
+
+- The sidebar sits **directly on the canvas** (no background of its own). The page content lives in a
+  white **floating panel** inset by `--panel-inset` (8px) with `--radius-panel` (16px),
+  `--shadow-panel` and a 1px `ring-border`. The panel scrolls internally.
+- Inside the panel: top bar `--topbar-height` (52px), then content padded with `--page-gutter` (24px,
+  16px on mobile via `--page-gutter-mobile`) and capped at `--page-max-width` (80rem), centered.
+- Below `md` the sidebar becomes a sheet and the panel fills the screen without inset or radius.
+- Full-screen pages outside the app (landing, login, 404) sit on the canvas; a single centered card
+  (login) uses `--radius-panel` and `--shadow-panel`.
+
+## Typography
+
+| Use | Font | Classes |
+| --- | --- | --- |
+| Everything | Inter Variable (`font-sans`) | default |
+| Page title (h1) | Inter, 24px semibold, tight | `text-2xl font-semibold tracking-tight` |
+| Section title (h2 inside a form/settings section) | Inter 14px medium | `text-sm font-medium` |
+| Body | Inter 14px | `text-sm` |
+| Secondary text, descriptions | Inter 13px, muted | `text-xs text-muted-foreground` / `text-sm text-muted-foreground` |
+| Card/sidebar eyebrows, table headers | Inter 11px medium, uppercase, tracked, muted | `label-caps` |
+| Numbers, IDs, SKUs, timestamps | Inter with tabular figures | `tabular-nums` |
+| KPI values | Inter 24px semibold, tabular | `text-2xl font-semibold tracking-tight tabular-nums` |
+
+- **Inter is the only font.** There is no monospace face: `font-mono` is disabled in `@theme`, and
+  `code`/`kbd`/`pre` inherit Inter. Do not add fonts.
+- The type scale (`text-2xs` 12px, `text-xs` 13px, `text-sm` 14px … `text-7xl`) and letter spacing are
+  tuned in `@theme inline`; use the scale, not arbitrary sizes. Exceptions already in the codebase
+  (`text-[13px]` nav items, `text-[10.5px]`/`text-[11px]` small meta) are the only allowed ones.
+- Uppercase `label-caps` is for **short labels only** (one to three words), never for sentences.
+  Numbers that line up (tables, KPIs, counters, times) use `tabular-nums`.
+- Headings use sentence case ("New order", not "New Order"), in both languages.
+
+## Spacing
+
+- Tailwind's 4px scale. Common rhythm: `gap-2` (8) inside controls, `gap-4` (16) between cards and
+  fields, `gap-6` (24) between page blocks, `p-4`/`p-5`/`p-6` inside cards.
+- Page frame: `Page` stacks header and body with `gap-6`.
+- Form sections: `p-5 md:p-6`, two columns (`16rem` label column + fields) from `md` up.
+- Layout spacing that defines the shell is tokenized: `--panel-inset`, `--page-gutter`,
+  `--page-gutter-mobile`, `--page-max-width`, `--topbar-height`.
+
+## Radius
+
+| Token / class | Value | Use |
+| --- | --- | --- |
+| `rounded-md` | 8px | small buttons (`sm`, `icon-sm`), segmented items, menu items |
+| `rounded-lg` | 10px | default buttons, inputs, icon tiles, nav pills |
+| `rounded-xl` = `--radius` | 12px | cards, panels, tables, form cards, controls groups |
+| `rounded-(--radius-panel)` = `rounded-2xl` | 16px | the floating content panel, login card, dialogs |
+| `rounded-full` | — | badges, status dots, avatars, landing pills |
+
+Nothing is rounder than 16px except pills and circles.
+
+## Shadows (very soft)
+
+| Token | Use |
+| --- | --- |
+| `shadow-(--shadow-card)` | every card / panel / table on the page |
+| `shadow-(--shadow-raised)` | raised pills: active nav item, segmented selection, workspace/user cards, icon tiles |
+| `shadow-(--shadow-panel)` | the floating content panel, login card |
+| `shadow-(--shadow-popover)` (`shadow-lg`) | menus, popovers, toasts |
+| `shadow-(--shadow-dialog)` (`shadow-xl`) | dialogs and sheets |
+
+Shadows are always paired with a 1px hairline (`border` or `ring-1 ring-border`). Never use
+Tailwind's default shadow values directly or invent a new one.
+
+## Borders
+
+1px hairlines everywhere: `border` (color `--border`), `divide-y` between rows, `ring-1 ring-border`
+for raised elements. Inputs use `--input` / `--field-border`. No 2px borders except focus rings.
+
+## Color tokens
+
+All colors are defined in `src/index.css` (`:root` for light, `.dark` for dark) and exposed as
+Tailwind utilities through `@theme inline`.
+
+### Surfaces
+
+| Token | Light | Dark | Use |
+| --- | --- | --- | --- |
+| `bg-canvas` | warm off-white `oklch(0.974 0.004 84.6)` | `oklch(0.155 …)` | app background, sidebar, full-screen pages |
+| `bg-background` | white | `oklch(0.195 …)` | floating content panel |
+| `bg-card` | white | `oklch(0.215 …)` | cards, tables, form cards |
+| `bg-popover` | white | `oklch(0.235 …)` | menus, popovers, toasts |
+| `bg-raised` | white | `oklch(0.26 …)` | raised pills on the canvas or inside fills |
+| `bg-fill-1` … `bg-fill-4` | gray at 5/8/12/16% | white at 4/7/11/15% | subtle fills: table header, icon tiles, segmented track, hover |
+| `bg-muted`, `bg-secondary` | very light warm gray | | rarely; prefer fills |
+
+### Text
+
+| Token | Use |
+| --- | --- |
+| `text-foreground` | primary text |
+| `text-muted-foreground` | descriptions, meta, inactive nav, table secondary columns |
+| `text-primary` | brand links and active icons only |
+
+### Lines and controls
+
+`border` (`--border`), `--input`, `--field`, `--field-border`, `bg-control`, `bg-control-hover`,
+`--control-border` are used by the SortUI controls. You rarely reference them directly.
+
+### Brand (the one accent)
+
+`--brand` / `--brand-foreground` (default indigo). Derived: `--primary`, `--primary-foreground`,
+`--ring`, `--selection`, `--sidebar-primary`, `--chart-1`. The brand comes from `appConfig.brand`
+and can be overridden in Settings → Company → Branding (stored in `localStorage` `fp:brand`).
+
+### Semantic
+
+| Token | Light / dark | Meaning |
+| --- | --- | --- |
+| `success` | green | active, healthy, positive delta, successful login |
+| `warning` | amber | needs attention, low stock, invited/pending |
+| `danger` / `destructive` | red | errors, negative delta, destructive actions, failed login |
+| `info` | blue | neutral informational events |
+
+### Charts
+
+`--chart-1` follows the brand; `--chart-2`…`--chart-10` are muted companions. Single-series charts use
+`--chart-1` only; sparklines use `--muted-foreground`.
+
+### Theme scoping
+
+Tokens are declared on `:root, .light` and `.dark`, so adding `light` or `dark` to an element forces
+that subtree into a theme regardless of the app theme. Use only for previews that must show a specific
+background (e.g. the logo tiles in Settings → Company → Branding).
+
+## When to use the accent
+
+Use the brand color for:
+- the primary action on a screen (one default `Button` per view, the rest `outline`/`ghost`),
+- focus rings (`--ring`), text selection,
+- the active nav icon, checked switches/checkboxes/radios, selected states,
+- unread indicators: the notification count badge and unread dots,
+- links inside prose (`text-primary`), chart series 1.
+
+Do **not** use it for: backgrounds of cards or sections, headings, large areas, borders around
+content, or as a status color.
+
+## When to use semantic colors
+
+Only when the color **means something** and always paired with text (never color alone):
+- status dot + label (`StatusBadge`, `StatusDot`),
+- deltas (`text-success` / `text-danger` with an arrow icon),
+- inline warnings like low stock (`text-warning`),
+- destructive buttons and menu items (`variant="destructive"`),
+- the error icon in `ErrorState`, password strength bars.
+
+Never tint whole cards or table rows with a semantic color. A danger-zone card uses a neutral card
+with destructive buttons, not a red background.
+
+## Utilities
+
+- `label-caps`: small uppercase Inter label (eyebrows, table headers, sidebar groups).
+- Table headers: use `TableHeaderCell` (`core/components/data-table/table-header-cell.tsx`), the one
+  shared header style (`label-caps`, `h-10`, `bg-fill-1`, outer cells aligned to the card padding).
+- `scrollbar-none`: horizontal scrollers (mobile settings sub-nav, tab lists) stay scrollable
+  without a visible bar.
+
+## Motion
+
+Subtle and fast: SortUI defaults (fade/scale ~150ms), `transition-opacity` for refetching tables, a
+short fade/slide-in when the settings save bar appears.
+Theme switches disable transitions for one frame. No decorative animation.
+
+## Icons
+
+lucide-react, 16px (`size-4`) in controls and lists, 20px (`size-5`) in empty states and feature
+tiles, `strokeWidth` default (1.75 for large decorative icons). Icon-only buttons always have an
+`aria-label` (translated).
+
+## Accessibility
+
+- Real links for navigation (`Link`, `ButtonLink`), buttons for actions.
+- Visible focus rings in the brand color; never remove outlines without a replacement.
+- Every control has a label (visible `FieldLabel` or translated `aria-label`).
+- Keyboard: ⌘K / Ctrl K command menu, ⌘B / Ctrl B sidebar toggle, menus and dialogs from SortUI.
+- Color is never the only signal (status dots have labels, deltas have arrows).
+- `<html lang>` follows the active language.

package/template/design/PATTERNS.md

@@ -0,0 +1,110 @@
+# Page patterns
+
+Copy the closest existing page instead of starting from scratch. Reference implementations are named
+for each pattern.
+
+## List page
+
+Reference: the list page `npm run new-module` generates, and `src/pages/settings/company/users-page.tsx`.
+
+```
+Page title="Orders" description="…" actions={<primary create button>}
+└ DataTable
+   ├ toolbar: TableSearch · FilterSelect × n · ClearFiltersButton (only when filters are active)
+   ├ columns: identity column first (icon/avatar + name link + muted sub-line),
+   │          status as StatusBadge, numbers right-aligned + tabular, dates muted,
+   │          secondary columns hideOnMobile, row actions last (… dropdown)
+   ├ empty: "no matches" (clear filters) vs "nothing yet" (create action)
+   └ footer: counter · rows per page · pager
+```
+
+- State lives in the URL (`useListUrlState`); pagination/sorting are server-side.
+- The name cell is a real `Link` to the detail page; the row itself is not clickable.
+- Deletion from a row: `useConfirm` → `toast.promise`.
+
+## Form page (create / edit)
+
+Reference: the form page `npm run new-module` generates.
+
+```
+Page title="New order" description="…"
+└ FormLayout submitLabel onCancel (saveBar="always")
+   ├ FormSection "Details"        — most important fields first, autofocus on create
+   ├ FormSection "Organization"
+   └ FormSection "Pricing & inventory"
+```
+
+- One schema (Zod) shared with the service; messages are translation keys.
+- Default `onSubmit` validation. Submit button disabled while submitting and (in edit) while clean.
+- On success: toast + navigate to the detail page. On error: `toast.error` with the message.
+- Two fields side by side with `grid gap-4 sm:grid-cols-2` only when they are related and short.
+
+## Detail page
+
+Reference: the detail page `npm run new-module` generates.
+
+```
+Page title={name} description={muted id} leading={icon tile} actions={Delete (destructive) · Edit (primary)}
+└ grid lg:grid-cols-3
+   ├ Panel "Overview" (lg:col-span-2) — prose / main content
+   └ Panel "Summary" — dl rows: muted label left, value right
+```
+
+- Loading: `LoadingState`. Errors: `ErrorState` with a "Back to list" `notFoundAction`.
+
+## Settings page
+
+Reference: `src/pages/settings/` (`settings-layout.tsx`, `account/profile-page.tsx`).
+
+```
+Settings layout: left sub-navigation (groups "My account", "Company") │ Outlet
+└ Page title="Profile" description="…"
+   └ FormLayout saveBar="dirty"
+      ├ FormSection …
+      └ FormSection …
+```
+
+- Each settings page is its own sub-route (`/app/settings/<page>` or `/app/settings/company/<page>`)
+  with a `crumb` and, for company pages, a `permission` in its route handle.
+- The save bar appears only when the form is dirty; Cancel resets to the saved values.
+- Settings that take effect immediately (theme, language) don't use a save bar.
+- Read-only states (e.g. a role without edit permission) disable fields and hide the save bar.
+- Saving company settings records an audit log entry (in the service layer).
+- Toggle lists (notifications): a card with one row per item, label + description on the left,
+  switches on the right, column headers in `label-caps`.
+- Danger zone: neutral cards, one per action, each with a title, a description of the consequence and a
+  `destructive` button that opens a typed confirmation.
+
+## Dashboard
+
+Reference: `src/pages/dashboard/dashboard-page.tsx`. KPI grid (4 cards, skeletons while loading) →
+main chart `Panel` + quick actions `Panel` → activity `Panel`. Period switch is a `Segmented` in the
+page actions.
+
+## No access / not found
+
+`src/pages/no-access-page.tsx`, `src/pages/not-found-page.tsx`: centered `label-caps` code, title,
+one sentence, one outline button back.
+
+## Do
+
+- Start every screen with `<Page>` and translated `title`/`description`.
+- Use `Panel` / `FormLayout` / `DataTable` for every boxed surface, so radius, border and shadow match.
+- Keep one primary (brand) button per view; put it last in the actions row.
+- Write copy in sentence case, short and specific ("Save changes", "Invite user").
+- Ship every string in EN **and** TR in the same change.
+- Check the screen in light + dark, EN + TR, and at 360px width.
+- Gate actions with permissions (`Can`, route `handle.permission`), and remember UI checks are
+  convenience only — the backend enforces security.
+
+## Don't
+
+- Don't hard-code colors, shadows, radii, fonts or text sizes outside the scale.
+- Don't use blur, glass, gradients on surfaces, or colored card backgrounds.
+- Don't use the brand color for decoration or status; don't use semantic colors without meaning.
+- Don't call `fetch` or mock data from a screen; go through module hooks → service.
+- Don't put navigation in tabs, or actions in links.
+- Don't write user-facing text in components (including `aria-label`, `placeholder`, toasts and
+  validation messages); add keys to the locale files.
+- Don't format numbers/dates by hand; use `useFormat()` (locale, timezone and date format aware).
+- Don't add another component library or edit vendored SortUI files.

package/template/index.html

@@ -0,0 +1,25 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="robots" content="noindex, nofollow" />
+    <meta name="description" content="Admin panel" />
+    <meta name="color-scheme" content="light dark" />
+    <title>freakpunch</title>
+    <script>
+      // Apply the saved theme before first paint (see src/core/theme/theme-context.tsx).
+      try {
+        var t = JSON.parse(localStorage.getItem('fp:theme') || '"system"')
+        var dark = t === 'dark' || (t === 'system' && matchMedia('(prefers-color-scheme: dark)').matches)
+        document.documentElement.classList.toggle('dark', dark)
+        document.documentElement.style.colorScheme = dark ? 'dark' : 'light'
+      } catch (e) {}
+    </script>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/template/nginx.conf

@@ -0,0 +1,32 @@
+server {
+    listen 80;
+    server_name _;
+    root /usr/share/nginx/html;
+    index index.html;
+
+    gzip on;
+    gzip_types text/plain text/css application/javascript application/json image/svg+xml;
+
+    # Block search engine indexing on every response
+    add_header X-Robots-Tag "noindex, nofollow" always;
+
+    # Hashed build assets: cache forever
+    location /assets/ {
+        expires 1y;
+        add_header Cache-Control "public, immutable";
+        # add_header in a location drops the server-level ones, so repeat it here
+        add_header X-Robots-Tag "noindex, nofollow" always;
+        try_files $uri =404;
+    }
+
+    # The app shell must always be revalidated so new deploys show up
+    location = /index.html {
+        add_header Cache-Control "no-cache";
+        add_header X-Robots-Tag "noindex, nofollow" always;
+    }
+
+    # SPA fallback: deep links like /app/settings load index.html on refresh
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+}