@reinvented/design 0.1.0 → 0.2.1

package/docs/layouts/detail-page.md

@@ -0,0 +1,83 @@
+# Detail Page Layout
+
+## When to Use
+- Viewing a single item's complete information
+- Item detail with related data sections
+- Edit-in-place forms
+
+## Skeleton Code
+
+```vue
+<script setup>
+import {
+  Button, Badge, Separator, Tabs, TabsContent, TabsList, TabsTrigger,
+  Card, CardContent, CardHeader, CardTitle, Skeleton,
+  Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator,
+} from '@reinvented/design'
+import { ArrowLeft, Pencil, Trash2 } from 'lucide-vue-next'
+
+const item = ref(null)
+const loading = ref(true)
+</script>
+
+<template>
+  <div class="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-8 space-y-6">
+
+    <!-- Breadcrumb -->
+    <Breadcrumb>
+      <BreadcrumbList>
+        <BreadcrumbItem><BreadcrumbLink href="/items">Items</BreadcrumbLink></BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbItem><BreadcrumbPage>{{ item?.name }}</BreadcrumbPage></BreadcrumbItem>
+      </BreadcrumbList>
+    </Breadcrumb>
+
+    <!-- Page Header -->
+    <div class="flex items-center justify-between">
+      <div class="flex items-center gap-3">
+        <h1 class="text-2xl font-bold tracking-tight">{{ item?.name }}</h1>
+        <Badge>{{ item?.status }}</Badge>
+      </div>
+      <div class="flex items-center gap-2">
+        <Button variant="outline"><Pencil class="mr-2 h-4 w-4" /> Edit</Button>
+        <Button variant="destructive"><Trash2 class="mr-2 h-4 w-4" /> Delete</Button>
+      </div>
+    </div>
+
+    <Separator />
+
+    <!-- Tabbed Content -->
+    <Tabs default-value="overview">
+      <TabsList>
+        <TabsTrigger value="overview">Overview</TabsTrigger>
+        <TabsTrigger value="activity">Activity</TabsTrigger>
+        <TabsTrigger value="settings">Settings</TabsTrigger>
+      </TabsList>
+
+      <TabsContent value="overview" class="space-y-6">
+        <!-- Detail Cards -->
+        <div class="grid gap-6 md:grid-cols-2">
+          <Card>
+            <CardHeader><CardTitle>Details</CardTitle></CardHeader>
+            <CardContent>
+              <dl class="space-y-3">
+                <div>
+                  <dt class="text-sm text-muted-foreground">Created</dt>
+                  <dd class="text-sm font-medium">{{ item?.createdAt }}</dd>
+                </div>
+              </dl>
+            </CardContent>
+          </Card>
+        </div>
+      </TabsContent>
+    </Tabs>
+  </div>
+</template>
+```
+
+## Key Patterns
+- **Breadcrumb** at the top for back navigation
+- **Header**: Title + badge + action buttons
+- **Tabbed sections** for detailed content
+- **Detail cards** in a 2-column grid for metadata
+- **Separator** between header and tabbed content

package/docs/layouts/index.md

@@ -0,0 +1,45 @@
+# Layout Documentation
+
+## Decision Tree
+
+Use this tree to choose the right layout for each view:
+
+```
+Is this a list of items?
+├─ Yes → List Page (list-page.md)
+├─ No
+│  ├─ Is this showing a single item's details?
+│  │  ├─ Yes → Detail Page (detail-page.md)
+│  │  ├─ No
+│  │  │  ├─ Is this a dashboard/overview?
+│  │  │  │  ├─ Yes → Dashboard (dashboard.md)
+│  │  │  │  ├─ No
+│  │  │  │  │  ├─ Is this a settings/configuration page?
+│  │  │  │  │  │  ├─ Yes → Settings Page (settings-page.md)
+│  │  │  │  │  │  ├─ No
+│  │  │  │  │  │  │  ├─ Is this a multi-step process?
+│  │  │  │  │  │  │  │  ├─ Yes → Step Wizard (step-wizard.md)
+│  │  │  │  │  │  │  │  ├─ No
+│  │  │  │  │  │  │  │  │  ├─ Is this a simple form?
+│  │  │  │  │  │  │  │  │  │  ├─ ≤5 fields → Modal Form (use Dialog)
+│  │  │  │  │  │  │  │  │  │  ├─ >5 fields → Full Page Form (detail-page.md variant)
+```
+
+## Available Layouts
+
+| Layout | File | Use for |
+|--------|------|---------|
+| [List Page](list-page.md) | ✅ | Filterable, searchable lists of items |
+| [Detail Page](detail-page.md) | ✅ | Single item view with actions |
+| [Dashboard](dashboard.md) | ✅ | Overview grids with stats and summaries |
+| [Settings Page](settings-page.md) | ✅ | Configuration with sidebar nav |
+| [Step Wizard](step-wizard.md) | ✅ | Multi-step guided processes |
+| Modal Form | — | Use Dialog component (≤5 fields) |
+
+## General Layout Rules
+
+1. **Max content width**: `max-w-7xl mx-auto` for main content
+2. **Page padding**: `px-4 sm:px-6 lg:px-8`
+3. **Section spacing**: `space-y-6` between major sections
+4. **Page header pattern**: Title + description + primary action
+5. **Responsive**: All layouts must work at mobile (320px+), tablet (768px+), desktop (1024px+)

package/docs/layouts/list-page.md

@@ -0,0 +1,107 @@
+# List Page Layout
+
+## When to Use
+- Browse a collection of items (tasks, users, apps)
+- Filterable, searchable, sortable data
+- Paginated or infinite-scroll lists
+
+## Skeleton Code
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import {
+  Button, Input, Select, SelectContent, SelectItem, SelectTrigger, SelectValue,
+  Card, CardContent, Badge, Skeleton,
+  DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger,
+} from '@reinvented/design'
+import { Plus, Search, MoreHorizontal } from 'lucide-vue-next'
+
+const search = ref('')
+const filter = ref('all')
+const items = ref([]) // from GraphQL query
+const loading = ref(true)
+</script>
+
+<template>
+  <div class="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-8 space-y-6">
+
+    <!-- Page Header -->
+    <div class="flex items-center justify-between">
+      <div>
+        <h1 class="text-2xl font-bold tracking-tight">Items</h1>
+        <p class="text-muted-foreground">Manage your items.</p>
+      </div>
+      <Button><Plus class="mr-2 h-4 w-4" /> New Item</Button>
+    </div>
+
+    <!-- Filters Bar -->
+    <div class="flex items-center gap-4">
+      <div class="relative flex-1 max-w-sm">
+        <Search class="absolute left-3 top-1/2 -translate-y-1/2 h-4 w-4 text-muted-foreground" />
+        <Input v-model="search" class="pl-9" placeholder="Search items..." />
+      </div>
+      <Select v-model="filter">
+        <SelectTrigger class="w-[150px]">
+          <SelectValue placeholder="Filter" />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="all">All</SelectItem>
+          <SelectItem value="active">Active</SelectItem>
+          <SelectItem value="archived">Archived</SelectItem>
+        </SelectContent>
+      </Select>
+    </div>
+
+    <!-- Loading State -->
+    <div v-if="loading" class="space-y-3">
+      <Skeleton v-for="i in 5" :key="i" class="h-16 w-full rounded-lg" />
+    </div>
+
+    <!-- Empty State -->
+    <div v-else-if="items.length === 0" class="flex flex-col items-center justify-center py-12 text-center">
+      <div class="rounded-full bg-muted p-4 mb-4">
+        <Search class="h-8 w-8 text-muted-foreground" />
+      </div>
+      <h3 class="text-lg font-semibold">No items found</h3>
+      <p class="text-muted-foreground mt-1">Get started by creating your first item.</p>
+      <Button class="mt-4"><Plus class="mr-2 h-4 w-4" /> Create Item</Button>
+    </div>
+
+    <!-- Data State -->
+    <div v-else class="space-y-3">
+      <Card v-for="item in items" :key="item.id" class="hover:shadow-sm transition-shadow">
+        <CardContent class="flex items-center justify-between p-4">
+          <div class="flex items-center gap-3">
+            <div>
+              <p class="font-medium">{{ item.name }}</p>
+              <p class="text-sm text-muted-foreground">{{ item.description }}</p>
+            </div>
+          </div>
+          <div class="flex items-center gap-2">
+            <Badge>{{ item.status }}</Badge>
+            <DropdownMenu>
+              <DropdownMenuTrigger as-child>
+                <Button variant="ghost" size="icon">
+                  <MoreHorizontal class="h-4 w-4" />
+                </Button>
+              </DropdownMenuTrigger>
+              <DropdownMenuContent align="end">
+                <DropdownMenuItem>Edit</DropdownMenuItem>
+                <DropdownMenuItem class="text-destructive">Delete</DropdownMenuItem>
+              </DropdownMenuContent>
+            </DropdownMenu>
+          </div>
+        </CardContent>
+      </Card>
+    </div>
+  </div>
+</template>
+```
+
+## Key Patterns
+- **Header**: Title + description + primary CTA
+- **Filters**: Search + dropdown filters in a row
+- **Three states**: Loading (skeletons), empty, data
+- **Item cards**: Name + description + badge + action menu
+- **Empty state**: Icon + message + CTA

package/docs/layouts/settings-page.md

@@ -0,0 +1,79 @@
+# Settings Page Layout
+
+## When to Use
+- User preferences
+- App configuration
+- Account management
+
+## Skeleton Code
+
+```vue
+<script setup>
+import {
+  Button, Input, Label, Separator, Switch, Textarea,
+  Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle,
+} from '@reinvented/design'
+</script>
+
+<template>
+  <div class="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-8">
+    <div class="flex flex-col md:flex-row gap-8">
+
+      <!-- Sidebar Nav -->
+      <nav class="w-full md:w-48 space-y-1">
+        <a v-for="section in sections" :key="section.id"
+           :href="`#${section.id}`"
+           class="block rounded-md px-3 py-2 text-sm font-medium text-muted-foreground hover:bg-muted hover:text-foreground"
+           :class="{ 'bg-muted text-foreground': activeSection === section.id }">
+          {{ section.label }}
+        </a>
+      </nav>
+
+      <!-- Settings Content -->
+      <div class="flex-1 space-y-6 max-w-2xl">
+        <Card id="profile">
+          <CardHeader>
+            <CardTitle>Profile</CardTitle>
+            <CardDescription>Update your personal information.</CardDescription>
+          </CardHeader>
+          <CardContent class="space-y-4">
+            <div class="space-y-2">
+              <Label for="name">Name</Label>
+              <Input id="name" placeholder="Your name" />
+            </div>
+            <div class="space-y-2">
+              <Label for="bio">Bio</Label>
+              <Textarea id="bio" placeholder="About you" />
+            </div>
+          </CardContent>
+          <CardFooter>
+            <Button>Save Changes</Button>
+          </CardFooter>
+        </Card>
+
+        <Card id="notifications">
+          <CardHeader>
+            <CardTitle>Notifications</CardTitle>
+            <CardDescription>Choose what notifications you receive.</CardDescription>
+          </CardHeader>
+          <CardContent class="space-y-4">
+            <div class="flex items-center justify-between">
+              <div>
+                <p class="text-sm font-medium">Email notifications</p>
+                <p class="text-sm text-muted-foreground">Receive updates via email.</p>
+              </div>
+              <Switch />
+            </div>
+          </CardContent>
+        </Card>
+      </div>
+    </div>
+  </div>
+</template>
+```
+
+## Key Patterns
+- **Sidebar nav** on left, content on right
+- **Each section** is a Card with header + form fields + save button
+- **Switch rows**: Label + description on left, Switch on right
+- **Mobile**: sidebar stacks above content

package/docs/layouts/step-wizard.md

@@ -0,0 +1,73 @@
+# Step Wizard Layout
+
+## When to Use  
+- Multi-step processes (onboarding, app creation, checkout)
+- 3–7 steps where each depends on the previous
+
+## Skeleton Code
+
+```vue
+<script setup>
+import { ref, computed } from 'vue'
+import { Button, Card, CardContent, CardFooter, CardHeader, CardTitle, Progress } from '@reinvented/design'
+import { Check } from 'lucide-vue-next'
+
+const currentStep = ref(0)
+const steps = [
+  { title: 'Details', component: 'StepDetails' },
+  { title: 'Configuration', component: 'StepConfig' },
+  { title: 'Review', component: 'StepReview' },
+]
+const progress = computed(() => ((currentStep.value + 1) / steps.length) * 100)
+</script>
+
+<template>
+  <div class="max-w-2xl mx-auto px-4 py-8 space-y-8">
+
+    <!-- Step Indicator -->
+    <div class="space-y-4">
+      <Progress :model-value="progress" />
+      <div class="flex justify-between">
+        <div v-for="(step, i) in steps" :key="i" class="flex items-center gap-2 text-sm">
+          <div
+            class="flex h-6 w-6 items-center justify-center rounded-full text-xs font-medium"
+            :class="i <= currentStep ? 'bg-primary text-primary-foreground' : 'bg-muted text-muted-foreground'"
+          >
+            <Check v-if="i < currentStep" class="h-3 w-3" />
+            <span v-else>{{ i + 1 }}</span>
+          </div>
+          <span :class="i <= currentStep ? 'text-foreground' : 'text-muted-foreground'">{{ step.title }}</span>
+        </div>
+      </div>
+    </div>
+
+    <!-- Step Content -->
+    <Card>
+      <CardHeader>
+        <CardTitle>{{ steps[currentStep].title }}</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <component :is="steps[currentStep].component" />
+      </CardContent>
+      <CardFooter class="flex justify-between">
+        <Button variant="outline" :disabled="currentStep === 0" @click="currentStep--">
+          Previous
+        </Button>
+        <Button v-if="currentStep < steps.length - 1" @click="currentStep++">
+          Next
+        </Button>
+        <Button v-else @click="submit">
+          Complete
+        </Button>
+      </CardFooter>
+    </Card>
+  </div>
+</template>
+```
+
+## Key Patterns
+- **Progress bar** + step circles at top
+- **Single card** with dynamic content
+- **Previous/Next** buttons in card footer
+- **Narrower max-width** than other layouts (`max-w-2xl`)
+- Completed steps show ✓, current step highlighted

package/docs/patterns/index.md

@@ -0,0 +1,39 @@
+# Patterns Index
+
+Reusable UI patterns — compositions of DS components for common use cases. Each pattern has a dedicated file with skeleton code.
+
+This directory grows via harmonization: when agents discover patterns used across multiple apps, they're promoted here.
+
+## Available Patterns
+
+*No patterns promoted yet. Agents should propose new patterns via PRs to this repo.*
+
+## How Patterns Get Added
+
+1. Agent builds an app and identifies a reusable UI pattern
+2. Agent opens a PR to this repo with a new `patterns/<name>.md` file
+3. Human or harmonization agent reviews
+4. On merge, all future agent runs benefit from the pattern
+
+## Pattern File Format
+
+Each pattern file should include:
+
+```markdown
+# Pattern: [Name]
+
+## When to Use
+[Describe the use case]
+
+## Skeleton Code
+[Working Vue code with TODO comments for app-specific parts]
+
+## Props / Configuration
+[What's customizable]
+
+## Related Components
+[Which DS components this pattern uses]
+
+## Apps Using This
+[List of apps where this pattern was first used or is in use]
+```

package/docs/rules.md

@@ -0,0 +1,43 @@
+# Design Rules
+
+Non-negotiable rules for all Reinvented apps. These are enforced by linting where possible.
+
+## Components
+
+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>` / `<Toast>`
+
+## Styling
+
+6. **No hardcoded colors** — use CSS variables (`bg-background`, `text-foreground`, `bg-primary`, etc.)
+7. **No arbitrary Tailwind values** — no `text-[#333]` or `p-[13px]`. Use only token-based utilities
+8. **No inline styles** — all styling through Tailwind utilities and DS component props
+9. **No `@apply` blocks** — prefer utility classes in templates
+
+## Icons & Media
+
+10. **No emojis** — use Lucide icons exclusively via `lucide-vue-next`
+11. **Default icon size**: `w-4 h-4` in buttons/nav, `w-12 h-12` in empty states
+
+## Layout
+
+12. **Modals for create/edit by default** — full pages only for forms with 8+ fields or rich content editing
+13. **Single-column responsive** — no split-screen layouts
+14. **Mobile-first** — no horizontal scrolling, minimum 44px touch targets
+15. **No custom scrollbars** — use `<ScrollArea>` from DS
+
+## States
+
+16. **Every view must have**: loading state, empty state, error state, data state
+17. **Every mutation button**: shows spinner during request, disabled while loading
+18. **Every list**: has empty state with descriptive text and CTA
+
+## Data
+
+19. **No `SELECT *`** — explicitly list columns
+20. **Parameterized queries only** — no string interpolation for user input
+21. **UUID primary keys** everywhere
+22. **RLS on every table** — no exceptions

package/docs/visual-polish.md

@@ -0,0 +1,141 @@
+# Visual Polish Guide
+
+Standards for animations, transitions, loading patterns, and interaction polish.
+
+## Transition Durations
+
+| Duration | Use |
+|----------|-----|
+| `duration-150` (150ms) | Hover states, color changes, opacity |
+| `duration-200` (200ms) | Modals open/close, tooltips, popovers |
+| `duration-300` (300ms) | Page transitions, slide-ins, expanded sections |
+
+**Easing**: Use `ease-out` for entrances, `ease-in` for exits, `ease-in-out` for state changes.
+
+## Modal Animations
+
+```vue
+<!-- Dialog with fade + scale -->
+<DialogContent class="
+  data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95
+  data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95
+  duration-200
+">
+```
+
+## List Item Animations
+
+```vue
+<TransitionGroup name="list" tag="div">
+  <Card v-for="item in items" :key="item.id">
+    <!-- content -->
+  </Card>
+</TransitionGroup>
+
+<style>
+.list-enter-active { transition: all 0.3s ease-out; }
+.list-leave-active { transition: all 0.2s ease-in; }
+.list-enter-from { opacity: 0; transform: translateY(8px); }
+.list-leave-to { opacity: 0; transform: translateX(-16px); }
+.list-move { transition: transform 0.3s ease; }
+</style>
+```
+
+## Button Loading State
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import { Button } from '@reinvented/design'
+import { Loader2 } from 'lucide-vue-next'
+
+const saving = ref(false)
+async function handleSave() {
+  saving.value = true
+  try {
+    await saveMutation()
+  } finally {
+    saving.value = false
+  }
+}
+</script>
+
+<template>
+  <Button :disabled="saving" @click="handleSave">
+    <Loader2 v-if="saving" class="w-4 h-4 mr-2 animate-spin" />
+    {{ saving ? 'Saving...' : 'Save' }}
+  </Button>
+</template>
+```
+
+## Skeleton Loading
+
+Skeletons must match the shape of the actual content:
+
+```vue
+<!-- Skeleton for a card list -->
+<div class="space-y-4">
+  <div v-for="i in 3" :key="i" class="p-4 border rounded-lg">
+    <div class="flex items-center gap-3">
+      <Skeleton class="w-10 h-10 rounded-full" />
+      <div class="flex-1 space-y-2">
+        <Skeleton class="h-4 w-3/4" />
+        <Skeleton class="h-3 w-1/2" />
+      </div>
+    </div>
+  </div>
+</div>
+```
+
+## Toast Notifications
+
+```vue
+<script setup>
+import { toast } from '@reinvented/design'
+
+// Success
+toast.success('Task created')
+
+// Error with action
+toast.error('Failed to save', {
+  action: { label: 'Retry', onClick: () => handleSave() }
+})
+
+// Promise-based (auto shows loading → success/error)
+toast.promise(saveMutation(), {
+  loading: 'Saving...',
+  success: 'Saved!',
+  error: 'Failed to save'
+})
+</script>
+```
+
+## Focus Management
+
+- **Modal open**: Focus first interactive element inside the modal
+- **Modal close**: Return focus to the trigger element
+- **After delete**: Focus the next item in the list (or empty state)
+- **After create**: Focus the newly created item (or close modal and show toast)
+- **Tab order**: Logical reading order, top-to-bottom, left-to-right
+
+## Hover Effects
+
+```vue
+<!-- Card with hover lift -->
+<Card class="transition-shadow duration-150 hover:shadow-md cursor-pointer">
+
+<!-- Button with subtle scale on press -->
+<Button class="active:scale-[0.98] transition-transform duration-150">
+```
+
+## Optimistic Updates
+
+Use for:
+- Toggles (like/unlike, pin/unpin)
+- Status changes (mark complete)
+- Reordering (drag and drop)
+
+Do NOT use for:
+- Creation (need server-generated ID)
+- Deletion (hard to undo if server rejects)
+- Complex mutations (multiple side effects)