@reinvented/design 0.4.0 → 1.1.0

package/skills/patterns/notifications.md

@@ -0,0 +1,91 @@
+# Pattern: Notifications
+
+Toast notifications, notification center, and badge indicators.
+
+## Notification Center
+
+A dropdown showing recent notifications:
+
+```tsx
+<DropdownMenu>
+  <DropdownMenuTrigger as-child>
+    <Button variant="ghost" size="icon" className="relative">
+      <Bell className="w-4 h-4" />
+      <span v-if="unreadCount > 0" className="absolute -top-0.5 -right-0.5 w-4 h-4 rounded-full bg-destructive text-xs font-medium text-destructive-foreground flex items-center justify-center">
+        {{ unreadCount }}
+      </span>
+    </Button>
+  </DropdownMenuTrigger>
+  <DropdownMenuContent align="end" className="w-80">
+    <DropdownMenuLabel className="flex items-center justify-between">
+      <span>Notifications</span>
+      <Button variant="ghost" size="sm" className="h-auto px-1 text-xs">Mark all read</Button>
+    </DropdownMenuLabel>
+    <DropdownMenuSeparator />
+    <div className="max-h-64 overflow-y-auto">
+      <DropdownMenuItem v-for="n in notifications" :key="n.id" className="flex-col items-start gap-1 py-3">
+        <div className="flex items-start gap-2 w-full">
+          <span v-if="!n.read" className="w-2 h-2 rounded-full bg-primary mt-1.5 shrink-0" />
+          <span v-else className="w-2 h-2 shrink-0" />
+          <div className="flex-1 min-w-0">
+            <p className="text-sm" className={!n.read ? 'font-medium' : ''}>{{ n.title }}</p>
+            <p className="text-xs text-muted-foreground">{{ n.time }}</p>
+          </div>
+        </div>
+      </DropdownMenuItem>
+    </div>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+## Notification Badge
+
+Small dot or count on icons:
+
+```tsx
+<!-- Dot indicator -->
+<div className="relative">
+  <Bell className="w-4 h-4" />
+  <span className="absolute -top-0.5 -right-0.5 w-2 h-2 rounded-full bg-destructive" />
+</div>
+
+<!-- Count badge -->
+<div className="relative">
+  <Inbox className="w-4 h-4" />
+  <span className="absolute -top-1 -right-1.5 min-w-4 h-4 rounded-full bg-destructive text-xs font-medium text-destructive-foreground flex items-center justify-center px-1">
+    5
+  </span>
+</div>
+```
+
+## Toast Notifications
+
+For action confirmations and transient feedback, use `toast()`:
+
+```ts
+import { toast } from '@reinvented/design'
+
+// Success (after a mutation)
+toast({ title: 'Project created', description: 'Your new project is ready.' })
+
+// Error (after a failed mutation)
+toast({ title: 'Failed to save', description: 'Please try again.', variant: 'destructive' })
+
+// With undo action
+toast({
+  title: 'Message archived',
+  description: '1 conversation moved to archive.',
+  action: { label: 'Undo', onClick: () => handleUndo() }
+})
+```
+
+### When to Use Toast vs Alert vs Dialog
+
+| Feedback Type | Component | Persists? |
+|--------------|-----------|-----------|
+| Action confirmed (save, create, send) | `toast()` | No, auto-dismiss |
+| Important warning (data limit reached) | `Alert` component | Yes, in-page |
+| Destructive confirmation (delete) | `AlertDialog` | Yes, blocks UI |
+| Form validation error | Inline `text-destructive` | Yes, per-field |
+
+See also: `components/feedback.md` for Alert, Tooltip, and other feedback components.

package/skills/patterns/onboarding.md

@@ -0,0 +1,42 @@
+# Pattern: Onboarding
+
+Welcome screens, setup wizards, and first-run experiences.
+
+## Multi-Step Wizard
+
+```tsx
+<div className="flex min-h-screen items-center justify-center px-4">
+  <Card className="w-full max-w-lg">
+    <CardHeader>
+      <div className="flex items-center justify-between mb-2">
+        <CardDescription>Step {{ currentStep }} of {{ totalSteps }}</CardDescription>
+        <span className="text-xs text-muted-foreground">{{ Math.round((currentStep / totalSteps) * 100) }}%</span>
+      </div>
+      <Progress :model-value="(currentStep / totalSteps) * 100" className="h-1" />
+      <CardTitle className="mt-4">{{ steps[currentStep - 1].title }}</CardTitle>
+      <CardDescription>{{ steps[currentStep - 1].description }}</CardDescription>
+    </CardHeader>
+    <CardContent className="space-y-4">
+      <!-- Step-specific fields -->
+    </CardContent>
+    <CardFooter className="justify-between">
+      <Button variant="ghost" v-if="currentStep > 1" onClick="currentStep--">
+        <ArrowLeft className="w-4 h-4" /> Back
+      </Button>
+      <div v-else></div>
+      <Button onClick="nextStep">
+        {{ currentStep === totalSteps ? 'Complete Setup' : 'Continue' }}
+        <ArrowRight v-if="currentStep < totalSteps" className="w-4 h-4" />
+      </Button>
+    </CardFooter>
+  </Card>
+</div>
+```
+
+## Key Rules
+
+- Show progress (Progress bar + "Step X of Y")
+- Back button is `variant="ghost"`, forward is `default`
+- Last step says "Complete Setup" or "Get Started"
+- Keep each step to 2–4 fields maximum
+- Center the wizard card like an auth page

package/skills/patterns/search.md

@@ -0,0 +1,55 @@
+# Pattern: Search
+
+Global search, filtered search results, and command palette.
+
+## Search Input in Toolbar
+
+```tsx
+<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..." defaultValue="query" />
+</div>
+```
+
+## Command Palette (⌘K)
+
+Full-page searchable command menu:
+
+```tsx
+<Dialog v-model:open="showSearch">
+  <DialogContent className="p-0 max-w-lg">
+    <Command>
+      <CommandInput placeholder="Search or type a command..." />
+      <CommandList>
+        <CommandEmpty>No results found.</CommandEmpty>
+        <CommandGroup heading="Recent">
+          <CommandItem v-for="item in recent" :key="item.id">
+            <Clock className="w-4 h-4" /> {{ item.title }}
+          </CommandItem>
+        </CommandGroup>
+        <CommandSeparator />
+        <CommandGroup heading="Actions">
+          <CommandItem><Plus className="w-4 h-4" /> Create new project</CommandItem>
+          <CommandItem><Settings className="w-4 h-4" /> Open settings</CommandItem>
+        </CommandGroup>
+      </CommandList>
+    </Command>
+  </DialogContent>
+</Dialog>
+```
+
+## Search Results Page
+
+```tsx
+<div className="space-y-4">
+  <p className="text-sm text-muted-foreground">{{ results.length }} results for "{{ query }}"</p>
+  <div className="space-y-2">
+    <Card v-for="result in results" :key="result.id" className="cursor-pointer hover:bg-accent/50 transition-colors">
+      <CardContent className="p-4">
+        <p className="text-sm font-medium">{{ result.title }}</p>
+        <p className="text-xs text-muted-foreground line-clamp-2">{{ result.excerpt }}</p>
+      </CardContent>
+    </Card>
+  </div>
+</div>
+```

package/skills/patterns/settings.md

@@ -0,0 +1,132 @@
+# Pattern: Settings
+
+Grouped settings pages with section navigation and mixed control types.
+
+## Settings Page Layout
+
+```tsx
+<div className="max-w-4xl mx-auto px-6 py-8 space-y-6">
+  <div>
+    <h1 className="text-2xl font-bold">Settings</h1>
+    <p className="text-muted-foreground">Manage your account and preferences.</p>
+  </div>
+
+  <div className="flex flex-col sm:flex-row gap-8">
+    <!-- Sidebar navigation -->
+    <nav className="w-full sm:w-48 shrink-0 space-y-1">
+      <button v-for="section in sections" :key="section.id"
+              className={cn(
+                'w-full text-left px-3 py-2 text-sm rounded-md transition-colors',
+                activeSection === section.id ? 'bg-accent font-medium' : 'text-muted-foreground hover:bg-accent/50'
+              )}>
+        {{ section.label }}
+      </button>
+    </nav>
+
+    <!-- Content -->
+    <div className="flex-1 space-y-8">
+      <!-- Profile Section -->
+      <Card>
+        <CardHeader>
+          <CardTitle>Profile</CardTitle>
+          <CardDescription>Your public profile information.</CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          <div className="grid grid-cols-1 sm:grid-cols-2 gap-4">
+            <div className="space-y-2">
+              <Label>First Name</Label>
+              <Input defaultValue="form.firstName" />
+            </div>
+            <div className="space-y-2">
+              <Label>Last Name</Label>
+              <Input defaultValue="form.lastName" />
+            </div>
+          </div>
+          <div className="space-y-2">
+            <Label>Email</Label>
+            <Input defaultValue="form.email" type="email" />
+          </div>
+        </CardContent>
+        <CardFooter className="border-t pt-4 justify-end">
+          <Button>Save Changes</Button>
+        </CardFooter>
+      </Card>
+
+      <!-- Notifications Section -->
+      <Card>
+        <CardHeader>
+          <CardTitle>Notifications</CardTitle>
+          <CardDescription>Choose what you want to be notified about.</CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          <div className="flex items-center justify-between">
+            <div>
+              <p className="text-sm font-medium">Email Notifications</p>
+              <p className="text-xs text-muted-foreground">Receive emails for important updates.</p>
+            </div>
+            <Switch v-model:checked="notifications.email" />
+          </div>
+          <Separator />
+          <div className="flex items-center justify-between">
+            <div>
+              <p className="text-sm font-medium">Push Notifications</p>
+              <p className="text-xs text-muted-foreground">Receive push notifications on your device.</p>
+            </div>
+            <Switch v-model:checked="notifications.push" />
+          </div>
+        </CardContent>
+      </Card>
+
+      <!-- Danger Zone -->
+      <Card className="border-destructive/50">
+        <CardHeader>
+          <CardTitle className="text-destructive">Danger Zone</CardTitle>
+          <CardDescription>Irreversible actions for your account.</CardDescription>
+        </CardHeader>
+        <CardContent>
+          <div className="flex items-center justify-between">
+            <div>
+              <p className="text-sm font-medium">Delete Account</p>
+              <p className="text-xs text-muted-foreground">Permanently delete your account and all data.</p>
+            </div>
+            <Button variant="destructive" size="sm">Delete Account</Button>
+          </div>
+        </CardContent>
+      </Card>
+    </div>
+  </div>
+</div>
+```
+
+## Expandable Setting Row (Switch & Reveal)
+
+When toggling a switch should reveal additional advanced options beneath it, use Shadcn's `<Collapsible>` rather than manually toggling `overflow: hidden` and `max-height`. `<Collapsible>` manages overflow states correctly during animations, preventing interactive elements (like focus rings and drop-downs) from being clipped off inside the expanding panel.
+
+```tsx
+<Collapsible v-model:open="advancedEnabled" className="p-4 rounded-lg border border-border bg-card">
+  <div className="flex items-center justify-between">
+    <div>
+      <h4 className="text-sm font-semibold tracking-tight">Advanced Filtering</h4>
+      <p className="text-xs text-muted-foreground mt-0.5">Filter incoming data by protocol rules.</p>
+    </div>
+    <Switch v-model:checked="advancedEnabled" />
+  </div>
+  
+  <CollapsibleContent className="pt-4 mt-4 border-t border-border/60 space-y-3">
+    <Label className="text-xs font-bold text-muted-foreground uppercase tracking-widest">Protocol Type</Label>
+    <Select>
+      <SelectTrigger className="w-full"><SelectValue placeholder="TCP/UDP" /></SelectTrigger>
+      <!-- ... -->
+    </Select>
+  </CollapsibleContent>
+</Collapsible>
+```
+
+## Key Rules
+
+- Settings sidebar uses `w-48` with text nav items (not icons)
+- Each settings section is its own Card
+- Toggle settings use the `label/description (left) + Switch (right)` pattern
+- Save buttons go in `CardFooter` with `border-t`
+- Danger zone card uses `border-destructive/50` for visual warning
+- On mobile, sidebar stacks above content (`flex-col sm:flex-row`)

package/skills/patterns/user-profiles.md

@@ -0,0 +1,67 @@
+# Pattern: User Profiles
+
+Profile cards, account pages, and user detail views.
+
+## Profile Header
+
+```tsx
+<div className="space-y-6">
+  <!-- Banner + Avatar -->
+  <div className="relative">
+    <div className="h-32 rounded-lg bg-gradient-to-br from-primary/20 via-primary/10 to-transparent" />
+    <div className="absolute -bottom-8 left-6 flex items-end gap-4">
+      <div className="w-20 h-20 rounded-2xl border-4 border-background bg-primary flex items-center justify-center text-xl font-bold text-primary-foreground">
+        SC
+      </div>
+    </div>
+  </div>
+
+  <!-- Info (below avatar offset) -->
+  <div className="pt-10 px-6 flex items-start justify-between">
+    <div>
+      <h1 className="text-2xl font-bold">Sarah Chen</h1>
+      <p className="text-muted-foreground">Engineering Lead · San Francisco, CA</p>
+      <p className="text-sm text-muted-foreground mt-1">Joined March 2023</p>
+    </div>
+    <div className="flex items-center gap-2">
+      <Button variant="outline"><Mail className="w-4 h-4" /> Message</Button>
+      <Button>Follow</Button>
+    </div>
+  </div>
+
+  <!-- Stats row -->
+  <div className="flex items-center gap-8 px-6">
+    <div>
+      <p className="text-xl font-bold">142</p>
+      <p className="text-xs text-muted-foreground">Projects</p>
+    </div>
+    <div>
+      <p className="text-xl font-bold">2.4k</p>
+      <p className="text-xs text-muted-foreground">Followers</p>
+    </div>
+    <div>
+      <p className="text-xl font-bold">891</p>
+      <p className="text-xs text-muted-foreground">Following</p>
+    </div>
+  </div>
+</div>
+```
+
+## Compact Profile Card
+
+For displaying a user in a list or sidebar:
+
+```tsx
+<Card>
+  <CardContent className="flex items-center gap-4 p-4">
+    <div className="w-12 h-12 rounded-full shrink-0 flex items-center justify-center text-sm font-medium bg-muted text-muted-foreground">
+      {{ user.initials }}
+    </div>
+    <div className="flex-1 min-w-0">
+      <p className="text-sm font-medium truncate">{{ user.name }}</p>
+      <p className="text-xs text-muted-foreground truncate">{{ user.role }}</p>
+    </div>
+    <Button variant="outline" size="sm">View Profile</Button>
+  </CardContent>
+</Card>
+```

package/skills/personas/business-operator.md

@@ -0,0 +1,114 @@
+# Persona: Business Operator
+
+Back-office users managing operations, data, and workflows.
+
+## Characteristics
+- Moderate technical proficiency
+- Uses app during work hours as a core part of their job
+- Needs to process many records efficiently (approvals, triage, routing)
+- Desires data at a glance, actionable summaries
+- Desktop primary
+
+## Design Adjustments
+
+| Aspect | Adjustment |
+|--------|-----------|
+| **Density** | Medium-high — data tables as primary view, stat cards prominent (`gap-4` spacing) |
+| **Dashboard** | Essential — always show KPIs and actionable metric cards at the top |
+| **Tables** | Feature-rich — filters, search, sort, bulk actions, export (`<Table>`) |
+| **Actions** | Clear workflow — step-by-step, status-based (Pending → Approved → Complete) |
+| **Reporting** | Prominent — date range selectors, export buttons, summary stats |
+| **Language** | Professional, clear — "Process", "Approve", "Archive" |
+| **Permissions** | Assumes role-based views. Show read-only fields where they lack edit rights |
+| **Badges** | Heavy use of `<Badge>` to indicate status (e.g. `variant="secondary"`, `variant="destructive"`) |
+
+## Component Composition Example
+
+```tsx
+<!-- Back Office Operations Layout -->
+<div className="space-y-6">
+  <!-- Page Header -->
+  <div className="flex flex-col sm:flex-row sm:items-center justify-between gap-4">
+    <div>
+      <h1 className="text-2xl font-bold tracking-tight">Order Fulfillment</h1>
+      <p className="text-muted-foreground">Process pending shipments and handle returns.</p>
+    </div>
+    <div className="flex items-center gap-2">
+      <!-- Date Picker Mockup -->
+      <Button variant="outline" className="w-60 justify-start text-left font-normal">
+        <CalendarIcon className="mr-2 h-4 w-4" />
+        <span>Oct 01, 2023 - Oct 31, 2023</span>
+      </Button>
+    </div>
+  </div>
+
+  <!-- Actionable KPIs -->
+  <div className="grid grid-cols-1 md:grid-cols-3 gap-4">
+    <Card>
+      <CardHeader className="flex flex-row items-center justify-between space-y-0 pb-2">
+        <CardTitle className="text-sm font-medium">Ready to Ship</CardTitle>
+        <PackageIcon className="h-4 w-4 text-muted-foreground" />
+      </CardHeader>
+      <CardContent>
+        <div className="text-2xl font-bold text-primary">145</div>
+        <p className="text-xs text-muted-foreground mt-1">Requires immediate processing</p>
+      </CardContent>
+    </Card>
+    <!-- More KPI cards... -->
+  </div>
+
+  <!-- Triage Table -->
+  <Card>
+    <CardHeader className="flex flex-row items-center justify-between pb-2">
+      <div className="space-y-1">
+        <CardTitle className="text-lg">Processing Queue</CardTitle>
+      </div>
+      <div className="flex items-center gap-2">
+        <div className="relative w-64">
+          <Search className="absolute left-2.5 top-2.5 h-4 w-4 text-muted-foreground" />
+          <Input pl="8" placeholder="Search orders..." />
+        </div>
+        <Button variant="outline">Filter</Button>
+      </div>
+    </CardHeader>
+    <CardContent>
+      <Table>
+        <TableHeader>
+          <TableRow>
+            <TableHead>Order #</TableHead>
+            <TableHead>Customer</TableHead>
+            <TableHead>Status</TableHead>
+            <TableHead className="text-right">Amount</TableHead>
+            <TableHead className="w-24"></TableHead>
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          <TableRow v-for="order in orders" :key="order.id">
+            <TableCell className="font-medium">#{{ order.id }}</TableCell>
+            <TableCell>{{ order.customerName }}</TableCell>
+            <TableCell>
+              <Badge variant="warning">
+                Pending Review
+              </Badge>
+            </TableCell>
+            <TableCell className="text-right">${{ order.total }}</TableCell>
+            <TableCell>
+              <Button size="sm">Process</Button>
+            </TableCell>
+          </TableRow>
+        </TableBody>
+      </Table>
+    </CardContent>
+  </Card>
+</div>
+```
+
+## Anti-Patterns (DO NOT DO)
+
+- ❌ **Do not bury the primary action**: A business operator's goal is to clear a queue. The "Process" or "Approve" button should be front and center on every row.
+- ❌ **Do not use "mystery meat" navigation**: Don't rely on icons without text labels for sidebars or tabs. Operators need unambiguous labels.
+- ❌ **Do not hide KPIs in reports**: Operational health (e.g., number of pending tickets) must be visible at a glance at the top of the workflow page.
+- ❌ **Do not force page reloads**: Use sliding panels (`<Sheet>`) or `<Dialog>` for data entry instead of navigating the user entirely away from their list context.
+
+## Layout Preference
+Always use `layouts/sidebar.md`. Back-office tooling requires jumping between modules constantly. The primary content area should follow a Dashboard (`layouts/dashboard.md`) or List/Detail (`layouts/list-detail.md`) structure depending on the task complexity.

package/skills/personas/consumer-casual.md

@@ -0,0 +1,60 @@
+# Persona: Consumer Casual
+
+General consumers using the app casually. Prioritize simplicity and visual appeal.
+
+## Characteristics
+- Low technical proficiency
+- Uses app occasionally
+- Wants tasks done quickly with minimal cognitive load
+- Primarily mobile, some tablet/desktop
+
+## Design Adjustments
+
+| Aspect | Adjustment |
+|--------|-----------|
+| **Density** | Lower — more whitespace (`gap-6`, `p-6`), larger touch targets |
+| **Typography** | `text-sm` for body (standard), but use `text-lg text-muted-foreground` for intro text |
+| **Navigation** | Simpler — 4-5 top-level items max, bottom tabs on mobile |
+| **Actions** | Obvious — large primary CTA buttons (`size="lg"`), clear labels |
+| **Feedback** | Immediate — success toast on every action, clear loading states |
+| **Language** | Friendly, casual — "Got it!", "You're all set!", "Here's what's new" |
+| **Visual** | High visual contrast — use cards with imagery, badges, and color |
+
+## Component Composition Example
+
+```tsx
+<!-- Casual Consumer Header Pattern -->
+<div className="space-y-6 text-center max-w-md mx-auto py-8">
+  <div className="space-y-2">
+    <h1 className="text-3xl font-bold tracking-tight">Welcome back!</h1>
+    <p className="text-lg text-muted-foreground">Ready to continue your journey today?</p>
+  </div>
+  
+  <Button size="lg" className="w-full sm:w-auto rounded-full px-8">
+    Let's get started
+  </Button>
+</div>
+
+<!-- Simplified Content Cards -->
+<div className="grid grid-cols-1 sm:grid-cols-2 gap-4">
+  <Card className="overflow-hidden hover:shadow-md transition-shadow">
+    <div className="aspect-video bg-muted border-b">
+      <!-- In mockups: <ComponentPlaceholder name="Image" description="Hero illustration" height="100%" /> (Mockup Mode Only) -->
+    </div>
+    <CardHeader className="p-4 text-center">
+      <CardTitle className="text-lg">Daily Challenge</CardTitle>
+      <CardDescription className="text-sm">Complete today's task to earn rewards.</CardDescription>
+    </CardHeader>
+  </Card>
+</div>
+```
+
+## Anti-Patterns (DO NOT DO)
+
+- ❌ **Do not use Data Tables (`<Table>`)**: Casual consumers don't read spreadsheets. Use grid layouts with visual `<Card>` elements instead.
+- ❌ **Do not use dense forms**: Never put 10 inputs on a single screen. Use progressive disclosure or a wizard.
+- ❌ **Do not rely on hover states**: Consumers are mobile-first. Crucial actions must be persistently visible.
+- ❌ **Do not use `text-base` for standard body text**: The design system rules dictate `text-sm` for body. Size up headers (`text-xl`, `text-2xl`), not standard body paragraphs.
+
+## Layout Preference
+Use `layouts/topbar.md` with simple, obvious navigation. Single-column, max-width centered layouts (`max-w-xl mx-auto`) work best.