@reinvented/design 1.0.0 → 1.1.0

package/skills/components/tabs.md

@@ -0,0 +1,105 @@
+# Tabs, Accordion, Collapsible
+
+Content organization components for showing/hiding sections.
+
+```ts
+import { Tabs, TabsList, TabsTrigger, TabsContent } from '@reinvented/design'
+import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from '@reinvented/design'
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '@reinvented/design'
+```
+
+## Tabs
+
+Switch between related content panels within a single view.
+
+```tsx
+<Tabs default-value="overview" className="w-full">
+  <TabsList>
+    <TabsTrigger value="overview">Overview</TabsTrigger>
+    <TabsTrigger value="analytics">Analytics</TabsTrigger>
+    <TabsTrigger value="settings">Settings</TabsTrigger>
+  </TabsList>
+  <TabsContent value="overview" className="mt-4">
+    <!-- Overview content -->
+  </TabsContent>
+  <TabsContent value="analytics" className="mt-4">
+    <!-- Analytics content -->
+  </TabsContent>
+  <TabsContent value="settings" className="mt-4">
+    <!-- Settings content -->
+  </TabsContent>
+</Tabs>
+```
+
+### When to Use Tabs
+- **Related content within one entity**: (Overview / Activity / Settings for a project)
+- **Alternative views of same data**: (Table / Cards / Chart views)
+- **3–6 tabs maximum** — if you need more, use sidebar navigation instead
+
+### Tabs with Counts
+```tsx
+<TabsTrigger value="open">
+  Open <Badge variant="secondary" className="ml-1.5">12</Badge>
+</TabsTrigger>
+```
+
+## Accordion
+
+Vertically stacked sections that expand/collapse. Use for FAQs, settings groups, or long lists of optional content.
+
+```tsx
+<Accordion type="single" collapsible className="w-full">
+  <AccordionItem value="item-1">
+    <AccordionTrigger>General Settings</AccordionTrigger>
+    <AccordionContent>
+      <!-- Settings content -->
+    </AccordionContent>
+  </AccordionItem>
+  <AccordionItem value="item-2">
+    <AccordionTrigger>Notifications</AccordionTrigger>
+    <AccordionContent>
+      <!-- Notification settings -->
+    </AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+### Accordion Types
+| Type | Behavior | When to Use |
+|------|----------|-------------|
+| `type="single" collapsible` | One item open at a time, can close all | Default for most use cases |
+| `type="multiple"` | Multiple items can be open simultaneously | FAQ pages, filter groups |
+
+## Collapsible
+
+Single expand/collapse section. Use for "show more" or optional advanced content.
+
+```tsx
+<Collapsible v-model:open="isOpen">
+  <div className="flex items-center justify-between">
+    <h4 className="text-sm font-semibold">Advanced Options</h4>
+    <CollapsibleTrigger as-child>
+      <Button variant="ghost" size="icon" className="h-8 w-8">
+        <ChevronsUpDown className="w-4 h-4" />
+      </Button>
+    </CollapsibleTrigger>
+  </div>
+  <CollapsibleContent className="mt-2 space-y-2">
+    <!-- Hidden content -->
+  </CollapsibleContent>
+</Collapsible>
+```
+
+## Decision Tree
+```
+Are these related panels for the same entity?
+├─ Yes → Tabs
+├─ No
+│  ├─ Multiple expandable sections (FAQ, settings)? → Accordion
+│  └─ Single "show more" section? → Collapsible
+```
+
+## Anti-Patterns (DO NOT DO)
+
+- ❌ **Do not hack Tab internals**: Never manually override the paddings, heights, or active states of `<TabsList>` or `<TabsTrigger>` (e.g., adding `h-7 px-0` to a trigger or `h-8 p-0` to a list). This will break text wrapping and ruin the layout, especially if the trigger contains an icon. Shadcn components are designed to work out-of-the-box.
+- ❌ **Do not hardcode active states**: Never use `data-[state=active]:bg-warning` to invent custom active tab indicators on the fly. The component handles its own accessible active state natively.

package/skills/components/utilities.md

@@ -0,0 +1,138 @@
+# Utility Components
+
+Separator, Skeleton, Toggle, ToggleGroup, Command, and ComponentPlaceholder (Mockup Mode Only).
+
+```ts
+import { Separator } from '@reinvented/design'
+import { Skeleton } from '@reinvented/design'
+import { Toggle } from '@reinvented/design'
+import { ToggleGroup, ToggleGroupItem } from '@reinvented/design'
+import { Command, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator } from '@reinvented/design'
+import { ComponentPlaceholder } from '@reinvented/design'
+```
+
+## Separator
+
+Visual divider between content sections.
+
+```tsx
+<Separator />                                    <!-- Horizontal (default) -->
+<Separator orientation="vertical" className="h-4" /> <!-- Vertical -->
+```
+
+Use between form sections, within cards to divide content groups, in dropdown menus (`DropdownMenuSeparator`).
+
+## Skeleton
+
+Loading placeholders. Must match the shape and layout of the actual content they replace.
+
+```tsx
+<!-- User list item skeleton -->
+<div className="flex items-center gap-3 p-4">
+  <Skeleton className="w-10 h-10 rounded-full" />
+  <div className="flex-1 space-y-2">
+    <Skeleton className="h-4 w-3/4" />
+    <Skeleton className="h-3 w-1/2" />
+  </div>
+</div>
+
+<!-- Stat card skeleton -->
+<Card>
+  <CardHeader className="pb-2">
+    <Skeleton className="h-4 w-24" />
+  </CardHeader>
+  <CardContent>
+    <Skeleton className="h-8 w-20 mb-1" />
+    <Skeleton className="h-3 w-32" />
+  </CardContent>
+</Card>
+
+<!-- Table row skeleton -->
+<TableRow>
+  <TableCell><Skeleton className="h-4 w-32" /></TableCell>
+  <TableCell><Skeleton className="h-4 w-48" /></TableCell>
+  <TableCell><Skeleton className="h-5 w-16 rounded-full" /></TableCell>
+  <TableCell className="text-right"><Skeleton className="h-4 w-16 ml-auto" /></TableCell>
+</TableRow>
+```
+
+Rules:
+- Skeletons must mirror the real content's shape, size, and position
+- Show 3–5 skeleton items for lists
+- Use `rounded-full` for avatar skeletons, `rounded-md` for badges
+
+## Toggle & ToggleGroup
+
+Pressed/unpressed state buttons. Use for view switching or formatting toolbar buttons.
+
+```tsx
+<!-- Single toggle -->
+<Toggle aria-label="Toggle bold">
+  <Bold className="w-4 h-4" />
+</Toggle>
+
+<!-- View switcher -->
+<ToggleGroup type="single" defaultValue="viewMode">
+  <ToggleGroupItem value="grid" aria-label="Grid view">
+    <LayoutGrid className="w-4 h-4" />
+  </ToggleGroupItem>
+  <ToggleGroupItem value="list" aria-label="List view">
+    <List className="w-4 h-4" />
+  </ToggleGroupItem>
+</ToggleGroup>
+```
+
+## Command
+
+Searchable command palette / combobox. Use for command-K menus or searchable selection lists.
+
+```tsx
+<Command className="rounded-lg border shadow-md">
+  <CommandInput placeholder="Type a command or search..." />
+  <CommandList>
+    <CommandEmpty>No results found.</CommandEmpty>
+    <CommandGroup heading="Suggestions">
+      <CommandItem>
+        <Calendar className="w-4 h-4" /> Calendar
+      </CommandItem>
+      <CommandItem>
+        <Search className="w-4 h-4" /> Search
+      </CommandItem>
+    </CommandGroup>
+    <CommandSeparator />
+    <CommandGroup heading="Settings">
+      <CommandItem>
+        <Settings className="w-4 h-4" /> Settings
+      </CommandItem>
+    </CommandGroup>
+  </CommandList>
+</Command>
+```
+
+For a command-K dialog, wrap in `Dialog`:
+```tsx
+<Dialog>
+  <DialogContent className="p-0">
+    <Command>
+      <!-- ... -->
+    </Command>
+  </DialogContent>
+</Dialog>
+```
+
+## ComponentPlaceholder (Mockup Mode Only)
+
+In mockup mode, use this when a component doesn't exist in the DS (charts, maps, rich text editors, video players). In production, use actual third-party libraries instead.
+
+```tsx
+<ComponentPlaceholder
+  name="AreaChart"
+  description="Revenue trend over the last 12 months with monthly breakdown"
+  height="300px"
+/>
+```
+
+Always provide:
+- `name`: What the component would be called
+- `description`: What it would show (specific enough to communicate the intent)
+- `height`: Approximate height to reserve in the layout

package/skills/devices/desktop.md

@@ -0,0 +1,43 @@
+# Device: Desktop
+
+Viewport ≥ 768px. This covers standard laptops, large monitors, and tablets (which behave like small desktops in landscape).
+
+## Breakpoints Used
+
+| Prefix | Min Width | Usage |
+|--------|-----------|-------|
+| `sm:` | 640px | 2-column grids, side-by-side buttons |
+| `md:` | 768px | Desktop layout kicks in — sidebars, multi-panel |
+| `lg:` | 1024px | Full multi-column grids (3-4 cols), wide content areas |
+| `xl:` | 1280px | Max-width containers fully visible |
+
+## Layout Rules
+
+- **Content container**: Always constrain width with `max-w-7xl mx-auto px-6` — don't let lines of text span 1400px+
+- **Sidebar**: Use `w-64` (256px), visible from `md:` breakpoint up
+- **Grids**: 2 cols at `sm:`, 3 cols at `lg:`, 4 cols at `lg:` for stat cards
+- **Spacing**: Standard `gap-4` for grids, `gap-6` to `gap-8` between major sections
+- **Side-by-side panels**: List-detail layouts work well on desktop
+
+## Responsive Pattern Summary
+
+```html
+<!-- Grid: stack → 2 → 3 cols -->
+className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4"
+
+<!-- Stack on small, row on larger -->
+className="flex flex-col sm:flex-row gap-4"
+
+<!-- Page header: stack on small, row on larger -->
+className="flex flex-col sm:flex-row sm:items-center justify-between gap-4"
+
+<!-- Full width on mobile, auto on desktop -->
+className="w-full sm:w-auto"
+```
+
+## Tablets
+
+Tablets in landscape (1024px+) behave like desktops. Tablets in portrait (768–1024px) may need:
+- `md:` breakpoint adjustments (sidebar visible but narrower, or use Sheet drawer)
+- Touch-friendly targets: keep interactive elements at `h-10` (40px) minimum
+- The standard responsive grid system handles tablet seamlessly — no special treatment needed

package/skills/devices/mobile.md

@@ -0,0 +1,77 @@
+# Device: Mobile
+
+Viewport < 768px. Smartphones in portrait mode.
+
+## Core Principles
+
+Everything is single-column. Touch targets are large. Navigation is simplified.
+
+## Layout Adaptations
+
+### No Sidebar
+Replace sidebar navigation with one of:
+
+**Bottom tabs** (recommended for consumer apps, max 5 items):
+*Note: Only include bottom nav if you are explicitly generating a full app shell. For specific inner views, omit top/bottom root navigation.*
+```tsx
+<nav className="fixed bottom-0 left-0 right-0 border-t bg-card z-50">
+  <div className="flex items-center justify-around h-14">
+    <button v-for="tab in tabs" :key="tab.label"
+            className={cn('flex flex-col items-center gap-1 p-2 text-xs transition-colors',
+              tab.active ? 'text-primary' : 'text-muted-foreground')}>
+      <component :is="tab.icon" className="w-5 h-5" />
+      <span>{{ tab.label }}</span>
+    </button>
+  </div>
+</nav>
+<!-- Add pb-16 to main content to clear bottom nav -->
+```
+
+**Hamburger menu** (for complex apps):
+```tsx
+<Sheet>
+  <SheetTrigger as-child>
+    <Button variant="ghost" size="icon">
+      <Menu className="w-5 h-5" />
+    </Button>
+  </SheetTrigger>
+  <SheetContent side="left" className="w-64 p-0">
+    <!-- Reuse sidebar nav content -->
+  </SheetContent>
+</Sheet>
+```
+
+### Single Column Everything
+```html
+className="grid grid-cols-1 gap-4"     <!-- All grids collapse to 1 column -->
+className="px-4 py-6"                  <!-- Tighter page padding than desktop -->
+```
+
+### Component Swaps
+
+| Desktop Pattern | Mobile Alternative |
+|----------------|-------------------|
+| Data table | Card list (stacked cards with key info) |
+| Dialog | Bottom Sheet (`Sheet side="bottom"`) |
+| Horizontal toolbar | Simplified — fewer filters, icon-only buttons |
+| Side-by-side panels | Drill-down navigation (list page → detail page) |
+| Dropdown menus | Bottom Sheet action list |
+| Stat cards (4 cols) | 2-column grid or horizontal scroll |
+
+### Touch Targets
+- **Minimum 44px** height (`h-11`) for all tappable elements
+- Use `size="lg"` buttons for primary actions
+- No hover-dependent interactions — everything must work on tap
+
+### Content Adjustments
+- **Content padding**: `px-4` (not `px-6`)
+- **Page titles**: `text-xl font-bold` (slightly smaller than desktop's `text-2xl`)
+- **Tables → cards**: Replace tabular data with stacked card layouts showing key fields
+- **Button groups**: Stack vertically with `w-full` on each button
+
+## Rules
+- Maximum 5 bottom tab items
+- No hover-only interactions — everything must be accessible via tap
+- Full-width primary action buttons
+- Bottom Sheet instead of Dialog for most interactions
+- `pb-16` on main content when using fixed bottom navigation

package/skills/foundation/design-principles.md

@@ -0,0 +1,77 @@
+# Design Principles
+
+These principles define what "good" looks like. Every decision should trace back to one of these.
+
+## 1. Quiet Confidence
+
+The UI should feel assured, not loud. Avoid heavy borders, intense shadows, and saturated backgrounds. Instead, use:
+- Subtle `border-border` borders (1px, muted)
+- Minimal shadows (`shadow-sm` on cards, `shadow-lg` only on overlays)
+- Generous whitespace that lets content breathe
+- A restrained color palette where `primary` is used sparingly for key actions
+
+**Good**: A clean card with a thin border, a clear title, and a well-spaced content area.
+**Bad**: A card with a thick colored border, a gradient header, heavy drop shadow, and cramped content.
+
+## 2. Clear Visual Hierarchy
+
+Every view must have an obvious reading order. Achieve this through:
+- **One `text-2xl font-bold` page title** per view — the most prominent text element
+- **Section headings at `text-lg font-semibold`** — clearly subordinate to the page title
+- **Body text at `text-sm`** — the default reading size
+- **Secondary text always uses `text-muted-foreground`** — visually recedes
+- **Primary actions stand out** — use the default Button variant; secondary actions use `variant="outline"` or `variant="ghost"`
+
+The eye should flow: Title → Stats/Summary → Primary Content → Secondary Content → Actions.
+
+## 3. Purposeful Density
+
+Show enough content to feel real, but not so much that it overwhelms:
+
+| Element | Too sparse | Right | Too dense |
+|---------|-----------|-------|-----------|
+| Table rows | 1–2 | 5–8 | 20+ without pagination |
+| Stat cards | 1 | 3–4 | 8+ |
+| Sidebar links | 1–2 | 4–7 | 15+ |
+| Form fields per section | 1 | 3–5 | 10+ without grouping |
+
+## 4. Consistent Rhythm
+
+Pages should have a predictable spatial cadence:
+- **Within a group** (e.g., label + input): `gap-2` (8px)
+- **Between items** (e.g., cards in a list): `gap-4` (16px)
+- **Between sections** (e.g., header → content → footer): `gap-6` (24px) or `gap-8` (32px)
+
+Never use the same gap for all three levels. The contrast creates hierarchy.
+
+## 5. Component-First
+
+Never write raw HTML when a design system component exists. Every `<button>` must be `<Button>`, every `<input>` must be `<Input>`, every `<select>` must be `<Select>`. The design system components carry the correct tokens, accessibility attributes, and interaction states.
+
+## 6. Token-Driven Color
+
+Never hardcode colors. The token system ensures light/dark mode compatibility:
+- Page backgrounds: `bg-background`
+- Card surfaces: `bg-card`
+- Primary text: `text-foreground`
+- Secondary text: `text-muted-foreground`
+- Borders: `border-border`
+- Primary actions: `bg-primary text-primary-foreground`
+- Destructive actions: `bg-destructive text-destructive-foreground`
+
+## 7. Resilient States
+
+Every view must handle four states:
+1. **Loading**: Skeleton placeholders matching the shape of real content
+2. **Empty**: Centered icon + title + description + CTA button
+3. **Error**: Alert banner with retry action, or toast for mutations
+4. **Populated**: The primary UI with realistic data
+
+## 8. Invisible Polish
+
+The best UIs feel good without the user knowing why. This comes from:
+- **Hover states on interactive elements**: `hover:bg-accent/50` on clickable cards, `hover:bg-accent` on list items
+- **Smooth transitions**: `transition-colors duration-150` on all interactive elements
+- **Proper cursor**: `cursor-pointer` on clickable elements
+- **Focus rings**: Built into DS components via `ring` token
+- **Consistent icon sizing**: `w-4 h-4` inline, `w-5 h-5` in nav, `w-12 h-12` in empty states

package/skills/foundation/design-tokens.md

@@ -0,0 +1,121 @@
+# Design Tokens
+
+All values are defined as CSS custom properties and exposed through Tailwind utility classes. Never hardcode colors, spacing, or typography — always use tokens.
+
+## Colors
+
+Brand color is **Emerald green**.
+
+### Semantic Color Tokens
+
+| Token | Tailwind Classes | Light Value | Dark Value | When to Use |
+|-------|-----------------|-------------|------------|-------------|
+| `background` | `bg-background` | White | Near-black `hsl(240 10% 3.9%)` | Page backgrounds |
+| `foreground` | `text-foreground` | Near-black | Near-white | Primary text |
+| `card` | `bg-card` | White | Near-black | Card and container surfaces |
+| `card-foreground` | `text-card-foreground` | Near-black | Near-white | Text inside cards |
+| `primary` | `bg-primary`, `text-primary` | Emerald `hsl(160 84% 39%)` | Brighter emerald `hsl(160 84% 45%)` | Primary buttons, links, active states |
+| `primary-foreground` | `text-primary-foreground` | White | White | Text on primary backgrounds |
+| `secondary` | `bg-secondary` | Light zinc | Dark zinc `hsl(240 3.7% 15.9%)` | Secondary buttons, subtle backgrounds |
+| `secondary-foreground` | `text-secondary-foreground` | Dark | Light | Text on secondary backgrounds |
+| `muted` | `bg-muted` | Light zinc | Dark zinc | Muted backgrounds, disabled states, chip backgrounds |
+| `muted-foreground` | `text-muted-foreground` | Medium gray | Light gray | Secondary text, captions, timestamps, placeholders |
+| `accent` | `bg-accent` | Light zinc | Dark zinc | Hover backgrounds for list items, nav items |
+| `destructive` | `bg-destructive` | Red | Darker red | Delete buttons, error states |
+| `border` | `border-border` | Light gray | Dark gray | All borders |
+| `input` | `border-input` | Light gray | Dark gray | Input field borders |
+| `ring` | `ring-ring` | Emerald | Emerald | Focus rings |
+
+### Status Colors
+
+| Token | Tailwind Classes | When to Use |
+|-------|-----------------|-------------|
+| `success` | `bg-success text-success-foreground` | Confirmation badges, success alerts |
+| `warning` | `bg-warning text-warning-foreground` | Warning badges, caution alerts |
+| `info` | `bg-info text-info-foreground` | Informational badges, info alerts |
+
+### Color Usage Rules
+
+- **Primary** (`bg-primary`): Use sparingly — only for the main CTA button, active nav items, and key interactive elements. Overusing primary color makes the UI feel noisy.
+- **Muted foreground** (`text-muted-foreground`): The workhorse for secondary text. Use for descriptions, timestamps, helper text, table column headers.
+- **Accent** (`bg-accent`): Hover/active state background for interactive list items and nav links. Not for static content.
+- **Destructive** (`bg-destructive`): Only for genuinely destructive actions (delete, remove). Never for warnings.
+- **NEVER invent new semantic solid colors**: Do not stack arbitrary Tailwind utilities (e.g., `bg-green-500` or `bg-blue-500`) to create custom filled buttons or alerts. Stick ONLY to `primary`, `secondary`, `destructive`, `muted`, or `warning/success/info`.
+- **NEVER use filled backgrounds for icons**: Icons should generally be transparent with `text-muted-foreground` or `text-primary`. Do not place icons inside saturated `bg-color/10` or solid colored squares/circles (especially in Stat Cards) as it breaks the Shadcn aesthetic.
+
+## Typography
+
+Font: **Inter** (loaded via Google Fonts, fallback: system sans-serif).
+
+| Class | Size | Weight | Use |
+|-------|------|--------|-----|
+| `text-3xl font-bold` | 30px / Bold | 700 | Hero headings (rare, marketing pages) |
+| `text-2xl font-bold` | 24px / Bold | 700 | Page titles — exactly one per view |
+| `text-xl font-semibold` | 20px / Semibold | 600 | Page subtitles (under the title) |
+| `text-lg font-semibold` | 18px / Semibold | 600 | Section headings inside a page |
+| `text-base` | 16px / Normal | 400 | Default body text (rarely used — prefer text-sm) |
+| `text-sm` | 14px / Normal | 400 | Standard body text, table cells, form labels |
+| `text-sm font-medium` | 14px / Medium | 500 | Labels, emphasized body text, nav items |
+| `text-xs text-muted-foreground` | 12px / Normal | 400 | Timestamps, captions, metadata |
+
+### Typography Rules
+
+- **`text-sm` is the default reading size**, not `text-base`. shadcn UIs are compact.
+- **Page titles** (`text-2xl font-bold`): Exactly one per view. Always at the top.
+- **Line height**: Use `leading-tight` (1.25) for headings, default (1.5) for body.
+- **Never use `text-lg` or larger for body text** — it makes the UI feel inflated.
+
+## Spacing
+
+Based on 4px increments. Use Tailwind utilities exclusively.
+
+| Class | Value | When to Use |
+|-------|-------|-------------|
+| `gap-1` | 4px | Icon-to-text within a button |
+| `gap-1.5` | 6px | Tight groupings (badge + text) |
+| `gap-2` | 8px | Label-to-input, items within a small group |
+| `gap-3` | 12px | Between form fields, inline elements |
+| `gap-4` | 16px | Between cards in a grid, between list items |
+| `gap-6` | 24px | Between major page sections |
+| `gap-8` | 32px | Between top-level page regions |
+| `p-4` | 16px | Standard internal padding (compact cards) |
+| `p-6` | 24px | Standard card padding, modal content padding |
+| `px-6 py-8` | 24px / 32px | Page-level padding around content |
+
+### Three-Level Spacing Rule
+
+Every page should use three levels of spacing, creating visual grouping:
+
+1. **Tight** (`gap-1` to `gap-2`): Between elements within a component (icon + label, label + input)
+2. **Medium** (`gap-3` to `gap-4`): Between sibling items (form fields, cards in a grid, list items)
+3. **Loose** (`gap-6` to `gap-8`): Between major sections (page header → content → footer)
+
+## Borders and Radius
+
+| Class | Value | When to Use |
+|-------|-------|-------------|
+| `rounded-sm` | ~6px | Small inner elements |
+| `rounded-md` | ~8px | Inputs, buttons, small containers |
+| `rounded-lg` | 10px | Cards, dialogs, containers |
+| `rounded-full` | 50% | Avatars, status dots |
+| `border` | 1px solid `border-border` | Card borders, section dividers |
+| `divide-y` | 1px borders between children | Lists, table-like layouts |
+
+## Shadows
+
+| Class | When to Use |
+|-------|-------------|
+| `shadow-sm` | Subtle — default cards (often unnecessary since borders define cards) |
+| `shadow-md` | Dropdowns, popovers, floating elements |
+| `shadow-lg` | Modals, dialogs, command palette |
+
+In dark mode, shadows are nearly invisible. Rely on borders (`border-border`) for elevation in dark mode.
+
+## Transitions
+
+| Class | When to Use |
+|-------|-------------|
+| `transition-colors duration-150` | Hover state color changes (buttons, links, list items) |
+| `transition-shadow duration-150` | Card hover shadow lift |
+| `transition-all duration-200` | Multi-property transitions (modals appearing, tooltips) |
+| `transition-transform duration-150` | Scale effects (button press: `active:scale-[0.98]`) |

package/skills/foundation/mockup-generation.md

@@ -0,0 +1,118 @@
+# Mockup Generation Mode
+
+> **This file is ONLY relevant when generating standalone mockups.** Skip this file if you're building production code with real data, routing, and APIs.
+
+Mockups are single-file Vue SFC demos that simulate a real UI without backend connections. They need special handling for data, images, and missing components.
+
+## Output Format
+
+Generate a **single Vue 3 SFC file**:
+
+```tsx
+// React Component
+import { ref, computed } from 'react'
+import { Button, Card, CardHeader, CardTitle, CardContent } from '@reinvented/design'
+import { Plus, Search } from 'lucide-react'
+
+// Reactive state and dummy data here
+
+
+export default function Component() {
+  return (
+    <>
+  <!-- Your UI here -->
+    </>
+  )
+}
+
+<!-- Only if absolutely needed for animations -->
+<style scoped>
+</style>
+```
+
+## Available Imports
+
+**Only these three packages exist in mockup mode.** Nothing else is installed.
+
+```ts
+import { ... } from 'react'                 // ref, computed, watch, onMounted, reactive, etc.
+import { ... } from '@reinvented/design'   // All DS components + cn() + toast
+import { ... } from 'lucide-react'      // All Lucide icons
+```
+
+No axios, no fetch, no lodash, no react-router-dom, no pinia. Data visualization should exclusively use the built-in Shadcn chart components (`AreaChart`, `BarChart`, `LineChart`, `DonutChart` from `@reinvented/design`). DO NOT use third-party chart libraries and DO NOT use `ComponentPlaceholder` for standard charts.
+
+## Dummy Data
+
+Fill the UI with **realistic, believable data**. This is critical for the mockup to feel real.
+
+```ts
+// ✅ Good — believable, diverse names and data
+const teamMembers = ref([
+  { id: 1, name: 'Sarah Chen', email: 'sarah.chen@acme.co', role: 'Engineering Lead', status: 'active' },
+  { id: 2, name: 'Marcus Johnson', email: 'marcus.j@acme.co', role: 'Product Designer', status: 'active' },
+  { id: 3, name: 'Priya Sharma', email: 'priya.s@acme.co', role: 'Frontend Developer', status: 'away' },
+  { id: 4, name: 'Alex Rivera', email: 'alex.r@acme.co', role: 'Backend Engineer', status: 'active' },
+  { id: 5, name: 'Emma Watson', email: 'emma.w@acme.co', role: 'QA Engineer', status: 'offline' },
+])
+
+// ❌ Bad — generic, fake-looking
+const users = ref([
+  { id: 1, name: 'User 1', email: 'user1@test.com' },
+  { id: 2, name: 'Test User', email: 'test@example.com' },
+])
+```
+
+Use plausible amounts ($12,450 not $1), realistic dates (Mar 15, 2024 not 01/01/2000), and genuine-sounding company/project names.
+
+## Image Replacements
+
+In mockups, never use `<img>` tags or image URLs. Replace with CSS gradient backgrounds:
+
+```tsx
+<!-- Avatar Fallback (Do NOT use vibrant gradients, stick to Shadcn defaults) -->
+<Avatar className="w-10 h-10">
+  <AvatarFallback className="bg-muted text-muted-foreground">
+    {{ user.name.split(' ').map(n => n[0]).join('') }}
+  </AvatarFallback>
+</Avatar>
+
+<!-- Hero/banner image placeholder -->
+<div className="w-full h-48 rounded-lg bg-gradient-to-br from-primary/20 via-primary/5 to-transparent" />
+<!-- Thumbnail -->
+<div className="w-16 h-16 rounded-md bg-gradient-to-br from-muted to-muted/50" />
+<!-- Product image -->
+<div className="aspect-square rounded-lg bg-gradient-to-br from-secondary to-secondary/50" />
+```
+
+## Missing Components — ComponentPlaceholder
+
+If you need a component that doesn't exist in the DS (maps, calendars, code editors, rich text editors), use `ComponentPlaceholder`:
+
+**NOTE:** Do NOT use `ComponentPlaceholder` for standard charts! `BarChart`, `AreaChart`, `LineChart`, and `DonutChart` are fully supported natively via `@reinvented/design`.
+
+```tsx
+import { ComponentPlaceholder } from '@reinvented/design'
+
+<ComponentPlaceholder
+  name="InteractiveMap"
+  description="Map showing multiple geographic locations with pins"
+  height="300px"
+/>
+```
+
+Always provide:
+- `name`: What the component would be called
+- `description`: What it would show (specific enough to communicate the intent)
+- `height`: Approximate height to reserve in the layout
+
+## Device Chrome & Navigation
+
+Do NOT render fake device hardware or OS-level chrome (e.g., phone bezels, status bars with time/wifi/battery, or browser address bars). 
+Mockups should only render the app's UI elements, filling the available viewport naturally. The testing environment will handle simulating device screens.
+
+Similarly, only include layout navigation (like sidebars, bottom tabs, or back buttons) if you are explicitly designing a full-page root layout. If you are asked to design a specific inner view, do not wrap it in a root nav shell — just render the view itself.
+
+## Dark Mode
+
+Mockups render with the `.dark` class on `<html>` by default. All token-based classes automatically resolve to dark values. You do NOT need to add `dark:` variants — just use the semantic tokens.