@reinvented/design 0.1.0 → 0.2.0

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/index.md

@@ -0,0 +1,50 @@
+# Components Index
+
+Usage guides for `@reinvented/design` components. Read individual files for detailed usage, gotchas, and skeleton code.
+
+## Styled Components
+
+| Component | File | Use for |
+|-----------|------|---------|
+| [Button](button.md) | `button.md` | All clickable actions |
+| [Card](card.md) | `card.md` | Content containers, list items |
+| [Input](input.md) | `input.md` | Text input fields |
+| [Badge](badge.md) | `badge.md` | Status indicators, counts, tags |
+| [Avatar](avatar.md) | `avatar.md` | User/entity profile images |
+| [Separator](separator.md) | `separator.md` | Visual dividers |
+| [Skeleton](skeleton.md) | `skeleton.md` | Loading placeholders |
+| [ScrollArea](scroll-area.md) | `scroll-area.md` | Custom scrollable regions |
+
+## Radix Primitives (styled via Tailwind + tokens)
+
+These are re-exported from radix-vue. Use with `cn()` and design tokens.
+
+| Component | Use for |
+|-----------|---------|
+| Dialog | Modal dialogs (create, edit, confirm) |
+| AlertDialog | Destructive action confirmation |
+| DropdownMenu | Context menus, action menus |
+| Select | Single-value selection |
+| Tabs | Section navigation within a view |
+| Tooltip | Hover hints |
+| Popover | Rich hover/click content |
+| Accordion | Collapsible sections |
+| Switch | On/off toggles |
+| Checkbox | Multi-select options |
+| RadioGroup | Single-select from options |
+| Progress | Progress indicators |
+| Slider | Range input |
+| Collapsible | Show/hide content blocks |
+| ContextMenu | Right-click menus |
+| NavigationMenu | Top-level navigation |
+| HoverCard | Rich hover preview |
+| ToggleGroup | Grouped toggles |
+| Pagination | Page navigation |
+
+## External Re-exports
+
+| Component | From | Use for |
+|-----------|------|---------|
+| Toaster / toast | vue-sonner | Toast notifications |
+
+> **Note**: Many primitives above need proper styled wrappers (like Button, Card, etc. have). See [rules.md](../rules.md) — agents should always use DS components, never raw HTML elements.

package/docs/conventions.md

@@ -0,0 +1,74 @@
+# UX Conventions
+
+Opinionated design decisions that ensure consistency across all Reinvented apps.
+
+## Create/Edit Flows
+
+| Scenario | Pattern | Why |
+|----------|---------|-----|
+| Simple form (≤ 5 fields) | Modal dialog | Fast, keeps context |
+| Medium form (6–8 fields) | Modal dialog with sections | Still fits in a modal |
+| Complex form (8+ fields) | Full page | Too much for a modal |
+| Rich content editing (markdown, images) | Full page | Needs space and toolbars |
+| Single-field update (e.g., rename) | Inline editing (click-to-edit) | Minimal friction |
+| Toggle/switch (enable/disable) | Inline toggle | Immediate feedback |
+| Status change | Inline dropdown or button group | Immediate feedback |
+
+**Default: modal.** Only escalate to full page when the modal becomes cramped.
+
+## Delete/Destructive Actions
+
+1. Always use `<AlertDialog>` with explicit confirmation
+2. Confirm button must say what it does: "Delete Task" not "OK"
+3. Cancel button is always the default focus
+4. Consider "undo via toast" for low-risk deletions instead of pre-confirmation
+
+## Navigation
+
+- **Back button**: Always present on detail views. Uses router history, not hardcoded routes
+- **Breadcrumbs**: Use on 3+ level deep hierarchies
+- **Tabs**: Use for related content within a single view (e.g., "Overview / Activity / Settings")
+- **Bottom navigation**: Mobile only, max 5 items
+
+## Information Hierarchy
+
+- **Page title**: `text-2xl font-bold` — one per page, describes the primary content
+- **Section headings**: `text-lg font-semibold` — group related content
+- **Cards**: Use to visually separate distinct content blocks
+- **Secondary text**: Always `text-muted-foreground`, never arbitrary gray
+
+## Empty States
+
+Every empty state must have:
+1. A relevant Lucide icon (`w-12 h-12 text-muted-foreground`)
+2. A title explaining what goes here
+3. A description explaining how to get started
+4. A primary CTA button
+
+## Loading States
+
+- **Page/section load**: Skeleton shapes matching the real content layout
+- **Button during mutation**: Spinner icon + disabled state
+- **Optimistic updates**: Use for toggles, status changes, likes — anything easily reversible
+- **Never**: bare spinner with no context. Always indicate WHAT is loading
+
+## Error States
+
+- **Query failures**: `<Alert variant="destructive">` with error message + retry button
+- **Mutation failures**: Toast notification with error message + retry action
+- **Form validation**: Inline field errors below the input, shown on blur or submit
+- **Network offline**: Banner at top of page
+
+## Responsive Behavior
+
+| Breakpoint | Width | Behavior |
+|------------|-------|----------|
+| Mobile | < 640px | Single column, bottom sheets, stacked cards |
+| Tablet | 640-1024px | Two columns possible, side panels collapse |
+| Desktop | > 1024px | Full layout, side panels open |
+
+## Consistency
+
+- Same object type → same card component everywhere
+- Same action → same pattern everywhere (e.g., all "delete" flows use AlertDialog)
+- Same icon → same meaning everywhere (e.g., Trash2 always means delete)

package/docs/layouts/index.md

@@ -0,0 +1,32 @@
+# Layouts Index
+
+Page-level layout components with slots. Each layout is a Vue component in `src/layouts/` AND documented here with skeleton code and usage guidance.
+
+## Available Layouts
+
+| Layout | File | Use for |
+|--------|------|---------|
+| [List Page](list-page.md) | `list-page.md` | Browsing collections (tasks, members, notifications) |
+| [Detail Page](detail-page.md) | `detail-page.md` | Viewing a single item with full context |
+| [Dashboard](dashboard.md) | `dashboard.md` | Overview with stats, charts, recent activity |
+| [Modal Form](modal-form.md) | `modal-form.md` | Create/edit dialogs with form fields |
+| [Settings Page](settings-page.md) | `settings-page.md` | Configuration with sectioned form |
+
+## Choosing a Layout
+
+```
+What is the user doing?
+  ├── Browsing a list of things → List Page
+  ├── Looking at one specific thing → Detail Page
+  ├── Getting an overview / summary → Dashboard
+  ├── Creating or editing something → Modal Form (default) or Settings Page (complex)
+  └── Configuring settings → Settings Page
+```
+
+## Layout Component Structure
+
+All layout components follow the same convention:
+- Accept a `class` prop for customization
+- Use named slots for content areas (header, content, footer, etc.)
+- Handle responsive breakpoints internally
+- Use DS tokens for spacing and typography

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