docs: reorganize LSD skill documentation structure

skills/nipsys-lsd/references/colors.md

@@ -1,282 +1,115 @@
-# LSD Color Token System
+# LSD Color Tokens Reference
 
-Complete color token system for @nipsys/lsd with semantic meanings and theme integration.
+## Overview
 
-## Concept
+LSD uses CSS custom properties (CSS variables) for theming. All colors must use these tokens—never raw hex values.
 
-LSD uses a controlled color system to maintain design consistency and theme coherence.
+## Color Categories
 
-## Semantic Colors
+| Category | Tokens | Purpose |
+|----------|--------|---------|
+| **Primary** | `--lsd-primary`, `--lsd-primary-foreground` | Brand color & contrast text |
+| **Text** | `--lsd-text-primary`, `--lsd-text-secondary` | Body and muted text |
+| **Surface/Border** | `--lsd-surface`, `--lsd-border` | Backgrounds and separators |
+| **Semantic** | `--lsd-destructive`, `--lsd-success`, `--lsd-warning`, `--lsd-info` | Status and actions |
 
-### Approved Colors
-**ALWAYS use these colors in your components:**
+## Token Values
 
-- `text-primary` - Primary text color, foreground content
-- `text-destructive` - Destructive actions, errors, warning states
+### Primary Colors
 
-### Forbidden Colors
-**NEVER use these colors - they are not part of LSD:**
-
-- `text-muted-foreground` ❌
-- `bg-muted` ❌
-- `ring-offset-background` ❌
-- `accent` ❌
-- `accent-foreground` ❌
-
-## Usage Syntax
+| Token | Light | Dark |
+|-------|-------|------|
+| `--lsd-primary` | #000000 | #ffffff |
+| `--lsd-primary-foreground` | #ffffff | #000000 |
 
 ### Text Colors
-```tsx
-// Primary text
-<Typography className="text-primary">Primary text</Typography>
-
-// Destructive text
-<Typography className="text-destructive">Error message</Typography>
-
-// With hover states
-<Button className="hover:text-destructive">Delete</Button>
-```
-
-### Border Colors
-```tsx
-// Primary border
-<div className="border border-primary">...</div>
-
-// With focus
-<Input className="focus:border-primary" />
-
-// With variants
-<Button variant="outlined" className="border-primary text-primary">
-  Border Button
-</Button>
-```
-
-### Background Colors
-```tsx
-// Transparent backgrounds (LSD default)
-<Card className="bg-transparent">...</Card>
-
-// Hover states
-<Button className="hover:bg-primary/10">Hover</Button>
-```
 
-## Theme Integration
+| Token | Light | Dark |
+|-------|-------|------|
+| `--lsd-text-primary` | #000000 | #ffffff |
+| `--lsd-text-secondary` | #4a4a4a | #d2d2d2 |
 
-### Light Mode (default)
-- `text-primary` → Dark gray (`#1a1a1a`)
-- `text-destructive` → Red (`#dc2626`)
+### Surface & Border
 
-### Dark Mode (`.dark` class)
-- `text-primary` → Light gray (`#e5e5e5`)
-- `text-destructive` → Light red (`#f87171`)
+| Token | Light | Dark |
+|-------|-------|------|
+| `--lsd-surface` | #ffffff | #000000 |
+| `--lsd-border` | #000000 | #ffffff |
 
-### Accent Themes
-Accent colors are applied via `data-theme` attribute on HTML element:
-- `monochrome` - Black/white
-- `teal` - Teal accent
-- `nord` - Nord color palette
-- `terracotta` - Terracotta accent
-- `catppuccin` - Catppuccin palette
+### Semantic Colors
 
-## Component Patterns
+| Token | Light | Dark |
+|-------|-------|------|
+| `--lsd-destructive` | #da0000 | #e5484d |
+| `--lsd-success` | #15803d | #22c55e |
+| `--lsd-warning` | #b45309 | #d97706 |
+| `--lsd-info` | #2563eb | #2563eb |
 
-### Button States
-```tsx
-// Filled button (primary action)
-<Button variant="filled">Save</Button>
-// Uses text-primary for text, theme accent for background
-
-// Outlined button (secondary action)
-<Button variant="outlined">Cancel</Button>
-// Uses border-primary and text-primary
-
-// Ghost button (subtle action)
-<Button variant="ghost">Close</Button>
-// Uses text-primary with transparent background
-
-// Link button (minimal action)
-<Button variant="link">Learn more</Button>
-// Uses text-primary with underline
-
-// Destructive button
-<Button variant="destructive">Delete</Button>
-// Uses text-destructive
-```
-
-### Input States
-```tsx
-// Default input
-<Input className="border-primary text-primary" />
-
-// Error state
-<Input className="border-destructive text-destructive" />
-
-// Disabled state
-<Input className="border-primary text-primary opacity-50" disabled />
-```
-
-### Alert States
-```tsx
-// Info alert (default)
-<Alert>
-  <InfoIcon className="text-primary" />
-  <AlertDescription className="text-primary">
-    Information message
-  </AlertDescription>
-</Alert>
-
-// Error alert
-<Alert variant="destructive">
-  <WarningIcon className="text-destructive" />
-  <AlertDescription className="text-destructive">
-    Error message
-  </AlertDescription>
-</Alert>
-```
+## Usage Examples (JSX)
 
-### Typography Colors
 ```tsx
-// All text uses text-primary by default
-<Typography variant="h1" className="text-primary">
-  Heading
-</Typography>
-
-<Typography variant="body1" className="text-primary">
-  Body text
-</Typography>
-
-// Destructive messages
-<Typography variant="body2" className="text-destructive">
-  This field is required
-</Typography>
-```
-
-### Icon Colors
-```tsx
-// Icons inherit text color
-<PlusIcon className="text-primary" />
-<TrashIcon className="text-destructive" />
-
-// Icon with hover
-<Button>
-  <ShareIcon className="text-primary hover:text-destructive" />
-</Button>
-```
-
-## Hover and Focus States
-
-### Hover States
-```tsx
-// Text hover
-<Typography className="text-primary hover:text-destructive cursor-pointer">
-  Delete
-</Typography>
-
-// Background hover
-<Button className="hover:bg-primary/10">
-  Hover effect
-</Button>
-
-// Border hover
-<Card className="border-primary hover:border-destructive">
-  Hover me
-</Card>
-```
-
-### Focus States
-```tsx
-// Focus ring (built into components)
-<Input className="focus:ring-2 focus:ring-primary" />
-
-// Focus text
-<Button className="focus:text-destructive">
-  Focus me
-</Button>
-```
-
-## Common Patterns
-
-### Success/Error States
-```tsx
-// Success (uses primary color for neutral success)
-<div className="flex items-center gap-(--lsd-spacing-smaller)">
-  <CheckIcon className="text-primary" />
-  <Typography variant="body1" className="text-primary">
-    Saved successfully
-  </Typography>
+import { cn } from '@/lib/utils';
+
+// Button with token colors
+<button className="bg-(--lsd-primary) text-(--lsd-primary-foreground)">
+  Primary Button
+</button>
+
+// Text variants
+<p className="text-(--lsd-text-primary)">Primary text</p>
+<p className="text-(--lsd-text-secondary)">Secondary text</p>
+
+// Semantic buttons
+<button className="bg-(--lsd-destructive)">Delete</button>
+<button className="bg-(--lsd-success)">Confirm</button>
+<button className="bg-(--lsd-warning)">Wait</button>
+<button className="bg-(--lsd-info)">Info</button>
+
+// Card with surface and border
+<div className="bg-(--lsd-surface) border border-(--lsd-border)">
+  Card content
 </div>
 
-// Error
-<div className="flex items-center gap-(--lsd-spacing-smaller)">
-  <ErrorIcon className="text-destructive" />
-  <Typography variant="body1" className="text-destructive">
-    Something went wrong
-</Typography>
+// With utility helper
+<div className={cn('p-(--lsd-spacing-base)', 'bg-(--lsd-surface)', 'border-(--lsd-border)')}>
+  Responsive card
 </div>
 ```
 
-### Form Validation
-```tsx
-// Error message
-<Typography variant="label1" className="text-destructive mb-(--lsd-spacing-smaller)">
-  This field is required
-</Typography>
-<Input className="border-destructive text-destructive" />
+## Theme Inheritance
 
-// Success message
-<Typography variant="label1" className="text-primary mb-(--lsd-spacing-smaller)">
-  Valid
-</Typography>
-<Input className="border-primary text-primary" />
-```
+Colors automatically switch based on the active theme (light/dark) set on the `html` or `body` element:
 
-### Badge Styles
 ```tsx
-// Default badge
-<Badge className="text-primary bg-primary/10">Default</Badge>
-
-// Destructive badge
-<Badge className="text-destructive bg-destructive/10">Error</Badge>
+// Theme provider handles token switching
+<ThemeProvider defaultTheme="dark">
+  <App />
+</ThemeProvider>
 ```
 
-## Color Reference Cards
+Tokens are defined in the theme stylesheet and applied globally. No conditional logic needed—use the token name consistently.
 
-### Approved Colors
-```
-text-primary       → Primary text, foreground content
-text-destructive   → Destructive actions, errors, warnings
-```
+## Overriding Tokens
 
-### Forbidden Colors
-```
-text-muted-foreground    ❌ Not part of LSD
-bg-muted                 ❌ Not part of LSD
-ring-offset-background   ❌ Not part of LSD
-accent                   ❌ Not part of LSD
-accent-foreground        ❌ Not part of LSD
-```
-
-### Theme Behavior
-```
-Light Mode:
-  text-primary      → Dark gray
-  text-destructive  → Red
+Override specific tokens in your component or global CSS:
 
-Dark Mode (.dark class):
-  text-primary      → Light gray
-  text-destructive  → Light red
+```css
+/* Component override */
+.custom-button {
+  --lsd-primary: #6366f1;
+}
 
-Accent Themes (data-theme):
-  monochrome, teal, nord, terracotta, catppuccin
+/* Global override */
+:root[data-theme="custom"] {
+  --lsd-primary: #6366f1;
+  --lsd-primary-foreground: #ffffff;
+}
 ```
 
-## Important Notes
+## Critical Rules
 
-- **ALWAYS** use `text-primary` for normal content
-- **ALWAYS** use `text-destructive` for destructive actions and errors
-- **NEVER** use `text-muted-foreground` or `bg-muted` - these don't exist in LSD
-- Colors automatically adapt to light/dark mode
-- Component variants (`filled`, `outlined`, `ghost`, `link`) handle colors internally
-- Icons inherit text color unless explicitly set
-- Hover and focus states should use the same color system
-- Maintain visual hierarchy with consistent color usage
+1. **NEVER use raw hex colors** in production code
+2. **ALWAYS use token variables** for color values
+3. **Token naming**: Prefixed with `--lsd-` for consistency
+4. **Theme switching**: Automatic via data attributes
+5. **Accessibility**: Semantic tokens maintain WCAG contrast ratios