@reinvented/design 1.0.0 → 1.1.0

package/skills/foundation/rules.md

@@ -0,0 +1,54 @@
+# Rules (Non-Negotiable)
+
+These rules must NEVER be violated. Any output that breaks these rules is rejected.
+
+## Component Rules
+
+1. **No raw `<button>`** — use `<Button>` from `@reinvented/design`
+2. **No raw `<input>`** — use `<Input>` from `@reinvented/design`
+3. **No raw `<select>`** — use `<Select>` from `@reinvented/design`
+4. **No raw `<textarea>`** — use `<Textarea>` from `@reinvented/design`
+5. **No `alert()`, `confirm()`, `prompt()`** — use `<Dialog>`, `<AlertDialog>`, or `toast()`
+6. **No raw `<table>`** — use `<Table>` and its subcomponents
+
+## Styling Rules
+
+7. **No hardcoded colors** — no `#333`, no `rgb(...)`, no `text-gray-500`. Use token classes: `text-foreground`, `text-muted-foreground`, `bg-primary`, `bg-card`, `border-border`, etc.
+8. **No arbitrary Tailwind values** — no `text-[#333]`, `p-[13px]`, `w-[347px]`. Use the spacing scale: `p-4`, `gap-6`. Use named sizes for widths: `max-w-md`, `max-w-7xl`.
+9. **No inline styles** — all styling through Tailwind utility classes. Exception in mockup mode: CSS gradients used as image replacements.
+10. **No `@apply` blocks** — compose utility classes directly in templates.
+
+## Icon Rules
+
+11. **No emojis** — use Lucide icons from `lucide-react` exclusively.
+12. **Icon sizing standard**: `w-4 h-4` in buttons/inline, `w-5 h-5` in navigation, `w-8 h-8` or `w-12 h-12` in empty states.
+
+## Composition Rules
+
+13. **Items always inside groups**: `<SelectItem>` must be wrapped in `<SelectGroup>`, `<DropdownMenuItem>` in `<DropdownMenuGroup>`, and `<ContextMenuItem>` in `<ContextMenuGroup>`.
+14. **Tabs structure**: `<TabsTrigger>` MUST be wrapped inside `<TabsList>`. Never place a trigger directly inside `<Tabs>`.
+15. **Overlays require titles**: `<Dialog>`, `<Sheet>`, and `<Drawer>` must always contain their respective title (`<DialogTitle>`, etc.) inside their Header components. Use `className="sr-only"` if it should be visually hidden.
+16. **Cards use full structure**: Never place content directly inside `<Card>`. Always use `<CardHeader>` and `<CardContent>`.
+17. **Use primitives for layout**: Use `<Separator>` instead of `<hr>` or border divs. Use `<Badge>` instead of rounded colorful spans.
+18. **Avatars require fallbacks**: Always include `<AvatarFallback>` alongside `<AvatarImage>`.
+
+## Layout Rules
+
+19. **No horizontal scrolling** on any viewport.
+20. **44px minimum touch targets** on mobile.
+21. **No custom scrollbar styling** — use `<ScrollArea>` from the DS.
+22. **Page content max width**: `max-w-7xl mx-auto` (1280px).
+23. **Page-level spacing**: Always use `space-y-6` for page-level vertical rhythm. Do not exceed `gap-6` or `space-y-6` for structural gaps.
+24. **No nested scrolling (scrolling within scrolling)**: This is a terrible UX pattern. If a specific section like a sidebar or Kanban column requires its own `<ScrollArea>`, the main parent page MUST be fixed height without scrolling (e.g., `h-[100dvh] overflow-hidden`). Otherwise, let the whole page scroll naturally and omit the inner `ScrollArea`s.
+
+## State Rules
+
+24. **Every view must handle**: loading state, empty state, error state, data state.
+25. **Every mutation button**: shows a `<Loader2>` spinner icon and is `:disabled` during the request.
+26. **Every list**: has an empty state with descriptive text and a primary CTA button.
+
+## Import Rules
+
+27. **Always import DS components** from `@reinvented/design` — this is the primary source for all UI components, `cn()`, and `toast`.
+28. **Always import icons** from `lucide-react`.
+29. You may use react-router-dom, pinia, data fetching libraries, chart libraries, etc., alongside standard UI components.

package/skills/foundation/tailwind-usage.md

@@ -0,0 +1,204 @@
+# Tailwind CSS Usage
+
+This design system uses Tailwind CSS with custom theme tokens. All styling is done through utility classes in templates.
+
+## About Numeric Classes
+
+In Tailwind, numeric utility classes (`gap-4`, `p-6`, `w-64`) **are** the design tokens — they map to a consistent 4px base scale. `gap-4` = 16px is semantically "the standard item gap" just as `gap-6` = 24px is "the standard section gap." These numbers are NOT arbitrary — they're the spacing system.
+
+**What IS bad practice**: arbitrary values via bracket notation (`w-[347px]`, `p-[13px]`). These break the spacing scale. Never use them.
+
+**Prefer `size-*` over `w-* h-*`**: For equal width and height (like icons, avatars, fixed squares), always use the `size-*` utility instead of separate width and height classes. `size-4` is preferred over `w-4 h-4`.
+
+**Prefer `gap-*` over margin between siblings**: When building flex or grid layouts, always use `gap-*` for spacing between elements. Avoid using `space-x-*` or direct margin utilities (`ml-2`) between siblings. `space-y-*` is acceptable ONLY for macro document flow (like `space-y-6` between major sections).
+
+**Prefer named sizes where available**: For max-widths, Tailwind provides semantic names that are more readable:
+
+| Named Size | Pixels | When to Use |
+|-----------|--------|-------------|
+| `max-w-sm` | 384px | Auth cards, small dialogs |
+| `max-w-md` | 448px | Standard forms, dialogs |
+| `max-w-lg` | 512px | Large forms, content panels |
+| `max-w-xl` | 576px | Complex dialogs |
+| `max-w-2xl` | 672px | Wide content areas |
+| `max-w-3xl` | 768px | Narrow page content (portfolio, blog) |
+| `max-w-4xl` | 896px | Settings pages |
+| `max-w-5xl` | 1024px | Marketing pages |
+| `max-w-7xl` | 1280px | Standard page content container |
+
+For container widths, always prefer named sizes (`max-w-md`, `max-w-7xl`) over numeric widths (`w-96`, `w-80`). For internal component dimensions like sidebar width (`w-64` = 256px), the numeric form is standard and correct.
+
+## The `cn()` Utility
+
+Use `cn()` (imported from `@reinvented/design`) to merge classes conditionally:
+
+```ts
+import { cn } from '@reinvented/design'
+
+// Conditional classes
+className={cn('flex items-center gap-2', isActive && 'bg-accent', className)}
+```
+
+## Common Class Patterns
+
+### Page Container
+```html
+<div className="max-w-7xl mx-auto px-6 py-8">
+```
+Centers content with a 1280px max width and consistent padding.
+
+### Page Header
+```tsx
+<!-- Always use the explicit PageHeader components instead of raw divs -->
+<PageHeader>
+  <PageHeaderHeading>
+    <PageHeaderTitle>Page Title</PageHeaderTitle>
+    <PageHeaderDescription>Description of this page.</PageHeaderDescription>
+  </PageHeaderHeading>
+  <PageHeaderActions>
+    <Button>Primary Action</Button>
+  </PageHeaderActions>
+</PageHeader>
+```
+
+### Section Stack
+```html
+<div className="space-y-6">
+  <!-- Section 1 -->
+  <!-- Section 2 -->
+  <!-- Section 3 -->
+</div>
+```
+Uses `space-y-6` for consistent vertical spacing between major sections.
+
+### Grid Layouts
+```html
+<!-- Equal columns -->
+<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
+
+<!-- Stat cards (4 columns on desktop) -->
+<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4">
+
+<!-- Asymmetric (main + sidebar) -->
+<div className="grid grid-cols-1 lg:grid-cols-3 gap-6">
+  <div className="lg:col-span-2"><!-- Main --></div>
+  <div><!-- Sidebar --></div>
+</div>
+```
+
+### Flexbox Patterns
+```html
+<!-- Horizontal layout with spacing -->
+<div className="flex items-center gap-3">
+
+<!-- Space between (header with action) -->
+<div className="flex items-center justify-between">
+
+<!-- Vertical stack -->
+<div className="flex flex-col gap-2">
+
+<!-- Push item to the right -->
+<div className="flex items-center gap-3">
+  <span>Left content</span>
+  <span className="ml-auto">Right content</span>
+</div>
+```
+
+### Interactive States
+```html
+<!-- Hoverable card -->
+className="cursor-pointer transition-colors hover:bg-accent/50"
+
+<!-- Hoverable list row -->
+className="flex items-center gap-3 px-3 py-2 rounded-md transition-colors hover:bg-accent cursor-pointer"
+
+<!-- Active/selected state -->
+className="bg-accent font-medium"
+
+<!-- Disabled state -->
+className="opacity-50 pointer-events-none"
+```
+
+### Text Truncation
+```html
+<!-- Single line truncate -->
+<span className="truncate">Long text that might overflow</span>
+
+<!-- Multi-line clamp -->
+<p className="line-clamp-2">Text that wraps to maximum 2 lines</p>
+```
+
+### Responsive Patterns
+```html
+<!-- Hide on mobile, show on desktop -->
+className="hidden lg:block"
+
+<!-- Show on mobile, hide on desktop -->
+className="lg:hidden"
+
+<!-- Stack on mobile, row on desktop -->
+className="flex flex-col sm:flex-row gap-4"
+
+<!-- Full width on mobile, fixed on desktop -->
+className="w-full sm:w-auto"
+```
+
+## Anti-Patterns (Do NOT Do These)
+
+```html
+<!-- ❌ Arbitrary values -->
+<div className="p-[13px] w-[347px] text-[#666]">
+
+<!-- ✅ Use token scale -->
+<div className="p-3 w-80 text-muted-foreground">
+```
+
+```html
+<!-- ❌ Inline styles -->
+<div style="color: gray; margin-top: 20px;">
+
+<!-- ✅ Utility classes -->
+<div className="text-muted-foreground mt-5">
+```
+
+```html
+<!-- ❌ Missing gap in flex/grid -->
+<div className="flex items-center">
+  <Icon /><span>Text</span>
+</div>
+
+<!-- ✅ Always specify gap -->
+<div className="flex items-center gap-2">
+  <Icon className="w-4 h-4" /><span>Text</span>
+</div>
+```
+
+```html
+<!-- ❌ Using margin for spacing between siblings -->
+<div className="mt-4">Item 1</div>
+<div className="mt-4">Item 2</div>
+
+<!-- ✅ Use gap or space-y on the parent -->
+<div className="space-y-4">
+  <div>Item 1</div>
+  <div>Item 2</div>
+</div>
+```
+
+```html
+<!-- ❌ Hacking Shadcn structural components -->
+<TabsList className="h-8 p-0 bg-transparent gap-2">
+  <TabsTrigger className="h-7 px-3 text-xs data-[state=active]:bg-warning/20">
+
+<!-- ✅ Use standard composition and let the DS handle internals -->
+<TabsList className="grid w-full grid-cols-2">
+  <TabsTrigger>
+```
+
+```html
+<!-- ❌ Inventing complex custom color variants with opacities -->
+<Badge variant="outline" className="bg-warning/5 text-warning-foreground border-warning/30">
+
+<!-- ✅ Trust the Design System tokens and default variants -->
+<Badge variant="warning">
+```

package/skills/layouts/dashboard.md

@@ -0,0 +1,71 @@
+# Layout: Dashboard
+
+Overview pages with stats, charts, tables, and activity feeds. Use within a sidebar or topbar layout.
+
+## Structure
+
+```tsx
+<div className="space-y-6">
+  <!-- Page header -->
+  <div className="flex items-center justify-between">
+    <div>
+      <h1 className="text-2xl font-bold">Dashboard</h1>
+      <p className="text-muted-foreground">Overview of your workspace.</p>
+    </div>
+    <div className="flex items-center gap-2">
+      <Button variant="outline" size="sm"><CalendarDays className="w-4 h-4" /> Last 30 Days</Button>
+      <Button variant="outline" size="sm"><Download className="w-4 h-4" /> Export</Button>
+    </div>
+  </div>
+
+  <!-- Stats grid: 4 columns on desktop -->
+  <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4">
+    <!-- 4 stat cards (see patterns/dashboards.md) -->
+  </div>
+
+  <!-- Main content: asymmetric 2/3 + 1/3 split -->
+  <div className="grid grid-cols-1 lg:grid-cols-7 gap-6">
+    <Card className="lg:col-span-4">
+      <CardHeader>
+        <CardTitle>Overview</CardTitle>
+        <CardDescription>Revenue for the current year.</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <AreaChart
+          :data="[{ month: 'Jan', total: 1200 }, { month: 'Feb', total: 2100 }]"
+          index="month"
+          :categories="['total']"
+          className="h-72"
+        />
+      </CardContent>
+    </Card>
+    <Card className="lg:col-span-3">
+      <CardHeader>
+        <CardTitle>Recent Activity</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <!-- Activity feed -->
+      </CardContent>
+    </Card>
+  </div>
+
+  <!-- Bottom section: full-width table -->
+  <Card>
+    <CardHeader className="flex flex-row items-center justify-between">
+      <CardTitle>Recent Transactions</CardTitle>
+      <Button variant="ghost" size="sm">View All <ArrowRight className="w-4 h-4" /></Button>
+    </CardHeader>
+    <CardContent className="p-0">
+      <!-- Table -->
+    </CardContent>
+  </Card>
+</div>
+```
+
+## Grid Proportions
+
+| Content Pair | Grid Setup |
+|-------------|------------|
+| Chart + sidebar | `lg:grid-cols-7` → `lg:col-span-4` + `lg:col-span-3` |
+| Equal halves | `lg:grid-cols-2` |
+| Main + narrow | `lg:grid-cols-3` → `lg:col-span-2` + `lg:col-span-1` |

package/skills/layouts/full-page-form.md

@@ -0,0 +1,75 @@
+# Layout: Full-Page Form
+
+Centered form card or multi-step wizard. Used for auth pages, onboarding, and standalone form flows.
+
+## Centered Card Form
+
+```tsx
+<div className="flex min-h-screen items-center justify-center px-4 bg-background">
+  <Card className="w-full max-w-md">
+    <CardHeader>
+      <CardTitle>Create Account</CardTitle>
+      <CardDescription>Get started with your free account.</CardDescription>
+    </CardHeader>
+    <CardContent>
+      <form className="space-y-4">
+        <div className="grid grid-cols-2 gap-4">
+          <div className="space-y-2">
+            <Label for="firstName">First Name</Label>
+            <Input id="firstName" placeholder="Sarah" />
+          </div>
+          <div className="space-y-2">
+            <Label for="lastName">Last Name</Label>
+            <Input id="lastName" placeholder="Chen" />
+          </div>
+        </div>
+        <div className="space-y-2">
+          <Label for="email">Email</Label>
+          <Input id="email" type="email" placeholder="sarah@example.com" />
+        </div>
+        <div className="space-y-2">
+          <Label for="password">Password</Label>
+          <Input id="password" type="password" />
+        </div>
+      </form>
+    </CardContent>
+    <CardFooter className="flex-col gap-3">
+      <Button type="submit" className="w-full">Create Account</Button>
+      <p className="text-xs text-center text-muted-foreground">
+        Already have an account? <Button variant="link" className="px-1 h-auto text-xs">Sign in</Button>
+      </p>
+    </CardFooter>
+  </Card>
+</div>
+```
+
+## Split Layout (Form + Hero)
+
+For marketing-oriented auth pages:
+
+```tsx
+<div className="flex min-h-screen">
+  <!-- Left: brand/hero panel -->
+  <div className="hidden lg:flex flex-1 bg-gradient-to-br from-primary/20 via-primary/5 to-transparent items-end p-12">
+    <div className="space-y-2">
+      <h2 className="text-2xl font-bold">Build something amazing.</h2>
+      <p className="text-muted-foreground">Join 10,000+ teams shipping faster with our platform.</p>
+    </div>
+  </div>
+  <!-- Right: form -->
+  <div className="flex-1 flex items-center justify-center px-6">
+    <Card className="w-full max-w-sm border-0 shadow-none">
+      <!-- Form content -->
+    </Card>
+  </div>
+</div>
+```
+
+## Key Rules
+- Use `min-h-screen` + `items-center justify-center` for vertical centering
+- Card widths: `max-w-sm` (auth), `max-w-md` (standard form), `max-w-lg` (complex form)
+- Submit button should be `className="w-full"` for full-width emphasis
+- Toggle link (sign in ↔ sign up) below the submit button, `text-xs text-muted-foreground`
+- For 2-column field grids (first + last name), use `grid grid-cols-2 gap-4`
+- For wizards, see `patterns/onboarding.md`
+- Split layout: hero panel on left (`hidden lg:flex`), form on right

package/skills/layouts/list-detail.md

@@ -0,0 +1,70 @@
+# Layout: List-Detail
+
+Master list on one side, detail view on the other. For email, messaging, or any browse-and-inspect workflow.
+
+## Side-by-Side (Desktop)
+
+```tsx
+<div className="flex h-screen">
+  <!-- Sidebar nav (if applicable) -->
+
+  <!-- List panel -->
+  <div className="w-80 border-r flex flex-col shrink-0">
+    <div className="h-14 flex items-center justify-between px-4 border-b">
+      <h2 className="text-sm font-semibold">Inbox</h2>
+      <Button variant="ghost" size="icon" className="h-8 w-8"><Plus className="w-4 h-4" /></Button>
+    </div>
+    <div className="p-2">
+      <div className="relative">
+        <Search className="absolute left-3 top-1/2 -translate-y-1/2 h-4 w-4 text-muted-foreground" />
+        <Input className="pl-9" placeholder="Search..." />
+      </div>
+    </div>
+    <ScrollArea className="flex-1">
+      <div className="space-y-0.5 p-2">
+        <button v-for="item in items" :key="item.id"
+                className={cn(
+                  'w-full text-left p-3 rounded-md transition-colors',
+                  selectedId === item.id ? 'bg-accent' : 'hover:bg-accent/50'
+                )}
+                onClick="selectedId = item.id">
+          <p className="text-sm font-medium truncate">{{ item.title }}</p>
+          <p className="text-xs text-muted-foreground truncate">{{ item.preview }}</p>
+          <p className="text-xs text-muted-foreground mt-1">{{ item.date }}</p>
+        </button>
+      </div>
+    </ScrollArea>
+  </div>
+
+  <!-- Detail panel -->
+  <div className="flex-1 overflow-y-auto">
+    <div v-if="selected" className="max-w-3xl mx-auto px-6 py-8">
+      <!-- Detail content -->
+    </div>
+    <div v-else className="flex items-center justify-center h-full text-muted-foreground">
+      <p className="text-sm">Select an item to view details</p>
+    </div>
+  </div>
+</div>
+```
+
+## Key Details
+
+- **List panel width**: `w-80` (320px) or `w-96` (384px)
+- **List items**: Full-width buttons with text-left alignment
+- **Selected state**: `bg-accent` background
+- **Empty detail state**: Centered message when nothing is selected
+- **Scroll**: List and detail scroll independently (`ScrollArea` + `overflow-y-auto`)
+
+## Drill-Down (Alternative)
+
+Instead of side-by-side, navigate from list → detail page:
+- List view: Card grid or stacked list (see `patterns/content-display.md`)
+- Detail view: Full-page detail with back button (see `patterns/content-display.md`)
+
+## When to Use
+
+| Pattern | Best For |
+|---------|----------|
+| Side-by-side | Email, messaging, task lists (frequent switching) |
+| Drill-down | Products, projects, articles (focused viewing) |

package/skills/layouts/marketing.md

@@ -0,0 +1,70 @@
+# Layout: Marketing / Landing Page
+
+Hero sections, feature grids, CTA blocks, and footer for marketing pages.
+
+## Structure
+
+```tsx
+<div className="min-h-screen bg-background">
+  <!-- Nav (see layouts/topbar.md) -->
+
+  <!-- Hero -->
+  <section className="max-w-5xl mx-auto px-6 py-24 text-center">
+    <Badge variant="secondary" className="mb-4">Now in Beta</Badge>
+    <h1 className="text-4xl sm:text-5xl font-bold tracking-tight mb-4">
+      Build beautiful interfaces<br />with confidence
+    </h1>
+    <p className="text-lg text-muted-foreground max-w-2xl mx-auto mb-8">
+      A complete design system for Vue 3 that helps you ship polished UIs faster than ever before.
+    </p>
+    <div className="flex items-center justify-center gap-3">
+      <Button size="lg">Get Started</Button>
+      <Button variant="outline" size="lg">View Demo</Button>
+    </div>
+  </section>
+
+  <!-- Features Grid -->
+  <section className="max-w-5xl mx-auto px-6 py-16">
+    <div className="text-center mb-12">
+      <h2 className="text-2xl font-bold mb-2">Everything you need</h2>
+      <p className="text-muted-foreground">Thoughtfully designed components for every use case.</p>
+    </div>
+    <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-6">
+      <Card v-for="feature in features" :key="feature.title">
+        <CardHeader>
+          <div className="w-10 h-10 rounded-lg bg-primary/10 flex items-center justify-center mb-2">
+            <component :is="feature.icon" className="w-5 h-5 text-primary" />
+          </div>
+          <CardTitle className="text-lg">{{ feature.title }}</CardTitle>
+          <CardDescription>{{ feature.description }}</CardDescription>
+        </CardHeader>
+      </Card>
+    </div>
+  </section>
+
+  <!-- CTA -->
+  <section className="max-w-3xl mx-auto px-6 py-16 text-center">
+    <h2 className="text-2xl font-bold mb-2">Ready to get started?</h2>
+    <p className="text-muted-foreground mb-6">Start building beautiful UIs today.</p>
+    <Button size="lg">Start Free Trial</Button>
+  </section>
+
+  <!-- Footer -->
+  <footer className="border-t">
+    <div className="max-w-5xl mx-auto px-6 py-8 flex items-center justify-between text-sm text-muted-foreground">
+      <p>© 2024 Acme Inc. All rights reserved.</p>
+      <div className="flex items-center gap-4">
+        <a href="#" className="hover:text-foreground transition-colors">Privacy</a>
+        <a href="#" className="hover:text-foreground transition-colors">Terms</a>
+      </div>
+    </div>
+  </footer>
+</div>
+```
+
+## Key Rules
+- **Narrow max width**: `max-w-5xl` (not 7xl) for marketing — improves readability
+- **Generous vertical padding**: `py-16` to `py-24` between sections
+- **Center-aligned text**: Hero and CTA sections are centered
+- **Feature icons**: Use `bg-primary/10` with `text-primary` icon for the tinted icon box pattern
+- **Button hierarchy**: Primary CTA first, outline secondary CTA second

package/skills/layouts/responsive.md

@@ -0,0 +1,67 @@
+# Layout: Responsive Behavior
+
+How layouts adapt across viewport sizes.
+
+## Breakpoints
+
+| Name | Min Width | Tailwind Prefix | Typical Behavior |
+|------|-----------|----------------|------------------|
+| Mobile | 0 | (default) | Single column, stacked, full-width |
+| sm | 640px | `sm:` | Two-column grids possible |
+| md | 768px | `md:` | Navigation visible, side panels |
+| lg | 1024px | `lg:` | Full multi-column layouts, sidebars |
+| xl | 1280px | `xl:` | Max-width containers fully visible |
+
+## Common Responsive Patterns
+
+### Grid Columns
+```html
+className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4"
+className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4"  <!-- Stat cards -->
+```
+
+### Sidebar Visibility
+```html
+<!-- Desktop: sidebar visible. Mobile: hidden (use Sheet for mobile nav) -->
+<aside className="hidden lg:flex w-64 border-r flex-col">
+```
+
+### Stack to Row
+```html
+className="flex flex-col sm:flex-row gap-4"
+```
+
+### Hide/Show Elements
+```html
+className="hidden sm:block"   <!-- Hide on mobile -->
+className="sm:hidden"          <!-- Show only on mobile -->
+```
+
+### Content Width
+```html
+<!-- Content respects max-width and has appropriate padding -->
+className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8"
+```
+
+## Mobile Adaptations
+
+1. **Sidebar → Sheet**: Replace sidebar with a hamburger menu that opens a Sheet
+2. **Tables → Card lists**: On mobile, consider replacing tables with stacked cards
+3. **Multi-column grids → Single column**: Everything stacks to `grid-cols-1`
+4. **Horizontal toolbars → Simplified**: Reduce filter options, hide secondary actions
+5. **Touch targets**: All interactive elements ≥ 44px (h-11) tall
+
+## Example: Responsive Page Header
+
+```tsx
+<!-- Desktop: title left, actions right. Mobile: stacked -->
+<div className="flex flex-col sm:flex-row sm:items-center justify-between gap-4">
+  <div>
+    <h1 className="text-2xl font-bold">Projects</h1>
+    <p className="text-muted-foreground">Manage your projects.</p>
+  </div>
+  <div className="flex items-center gap-2">
+    <Button className="w-full sm:w-auto"><Plus className="w-4 h-4" /> New Project</Button>
+  </div>
+</div>
+```