create-tigra 2.1.2 → 2.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-tigra",
-  "version": "2.1.2",
+  "version": "2.1.3",
   "type": "module",
   "description": "Create a production-ready full-stack app with Next.js 16 + Fastify 5 + Prisma + Redis",
   "bin": {

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

@@ -2,9 +2,11 @@
 
 # Design System
 
-## Philosophy: "Neuro-Minimalism"
+## Philosophy: "Mobile-First Neuro-Minimalism"
 
-Clean, airy, "expensive" look inspired by Linear, Vercel, Stripe, Arc. Every visual decision reduces cognitive load.
+**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.
 
 ---
 
@@ -67,6 +69,34 @@ This project uses **Tailwind CSS v4** with **OKLCH color space** and the `@theme
 - `@custom-variant dark` replaces `darkMode: 'class'`
 - No `@layer base { :root { } }` — variables defined directly on `:root`
 
+---
+
+## 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 |
@@ -109,34 +139,41 @@ This project uses **Tailwind CSS v4** with **OKLCH color space** and the `@theme
 ## Typography
 
 - **Font**: Inter v4 (variable) or Geist Sans via `next/font`.
-- **Headings**: `text-wrap: balance`, `leading-tight`. H1: `text-3xl`–`text-4xl`, H2: `text-2xl`.
+- **Headings**: `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**: `space-y-16` between sections, `space-y-6` within.
+- **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 md:px-6 lg:px-8`.
+- **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 `:hover`, `:active`, and `:focus-visible` states.
+Every interactive element MUST have visible `:active` and `:focus-visible` states. `:hover` is a desktop enhancement — never the only feedback.
 
-### Standard Patterns
+### Standard Patterns (Mobile-First)
 ```
-Button:  transition-all duration-200 ease-out hover:brightness-110 active:scale-[0.98]
-Card:    transition-all duration-300 ease-out hover:shadow-lg hover:-translate-y-0.5
-Link:    transition-colors duration-150 hover:text-primary
+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.
@@ -144,6 +181,45 @@ Link:    transition-colors duration-150 hover:text-primary
 
 ---
 
+## 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.
+
+---
+
 ## Images
 
 - **Format priority**: AVIF > WebP > JPEG (Next.js `<Image>` handles this).
@@ -170,10 +246,12 @@ Link:    transition-colors duration-150 hover:text-primary
 
 ## Component Visual Patterns
 
-- **Cards**: `rounded-xl border border-border/50 bg-card shadow-sm transition-all duration-300 hover:shadow-md hover:-translate-y-0.5`
+- **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**: Max `max-w-lg`. Dismissible with Escape + backdrop click. Glassmorphism backdrop.
+- **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`.
 
 ---
 

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

@@ -2,6 +2,19 @@
 
 # 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.
@@ -17,38 +30,45 @@
 
 | User action | Required feedback | Timing |
 |---|---|---|
-| Click button | Press state (`active:scale-[0.98]`) | Instant |
+| 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 page transition | Instant |
-| Hover interactive | Color/shadow/scale change | <100ms |
+| 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
+## Nielsen's 10 Heuristics (Mobile-Adapted)
 
-1. **System status**: Show loading, toast on completion, inline validation as user types.
-2. **Real-world match**: Human language ("Sign in" not "Authenticate"). Locale-formatted dates/currencies.
-3. **User control**: Every modal dismissible with Escape + backdrop. Undo for destructive actions. Back always works.
-4. **Consistency**: Same action = same button style, position, label everywhere.
-5. **Error prevention**: Real-time validation. Disable submit until valid. Type-appropriate inputs. Confirm destructive actions.
-6. **Recognition > recall**: Visible labels (not placeholder-only). Show recent searches. Visible nav on desktop.
-7. **Flexibility**: Keyboard shortcuts (Cmd+K). Preserve filters in URL. Bulk actions where appropriate.
-8. **Minimalist design**: Every element earns its place. Prefer whitespace over separators.
-9. **Error recovery**: Say what went wrong + how to fix it. Highlight the field. Never clear form on error.
-10. **Help**: Contextual tooltips on complex features. Dismissible onboarding hints.
+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 | Target |
-|---|---|
-| Lighthouse Performance | 98+ |
-| Lighthouse Accessibility | 98+ |
-| LCP | <2.5s |
-| CLS | 0 |
-| INP | <200ms |
+| 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
 
@@ -59,6 +79,9 @@
 - 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
 
@@ -71,11 +94,18 @@
 
 1. Interactive elements per section ≤ 7?
 2. All elements on grid?
-3. Every button/link has hover + active + focus-visible?
+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 dismissible with Escape?
+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/core.md

@@ -33,10 +33,11 @@ State: Server data (SSR) → Server Components
 
 ## Non-negotiable rules
 
-1. **Server Components by default.** Only add `'use client'` when you need hooks, state, or event handlers.
-2. **Component limits**: Max 250 lines, max 5 props, max 3 JSX nesting levels.
-3. **No hardcoded colors**: Use Tailwind semantic tokens (`bg-primary`, `text-foreground`). Never hex/rgb.
-4. **No inline styles**: Tailwind only. Use `cn()` for conditional classes.
-5. **Import order**: React/Next → third-party → UI → local → hooks → services → types → utils.
-6. **Forms**: Validate with Zod. Always validate client-side AND server-side.
-7. **Security**: Never inject raw HTML without sanitization. Never prefix secrets with `NEXT_PUBLIC_`.
+1. **Mobile-first**: All Tailwind classes start at mobile. Desktop is the enhancement (`md:`, `lg:`). Touch targets min 44x44px. No functionality behind hover-only states.
+2. **Server Components by default.** Only add `'use client'` when you need hooks, state, or event handlers.
+3. **Component limits**: Max 250 lines, max 5 props, max 3 JSX nesting levels.
+4. **No hardcoded colors**: Use Tailwind semantic tokens (`bg-primary`, `text-foreground`). Never hex/rgb.
+5. **No inline styles**: Tailwind only. Use `cn()` for conditional classes.
+6. **Import order**: React/Next → third-party → UI → local → hooks → services → types → utils.
+7. **Forms**: Validate with Zod. Always validate client-side AND server-side.
+8. **Security**: Never inject raw HTML without sanitization. Never prefix secrets with `NEXT_PUBLIC_`.