@reinvented/design 0.1.0 → 0.2.1

package/DESIGN_GUIDE.md

@@ -0,0 +1,148 @@
+# Reinvented Design Guide
+
+## Overview
+The Reinvented design system uses **Shadcn-vue** components with custom **Radix-vue** primitives,
+**Tailwind CSS** for styling, and **Lucide** icons. All UI surfaces share this consistent foundation.
+
+---
+
+## Typography
+
+| Token          | Size   | Weight   | Use                    |
+|---------------|--------|----------|------------------------|
+| `text-xs`     | 12px   | 400      | Timestamps, captions   |
+| `text-sm`     | 14px   | 400–500  | Body text, labels      |
+| `text-base`   | 16px   | 400      | Default body           |
+| `text-lg`     | 18px   | 600      | Section headings       |
+| `text-xl`     | 20px   | 600      | Page subtitles         |
+| `text-2xl`    | 24px   | 700      | Page titles            |
+| `text-3xl`    | 30px   | 700      | Hero text              |
+
+**Font:** Inter (loaded via Google Fonts).
+**Line height:** Use `leading-tight` (1.25) for headings, `leading-normal` (1.5) for body.
+
+---
+
+## Colors
+
+Our brand color is **purple** (`hsl(252 100% 63%)`).
+
+| Token            | Light             | Dark              | Use                    |
+|-----------------|-------------------|-------------------|------------------------|
+| `primary`       | Purple 63%        | Purple 69%        | Buttons, links, focus  |
+| `secondary`     | Zinc 96%          | Zinc 16%          | Secondary actions      |
+| `muted`         | Zinc 96%          | Zinc 16%          | Backgrounds, disabled  |
+| `destructive`   | Red 60%           | Red 31%           | Delete, errors         |
+| `success`       | Green 36%         | Green 45%         | Confirmations          |
+| `warning`       | Amber 50%         | Amber 55%         | Alerts                 |
+| `info`          | Blue 60%          | Blue 65%          | Information            |
+
+**Usage rules:**
+- Never hardcode colors — always use `hsl(var(--token))`
+- Use `text-muted-foreground` for secondary text (not arbitrary gray)
+- Apply `bg-card` for card surfaces, `bg-background` for page backgrounds
+
+---
+
+## Spacing
+
+Based on **4px increments**. Use Tailwind utilities:
+
+| Class    | Value | Use                        |
+|----------|-------|----------------------------|
+| `gap-1`  | 4px   | Icon-to-text gap           |
+| `gap-2`  | 8px   | Between small elements     |
+| `gap-3`  | 12px  | Between form fields        |
+| `gap-4`  | 16px  | Section spacing            |
+| `gap-6`  | 24px  | Between major sections     |
+| `p-4`    | 16px  | Standard padding           |
+| `p-6`    | 24px  | Card padding               |
+| `px-4`   | 16px  | Page horizontal padding    |
+
+**Rules:**
+- Always use spacing tokens, never arbitrary values
+- Vertical rhythm: Use `gap-4` or `gap-6` for stacking sections
+- Horizontal rhythm: Use `gap-2` or `gap-3` for inline elements
+
+---
+
+## Icons
+
+- **Library:** Lucide Vue Next (`lucide-vue-next`)
+- **NO emojis** anywhere in the UI
+- Default icon size: `16px` (`w-4 h-4`)
+- In buttons/nav: `w-4 h-4`
+- In empty states: `w-12 h-12` with `text-muted-foreground`
+- Always use `stroke-width="2"` (Lucide default)
+
+---
+
+## Shadows & Borders
+
+| Token       | CSS                            | Use                        |
+|-------------|-------------------------------|----------------------------|
+| `shadow-sm` | Subtle 1px shadow             | Cards, buttons             |
+| `shadow-md` | Medium depth                  | Dropdowns, popovers        |
+| `shadow-lg` | Strong depth                  | Modals, dialogs            |
+| `rounded-md`| `calc(var(--radius) - 2px)`  | Inputs, small elements     |
+| `rounded-lg`| `var(--radius)` (10px)       | Cards, containers          |
+
+---
+
+## Component Guidelines
+
+### When to use existing components
+Always check `@reinvented/design` first:
+```ts
+import { Button, Card, Input, Avatar, Badge } from '@reinvented/design'
+```
+
+### Using Radix primitives
+For Dialog, DropdownMenu, Tabs, Tooltip, PopoverSelect, etc.:
+```ts
+import { Dialog, DialogTrigger, DialogContent, DialogTitle } from '@reinvented/design'
+```
+Style them using `cn()` and Tailwind:
+```vue
+<DialogContent :class="cn('fixed inset-0 z-50 flex items-center justify-center')">
+```
+
+### Building new components
+1. Create in `packages/ds/src/components/ui/<name>/`
+2. Use `cn()` for class merging
+3. Accept `class` prop for customization
+4. Use design tokens (never hardcode colors)
+5. Export from barrel (`src/index.ts`)
+
+---
+
+## Page Patterns
+
+Import from `@reinvented/design/patterns/*`:
+
+| Pattern       | Use                                          |
+|--------------|----------------------------------------------|
+| `ListView`   | Lists with search, filters, items            |
+| `DetailView` | Detail pages with hero, tabs, content        |
+| `FormView`   | Forms with validation and submit             |
+| `EmptyState` | Centered empty state with icon and CTA       |
+
+---
+
+## Dark Mode
+
+- Controlled via `.dark` class on `<html>` or `<body>`
+- All tokens automatically switch in dark mode
+- Test both modes when building surfaces
+- Use `dark:` prefix sparingly — prefer CSS variable-driven theming
+
+---
+
+## Do NOT
+
+- Use `alert()`, `confirm()`, or `prompt()` — use Dialog/AlertDialog
+- Use emojis — use Lucide icons
+- Hardcode colors — use CSS variables
+- Use arbitrary Tailwind values (e.g., `text-[#333]`) — use tokens
+- Create split-screen layouts — use single-column responsive design
+- Use `@apply` excessively — prefer utility classes in templates

package/README.md

@@ -1,179 +1,56 @@
-# @reinvented/design
+# Reinvented Design System
 
-Opinionated design system for the Reinvented platform. Built on **Shadcn/ui + Radix + Tailwind CSS** with a **Linear-inspired** dark-first premium aesthetic.
+The opinionated visual foundation for all Reinvented apps. Components, patterns, layouts, conventions, rules, and documentation.
 
-## Design Principles
-
-- **Dark-first** — Nearly-black backgrounds (`#0a0a0b`) with subtle surface elevation, not obvious cards
-- **Restrained palette** — Mostly grays with one accent color (violet-blue `#5b6af0`), used sparingly on interactive elements
-- **Muted borders** — No heavy shadows in dark mode; borders at 4–16% white opacity
-- **Tight typography** — Inter font, compact scale (11px–36px), 4 main text styles
-- **Smooth animations** — Subtle fade-in, slide-up, scale-in transitions (200ms default)
-- **Consistency-first** — Composition components with locked styling prevent visual drift
-
-## Installation
+## Quick Start
 
 ```bash
-pnpm add @reinvented/design
+npm install @reinvented/design
 ```
 
-Import CSS in your app entry:
-
-```tsx
-import "@reinvented/design/css";
+```vue
+<script setup>
+import { Button, Card, Input, Badge, Dialog } from '@reinvented/design'
+</script>
 ```
 
-## Usage
+## Stack
 
-### Primitives (flexible, accept className)
+- **Components**: [Shadcn-vue](https://www.shadcn-vue.com/) (all components, styled with our tokens)
+- **Primitives**: [Radix Vue](https://www.radix-vue.com/) (accessible headless components)
+- **Styling**: [Tailwind CSS](https://tailwindcss.com/) with design tokens
+- **Icons**: [Lucide Vue Next](https://lucide.dev/) (no emojis, ever)
+- **Typography**: Inter (via Google Fonts)
 
-```tsx
-import { Button, Input, Card, Badge, Dialog } from "@reinvented/design";
+## Structure
 
-<Button variant="primary" size="md">Save</Button>
-<Button variant="ghost" size="sm">Cancel</Button>
-<Input label="Email" placeholder="you@example.com" error="Required" />
-<Badge variant="success">Active</Badge>
 ```
-
-### Composition Components (locked, no className)
-
-These are the **recommended API** — use them for guaranteed visual consistency:
-
-```tsx
-import { ContentCard, PageHeader, ListItem, FormSection, ActionBar, EmptyState } from "@reinvented/design";
-
-<PageHeader title="Settings" description="Manage your account" actions={<Button>Save</Button>} />
-
-<ContentCard title="Profile" description="Your personal information">
-  <Input label="Name" />
-</ContentCard>
-
-<ListItem
-  leading={<UserIcon size={16} />}
-  title="John Doe"
-  description="john@example.com"
-  trailing={<Badge>Admin</Badge>}
-  onClick={() => navigate("/users/1")}
-/>
-
-<EmptyState
-  icon={<InboxIcon size={32} />}
-  title="No items yet"
-  description="Create your first item to get started"
-  action={<Button>Create</Button>}
-/>
+src/
+  components/ui/    All styled components
+  patterns/         Reusable compositions (ListView, DetailView, etc.)
+  layouts/          Page-level layout components with slots
+  lib/              Utilities (cn, etc.)
+  styles/           Tokens, CSS variables
+docs/
+  rules.md          Hard design rules
+  conventions.md    Opinionated UX decisions
+  visual-polish.md  Animations, transitions, polish guidelines
+  components/       Per-component usage guides
+  patterns/         Per-pattern docs with skeleton code
+  layouts/          Per-layout docs with skeleton code
+examples/           Full skeleton examples
 ```
 
-### Layout
-
-```tsx
-import { AppShell, TopBar, SideRail, SideRailItem, PageContainer } from "@reinvented/design";
+## Documentation
 
-<AppShell
-  topBar={<TopBar brand={<Logo />} actions={<Avatar />} />}
-  sideRail={
-    <SideRail>
-      <SideRailItem active tooltip="Home"><HomeIcon size={18} /></SideRailItem>
-      <SideRailItem tooltip="Settings"><SettingsIcon size={18} /></SideRailItem>
-    </SideRail>
-  }
->
-  <PageContainer>
-    {/* Page content */}
-  </PageContainer>
-</AppShell>
-```
-
-### Icons
-
-```tsx
-import { DynamicIcon, Settings, ChevronRight } from "@reinvented/design";
-
-// Static icon
-<Settings size={16} />
-
-// Dynamic icon by name string (for app manager)
-<DynamicIcon name="Settings" size={16} />
-```
-
-### Hooks
-
-```tsx
-import { useTheme, useMediaQuery } from "@reinvented/design";
-
-const { theme, toggleTheme, isDark } = useTheme();
-const isMobile = useMediaQuery("(max-width: 768px)");
-```
-
-### Utilities
-
-```tsx
-import { cn } from "@reinvented/design";
-
-<div className={cn("text-fg-primary", isActive && "text-accent")} />
-```
-
-### Command Palette
-
-```tsx
-import { CommandPalette, CommandGroup, CommandItem, CommandEmpty } from "@reinvented/design";
-
-<CommandPalette placeholder="Search or jump to…">
-  <CommandEmpty>No results found.</CommandEmpty>
-  <CommandGroup heading="Actions">
-    <CommandItem onSelect={() => navigate("/settings")}>Settings</CommandItem>
-  </CommandGroup>
-</CommandPalette>
-// Opens with Cmd+K / Ctrl+K
-```
-
-## Token Reference
-
-| Token | Dark Value | Purpose |
-|-------|-----------|---------|
-| `--bg-base` | `#0a0a0b` | App background |
-| `--bg-surface` | `#111113` | Cards, panels |
-| `--bg-elevated` | `#191a1f` | Dropdowns, popovers |
-| `--fg-primary` | `#ededef` | Primary text |
-| `--fg-secondary` | `#a1a1a6` | Secondary text |
-| `--fg-muted` | `#6e6e76` | Placeholder, hints |
-| `--accent` | `#5b6af0` | Interactive elements |
-| `--border-default` | `rgba(255,255,255,0.08)` | Standard borders |
-
-## Component Catalog
-
-### Primitives
-Button, Input, Badge, Avatar, Card, Label, Dialog, DropdownMenu, Toast, Separator, ScrollArea, Select, Switch, Checkbox, Tabs, Tooltip, Skeleton, Sheet
-
-### Composition (locked)
-ContentCard, PageHeader, ListItem, FormSection, ActionBar, EmptyState
-
-### Layout
-AppShell, TopBar, SideRail, BottomBar, PageContainer
-
-### Feedback & Overlays
-Spinner, ErrorBoundary, CommandPalette
-
-## Tailwind Config
-
-Consuming apps should extend the design system's Tailwind config:
-
-```ts
-// tailwind.config.ts in your app
-import designConfig from "@reinvented/design/tailwind";
-
-export default {
-  presets: [designConfig],
-  content: [
-    "./src/**/*.{ts,tsx}",
-    "../../packages/design/src/**/*.{ts,tsx}",
-  ],
-};
-```
+- **[Rules](docs/rules.md)** — Non-negotiable design constraints
+- **[Conventions](docs/conventions.md)** — Opinionated UX decisions
+- **[Visual Polish](docs/visual-polish.md)** — Animation and polish guide
+- **[Components](docs/components/index.md)** — Component usage guides
+- **[Patterns](docs/patterns/index.md)** — Reusable UI patterns
+- **[Layouts](docs/layouts/index.md)** — Page layout recipes
+- **[Design Guide](DESIGN_GUIDE.md)** — Tokens, typography, colors, spacing
 
-## Adding New Components
+## Contributing
 
-1. Create the component in `src/components/`
-2. Export it from `src/index.ts`
-3. Run `pnpm build` to verify
+Agents and humans can propose changes via PRs. See [conventions](docs/conventions.md) for design principles.

package/docs/components/alert-dialog.md

@@ -0,0 +1,32 @@
+# AlertDialog
+## When to Use
+- Destructive action confirmation (delete, remove, irreversible changes)
+
+## Skeleton Code
+```vue
+<script setup>
+import { AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogTitle, AlertDialogTrigger, Button } from '@reinvented/design'
+</script>
+
+<template>
+  <AlertDialog>
+    <AlertDialogTrigger as-child>
+      <Button variant="destructive">Delete</Button>
+    </AlertDialogTrigger>
+    <AlertDialogContent>
+      <AlertDialogHeader>
+        <AlertDialogTitle>Are you sure?</AlertDialogTitle>
+        <AlertDialogDescription>This action cannot be undone.</AlertDialogDescription>
+      </AlertDialogHeader>
+      <AlertDialogFooter>
+        <AlertDialogCancel>Cancel</AlertDialogCancel>
+        <AlertDialogAction>Delete Item</AlertDialogAction>
+      </AlertDialogFooter>
+    </AlertDialogContent>
+  </AlertDialog>
+</template>
+```
+
+## Gotchas
+- Action button text must describe what it does ("Delete Task", not "OK")
+- Cancel is always the default focused element

package/docs/components/avatar.md

@@ -0,0 +1,14 @@
+# Avatar
+## Skeleton Code
+```vue
+<script setup>
+import { Avatar } from '@reinvented/design'
+</script>
+<template>
+  <Avatar src="/user.jpg" alt="User name" />
+  <Avatar>JD</Avatar> <!-- Fallback initials -->
+</template>
+```
+## Gotchas
+- Always provide `alt` text for accessibility
+- Fallback shows slot content when `src` fails to load

package/docs/components/badge.md

@@ -0,0 +1,24 @@
+# Badge
+## Variants
+| Variant | Use for |
+|---------|---------|
+| `default` | Neutral status |
+| `secondary` | Subtle labels |
+| `destructive` | Error/danger status |
+| `outline` | Bordered labels |
+
+## Skeleton Code
+```vue
+<script setup>
+import { Badge } from '@reinvented/design'
+</script>
+<template>
+  <Badge>Active</Badge>
+  <Badge variant="destructive">Error</Badge>
+  <Badge variant="secondary">Draft</Badge>
+  <Badge variant="outline">v1.2</Badge>
+</template>
+```
+## Gotchas
+- Use for status indicators, never for interactive actions (use Button for that)
+- Keep text short (1-2 words)

package/docs/components/button.md

@@ -0,0 +1,69 @@
+# Button
+
+## Variants
+| Variant | Use for |
+|---------|---------|
+| `default` | Primary actions |
+| `secondary` | Secondary actions |
+| `destructive` | Delete, remove, cancel |
+| `outline` | Tertiary actions |
+| `ghost` | Toolbar actions, icon-only buttons |
+| `link` | Inline text actions |
+| `success` | Positive confirmation actions |
+
+## Sizes
+| Size | Use for |
+|------|---------|
+| `default` | Standard buttons |
+| `xs` | Compact UI, inline actions |
+| `sm` | Compact UI, table rows |
+| `lg` | Hero CTAs, empty state actions |
+| `xl` | Landing page CTAs |
+| `icon` | Icon-only square buttons |
+
+## Skeleton Code
+
+```vue
+<script setup>
+import { Button } from '@reinvented/design'
+</script>
+
+<template>
+  <Button>Default</Button>
+  <Button variant="secondary">Secondary</Button>
+  <Button variant="destructive">Delete</Button>
+  <Button variant="outline">Outline</Button>
+  <Button variant="ghost">Ghost</Button>
+  <Button size="sm">Small</Button>
+  <Button size="icon"><Trash2 class="w-4 h-4" /></Button>
+</template>
+```
+
+## With 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>
+```
+
+## Gotchas
+- Always provide `aria-label` for icon-only buttons
+- Use `type="button"` to prevent form submission unless intended
+- Use `as="a"` prop to render as a link element with button styling

package/docs/components/card.md

@@ -0,0 +1,49 @@
+# Card
+
+## Sub-components
+| Component | Use for |
+|-----------|---------|
+| `Card` | Container wrapper |
+| `CardHeader` | Title + description area |
+| `CardTitle` | Main heading |
+| `CardDescription` | Subtitle or description |
+| `CardContent` | Main content area |
+| `CardFooter` | Actions area |
+
+## Skeleton Code
+
+```vue
+<script setup>
+import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter, Button } from '@reinvented/design'
+</script>
+
+<template>
+  <Card>
+    <CardHeader>
+      <CardTitle>Card Title</CardTitle>
+      <CardDescription>Card description text</CardDescription>
+    </CardHeader>
+    <CardContent>
+      <p>Card content goes here</p>
+    </CardContent>
+    <CardFooter>
+      <Button>Action</Button>
+    </CardFooter>
+  </Card>
+</template>
+```
+
+## Clickable Card
+
+```vue
+<template>
+  <Card class="transition-shadow duration-150 hover:shadow-md cursor-pointer" @click="navigate">
+    <!-- content -->
+  </Card>
+</template>
+```
+
+## Gotchas
+- Don't nest cards inside cards
+- Use `CardFooter` for actions, not `CardContent`
+- Apply hover styles via `class` prop, not custom CSS

package/docs/components/dialog.md

@@ -0,0 +1,46 @@
+# Dialog
+## When to Use
+- Simple create/edit forms (≤ 5 fields)
+- Confirmations
+- Quick actions that keep page context
+
+When NOT to use: Forms with 8+ fields (use full page), rich content editing (use full page).
+
+## Sub-components
+`Dialog`, `DialogTrigger`, `DialogContent`, `DialogHeader`, `DialogFooter`, `DialogTitle`, `DialogDescription`, `DialogClose`, `DialogScrollContent`
+
+## Skeleton Code
+```vue
+<script setup>
+import { Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger, Button, Input, Label } from '@reinvented/design'
+</script>
+
+<template>
+  <Dialog>
+    <DialogTrigger as-child>
+      <Button>Create Item</Button>
+    </DialogTrigger>
+    <DialogContent>
+      <DialogHeader>
+        <DialogTitle>Create New Item</DialogTitle>
+        <DialogDescription>Fill in the details below.</DialogDescription>
+      </DialogHeader>
+      <div class="grid gap-4 py-4">
+        <div class="space-y-2">
+          <Label for="name">Name</Label>
+          <Input id="name" placeholder="Item name" />
+        </div>
+      </div>
+      <DialogFooter>
+        <Button variant="outline">Cancel</Button>
+        <Button>Save</Button>
+      </DialogFooter>
+    </DialogContent>
+  </Dialog>
+</template>
+```
+
+## Gotchas
+- Use `as-child` on `DialogTrigger` to avoid nested buttons
+- For long content, use `DialogScrollContent` instead of `DialogContent`
+- Always include `DialogTitle` for accessibility (even if visually hidden)

package/docs/components/dropdown-menu.md

@@ -0,0 +1,32 @@
+# DropdownMenu
+## When to Use
+- Action menus on items (edit, delete, share)
+- User profile menus
+- More options (...) buttons
+
+## Skeleton Code
+```vue
+<script setup>
+import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuTrigger, Button } from '@reinvented/design'
+import { MoreHorizontal, Pencil, Trash2 } from 'lucide-vue-next'
+</script>
+
+<template>
+  <DropdownMenu>
+    <DropdownMenuTrigger as-child>
+      <Button variant="ghost" size="icon"><MoreHorizontal class="w-4 h-4" /></Button>
+    </DropdownMenuTrigger>
+    <DropdownMenuContent align="end">
+      <DropdownMenuLabel>Actions</DropdownMenuLabel>
+      <DropdownMenuSeparator />
+      <DropdownMenuItem><Pencil class="mr-2 h-4 w-4" /> Edit</DropdownMenuItem>
+      <DropdownMenuItem class="text-destructive"><Trash2 class="mr-2 h-4 w-4" /> Delete</DropdownMenuItem>
+    </DropdownMenuContent>
+  </DropdownMenu>
+</template>
+```
+
+## Gotchas
+- Use `align="end"` for right-aligned menus
+- Use `as-child` on trigger to compose with existing buttons
+- Destructive items should use `class="text-destructive"`