@reinvented/design 1.0.0 → 1.1.0

package/skills/patterns/data-tables.md

@@ -0,0 +1,113 @@
+# Pattern: Data Tables
+
+Complete table layouts with toolbar, search, filters, sorting indicators, pagination, and row actions.
+
+## Standard Data Table
+
+```tsx
+<Card>
+  <!-- Toolbar -->
+  <CardHeader className="pb-4">
+    <div className="flex items-center justify-between">
+      <CardTitle>Team Members</CardTitle>
+      <Button size="sm"><Plus className="w-4 h-4" /> Add Member</Button>
+    </div>
+    <div className="flex items-center gap-3 mt-3">
+      <div className="relative flex-1 max-w-sm">
+        <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 members..." defaultValue="search" />
+      </div>
+      <Select defaultValue="roleFilter">
+        <SelectTrigger className="w-36">
+          <SelectValue placeholder="All Roles" />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="all">All Roles</SelectItem>
+          <SelectItem value="admin">Admin</SelectItem>
+          <SelectItem value="member">Member</SelectItem>
+        </SelectContent>
+      </Select>
+    </div>
+  </CardHeader>
+  <!-- Table -->
+  <CardContent className="p-0">
+    <Table>
+      <TableHeader>
+        <TableRow>
+          <TableHead className="pl-6">Member</TableHead>
+          <TableHead>Role</TableHead>
+          <TableHead>Status</TableHead>
+          <TableHead className="text-right">Last Active</TableHead>
+          <TableHead className="w-10 pr-6"></TableHead>
+        </TableRow>
+      </TableHeader>
+      <TableBody>
+        <TableRow v-for="member in members" :key="member.id">
+          <!-- Avatar + name + email in first column -->
+          <TableCell className="pl-6">
+            <div className="flex items-center gap-3">
+              <div className="w-8 h-8 rounded-full shrink-0 flex items-center justify-center text-xs font-medium bg-muted text-muted-foreground">
+                {{ member.name.split(' ').map(n => n[0]).join('') }}
+              </div>
+              <div className="min-w-0">
+                <p className="text-sm font-medium truncate">{{ member.name }}</p>
+                <p className="text-xs text-muted-foreground">{{ member.email }}</p>
+              </div>
+            </div>
+          </TableCell>
+          <TableCell className="text-sm">{{ member.role }}</TableCell>
+          <TableCell>
+            <Badge :variant="member.status === 'active' ? 'default' : 'secondary'">{{ member.status }}</Badge>
+          </TableCell>
+          <TableCell className="text-right text-sm text-muted-foreground">{{ member.lastActive }}</TableCell>
+          <TableCell className="pr-6">
+            <DropdownMenu>
+              <DropdownMenuTrigger as-child>
+                <Button variant="ghost" size="icon" className="h-8 w-8">
+                  <MoreHorizontal className="w-4 h-4" />
+                </Button>
+              </DropdownMenuTrigger>
+              <DropdownMenuContent align="end">
+                <DropdownMenuItem><Pencil className="w-4 h-4" /> Edit</DropdownMenuItem>
+                <DropdownMenuSeparator />
+                <DropdownMenuItem className="text-destructive"><Trash2 className="w-4 h-4" /> Remove</DropdownMenuItem>
+              </DropdownMenuContent>
+            </DropdownMenu>
+          </TableCell>
+        </TableRow>
+      </TableBody>
+    </Table>
+  </CardContent>
+  <!-- Pagination -->
+  <CardFooter className="justify-between border-t py-3">
+    <p className="text-sm text-muted-foreground">Showing 1–10 of 47 members</p>
+    <div className="flex items-center gap-2">
+      <Button variant="outline" size="sm" disabled><ChevronLeft className="w-4 h-4" /></Button>
+      <Button variant="outline" size="sm"><ChevronRight className="w-4 h-4" /></Button>
+    </div>
+  </CardFooter>
+</Card>
+```
+
+## Key Structural Rules
+
+1. **Wrap table in Card** — `CardContent` gets `className="p-0"` to let the table bleed edge-to-edge.
+2. **Cell Alignment** — Because the `CardHeader` has 24px padding (`p-6`) and `Table` cells default to 16px (`p-4`), you must add `className="pl-6"` to the first `TableHead`/`TableCell` and `className="pr-6"` to the last `TableHead`/`TableCell` so the table visually aligns with the header above it.
+3. **Toolbar in CardHeader** — search + filters above the table, primary action button top-right.
+4. **Pagination in CardFooter** — results count left, page controls right, separated by `border-t`.
+5. **First column is the identifier** — always name/title with `font-medium`, often with avatar.
+6. **Last column is actions** — `w-10` header, three-dot DropdownMenu.
+7. **5–8 rows for mockups** — enough to feel real, not so many it's overwhelming.
+
+## Bulk Actions
+
+When the table supports multi-select, show a floating action bar:
+
+```tsx
+<div v-if="selectedCount > 0" className="flex items-center gap-3 px-4 py-2 bg-muted rounded-md">
+  <p className="text-sm font-medium">{{ selectedCount }} selected</p>
+  <Separator orientation="vertical" className="h-4" />
+  <Button variant="ghost" size="sm">Archive</Button>
+  <Button variant="ghost" size="sm" className="text-destructive">Delete</Button>
+</div>
+```

package/skills/patterns/empty-states.md

@@ -0,0 +1,71 @@
+# Pattern: Empty States
+
+Every empty view must have a well-designed empty state. Never show a blank page.
+
+## Standard Empty State
+
+```tsx
+<div className="flex flex-col items-center justify-center py-16 text-center">
+  <div className="w-12 h-12 rounded-xl bg-muted flex items-center justify-center mb-4">
+    <Inbox className="w-6 h-6 text-muted-foreground" />
+  </div>
+  <h3 className="text-lg font-semibold mb-1">No messages yet</h3>
+  <p className="text-sm text-muted-foreground max-w-sm mb-4">
+    When you receive messages, they'll appear here. Start a conversation to get going.
+  </p>
+  <Button>
+    <Plus className="w-4 h-4" /> New Message
+  </Button>
+</div>
+```
+
+## Required Elements
+
+Every empty state needs all four:
+
+1. **Icon** — A relevant Lucide icon in a muted background container (`w-12 h-12 rounded-xl bg-muted`)
+2. **Title** — Clear, specific headline (`text-lg font-semibold`)
+3. **Description** — Explains what goes here and how to get started (`text-sm text-muted-foreground max-w-sm`)
+4. **CTA Button** — Primary action to create the first item
+
+## Context-Specific Examples
+
+### Empty Table
+```tsx
+<TableRow>
+  <TableCell :colspan="columnCount" className="h-48">
+    <div className="flex flex-col items-center justify-center text-center">
+      <div className="w-12 h-12 rounded-xl bg-muted flex items-center justify-center mb-4">
+        <FileX className="w-6 h-6 text-muted-foreground" />
+      </div>
+      <p className="text-sm font-medium mb-1">No results found</p>
+      <p className="text-xs text-muted-foreground">Try adjusting your search or filters.</p>
+    </div>
+  </TableCell>
+</TableRow>
+```
+
+### Empty Search Results
+No CTA button — instead, suggest adjusting the search:
+```tsx
+<div className="flex flex-col items-center justify-center py-12 text-center">
+  <Search className="w-10 h-10 text-muted-foreground mb-4" />
+  <h3 className="text-lg font-semibold mb-1">No results for "{{ query }}"</h3>
+  <p className="text-sm text-muted-foreground">Check your spelling or try different keywords.</p>
+</div>
+```
+
+## Icon Suggestions
+
+| Context | Icon |
+|---------|------|
+| Messages/inbox | `Inbox` or `MessageSquare` |
+| Files/documents | `FileText` or `FolderOpen` |
+| Users/team | `Users` or `UserPlus` |
+| Tasks/projects | `CheckSquare` or `Clipboard` |
+| Search results | `Search` |
+| Products/items | `Package` or `ShoppingBag` |
+| Events/calendar | `Calendar` |
+| Analytics/data | `BarChart3` or `LineChart` |
+| Notifications | `Bell` |
+| Errors | `AlertCircle` or `FileX` |

package/skills/patterns/error-states.md

@@ -0,0 +1,73 @@
+# Pattern: Error States
+
+Error handling UI for queries, mutations, forms, and network issues.
+
+## Page-Level Error
+
+When a data fetch fails and the entire page can't render:
+
+```tsx
+<div className="flex flex-col items-center justify-center py-16 text-center">
+  <div className="w-12 h-12 rounded-xl bg-destructive/10 flex items-center justify-center mb-4">
+    <AlertCircle className="w-6 h-6 text-destructive" />
+  </div>
+  <h3 className="text-lg font-semibold mb-1">Something went wrong</h3>
+  <p className="text-sm text-muted-foreground max-w-sm mb-4">
+    We couldn't load this page. Please try again.
+  </p>
+  <Button variant="outline" onClick="retry">
+    <RefreshCw className="w-4 h-4" /> Try Again
+  </Button>
+</div>
+```
+
+## Inline Error (Alert Banner)
+
+For errors within a page that still has other functional content:
+
+```tsx
+<Alert variant="destructive">
+  <AlertCircle className="h-4 w-4" />
+  <AlertTitle>Failed to load recent activity</AlertTitle>
+  <AlertDescription className="flex items-center justify-between">
+    <span>Please check your connection and try again.</span>
+    <Button variant="outline" size="sm" onClick="retry">Retry</Button>
+  </AlertDescription>
+</Alert>
+```
+
+## Mutation Error (Toast)
+
+For save/create/update/delete failures:
+
+```ts
+try {
+  await saveData()
+  toast.success('Changes saved successfully')
+} catch (error) {
+  toast.error('Failed to save changes', {
+    action: { label: 'Retry', onClick: () => saveData() }
+  })
+}
+```
+
+## Form Validation Errors
+
+```tsx
+<div className="space-y-2">
+  <Label for="email" className="text-destructive">Email</Label>
+  <Input id="email" className="border-destructive focus-visible:ring-destructive" defaultValue="email" />
+  <p className="text-xs text-destructive">Please enter a valid email address.</p>
+</div>
+```
+
+## Decision Tree
+
+```
+What failed?
+├─ Page data fetch → Full-page error state
+├─ Section data fetch → Inline Alert with retry
+├─ Save/update/delete → Toast with retry action
+├─ Form validation → Inline field errors (red border + message)
+├─ Network offline → Banner at top of page
+```

package/skills/patterns/forms.md

@@ -0,0 +1,136 @@
+# Pattern: Forms
+
+Create/edit forms, multi-step wizards, inline editing, and validation patterns.
+
+## Standard Create Form (in Dialog)
+
+For simple entities with ≤5 fields:
+
+```tsx
+<Dialog v-model:open="showCreate">
+  <DialogTrigger as-child>
+    <Button><Plus className="w-4 h-4" /> New Project</Button>
+  </DialogTrigger>
+  <DialogContent className="sm:max-w-md">
+    <DialogHeader>
+      <DialogTitle>Create Project</DialogTitle>
+      <DialogDescription>Add a new project to your workspace.</DialogDescription>
+    </DialogHeader>
+    <form @submit.prevent="handleCreate" className="space-y-4 py-4">
+      <div className="space-y-2">
+        <Label for="name">Name</Label>
+        <Input id="name" defaultValue="form.name" placeholder="My Project" />
+      </div>
+      <div className="space-y-2">
+        <Label for="desc">Description</Label>
+        <Textarea id="desc" defaultValue="form.description" placeholder="What is this project about?" rows="3" />
+      </div>
+      <div className="space-y-2">
+        <Label>Priority</Label>
+        <Select defaultValue="form.priority">
+          <SelectTrigger><SelectValue placeholder="Select priority" /></SelectTrigger>
+          <SelectContent>
+            <SelectItem value="low">Low</SelectItem>
+            <SelectItem value="medium">Medium</SelectItem>
+            <SelectItem value="high">High</SelectItem>
+          </SelectContent>
+        </Select>
+      </div>
+    </form>
+    <DialogFooter>
+      <DialogClose as-child>
+        <Button variant="outline">Cancel</Button>
+      </DialogClose>
+      <Button onClick="handleCreate" :disabled="creating">
+        <Loader2 v-if="creating" className="w-4 h-4 animate-spin" />
+        {{ creating ? 'Creating...' : 'Create Project' }}
+      </Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+## Full-Page Form (Complex)
+
+For forms with 6+ fields or grouped sections:
+
+```tsx
+<div className="max-w-2xl mx-auto px-6 py-8 space-y-8">
+  <div>
+    <Button variant="ghost" size="sm" className="gap-1 mb-4">
+      <ArrowLeft className="w-4 h-4" /> Back
+    </Button>
+    <h1 className="text-2xl font-bold">Create Organization</h1>
+    <p className="text-muted-foreground">Set up your organization details.</p>
+  </div>
+
+  <form @submit.prevent="handleSubmit" className="space-y-8">
+    <!-- Section 1 -->
+    <div className="space-y-4">
+      <h2 className="text-lg font-semibold">Basic Information</h2>
+      <div className="grid grid-cols-1 sm:grid-cols-2 gap-4">
+        <div className="space-y-2">
+          <Label>Organization Name</Label>
+          <Input defaultValue="form.name" />
+        </div>
+        <div className="space-y-2">
+          <Label>Website (optional)</Label>
+          <Input defaultValue="form.website" placeholder="https://" />
+        </div>
+      </div>
+      <div className="space-y-2">
+        <Label>Description</Label>
+        <Textarea defaultValue="form.description" rows="3" />
+      </div>
+    </div>
+
+    <Separator />
+
+    <!-- Section 2 -->
+    <div className="space-y-4">
+      <h2 className="text-lg font-semibold">Settings</h2>
+      <!-- More fields -->
+    </div>
+
+    <!-- Actions (sticky or at bottom) -->
+    <div className="flex items-center justify-end gap-2 pt-4 border-t">
+      <Button variant="outline" type="button">Cancel</Button>
+      <Button type="submit" :disabled="saving">
+        <Loader2 v-if="saving" className="w-4 h-4 animate-spin" />
+        {{ saving ? 'Creating...' : 'Create Organization' }}
+      </Button>
+    </div>
+  </form>
+</div>
+```
+
+## Edit Form
+
+Same structure as create, but pre-filled with existing data and using "Save Changes" as the submit label.
+
+## Inline Edit
+
+For single-field updates:
+
+```tsx
+<div className="flex items-center gap-2 group">
+  <p v-if="!editing" className="text-sm" onClick="editing = true">
+    {{ value }}
+  </p>
+  <Input v-else defaultValue="value" @blur="save" @keyup.enter="save" className="h-7 text-sm" autofocus />
+  <Button v-if="!editing" variant="ghost" size="icon" className="h-6 w-6 opacity-0 group-hover:opacity-100"
+          onClick="editing = true">
+    <Pencil className="w-3 h-3" />
+  </Button>
+</div>
+```
+
+## Decision Tree
+
+```
+How many fields?
+├─ 1 field → Inline edit (click-to-edit)
+├─ 2–5 fields → Dialog
+├─ 6–8 fields → Full-page form with sections
+├─ 9+ fields or rich content → Full-page form with section nav
+```

package/skills/patterns/loading-states.md

@@ -0,0 +1,92 @@
+# Pattern: Loading States
+
+Skeleton placeholders, spinners, and progressive loading patterns.
+
+## Skeleton Loading (Preferred)
+
+Skeletons replace content with gray shapes that match the content's layout. They signal that content is loading without a jarring spinner.
+
+### Page with Stat Cards + Table
+```tsx
+<!-- Stat card skeletons -->
+<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4">
+  <Card v-for="i in 4" :key="i">
+    <CardHeader className="pb-2">
+      <Skeleton className="h-4 w-24" />
+    </CardHeader>
+    <CardContent>
+      <Skeleton className="h-7 w-20 mb-1" />
+      <Skeleton className="h-3 w-32" />
+    </CardContent>
+  </Card>
+</div>
+
+<!-- Table skeleton -->
+<Card>
+  <CardHeader>
+    <Skeleton className="h-5 w-32" />
+  </CardHeader>
+  <CardContent className="space-y-3">
+    <div v-for="i in 5" :key="i" className="flex items-center gap-4">
+      <Skeleton className="w-8 h-8 rounded-full" />
+      <div className="flex-1 space-y-2">
+        <Skeleton className="h-4 w-1/3" />
+        <Skeleton className="h-3 w-1/4" />
+      </div>
+      <Skeleton className="h-5 w-16 rounded-full" />
+      <Skeleton className="h-4 w-20" />
+    </div>
+  </CardContent>
+</Card>
+```
+
+### Rules for Skeletons
+- **Match the shape**: Round for avatars (`rounded-full`), pill for badges (`rounded-full`), rectangle for text
+- **Vary widths**: Don't make all skeletons the same width — use `w-1/3`, `w-1/2`, `w-3/4` to look natural
+- **Show 3–5 rows**: Don't show 1 skeleton or 20 — 3-5 feels right
+- **No text**: Skeletons are gray blocks, never "Loading..." text
+
+## Button Loading State
+
+```tsx
+<Button :disabled="saving" onClick="handleSave">
+  <Loader2 v-if="saving" className="w-4 h-4 animate-spin" />
+  {{ saving ? 'Saving...' : 'Save Changes' }}
+</Button>
+```
+
+The button shows a spinner icon AND is disabled during the operation.
+
+## Full-Page Loading
+
+For initial page load where no skeleton shape is known:
+
+```tsx
+<div className="flex items-center justify-center h-64">
+  <Loader2 className="w-6 h-6 animate-spin text-muted-foreground" />
+</div>
+```
+
+Use sparingly — skeletons are almost always better.
+
+## Progressive Loading
+
+Load and show content as it becomes available:
+```tsx
+<div v-if="stats" className="grid grid-cols-4 gap-4">
+  <!-- Stats render immediately -->
+</div>
+<div v-else className="grid grid-cols-4 gap-4">
+  <!-- Stat skeletons -->
+</div>
+
+<!-- Table loads independently -->
+<Card>
+  <CardContent v-if="tableData" className="p-0">
+    <Table><!-- ... --></Table>
+  </CardContent>
+  <CardContent v-else>
+    <!-- Table skeleton -->
+  </CardContent>
+</Card>
+```

package/skills/patterns/navigation.md

@@ -0,0 +1,113 @@
+# Pattern: Navigation
+
+Navigation structures for apps: sidebars, top bars, mobile nav, and nav composition.
+
+## Sidebar Navigation
+
+The most common desktop navigation pattern. Vertical nav links on the left, content on the right.
+
+```tsx
+<div className="flex h-screen">
+  <!-- Sidebar -->
+  <aside className="w-64 border-r bg-card flex flex-col shrink-0">
+    <!-- Logo -->
+    <div className="h-14 flex items-center px-4 border-b">
+      <div className="flex items-center gap-2">
+        <div className="w-7 h-7 rounded-md bg-primary flex items-center justify-center">
+          <Zap className="w-4 h-4 text-primary-foreground" />
+        </div>
+        <span className="text-sm font-semibold">Acme Inc</span>
+      </div>
+    </div>
+    <!-- Nav Links -->
+    <nav className="flex-1 p-3 space-y-1">
+      <button v-for="item in navItems" :key="item.label"
+              className={cn(
+                'w-full flex items-center gap-3 px-3 py-2 text-sm rounded-md transition-colors',
+                item.active ? 'bg-accent font-medium' : 'text-muted-foreground hover:bg-accent/50 hover:text-foreground'
+              )}>
+        <component :is="item.icon" className="w-4 h-4" />
+        {{ item.label }}
+      </button>
+    </nav>
+    <!-- User menu at bottom -->
+    <div className="border-t p-3">
+      <div className="flex items-center gap-3 px-3 py-2">
+        <div className="w-8 h-8 rounded-full bg-gradient-to-br from-primary/60 to-primary shrink-0" />
+        <div className="flex-1 min-w-0">
+          <p className="text-sm font-medium truncate">Sarah Chen</p>
+          <p className="text-xs text-muted-foreground truncate">sarah@acme.co</p>
+        </div>
+      </div>
+    </div>
+  </aside>
+  <!-- Main Content -->
+  <main className="flex-1 overflow-y-auto">
+    <div className="max-w-7xl mx-auto px-6 py-8">
+      <!-- Page content -->
+    </div>
+  </main>
+</div>
+```
+
+### Sidebar Nav Item States
+| State | Classes |
+|-------|---------|
+| Default | `text-muted-foreground hover:bg-accent/50 hover:text-foreground` |
+| Active | `bg-accent font-medium` (text color inherits foreground) |
+| Disabled | `opacity-50 pointer-events-none` |
+
+### Sidebar with Sections
+```tsx
+<nav className="flex-1 p-3 space-y-6">
+  <div className="space-y-1">
+    <p className="px-3 text-xs font-medium text-muted-foreground uppercase tracking-wider mb-2">Main</p>
+    <!-- Main nav items -->
+  </div>
+  <div className="space-y-1">
+    <p className="px-3 text-xs font-medium text-muted-foreground uppercase tracking-wider mb-2">Settings</p>
+    <!-- Settings nav items -->
+  </div>
+</nav>
+```
+
+## Top Navigation Bar
+
+For simpler apps or when sidebar isn't appropriate.
+
+```tsx
+<header className="h-14 border-b bg-card flex items-center px-6">
+  <div className="flex items-center gap-6 w-full max-w-7xl mx-auto">
+    <!-- Logo -->
+    <div className="flex items-center gap-2 shrink-0">
+      <div className="w-7 h-7 rounded-md bg-primary flex items-center justify-center">
+        <Zap className="w-4 h-4 text-primary-foreground" />
+      </div>
+      <span className="text-sm font-semibold">Acme</span>
+    </div>
+    <!-- Nav links -->
+    <nav className="flex items-center gap-1">
+      <Button v-for="item in navItems" :key="item.label"
+              :variant="item.active ? 'secondary' : 'ghost'" size="sm">
+        {{ item.label }}
+      </Button>
+    </nav>
+    <!-- Right side -->
+    <div className="ml-auto flex items-center gap-2">
+      <Button variant="ghost" size="icon"><Bell className="w-4 h-4" /></Button>
+      <Button variant="ghost" size="icon" className="rounded-full">
+        <div className="w-7 h-7 rounded-full bg-gradient-to-br from-primary/60 to-primary" />
+      </Button>
+    </div>
+  </div>
+</header>
+```
+
+## When to Use Which
+
+| Navigation Type | Best For |
+|----------------|----------|
+| Sidebar | SaaS dashboards, admin panels, complex apps with many sections |
+| Top bar | Marketing sites, simple apps, consumer products |
+| Top bar + sidebar | Very complex apps (e.g., settings under an app that uses top bar) |
+| Bottom tabs | Mobile apps (max 5 items) |