@reinvented/design 1.0.0 → 1.2.0

package/skills/personas/consumer-power-user.md

@@ -0,0 +1,109 @@
+# Persona: Consumer Power User
+
+Experienced software users who demand efficiency, high data density, and keyboard shortcuts. Examples include developers using dev tools, traders, or prosumer productivity app obsessives.
+
+## Characteristics
+- High technical proficiency
+- Uses the app frequently (daily, often hours at a time)
+- Values speed and functionality over simple visual appeal
+- Willing to learn UI paradigms if they make them faster
+- Primarily Desktop
+
+## Design Adjustments
+
+| Aspect | Adjustment |
+|--------|-----------|
+| **Density** | Higher — compact spacing (`p-3`, `gap-2`), more data visible above the fold |
+| **Typography** | Standard compact — `text-sm` body, `text-xs` metadata, monospace for technical strings |
+| **Navigation** | Comprehensive — sidebar with collapsible sections (`<Accordion>`), keyboard shortcuts ubiquitous |
+| **Actions** | Keyboard-centric — shortcuts explicitly shown in menus using `<DropdownMenuShortcut>` |
+| **Tables/Lists** | Dense — sortable columns, visible metadata, bulk actions without excessive spacing |
+| **Keyboard** | The Command Palette (`<Command>`) triggered by `⌘K` is essential |
+| **Customization** | Allow view toggles (grid vs list), column visibility, and saved filters |
+| **Feedback** | Subtle and non-blocking — use small toasts (`toast()`). No full-screen confirmation blocks |
+
+## Component Composition Example
+
+```tsx
+<!-- Prosumer Tool Layout -->
+<div className="space-y-4">
+  <div className="flex items-center justify-between border-b pb-4">
+    <div className="flex items-center gap-4">
+      <h2 className="text-lg font-semibold tracking-tight">API Keys</h2>
+      <Badge variant="secondary" className="font-mono text-[10px]">PROD</Badge>
+    </div>
+    
+    <div className="flex items-center gap-2">
+      <!-- Search triggered via shortcut -->
+      <Button variant="outline" size="sm" className="h-8 text-muted-foreground bg-muted/50 border-dashed">
+        <Search className="h-3 w-3 mr-2" />
+        Search keys
+        <kbd className="ml-4 inline-flex items-center rounded border bg-background px-1.5 font-mono text-[10px] font-medium text-muted-foreground">⌘K</kbd>
+      </Button>
+      <Button size="sm" className="h-8">Generate Key</Button>
+    </div>
+  </div>
+
+  <!-- Data Display: Compact, Mono, Copyable -->
+  <Card className="rounded-none sm:rounded-md">
+    <Table>
+      <TableHeader>
+        <TableRow className="h-10 hover:bg-transparent">
+          <TableHead className="font-medium text-xs">Name</TableHead>
+          <TableHead className="font-medium text-xs">Key Prefix</TableHead>
+          <TableHead className="font-medium text-xs">Permissions</TableHead>
+          <TableHead className="font-medium text-xs">Created</TableHead>
+          <TableHead className="text-right w-12"></TableHead>
+        </TableRow>
+      </TableHeader>
+      <TableBody>
+        <TableRow className="h-10">
+          <TableCell className="font-medium text-sm w-1/4">Production Frontend</TableCell>
+          <TableCell className="w-1/4">
+            <div className="flex items-center gap-2 group">
+              <span className="font-mono text-xs text-muted-foreground">pk_live_51M...</span>
+              <Button variant="ghost" size="icon" className="h-5 w-5 opacity-0 group-hover:opacity-100 transition-opacity">
+                <Copy className="h-3 w-3" />
+              </Button>
+            </div>
+          </TableCell>
+          <TableCell className="text-xs">
+            <span className="text-muted-foreground">Read-only</span>
+          </TableCell>
+          <TableCell className="text-xs text-muted-foreground">Oct 12, 2023</TableCell>
+          <TableCell className="text-right">
+            <DropdownMenu>
+              <DropdownMenuTrigger as-child>
+                 <Button variant="ghost" size="icon" className="h-7 w-7">
+                   <MoreVertical className="h-4 w-4" />
+                 </Button>
+              </DropdownMenuTrigger>
+              <DropdownMenuContent align="end" className="w-48">
+                <DropdownMenuItem>
+                  Edit Scopes
+                  <DropdownMenuShortcut>⌘E</DropdownMenuShortcut>
+                </DropdownMenuItem>
+                <DropdownMenuSeparator />
+                <DropdownMenuItem className="text-destructive">
+                  Revoke Key
+                  <DropdownMenuShortcut>⌫</DropdownMenuShortcut>
+                </DropdownMenuItem>
+              </DropdownMenuContent>
+            </DropdownMenu>
+          </TableCell>
+        </TableRow>
+      </TableBody>
+    </Table>
+  </Card>
+</div>
+```
+
+## Anti-Patterns (DO NOT DO)
+
+- ❌ **Do not use massive padding**: Power users loathe `p-6` or `p-8` inside list elements or forms. Keep padding tight (`p-3` or `p-4`) so more information fits on the screen.
+- ❌ **Do not force wizards on experienced users**: While Consumer Casuals love wizards, Power Users despise being funneled into a long 4-step process. Put everything on one dense settings page.
+- ❌ **Do not use icons without labels (unless universally known)**: Even power users get frustrated by "mystery meat" navigation. Give tooltips (`<Tooltip>`) to every icon-only button and provide `<kbd>` shortcuts.
+- ❌ **Do not block the screen with alerts**: Do not pop up an `<AlertDialog>` for trivial actions like "Item Saved". Use a subtle `toast()` at the bottom right.
+
+## Layout Preference
+`layouts/sidebar.md` heavily featuring collapsible groups and deep routing. The main view should frequently resemble `layouts/list-detail.md` to avoid constant page loads.

package/skills/personas/creative-professional.md

@@ -0,0 +1,109 @@
+# Persona: Creative Professional
+
+Designers, writers, and creators who value aesthetics and flexible workflows.
+
+## Characteristics
+- High standard for visual aesthetics
+- Uses the app as a daily primary workspace
+- Demands fluidity and high performance
+- Customizes their workspace to fit their unique workflow
+
+## Design Adjustments
+
+| Aspect | Adjustment |
+|--------|-----------|
+| **Layout** | Canvas-first — minimize chrome to maximize the work area (`p-0` wrappers) |
+| **Visual** | Minimalist but refined — subtle borders (`border-border/50`), refined typography (`tracking-tight`), extra polish |
+| **Spacing** | Generous content spacing but tight tooling — (`gap-8` for content, `gap-1` for toolbars) |
+| **Data Display** | Visual-first — use masonry or rigid `<Card>` grids for assets, rather than `<Table>` |
+| **Customization** | High — include controls like View Options (`<DropdownMenu>`), layouts, zoom levels |
+| **Tools** | Creative-tool patterns — compact toolbar strips (`<Menubar>` style), context properties panel on right |
+
+## Component Composition Example
+
+```tsx
+<!-- Creative Canvas Interface -->
+<div className="flex h-screen bg-muted/30 overflow-hidden">
+  <!-- Minimal Sidebar / Assets Panel -->
+  <aside className="w-64 border-r bg-background flex flex-col">
+    <div className="p-4 border-b flex items-center justify-between">
+      <span className="text-sm font-medium">Assets</span>
+      <Button variant="ghost" size="icon" className="h-8 w-8">
+        <Plus className="w-4 h-4" />
+      </Button>
+    </div>
+    <ScrollArea className="flex-1 p-2">
+      <!-- Tightly packed tool elements -->
+      <div className="space-y-1">
+        <Button variant="ghost" className="w-full justify-start h-8 px-2 text-xs">
+          <FolderIcon className="w-3 h-3 mr-2 text-muted-foreground" /> 
+          Project Files
+        </Button>
+        <Button variant="ghost" className="w-full justify-start h-8 px-2 text-xs">
+          <ImageIcon className="w-3 h-3 mr-2 text-muted-foreground" /> 
+          Library
+        </Button>
+      </div>
+    </ScrollArea>
+  </aside>
+
+  <!-- Central Canvas -->
+  <main className="flex-1 flex flex-col">
+    <!-- Slim Top Toolbar -->
+    <header className="h-12 border-b bg-background flex items-center px-4 justify-between shrink-0">
+      <div className="flex items-center gap-1">
+        <Button variant="outline" size="sm" className="h-8 shadow-none">
+          <MousePointer2 className="w-4 h-4" />
+        </Button>
+        <Button variant="ghost" size="sm" className="h-8 text-muted-foreground">
+          <Hand className="w-4 h-4" />
+        </Button>
+      </div>
+      
+      <!-- View Controls -->
+      <div className="flex items-center gap-2">
+        <span className="text-xs text-muted-foreground">100%</span>
+        <Slider :default-value="[100]" :max="200" :step="10" className="w-24" />
+      </div>
+    </header>
+
+    <!-- Canvas Wrapper -->
+    <div className="flex-1 overflow-auto p-12 flex items-center justify-center">
+      <!-- In mockups: <ComponentPlaceholder name="CanvasView" description="Main creative workspace" height="500px" /> (Mockup Mode Only) -->
+    </div>
+  </main>
+
+  <!-- Right Properties Shelf -->
+  <aside className="w-72 border-l bg-background hidden lg:block">
+    <div className="p-4 border-b">
+      <span className="text-sm font-medium">Properties</span>
+    </div>
+    <div className="p-4 space-y-6">
+      <!-- Tightly spaced form controls -->
+      <div className="space-y-3">
+        <Label className="text-xs text-muted-foreground uppercase tracking-wider">Dimensions</Label>
+        <div className="grid grid-cols-2 gap-2">
+          <div className="flex items-center gap-2">
+            <span className="text-xs text-muted-foreground w-4">W</span>
+            <Input className="h-8 text-xs" value="1920" />
+          </div>
+          <div className="flex items-center gap-2">
+            <span className="text-xs text-muted-foreground w-4">H</span>
+            <Input className="h-8 text-xs" value="1080" />
+          </div>
+        </div>
+      </div>
+    </div>
+  </aside>
+</div>
+```
+
+## Anti-Patterns (DO NOT DO)
+
+- ❌ **Do not use chunky headers**: Creative apps need vertical space. Do not use a 100px high header with large text. Use compact toolbars (`h-10` or `h-12`).
+- ❌ **Do not lock the user in**: Creatives hate rigid wizards. Give them a canvas where tools and settings are accessible on demand (via collapsible sidebars).
+- ❌ **Do not use large buttons for tools**: Toolbars should use `size="sm"` or `h-8 w-8` icon buttons to maximize screen real estate.
+- ❌ **Do not rely heavily on data tables**: Visual assets are preferred over spreadsheet views. If lists are needed, make them image-first.
+
+## Layout Preference
+Content-editor style: minimal topbar, maximized work area, sidebars for properties and layers. See `layouts/sidebar.md`, but consider making sidebars dual-pane (left and right).

package/skills/personas/enterprise-admin.md

@@ -0,0 +1,134 @@
+# Persona: Enterprise Admin
+
+IT administrators, compliance officers, and system managers in large organizations.
+
+## Characteristics
+- Deep technical understanding
+- Values speed, bulk actions, and data clarity over aesthetics
+- Needs to monitor system health and resolve incidents quickly
+- Works with massive datasets (users, logs, permissions)
+
+## Design Adjustments
+
+| Aspect | Adjustment |
+|--------|-----------|
+| **Density** | High — maximum data visibility, compact rows (`p-2`, `gap-2`). Everything must fit above the fold. |
+| **Navigation** | Deep hierarchy — sidebar with nested sections, breadcrumbs (`<Breadcrumb>`) are essential |
+| **Tables** | Core pattern — dense `<Table>` with column sorting, filtering, row selection (`<Checkbox>`), export options |
+| **Audit** | Omnipresent — show who changed what, when (timestamps, user attribution strings) |
+| **Permissions** | Highly visible — role badges (`<Badge>`), access-level indicators, permission matrices |
+| **Actions** | Conservative — `<AlertDialog>` for all state changes, audit trail logging |
+| **Language** | Formal/Technical — "Configure", "Provision", "Revoke Access", "Audit Log" |
+| **Bulk operations** | Essential — header-row selection with floating bulk action bars |
+
+## Component Composition Example
+
+```tsx
+<!-- Enterprise Data Grid Layout -->
+<div className="space-y-4">
+  <div className="flex items-center justify-between">
+    <div className="space-y-1">
+      <h2 className="text-xl font-semibold tracking-tight">Identity Management</h2>
+      <p className="text-xs text-muted-foreground">Manage organizational directories, SAML providers, and user policies.</p>
+    </div>
+    <div className="flex items-center gap-2">
+      <Button variant="outline" size="sm">
+        <Download className="w-4 h-4 mr-2" />
+        Export CSV
+      </Button>
+      <Button size="sm">
+        <Plus className="w-4 h-4 mr-2" />
+        Provision User
+      </Button>
+    </div>
+  </div>
+
+  <!-- Advanced Filtering Bar -->
+  <Card className="p-2 flex items-center gap-2 bg-muted/50 border-dashed">
+    <div className="relative flex-1 max-w-sm">
+      <Search className="absolute left-2.5 top-2 h-4 w-4 text-muted-foreground" />
+      <Input className="h-8 pl-8 text-sm" placeholder="Filter by email, ID or role..." />
+    </div>
+    <Separator orientation="vertical" className="h-6" />
+    <Select>
+      <SelectTrigger className="h-8 w-36 text-xs">
+        <SelectValue placeholder="Status: Active" />
+      </SelectTrigger>
+      <!-- Content omitted for brevity -->
+    </Select>
+    <Select>
+      <SelectTrigger className="h-8 w-36 text-xs">
+        <SelectValue placeholder="Department: All" />
+      </SelectTrigger>
+    </Select>
+  </Card>
+
+  <!-- Dense Enterprise Table -->
+  <div className="border rounded-md">
+    <Table>
+      <TableHeader>
+        <TableRow className="bg-muted/50">
+          <TableHead className="w-12 text-center">
+            <Checkbox />
+          </TableHead>
+          <TableHead className="h-8 px-2 text-xs">User / Email</TableHead>
+          <TableHead className="h-8 px-2 text-xs">Role</TableHead>
+          <TableHead className="h-8 px-2 text-xs">Status</TableHead>
+          <TableHead className="h-8 px-2 text-xs">Last Login</TableHead>
+          <TableHead className="h-8 px-2 w-12 text-center"></TableHead>
+        </TableRow>
+      </TableHeader>
+      <TableBody>
+        <TableRow v-for="user in users" :key="user.id" className="h-12 border-b">
+          <TableCell className="p-2 text-center">
+            <Checkbox />
+          </TableCell>
+          <TableCell className="p-2">
+            <div className="font-medium text-sm">{{ user.name }}</div>
+            <div className="text-xs text-muted-foreground">{{ user.email }}</div>
+          </TableCell>
+          <TableCell className="p-2">
+            <Badge variant="outline" className="h-5 text-[10px] uppercase">{{ user.role }}</Badge>
+          </TableCell>
+          <TableCell className="p-2">
+            <div className="flex items-center gap-1.5">
+              <span className="w-2 h-2 rounded-full bg-success"></span>
+              <span className="text-xs">Active</span>
+            </div>
+          </TableCell>
+          <TableCell className="p-2 text-xs text-muted-foreground">
+            {{ user.lastLogin }}
+          </TableCell>
+          <TableCell className="p-2 text-center">
+            <DropdownMenu>
+              <DropdownMenuTrigger as-child>
+                <Button variant="ghost" size="icon" className="h-6 w-6">
+                  <MoreHorizontal className="h-4 w-4" />
+                </Button>
+              </DropdownMenuTrigger>
+              <DropdownMenuContent align="end">
+                <DropdownMenuLabel>Actions</DropdownMenuLabel>
+                <DropdownMenuSeparator />
+                <DropdownMenuItem>Reset Password</DropdownMenuItem>
+                <DropdownMenuItem>Manage Groups</DropdownMenuItem>
+                <DropdownMenuSeparator />
+                <DropdownMenuItem className="text-destructive">Suspend User</DropdownMenuItem>
+              </DropdownMenuContent>
+            </DropdownMenu>
+          </TableCell>
+        </TableRow>
+      </TableBody>
+    </Table>
+  </div>
+</div>
+```
+
+## Anti-Patterns (DO NOT DO)
+
+- ❌ **Do not use large, airy spacing**: Admins hate scrolling. Use `p-2` instead of `p-6`. Make table headers `h-8` instead of `h-12`.
+- ❌ **Do not use Cards for large collections**: Never use a grid of identical Cards to represent 500 users. Always use a `<Table>`.
+- ❌ **Do not hide destructive actions in tooltips**: Deleting a user must be explicit and confirmable via `<AlertDialog>`.
+- ❌ **Do not rely on icons alone for actions**: Use `Icon + Text` (e.g., `Export CSV` not just an export icon) to eliminate ambiguity.
+
+## Layout Preference
+Always use `layouts/sidebar.md`. A topbar alone is insufficient for enterprise depth. Breadcrumbs (`<Breadcrumb>`) are mandatory at the top of the main content area.

package/skills/visual/color-usage.md

@@ -0,0 +1,62 @@
+# Visual: Color Usage
+
+How to apply semantic colors correctly.
+
+## The Color Budget
+
+A well-composed page uses color sparingly:
+
+- **90% neutral**: `bg-background`, `bg-card`, `text-foreground`, `text-muted-foreground`, `border-border`
+- **8% accent**: `bg-accent`, `bg-muted`, `bg-secondary` (hover states, secondary elements)
+- **2% primary**: `bg-primary`, `text-primary` (CTA buttons, active nav items, key indicators)
+
+If every element is colorful, nothing stands out. The primary color is effective because it's rare.
+
+## When to Use Each Color
+
+| Color | Token Classes | Used For | Frequency |
+|-------|--------------|----------|-----------|
+| **Background** | `bg-background` | Page background | Every page |
+| **Card** | `bg-card` | Card surfaces, overlays | Many containers |
+| **Foreground** | `text-foreground` | Primary text, headings | Most text |
+| **Muted foreground** | `text-muted-foreground` | Descriptions, timestamps, secondary text | Very common |
+| **Border** | `border-border` | Card borders, dividers | Many borders |
+| **Accent** | `bg-accent` | Hover backgrounds, active list items | Interactive states |
+| **Primary** | `bg-primary text-primary-foreground` | Main CTA button, active nav item | 1-2 per section |
+| **Destructive** | `bg-destructive` | Delete buttons, error states | Rare |
+| **Success** | `bg-success` | Confirmation badges | Rare |
+| **Warning** | `bg-warning` | Warning badges | Rare |
+
+## Anti-Patterns
+
+```html
+<!-- ❌ Too much primary — everything screams for attention -->
+<div className="bg-primary/10 border-primary">
+  <h2 className="text-primary">Section Title</h2>
+  <Button>Action 1</Button>
+  <Button>Action 2</Button>
+</div>
+
+<!-- ✅ Restrained primary — one CTA, neutral everything else -->
+<div className="border-border">
+  <h2 className="text-foreground">Section Title</h2>
+  <Button variant="outline">Action 1</Button>
+  <Button>Action 2</Button>
+</div>
+```
+
+## Tinted Icon Boxes
+
+For feature icons or stat card icons, use a tinted primary background:
+
+```tsx
+<!-- Primary tint — for feature highlights -->
+<div className="w-10 h-10 rounded-lg bg-primary/10 flex items-center justify-center">
+  <Zap className="w-5 h-5 text-primary" />
+</div>
+
+<!-- Muted — for general-purpose icons -->
+<div className="w-10 h-10 rounded-lg bg-muted flex items-center justify-center">
+  <FileText className="w-5 h-5 text-muted-foreground" />
+</div>
+```

package/skills/visual/dark-mode.md

@@ -0,0 +1,50 @@
+# Visual: Dark Mode
+
+How the design system handles dark mode and what to keep in mind.
+
+## How It Works
+
+Dark mode is activated by adding `className="dark"` to the `<html>` element. All CSS token classes automatically resolve to dark values. You do NOT need to add `dark:` variant classes.
+
+```css
+/* These resolve automatically: */
+bg-background   /* white → near-black */
+bg-card          /* white → near-black */
+text-foreground  /* near-black → near-white */
+border-border    /* light gray → dark gray */
+bg-primary       /* emerald → brighter emerald */
+```
+
+## What You Must Do
+
+1. **Use only token-based classes** — never hardcode colors
+2. **Never use white or black directly** — no `bg-white`, `text-black`, `text-gray-500`
+3. **All gradients should use token colors** — `from-primary/20` works in both modes
+4. **Shadows are nearly invisible in dark mode** — rely on `border-border` for container definition
+
+## Common Dark Mode Issues and Fixes
+
+| Issue | Wrong | Right |
+|-------|-------|-------|
+| White text on white bg | `text-white bg-white` | `text-foreground bg-card` |
+| Hard-coded grays | `text-gray-500` | `text-muted-foreground` |
+| Invisible shadows | `shadow-lg` (only) | `border shadow-lg` (border + shadow) |
+| Harsh contrast | `bg-black text-white` | `bg-card text-card-foreground` |
+| Colored backgrounds | `bg-blue-100` | `bg-primary/10` (use opacity) |
+
+## Using Color with Opacity
+
+When you need tinted backgrounds that work in both modes, use token colors with opacity:
+
+```html
+bg-primary/5    <!-- Very subtle primary tint -->
+bg-primary/10   <!-- Light primary tint (feature icon boxes) -->
+bg-primary/20   <!-- Noticeable primary tint (banners, highlights) -->
+bg-destructive/10  <!-- Error/danger tint -->
+```
+
+These automatically adapt because the base token color changes.
+
+## Testing Rule
+
+Every generated UI must look correct in both light and dark mode. If you use semantic tokens consistently, this happens automatically.

package/skills/visual/polish-techniques.md

@@ -0,0 +1,101 @@
+# Visual: Polish Techniques
+
+Subtle effects that elevate a UI from "functional" to "professional."
+
+## 1. Frosted Glass Header
+
+```html
+<header className="sticky top-0 z-50 h-14 border-b bg-card/95 backdrop-blur supports-[backdrop-filter]:bg-card/60">
+```
+
+The `backdrop-blur` creates a frosted glass effect when content scrolls behind the header.
+
+## 2. Show-on-Hover Actions
+
+Use `group` on the parent, `opacity-0 group-hover:opacity-100` on the action:
+
+```tsx
+<div className="flex items-center gap-3 group">
+  <p className="text-sm">Item name</p>
+  <Button variant="ghost" size="icon" className="h-7 w-7 opacity-0 group-hover:opacity-100 transition-opacity">
+    <Pencil className="w-3 h-3" />
+  </Button>
+</div>
+```
+
+## 3. Subtle Card Hover
+
+```html
+className="cursor-pointer transition-colors hover:bg-accent/50"
+```
+
+Not `hover:shadow-md` (which can be jarring). A gentle background tint is cleaner.
+
+## 4. Gradient Accents
+
+For visual interest in headers or hero areas:
+
+```html
+<div className="h-32 rounded-lg bg-gradient-to-br from-primary/20 via-primary/5 to-transparent" />
+```
+
+Always use token-based gradients (`from-primary/20`) so they work in dark mode.
+
+## 5. Dot Status Indicators
+
+```tsx
+<span className="w-2 h-2 rounded-full bg-success" />   <!-- Online/Active -->
+<span className="w-2 h-2 rounded-full bg-warning" />    <!-- Away/Warning -->
+<span className="w-2 h-2 rounded-full bg-muted" />      <!-- Offline/Inactive -->
+```
+
+## 6. Truncation with min-w-0
+
+In flex layouts, text won't truncate unless its container has `min-w-0`:
+
+```html
+<div className="flex items-center gap-3">
+  <div className="shrink-0"><!-- Fixed-size element --></div>
+  <div className="flex-1 min-w-0">
+    <p className="truncate">This very long text will properly truncate</p>
+  </div>
+</div>
+```
+
+## 7. Number-Aware Formatting
+
+```
+$45,231.89    (currency: font-bold, right-aligned)
+2,350         (counts: font-bold)
++20.1%        (positive change: text-success or text-foreground)
+-8.3%         (negative change: text-destructive)
+Mar 15, 2024  (dates: text-muted-foreground)
+2 hours ago   (relative time: text-xs text-muted-foreground)
+```
+
+## 8. Consistent Icon Treatment
+
+| Context | Size | Color |
+|---------|------|-------|
+| Inside buttons | `w-4 h-4` | Inherits button text color |
+| Navigation items | `w-4 h-4` or `w-5 h-5` | `text-muted-foreground`, active: inherits |
+| Stat card decorative | `h-4 w-4` | `text-muted-foreground` |
+| Empty state central | `w-6 h-6` (in container) | `text-muted-foreground` |
+| Feature highlights | `w-5 h-5` (in bg-primary/10 box) | `text-primary` |
+
+## 9. Text Emphasis Patterns
+
+```html
+<!-- Primary text with highlight -->
+<span className="font-medium">John Smith</span> updated the project
+
+<!-- De-emphasized metadata -->
+<span className="text-xs text-muted-foreground">3 minutes ago</span>
+
+<!-- Inline code/value -->
+<code className="bg-muted px-1.5 py-0.5 rounded text-sm font-mono">API_KEY</code>
+```
+
+## 10. Separator Usage
+
+Use `<Separator />` to visually break sections within a card or panel. Don't overuse — only between distinctly different content groups. For mere spacing, use `space-y-*` instead.

package/skills/visual/spacing-composition.md

@@ -0,0 +1,69 @@
+# Visual: Spacing Composition
+
+How to use spacing to create visual hierarchy and rhythm on a page.
+
+## The Three-Level Rule
+
+Every well-designed page uses exactly three levels of spacing:
+
+| Level | Gap | Purpose | Example |
+|-------|-----|---------|---------|
+| **Tight** | `gap-1` to `gap-2` (4–8px) | Within a component | Icon + text in a button, Label + Input |
+| **Medium** | `gap-3` to `gap-4` (12–16px) | Between sibling items | Form fields, cards in a grid, list items |
+| **Loose** | `gap-6` to `gap-8` (24–32px) | Between major sections | Page header → stats → table → footer |
+
+The contrast between these three levels creates grouping — the eye understands what belongs together because related things are close and unrelated things are far apart.
+
+## Page Rhythm Template
+
+```
+py-8           ← Top padding
+  gap-6/gap-8  ← Between page header and first section
+    gap-4      ← Between items within a section (cards, rows)
+      gap-2    ← Between elements within an item (label + input)
+  gap-6/gap-8  ← Between first section and second section
+    gap-4      ← Between items within section
+  gap-6/gap-8  ← Between last section and footer
+py-8           ← Bottom padding
+```
+
+## Common Mistakes
+
+```html
+<!-- ❌ Same gap everywhere — flat hierarchy, nothing groups together -->
+<div className="space-y-4">
+  <h1>Title</h1>
+  <p>Description</p>
+  <Card>...</Card>
+  <Card>...</Card>
+  <h2>Next Section</h2>
+  <Card>...</Card>
+</div>
+
+<!-- ✅ Varied gaps — clear grouping -->
+<div className="space-y-8">                    <!-- Loose: between sections -->
+  <div className="space-y-1">                  <!-- Tight: title + description -->
+    <h1 className="text-2xl font-bold">Title</h1>
+    <p className="text-muted-foreground">Description</p>
+  </div>
+  <div className="grid grid-cols-3 gap-4">    <!-- Medium: between cards -->
+    <Card>...</Card>
+    <Card>...</Card>
+    <Card>...</Card>
+  </div>
+  <div className="space-y-4">                 <!-- Medium within section -->
+    <h2 className="text-lg font-semibold">Next Section</h2>
+    <Card>...</Card>
+  </div>
+</div>
+```
+
+## Card Internal Spacing
+
+| Element | Spacing |
+|---------|---------|
+| Card padding | `p-6` (standard) or `p-4` (compact) |
+| Header to content | `CardContent className="p-6 pt-0"` (auto via DS) |
+| Fields inside card | `space-y-4` |
+| Label to input | `space-y-2` |
+| Footer action buttons | `gap-2` |