create-tigra 3.0.5 → 3.1.0

package/template/_claude/rules/client/04-design-system.md

@@ -1,408 +0,0 @@
-> **SCOPE**: These rules apply specifically to the **client** directory (Next.js App Router).
-
-# Design System
-
-## Philosophy: "Mobile-First Neuro-Minimalism"
-
-**Mobile is the default. Desktop is the enhancement.** 80%+ of traffic is mobile — design for thumbs first, cursors second.
-
-Clean, airy, "expensive" look inspired by Linear, Vercel, Stripe, Arc. Every visual decision reduces cognitive load. Every screen must feel like a native app on mobile.
-
----
-
-## CSS Architecture (Source of Truth)
-
-This project uses **Tailwind CSS v4** with **HEX colors** and the `@theme inline` directive (not the legacy `tailwind.config.ts`).
-
-**Key differences from Tailwind v3:**
-- No `tailwind.config.ts` — all config is CSS-based via `@theme inline`
-- Colors use **HEX** values (e.g., `#c15f3c`), with `rgba()` for alpha values
-- `@custom-variant dark` replaces `darkMode: 'class'`
-- No `@layer base { :root { } }` — variables defined on `:root` via theme file
-
----
-
-## Theme System (Color Management)
-
-**ALL color variables live in `src/styles/themes/default.css`, NOT in `globals.css` or components.** This is the single source of truth for the entire app's color palette.
-
-### How It Works
-
-```
-src/
-├── app/globals.css                    ← imports the theme + defines smooth transitions
-└── styles/themes/
-    └── default.css                    ← Claude-inspired warm palette (HEX)
-```
-
-`globals.css` imports the theme:
-
-```css
-@import "../styles/themes/default.css";
-```
-
-### Theme File Structure
-
-`default.css` defines ALL semantic color variables for both `:root` (light) and `.dark` (dark mode) using HEX:
-
-```css
-:root {
-  --radius: 0.625rem;
-  --background: #f4f3ee;
-  --foreground: #1a170f;
-  --primary: #c15f3c;
-  --primary-foreground: #ffffff;
-  /* ... all ~35 semantic tokens */
-}
-
-.dark {
-  --background: #15130d;
-  --foreground: #e9e8e3;
-  --primary: #d6724f;
-  /* ... dark mode overrides for all tokens */
-}
-```
-
-### Customizing Colors
-
-To change the brand palette, edit the HEX values in `default.css`. That's it — every color in the app updates instantly for both light and dark modes.
-
-### Smooth Theme Transitions
-
-`globals.css` includes a global transition rule in `@layer base` that smoothly animates color changes when toggling light/dark mode:
-
-```css
-*, *::before, *::after {
-  transition-property: background-color, color, border-color, box-shadow;
-  transition-duration: 200ms;
-  transition-timing-function: ease-out;
-}
-```
-
-### Light/Dark Mode Toggle
-
-- Managed by `next-themes` with `attribute="class"` and `defaultTheme="light"`
-- The `ThemeToggle` component (`components/common/ThemeToggle.tsx`) provides the UI
-- The Header component also includes a sun/moon toggle button
-
-### CRITICAL RULES — Color Management
-
-1. **NEVER add or modify color variables in `globals.css`.** All `:root` and `.dark` color variables belong in `default.css` only.
-2. **NEVER hardcode hex/rgb values in components.** Always use semantic tokens (`bg-primary`, `text-foreground`).
-3. **NEVER use OKLCH color values.** All colors must be HEX (e.g., `#c15f3c`). Use `rgba()` only when alpha transparency is needed.
-4. **NEVER rename CSS variables.** The variable names (`--primary`, `--background`, `--muted`, etc.) are locked for consistency. Only edit their HEX values.
-5. **NEVER modify the smooth transition rules in `globals.css`.** The `transition-property`, `transition-duration`, and `transition-timing-function` on `*` are part of the theme system and must not be changed or removed.
-6. **NEVER modify the `@theme inline` block in `globals.css`.** It maps CSS vars to Tailwind — it does NOT define colors. Colors come from `default.css`.
-7. **To change the brand palette**: edit the HEX values in `default.css`. Never scatter color values across multiple files.
-8. **New semantic tokens**: If you need a new token (rare), add it to both `:root` and `.dark` in `default.css`.
-
----
-
-## Font Preset System (Font Management)
-
-**Font families are defined in font preset files, NOT hardcoded in components.** This mirrors the color theme preset system — switch the entire font pairing by changing one import.
-
-### How It Works
-
-```
-src/
-├── app/
-│   ├── layout.tsx                     ← loads fonts via next/font/google
-│   └── globals.css                    ← imports ONE font preset (switch here)
-└── styles/fonts/
-    └── inter-jetbrains.css            ← Default (Inter + JetBrains Mono)
-```
-
-### Three Semantic Font Roles
-
-| Role | CSS Variable | Tailwind Class | Default Font |
-|------|-------------|----------------|--------------|
-| Body text | `--font-sans-value` | `font-sans` | Inter |
-| Headings | `--font-heading-value` | `font-heading` | Inter |
-| Code/mono | `--font-mono-value` | `font-mono` | JetBrains Mono |
-
-### How to Switch Fonts
-
-Switching fonts requires two changes:
-
-**Step 1 — Update font imports in `layout.tsx`:**
-
-```tsx
-// Change these imports to your desired fonts
-import { Roboto, Fira_Code } from 'next/font/google';
-
-const roboto = Roboto({
-  variable: '--font-roboto',
-  subsets: ['latin'],
-  weight: ['400', '500', '600', '700'],
-});
-
-const firaCode = Fira_Code({
-  variable: '--font-fira-code',
-  subsets: ['latin'],
-});
-
-// Update the className to use new variables
-<body className={`${roboto.variable} ${firaCode.variable} font-sans antialiased`}>
-```
-
-**Step 2 — Update the font preset file (or create a new one):**
-
-```css
-/* styles/fonts/roboto-fira.css */
-:root {
-  --font-sans-value: var(--font-roboto);
-  --font-heading-value: var(--font-roboto);
-  --font-mono-value: var(--font-fira-code);
-}
-```
-
-Then update the import in `globals.css`:
-```css
-@import "../styles/fonts/roboto-fira.css";
-```
-
-### Font Preset Structure
-
-Each preset maps raw font variables (set by `next/font/google` in `layout.tsx`) to semantic roles:
-
-```css
-:root {
-  --font-sans-value: var(--font-inter);        /* body text */
-  --font-heading-value: var(--font-inter);      /* headings */
-  --font-mono-value: var(--font-jetbrains-mono); /* code */
-}
-```
-
-### Creating a Custom Font Preset
-
-1. Choose your fonts from [Google Fonts](https://fonts.google.com)
-2. Update `layout.tsx` — import fonts via `next/font/google`, set CSS variable names
-3. Create a new preset file in `src/styles/fonts/` (or edit the existing one)
-4. Map your font variables to the three semantic roles
-5. Update the import in `globals.css` to point to your preset
-
-### CRITICAL RULES — Font Management
-
-1. **NEVER hardcode font-family values in components.** Always use Tailwind classes (`font-sans`, `font-heading`, `font-mono`).
-2. **ALL font-family mappings live in the font preset file**, not in `globals.css` or components.
-3. **To change fonts**: update `layout.tsx` imports + update the font preset file. Never scatter font-family values across the codebase.
-4. **The `@theme inline` block in `globals.css` maps preset variables to Tailwind** — it does NOT define fonts. Fonts come from the preset.
-5. **Fonts are loaded via `next/font/google`** — this self-hosts fonts automatically at build time. No external requests at runtime, no manual file downloads needed.
-
----
-
-## Mobile-First Responsive Strategy
-
-**All Tailwind utilities are written for mobile first.** `md:` and `lg:` are progressive enhancements, not the other way around.
-
-### Rules
-
-1. **Write mobile styles as the base.** Add `md:` / `lg:` to override for larger screens. Never use `max-*:` breakpoints.
-2. **Breakpoints**: `sm:` (640px) → `md:` (768px) → `lg:` (1024px) → `xl:` (1280px). Scale UP, never down.
-3. **Test mobile first** during development. Open DevTools at 375px before checking desktop.
-4. **Every screen must be fully usable at 375px width.** No horizontal scroll, no truncated actions, no hidden critical UI.
-
-### Viewport & Safe Areas
-
-- **Use `dvh` instead of `vh`** for full-height layouts — accounts for mobile browser chrome (URL bar, bottom bar).
-- **Viewport meta**: `<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">`.
-- **Respect safe areas** on notched/dynamic island devices:
-  - Bottom-fixed elements: add `pb-[env(safe-area-inset-bottom)]`
-  - Top-fixed elements: add `pt-[env(safe-area-inset-top)]`
-- **No `100vh` anywhere.** Always `100dvh` or `min-h-dvh`.
-
-### Anti-patterns
-
-- Do NOT write desktop-first classes like `w-1/3 max-md:w-full`. Write `w-full md:w-1/3`.
-- Do NOT hide mobile-critical content behind `hidden md:block`. Content strategy must work on mobile first.
-- Do NOT use fixed pixel widths. Use `w-full`, percentage-based, or `max-w-*` utilities.
-
-## Color Usage
-
-| Token | Purpose | Example use |
-|---|---|---|
-| `primary` | Main CTAs, links, active states | "Get started" button |
-| `secondary` | Secondary actions | Cancel, back |
-| `destructive` | Delete, errors | Delete button, error alert |
-| `success` | Success states | "Action completed" |
-| `warning` | Warnings | "Pending approval" |
-| `info` | Information | "New feature" badge |
-| `muted` | Disabled, placeholders | Disabled input |
-| `accent` | Highlights | "Featured" badge |
-| `card` | Card backgrounds | Content card |
-| `border` | Borders, dividers | Card border |
-
-### Color Rules
-
-1. **Never hardcode**: No `bg-blue-500`, no `bg-[#3b82f6]`, no `style={{ color }}`. Always semantic tokens.
-2. **Semantic names by purpose**: `bg-destructive` not `bg-red`.
-3. **Always pair bg + foreground**: `bg-primary text-primary-foreground` for contrast.
-4. **Single source of truth**: Change colors ONLY in the active theme preset file (`src/styles/themes/*.css`). Never in `globals.css`, never in components.
-5. **90% monochrome**: 90% of UI uses `background`, `foreground`, `muted`, `border`. Color is the exception.
-6. **Opacity for hierarchy**: Use `bg-primary/10`, `bg-primary/5` for tinted backgrounds.
-
----
-
-## Surfaces & Depth
-
-- **Border radius**: `rounded-xl` (12px) or `rounded-2xl` (16px) for cards, modals, containers.
-- **Shadows** (layered by elevation):
-  - Resting cards: `shadow-sm`
-  - Hovered/elevated: `shadow-md` to `shadow-lg`
-  - Modals/popovers: `shadow-xl`
-- **Glassmorphism**: Only on sticky headers, floating toolbars, modal backdrops. Never on content cards.
-  Use `backdrop-blur-md` + `bg-background/80` in Tailwind.
-- **No pure black/white**: Use `--background` and `--foreground` tokens (already off-pure).
-
----
-
-## Typography
-
-- **Font**: Defined by the active font preset (default: Inter for sans/heading, JetBrains Mono for mono). See "Font Preset System" above for how to switch.
-- **Headings**: Use `font-heading`. `text-wrap: balance`, `leading-tight`. Mobile-first responsive sizes:
-  - H1: `text-2xl md:text-3xl lg:text-4xl`
-  - H2: `text-xl md:text-2xl`
-  - H3: `text-lg md:text-xl`
-- **Body**: `text-base`, `leading-relaxed`. Max reading width: `max-w-prose` (~65ch).
-- **Data/numbers**: Always `tabular-nums` for alignment.
-- **Captions/meta**: `text-sm text-muted-foreground`.
-- **Mobile readability**: Minimum `text-sm` (14px) for any readable text. Never go below 12px.
-
----
-
-## Spacing
-
-- **Whitespace IS the divider.** Prefer spacing over visible borders/lines.
-- **Section gap = 2x internal gap**: Mobile: `space-y-10` between sections, `space-y-4` within. Desktop: `space-y-16` between sections, `space-y-6` within.
-- **Stick to scale**: `4, 6, 8, 12, 16, 20, 24` from Tailwind. Avoid arbitrary values.
-- **Container**: `container mx-auto px-4 sm:px-6 lg:px-8` (mobile gets comfortable 16px padding).
-
----
-
-## Motion & Interactions
-
-Every interactive element MUST have visible `:active` and `:focus-visible` states. `:hover` is a desktop enhancement — never the only feedback.
-
-### Standard Patterns (Mobile-First)
-```
-Button:  transition-all duration-200 ease-out active:scale-[0.97] md:hover:brightness-110
-Card:    transition-all duration-300 ease-out active:scale-[0.98] md:hover:shadow-lg md:hover:-translate-y-0.5
-Link:    transition-colors duration-150 active:opacity-70 md:hover:text-primary
-```
-
-### Rules
-- **`active:` is the primary feedback** on mobile. Tap must feel instant and responsive.
-- **`hover:` is desktop-only** — always prefix with `md:hover:` to avoid sticky hover on touch devices.
-- **No hover-gated functionality**: Anything revealed on hover (tooltips, menus) MUST have a tap/click alternative.
-- **Transform + opacity only** — never animate layout properties (`width`, `height`, `top`).
-- **Respect `prefers-reduced-motion`**: Use `motion-safe:` / `motion-reduce:` variants.
-- **Motion budget**: Max 2-3 animated elements in viewport at once.
-- **Zero CLS**: Animations must never cause layout shift.
-
----
-
-## Touch & Interaction Design
-
-### Touch Targets
-
-- **Minimum size**: 44x44px (`min-h-11 min-w-11`). Recommended: 48x48px (`min-h-12 min-w-12`).
-- **Spacing between targets**: Minimum 8px gap to prevent mis-taps.
-- **Icon-only buttons**: Use `p-2.5` or `p-3` to ensure the tap area is large enough even if the icon is small.
-- **Inline links in text**: Add `py-1` for vertical tap padding without affecting line height visually.
-
-### Thumb Zone Design
-
-- **Primary actions in the bottom third** of the screen — thumbs naturally rest there.
-- **Avoid top corners** for critical interactive elements (hardest to reach one-handed).
-- **Sticky bottom CTAs**: Primary action buttons stick to bottom of viewport on mobile: `sticky bottom-0 pb-[env(safe-area-inset-bottom)]`.
-- **FABs (Floating Action Buttons)**: Position `bottom-6 right-4` for primary creation actions.
-
-### Gesture Support
-
-- **Swipe-to-dismiss** on bottom sheets and drawers (use Vaul / shadcn Drawer).
-- **Pull-to-refresh** where contextually appropriate (feed pages, lists).
-- **Swipe actions on list items** for quick actions (archive, delete) — use sparingly, always with undo.
-- **Pinch-to-zoom** on images and maps — never disable native zoom.
-
-### Mobile Navigation Patterns
-
-| Nav items | Mobile pattern | Desktop pattern |
-|---|---|---|
-| 2-5 core routes | **Bottom tab bar** (sticky, always visible) | Top horizontal nav |
-| 6+ routes | Bottom tab bar (4 items + "More") | Sidebar or top nav with dropdowns |
-| Contextual actions | **Bottom sheet** (Drawer component) | Dropdown menu or popover |
-| Filters/settings | Full-screen sheet or slide-over panel | Side panel or modal |
-
-- **Bottom nav is the default** on mobile. Top nav on `md:` and above.
-- **Bottom sheets over modals** for contextual actions on mobile — they're within thumb reach and feel native.
-- **Sticky action bars**: Form submit buttons, checkout CTAs — `sticky bottom-0` on mobile.
-- **No hamburger menus** for ≤5 items. Use bottom tab bar instead.
-
-### BottomNav Overlap — Fixed Bottom Elements
-
-When a page has its own `fixed bottom-0` element (e.g., sticky order bar, floating CTA), it **will be hidden behind BottomNav** on mobile. The BottomNav is `fixed bottom-0 z-50` with a height of `4rem` (64px).
-
-**Define the CSS variable** in the BottomNav component:
-```css
-:root {
-  --bottom-nav-height: 4rem;
-}
-```
-
-**Every fixed bottom element on a page** must offset itself above BottomNav on mobile:
-```
-bottom-[var(--bottom-nav-height)] md:bottom-0
-```
-Or the shorthand equivalent:
-```
-bottom-16 md:bottom-0
-```
-
-This is not optional — without it, BottomNav covers the element and users cannot tap it on mobile.
-
----
-
-## Images
-
-- **Format priority**: AVIF > WebP > JPEG (Next.js `<Image>` handles this).
-- **LCP image**: Always add `priority` prop.
-- **Blur placeholder**: Use `placeholder="blur"` with `blurDataURL`.
-- **Always set** explicit `width`/`height` or use `aspect-ratio` to prevent CLS.
-
----
-
-## Modern CSS Features (Use Where Appropriate)
-
-| Feature | Use for |
-|---|---|
-| `@container` | Component-level responsive behavior |
-| CSS Subgrid | Child alignment with parent grid |
-| `dvh` | Full-height layouts (avoids mobile browser bar) |
-| `<dialog>` | Modals (with glassmorphism backdrop) |
-| Popover API | Dropdowns, tooltips |
-| `:has()` | Parent-based styling without JS |
-| `content-visibility: auto` | Long lists/pages performance |
-| `@starting-style` | Entry animations |
-
----
-
-## Component Visual Patterns
-
-- **Cards**: `rounded-xl border border-border/50 bg-card shadow-sm transition-all duration-300 active:scale-[0.98] md:hover:shadow-md md:hover:-translate-y-0.5`
-- **Empty states**: Centered, muted icon, 2-line text max, one clear CTA.
-- **Loading**: Skeleton loaders matching content shape. Show immediately, no delay.
-- **Modals (desktop)**: Max `max-w-lg`. Dismissible with Escape + backdrop click. Glassmorphism backdrop.
-- **Bottom sheets (mobile)**: Prefer over centered modals on mobile. Use shadcn Drawer (Vaul). Swipe-down to dismiss. Max 70% viewport height for partial sheets. Respect `pb-[env(safe-area-inset-bottom)]`.
-- **Lists**: Full-width on mobile (no horizontal padding on list items — let them bleed to edges for native feel). Add dividers with `border-b border-border/50`.
-
----
-
-## Dark Mode
-
-- Use `next-themes` with `attribute="class"`, `defaultTheme="light"`.
-- Smooth transitions handled by the global CSS transition rules in `globals.css` — do NOT add `disableTransitionOnChange` to `ThemeProvider`.
-- Reduce shadow visibility in dark mode (use subtle light borders instead).
-- Consider `brightness-90` on images in dark mode.
-- Add `suppressHydrationWarning` to `<html>` tag.
-- **Hydration guard for conditional theme renders**: `useTheme()` returns `undefined` on the server. Any component that renders *different JSX* based on `theme` (e.g. showing a Sun icon OR a Moon icon — not both) will throw a hydration mismatch. Either render both icons and style the active one (see `components/common/ThemeToggle.tsx`), or add a `mounted` guard: `const [mounted, setMounted] = useState(false); useEffect(() => setMounted(true), []);` and return `null`/a placeholder until `mounted` is true.

package/template/_claude/rules/client/05-security.md

@@ -1,55 +0,0 @@
-> **SCOPE**: These rules apply specifically to the **client** directory (Next.js App Router).
-
-# Security
-
-## Token Storage
-
-- **httpOnly cookies** (`access_token` + `refresh_token`) set by the server via `Set-Cookie` headers.
-- Tokens are **never accessible from JavaScript** — no localStorage, no Redux token state.
-- Axios sends cookies automatically via `withCredentials: true`.
-- `AuthInitializer` hydrates user state on page load by calling `getMe()` (cookie sent automatically).
-- On logout: call logout API endpoint (server clears cookies), dispatch `logout()` action, redirect to `/login`.
-
-## Environment Variables
-
-- **Never prefix secrets with `NEXT_PUBLIC_`** — only public values (API URL, app name) get the prefix.
-- Server-only secrets (DB URL, JWT secret) have no prefix and are only accessible in Server Components / Server Actions.
-- Validate env with Zod at startup.
-
-## File Upload Validation
-
-- Allowed types: `image/jpeg`, `image/png`, `image/webp`
-- Max size: 5MB
-- Validate both MIME type AND file extension.
-
-## Security Headers (`next.config.ts`)
-
-```
-X-Frame-Options: DENY
-X-Content-Type-Options: nosniff
-Referrer-Policy: origin-when-cross-origin
-X-XSS-Protection: 1; mode=block
-```
-
-## Content Security Policy
-
-```
-default-src 'self';
-script-src 'self' 'unsafe-eval' 'unsafe-inline';
-style-src 'self' 'unsafe-inline';
-img-src 'self' blob: data: https: ${apiOrigin};
-font-src 'self';
-object-src 'none';
-base-uri 'self';
-form-action 'self';
-frame-ancestors 'none';
-connect-src 'self' ${NEXT_PUBLIC_API_BASE_URL};
-```
-
-## Rules
-
-1. **Never inject raw HTML** without sanitizing it first (use DOMPurify with allowed tags/attrs).
-2. **Never log sensitive data** (tokens, passwords, full user objects). Dev-only: log IDs at most.
-3. **Validate all inputs** with Zod — client-side (UX) AND server-side (security).
-4. **External links**: Always `target="_blank" rel="noopener noreferrer"`.
-5. **Sanitize URLs**: Only allow `http:`, `https:`, `mailto:` protocols before rendering as links.

package/template/_claude/rules/client/06-ux-checklist.md

@@ -1,111 +0,0 @@
-> **SCOPE**: These rules apply specifically to the **client** directory (Next.js App Router).
-
-# Neuro-UX Checklist
-
-## Mobile-First UX
-
-**80%+ of traffic is mobile. Design for thumbs, not cursors. Every screen must feel like a native app.**
-
-- Every screen must be fully usable on a 375px viewport. No exceptions.
-- **One-handed reachability**: critical actions in the thumb zone (bottom 60% of screen).
-- **App-like feel**: smooth transitions between views, no full-page flash reloads, instant feedback on every tap.
-- **Content above the fold**: the most important action or information visible without scrolling on mobile.
-- **Reduce input friction**: use native input types (`type="tel"`, `type="email"`, `inputMode="numeric"`), autofill, and smart defaults.
-- **Scroll is natural**: long pages are fine on mobile — vertical scroll is free. Horizontal scroll is forbidden.
-
----
-
-## Cognitive Load — Miller's Law
-
-- **Max 5-7 interactive elements** per viewport section. Use progressive disclosure (tabs, accordions, "Show more") for more.
-
-## Gestalt Principles
-
-- **Proximity**: Related items close together. Gap between groups = 2x gap within groups.
-- **Grid alignment**: All elements on a strict grid. No floating/misaligned elements.
-- **Similarity**: Same action = same visual style across all pages.
-- **Common region**: Group related controls in a visual container (`bg-muted/50` or subtle border).
-
-## Instant Feedback
-
-| User action | Required feedback | Timing |
-|---|---|---|
-| Tap interactive | Press state (`active:scale-[0.97]`) | Instant |
-| Tap button | Press state + ripple or scale | Instant |
-| Submit form | Loading state on button + disable | Instant |
-| Successful action | Toast notification | <500ms |
-| Failed action | Inline error OR toast | <500ms |
-| Navigate | Skeleton or smooth page transition | Instant |
-| Swipe drawer/sheet | Follow finger + snap or dismiss | Instant |
-| Pull to refresh | Pull indicator + content reload | Instant |
-| Hover interactive (desktop only) | Color/shadow/scale change | <100ms |
-
-- **Optimistic UI**: Update UI immediately before server confirms. Revert on error.
-- **Skeletons over spinners. Always.** Spinners only inside buttons during submission.
-- **Touch feedback is non-negotiable**: Every tappable element must visually respond to touch immediately.
-
-## Nielsen's 10 Heuristics (Mobile-Adapted)
-
-1. **System status**: Show loading, toast on completion, inline validation as user types. On mobile: progress indicators for multi-step flows.
-2. **Real-world match**: Human language ("Sign in" not "Authenticate"). Locale-formatted dates/currencies. Native input types (`type="email"`, `inputMode="numeric"`).
-3. **User control**: Swipe gestures for dismiss/back. Bottom sheets dismissible by swipe-down. Every modal dismissible with Escape (desktop) + backdrop + swipe (mobile). Undo for destructive actions. Back always works — preserve scroll position on back navigation.
-4. **Consistency**: Same action = same button style, position, label everywhere. Bottom nav consistent across all pages on mobile.
-5. **Error prevention**: Real-time validation. Disable submit until valid. Type-appropriate inputs with correct keyboard (`inputMode`). Confirm destructive actions with bottom sheet confirmation on mobile.
-6. **Recognition > recall**: Visible labels (not placeholder-only). Show recent searches. Bottom nav on mobile, top nav on desktop.
-7. **Flexibility**: Keyboard shortcuts (Cmd+K) on desktop. Gesture shortcuts (swipe actions on list items) on mobile. Preserve filters in URL. Bulk actions where appropriate.
-8. **Minimalist design**: Every element earns its place. Prefer whitespace over separators. On mobile: even more aggressive — reduce to one primary action per screen.
-9. **Error recovery**: Say what went wrong + how to fix it. Highlight the field. Never clear form on error. On mobile: scroll to the first error field automatically.
-10. **Help**: Contextual tooltips (tap-to-show on mobile, hover on desktop). Dismissible onboarding hints.
-
-## Performance Targets
-
-| Metric | Mobile Target | Desktop Target |
-|---|---|---|
-| Lighthouse Performance | 90+ | 98+ |
-| Lighthouse Accessibility | 98+ | 98+ |
-| LCP | <2.5s | <2.0s |
-| CLS | 0 | 0 |
-| INP | <150ms | <200ms |
-
-- **Test on real mobile devices** or throttled Chrome DevTools (4x CPU slowdown, Fast 3G).
-- **Bundle size matters more on mobile**: lazy-load routes, code-split aggressively, defer non-critical JS.
-
-## Accessibility
-
-- All interactive elements reachable via Tab in logical order.
-- Focus rings: `:focus-visible` only (not `:focus`). Style: `ring-2 ring-primary/50`.
-- Icon-only buttons: must have `aria-label`.
-- One `h1` per page. No skipped heading levels.
-- Dynamic content updates: `aria-live="polite"`.
-- All animations in `motion-safe:` variant.
-- WCAG AA contrast: 4.5:1 for text, 3:1 for large text/UI.
-- **Touch targets**: min 44x44px, recommended 48x48px. No exceptions.
-- **Spacing between touch targets**: min 8px gap to prevent mis-taps.
-- **No hover-only functionality**: everything accessible via tap on mobile.
-
-## Microcopy
-
-- **Buttons**: Action verbs — "Save changes", "Create item", "Delete account". Never "Submit" or "OK".
-- **Toasts**: Under 10 words. Success: confirm. Error: what happened + what to do.
-- **Empty states**: Explain what this area is for + CTA to fill it. ("No items yet. Create your first one.")
-- **Form errors**: Specific to the field. Below the field. Red text + red border.
-
-## Page Audit Checklist
-
-1. Interactive elements per section ≤ 7?
-2. All elements on grid?
-3. Every button/link has active + focus-visible? (hover is `md:` only)
-4. Skeletons for all async content?
-5. Inline field-level errors on forms?
-6. Every modal/sheet dismissible with Escape (desktop) + swipe (mobile)?
-7. Tab through all elements in logical order?
-8. Text passes WCAG AA contrast?
-9. All animation in `motion-safe:`?
-10. LCP image has `priority`?
-11. All touch targets ≥ 44x44px?
-12. Primary actions in thumb zone (bottom of screen)?
-13. Bottom sheet used instead of centered modal on mobile?
-14. Tested on 375px viewport width?
-15. No hover-only functionality?
-16. Safe areas respected on fixed/sticky elements?
-17. Native input types used (`type="email"`, `inputMode="numeric"`, etc.)?

package/template/_claude/rules/client/07-deployment.md

@@ -1,99 +0,0 @@
-> **SCOPE**: These rules apply specifically to the **client** directory (Next.js App Router).
-
-# Deployment & Docker
-
-This project is deployed via **Docker** on **Coolify** (or any Docker-based platform). The `Dockerfile` is the production deployment contract. Every code change must remain compatible with it.
-
----
-
-## Dockerfile Architecture
-
-The client uses a **3-stage multi-stage build** with Next.js `standalone` output:
-
-```
-Stage 1 (dependencies)  → Installs all node_modules (cached layer)
-Stage 2 (builder)        → Copies deps, builds Next.js with standalone output
-Stage 3 (production)     → Alpine + dumb-init, non-root user, copies standalone + static + public
-```
-
-**Entry point**: `node server.js` (generated by Next.js standalone output in `.next/standalone/`)
-**Health check**: `GET /` — returns 200 if the Next.js server is running.
-
-### Critical Config Requirement
-
-`next.config.ts` **must** have `output: "standalone"`. Without it, the Dockerfile will fail because `.next/standalone/` won't be generated. Never remove this setting.
-
----
-
-## Build Arguments (NEXT_PUBLIC_* Variables)
-
-Next.js **inlines** all `NEXT_PUBLIC_*` values into the JavaScript bundle at build time. They are NOT read from the environment at runtime. This means:
-
-- Every `NEXT_PUBLIC_*` variable must be declared as `ARG` + `ENV` in the **builder stage** of the Dockerfile.
-- They must be passed via `--build-arg` during `docker build` (or via Coolify's Build Arguments UI).
-- **If you add a new `NEXT_PUBLIC_*` env var, you MUST add it to the Dockerfile builder stage.**
-
-```dockerfile
-# In the builder stage:
-ARG NEXT_PUBLIC_NEW_VAR
-ENV NEXT_PUBLIC_NEW_VAR=$NEXT_PUBLIC_NEW_VAR
-```
-
-Current build arguments:
-- `NEXT_PUBLIC_API_BASE_URL` — Backend API URL (e.g., `https://api.yourdomain.com/api/v1`)
-- `NEXT_PUBLIC_APP_NAME` — App display name
-
----
-
-## When to Update the Dockerfile
-
-| You did this... | Update Dockerfile? | What to change |
-|---|---|---|
-| Added a new npm dependency | No | Automatic — installed during build |
-| Added a native/system dependency (e.g., `sharp` for image optimization) | **Yes** | Add `apk add` in the production stage |
-| Added a new `NEXT_PUBLIC_*` env var | **Yes** | Add `ARG` + `ENV` in the builder stage |
-| Changed the public directory structure | No | Automatic — `COPY /app/public ./public` |
-| Added server-only env vars (no `NEXT_PUBLIC_` prefix) | No | Injected at runtime via Coolify |
-| Changed the default port | **Yes** | Update `ENV PORT`, `EXPOSE`, and `HEALTHCHECK` |
-| Added custom `next.config.ts` rewrites/redirects | No | Baked into the build automatically |
-| Added API routes (`app/api/`) | No | Included in standalone output |
-| Removed `output: "standalone"` from next.config.ts | **BREAKING** | Entire Dockerfile depends on standalone output |
-
----
-
-## Critical Rules
-
-1. **Never remove `output: "standalone"`** from `next.config.ts`. The entire Docker build depends on it. Without it, the standalone server won't be generated and the Dockerfile will fail.
-
-2. **Every `NEXT_PUBLIC_*` var needs a Dockerfile `ARG`.** Next.js inlines these at build time. If you add one to `.env.example` but forget the Dockerfile, the value will be `undefined` in production.
-
-3. **Static assets and public files are separate.** The standalone output does NOT include `.next/static/` or `public/`. The Dockerfile copies them explicitly. If you add a new top-level directory that must be available at runtime (unlikely), add a `COPY` line.
-
-4. **Non-root user.** The app runs as `nextjs:nodejs` (UID 1001). Next.js standalone doesn't write to disk at runtime, so this is straightforward.
-
-5. **No secrets in the image.** Server-only env vars (without `NEXT_PUBLIC_` prefix) are injected at runtime. Never hardcode secrets or use `ENV` for sensitive values in the Dockerfile.
-
-6. **Keep `.dockerignore` in sync.** When adding directories that should NOT be in the build context (test fixtures, docs, Storybook), add them to `.dockerignore`. When adding files needed at build time, ensure they're not ignored.
-
-7. **`HOSTNAME="0.0.0.0"`** is required. Without it, Next.js standalone only listens on `127.0.0.1` inside the container, making it unreachable from outside.
-
----
-
-## Coolify-Specific Notes
-
-- **Build Arguments**: Set `NEXT_PUBLIC_API_BASE_URL` and `NEXT_PUBLIC_APP_NAME` in Coolify's "Build Arguments" section (not environment variables — those are runtime only).
-- **Environment Variables**: Server-only vars (database URLs, API keys used in Server Components/Route Handlers) go in Coolify's "Environment Variables" section — available at runtime.
-- **Port**: Default `3000`. Override via `PORT` environment variable in Coolify.
-- **No volume mounts needed**: Next.js client apps are stateless — no uploads, no local file writes.
-
----
-
-## Files That Matter for Deployment
-
-| File | Purpose | Must exist? |
-|---|---|---|
-| `Dockerfile` | Production build instructions | Yes |
-| `.dockerignore` | Excludes files from Docker build context | Yes |
-| `next.config.ts` | Must have `output: "standalone"` | Yes |
-| `package.json` | Dependencies and build script | Yes |
-| `public/` | Static assets (favicon, images) | Yes |