@thierrynakoa/fire-flow 12.2.2 → 13.0.1

package/skills-library/_general/database-solutions/sqlite-to-pg-migration.md

@@ -0,0 +1,219 @@
+---
+name: sqlite-to-pg-migration
+category: database-solutions
+version: 1.0.0
+contributed: 2026-03-10
+contributor: research
+last_updated: 2026-03-10
+tags: [sqlite, postgresql, migration, prototype, production]
+difficulty: medium
+---
+
+# SQLite to PostgreSQL Migration
+
+## Problem
+
+Applications that start on SQLite for simplicity need to graduate to PostgreSQL for concurrency, scale, and production features. This is the most common "prototype to production" migration path (n8n, many Next.js apps, self-hosted tools). The challenge: SQLite's dynamic typing, file-based storage, and limited ALTER TABLE make the migration non-trivial.
+## Solution Pattern
+
+### Step 0: Should You Even Migrate?
+
+Before migrating, consider whether SQLite is actually insufficient:
+
+| Stay on SQLite if... | Migrate to PG if... |
+|---|---|
+| Single-user or read-heavy workload | Multiple concurrent writers |
+| < 1GB database | > 1GB or growing fast |
+| Edge/embedded deployment | Centralized server |
+| Litestream/LiteFS replication is sufficient | Need full ACID with concurrent transactions |
+| Simple queries, no joins across large tables | Complex queries, full-text search, JSON indexing |
+
+### Step 1: Audit SQLite Schema
+
+```bash
+# List all tables
+sqlite3 mydb.db ".tables"
+
+# Dump schema
+sqlite3 mydb.db ".schema"
+
+# Check for dynamic typing issues
+sqlite3 mydb.db "SELECT typeof(col), COUNT(*) FROM mytable GROUP BY typeof(col);"
+```
+
+**Dynamic typing audit:** SQLite allows any value in any column regardless of declared type. Before migration, verify actual stored types match intended types:
+
+```sql
+-- Find columns with mixed types (SQLite-specific problem)
+SELECT 'users' AS tbl, 'age' AS col,
+  SUM(CASE WHEN typeof(age) = 'integer' THEN 1 ELSE 0 END) AS int_count,
+  SUM(CASE WHEN typeof(age) = 'text' THEN 1 ELSE 0 END) AS text_count,
+  SUM(CASE WHEN typeof(age) = 'null' THEN 1 ELSE 0 END) AS null_count
+FROM users;
+```
+
+### Step 2: Type Mapping
+
+| SQLite | PostgreSQL | Notes |
+|---|---|---|
+| `INTEGER` (any size) | `INTEGER` or `BIGINT` | Check max values to choose |
+| `INTEGER PRIMARY KEY` | `SERIAL PRIMARY KEY` | SQLite auto-increment via ROWID |
+| `REAL` | `DOUBLE PRECISION` | |
+| `TEXT` | `TEXT` or `VARCHAR(n)` | Add length constraints as needed |
+| `BLOB` | `BYTEA` | |
+| `TEXT` (storing dates) | `TIMESTAMPTZ` | Parse ISO 8601 strings |
+| `INTEGER` (storing booleans 0/1) | `BOOLEAN` | Cast during migration |
+| `TEXT` (storing JSON) | `JSONB` | Parse and validate during migration |
+| `TEXT` (storing UUIDs) | `UUID` | Validate format during migration |
+
+### Step 3: Migration with pgloader
+
+```lisp
+-- pgloader-sqlite.conf
+LOAD DATABASE
+  FROM sqlite:///path/to/mydb.db
+  INTO postgresql://user:pass@localhost/mydb_pg
+
+WITH
+  include drop,
+  create tables,
+  create indexes,
+  reset sequences
+
+-- Override dynamic types
+CAST
+  type string to text,
+  type integer to bigint when (> 2147483647 max-value)
+
+AFTER LOAD DO
+  $$ VACUUM ANALYZE; $$
+;
+```
+
+```bash
+pgloader pgloader-sqlite.conf
+```
+
+### Step 4: Manual Migration (Alternative)
+
+If pgloader is unavailable or you need more control:
+
+```bash
+# 1. Dump SQLite as SQL
+sqlite3 mydb.db .dump > dump.sql
+
+# 2. Clean up for PG compatibility
+sed -i 's/INTEGER PRIMARY KEY AUTOINCREMENT/SERIAL PRIMARY KEY/g' dump.sql
+sed -i 's/PRAGMA.*//g' dump.sql
+sed -i 's/BEGIN TRANSACTION/BEGIN/g' dump.sql
+
+# 3. Create PG database and import
+createdb mydb_pg
+psql -d mydb_pg -f dump.sql
+```
+
+**Better approach — use Python for type-aware migration:**
+
+```python
+import sqlite3
+import psycopg2
+
+# Connect to both
+sqlite_conn = sqlite3.connect('mydb.db')
+pg_conn = psycopg2.connect('postgresql://user:pass@localhost/mydb_pg')
+
+# For each table: read from SQLite, insert into PG
+cursor = sqlite_conn.execute("SELECT * FROM users")
+columns = [d[0] for d in cursor.description]
+placeholders = ','.join(['%s'] * len(columns))
+
+pg_cur = pg_conn.cursor()
+for row in cursor:
+    pg_cur.execute(f"INSERT INTO users ({','.join(columns)}) VALUES ({placeholders})", row)
+
+pg_conn.commit()
+```
+
+### Step 5: Application Code Changes
+
+1. **Connection:** `better-sqlite3` / `sql.js` → `pg` / `postgres.js`
+2. **Parameters:** `?` → `$1, $2, $3`
+3. **Boolean values:** `0/1` → `true/false`
+4. **Date handling:** Parse TEXT dates into proper TIMESTAMP values
+5. **JSON columns:** TEXT → JSONB (add validation)
+6. **RETURNING:** Now available natively (SQLite 3.35+ also has it)
+7. **Concurrent access:** Remove `PRAGMA journal_mode=WAL` and similar
+
+### Step 6: Post-Migration Health Check
+
+```sql
+-- Run ANALYZE on all tables
+ANALYZE;
+
+-- Verify row counts match
+SELECT relname, n_live_tup FROM pg_stat_user_tables ORDER BY n_live_tup DESC;
+
+-- Check for NULL where not expected (dynamic typing cleanup)
+SELECT COUNT(*) FROM users WHERE email IS NULL;  -- should be 0 if required
+
+-- Verify sequences
+SELECT sequencename, last_value FROM pg_sequences;
+
+-- Test indexes are working
+EXPLAIN ANALYZE SELECT * FROM users WHERE email = 'test@example.com';
+```
+
+### SQLite File Safety
+
+When copying SQLite databases:
+
+```bash
+# WRONG: copying while app is running risks corruption
+cp mydb.db backup.db  # ❌
+
+# RIGHT: close all connections first, then copy ALL files
+# SQLite may have -wal (write-ahead log) and -shm (shared memory) files
+cp mydb.db mydb.db-wal mydb.db-shm /backup/  # ✅
+
+# BEST: use sqlite3 backup command
+sqlite3 mydb.db ".backup /backup/mydb.db"  # ✅
+
+# VERIFY backup integrity
+sqlite3 /backup/mydb.db "PRAGMA integrity_check;"  # Should return "ok"
+```
+
+## Common Pitfalls
+
+1. **Dynamic typing:** SQLite column "age" might contain strings, integers, and NULLs. PG will reject mixed types.
+2. **Missing constraints:** SQLite doesn't enforce CHECK constraints by default. Data may violate PG constraints.
+3. **Foreign keys off:** SQLite FKs are OFF by default (`PRAGMA foreign_keys = ON`). Data may have orphaned references.
+4. **Date strings:** SQLite stores dates as TEXT. Must parse and validate every date value during migration.
+5. **Boolean ambiguity:** SQLite has no BOOLEAN. Values could be 0/1, 'true'/'false', 'yes'/'no', or anything else.
+6. **AUTOINCREMENT behavior:** SQLite AUTOINCREMENT prevents reuse of deleted IDs. PG SERIAL allows reuse. If your app depends on never-reused IDs, use `GENERATED ALWAYS AS IDENTITY`.
+
+## When to Use
+
+- Graduating a prototype from SQLite to PostgreSQL
+- Migrating self-hosted tools (n8n, etc.) to managed databases
+- Building the DATABASE phase of `/fire-resurrect` for SQLite sources
+
+## When NOT to Use
+
+- Staying on SQLite (edge deployments, read-heavy, small data)
+- Migrating between client-server databases (use mysql-to-pg-migration or pg-to-mysql)
+- Migrating to MySQL (rare — use the compatibility matrix)
+
+## Related Skills
+
+- [sql-dialect-compatibility-matrix](sql-dialect-compatibility-matrix.md)
+- [data-type-mapping-reference](data-type-mapping-reference.md)
+- [mysql-to-pg-migration](mysql-to-pg-migration.md)
+
+## References
+
+- Render — "How to Migrate from SQLite to PostgreSQL" (2025)
+- Bytebase — "Database Migration: SQLite to PostgreSQL" (2025)
+- n8n Community — SQLite to PostgreSQL migration thread (2025)
+- SitePoint — "Is SQLite on the Edge Production Ready?" (2026)
+- pgloader SQLite source documentation
+- sqlite3_rsync — SQLite safe remote copy tool

package/skills-library/_general/frontend/canvas-bubble-animation-grouping.md

@@ -0,0 +1,270 @@
+---
+name: canvas-bubble-animation-grouping
+category: frontend
+version: 1.0.0
+contributed: 2026-02-27
+contributor: scribe-bible
+last_updated: 2026-02-27
+tags: [canvas, animation, framer-motion, bubble-chart, grouping, layout-algorithm, data-visualization, react, golden-spiral, rectangular-grid]
+difficulty: medium
+usage_count: 0
+success_rate: 100
+---
+
+# Canvas Bubble Animation & Grouping Patterns
+
+## Problem
+
+You have a large collection of items (100-500+) that need to be visualized as bubbles on a canvas. Users switch between multiple view modes (e.g., "by category", "by author", "by feature"), and bubbles should smoothly animate to new positions in each mode. The modes require fundamentally different layouts:
+
+- **Overview**: All items in a single cluster (spiral)
+- **Grouped modes**: Items clustered into labeled groups (rectangular grids)
+- **Filter modes**: Binary split — items with/without a feature (quadrants)
+
+Flex-wrap layouts can't handle this — you need absolute positioning with computed coordinates, but the items must still animate smoothly between modes.
+
+## Solution Pattern
+
+Use **Framer Motion absolute-positioned bubbles** with a **layout algorithm registry**. Each mode computes `(x, y, opacity, scale)` for every item. When the mode changes, React re-renders with new coordinates, and Framer Motion's `spring` transition animates each bubble to its new position.
+
+Three layout algorithms cover all common data visualization needs:
+
+1. **Golden-angle spiral** — uniform radial distribution for "all items" overview
+2. **Rectangular grid packing** — items arranged in rows/columns within labeled group clusters
+3. **Binary filter quadrants** — items split into "has feature" / "doesn't have feature" regions
+
+### Architecture
+
+```
+ViewMode → layout algorithm → Map<id, {x, y, opacity, scale}> + GroupLabel[]
+                                            ↓
+                         Framer Motion spring transition animates delta
+```
+
+- **Pure functions** compute positions from `(mode, items, canvasWidth, canvasHeight)` — no side effects
+- **`useMemo`** recomputes only when mode, items, or container size changes
+- **Dynamic canvas height** — grouped modes return `totalHeight` so the container expands to fit content
+- **Bubble size by data** — each item's size is proportional to a data attribute (e.g., verse count), scaled down in grouped modes via `GROUPED_BUBBLE_SCALE`
+
+## Code Example
+
+### 1. Golden-Angle Spiral (Overview)
+
+```typescript
+function packInCircle(count: number, cx: number, cy: number, maxRadius: number) {
+  if (count === 0) return [];
+  if (count === 1) return [{ x: cx, y: cy }];
+
+  const goldenAngle = Math.PI * (3 - Math.sqrt(5));
+  const positions: { x: number; y: number }[] = [];
+
+  for (let i = 0; i < count; i++) {
+    const r = maxRadius * Math.sqrt(i / count) * 0.9;
+    const theta = i * goldenAngle;
+    positions.push({
+      x: cx + r * Math.cos(theta),
+      y: cy + r * Math.sin(theta),
+    });
+  }
+  return positions;
+}
+```
+
+**When**: "Show all N items" mode. Distributes items uniformly in a circle with no gaps or clusters. The golden angle (137.5°) ensures even spacing at any count.
+
+### 2. Rectangular Grid Packing (Grouped Modes)
+
+```typescript
+const GROUPED_BUBBLE_SCALE = 0.5;
+
+function packInRect(
+  count: number, cx: number, cy: number, avgBubbleSize: number, gap: number,
+): { positions: { x: number; y: number }[]; gridW: number; gridH: number } {
+  if (count === 0) return { positions: [], gridW: 0, gridH: 0 };
+  if (count === 1) return { positions: [{ x: cx, y: cy }], gridW: avgBubbleSize, gridH: avgBubbleSize };
+
+  const step = avgBubbleSize + gap;
+  const cols = Math.ceil(Math.sqrt(count * 1.3)); // Slightly wider than tall
+  const rows = Math.ceil(count / cols);
+  const gridW = cols * step;
+  const gridH = rows * step;
+  const startX = cx - (gridW - step) / 2;
+  const startY = cy - (gridH - step) / 2;
+
+  const positions: { x: number; y: number }[] = [];
+  for (let i = 0; i < count; i++) {
+    positions.push({
+      x: startX + (i % cols) * step,
+      y: startY + Math.floor(i / cols) * step,
+    });
+  }
+  return { positions, gridW, gridH };
+}
+```
+
+**When**: Grouping by a categorical attribute (genre, author, category). Each group gets a labeled rectangular region with items laid out in a grid. The `1.3` aspect ratio factor creates rectangles that feel natural (slightly wider than tall).
+
+### 3. Dynamic Grouped Layout with Row-Based Height
+
+```typescript
+function calculateGroupedCanvasPositions(
+  mode: ViewMode, nodes: Item[], canvasWidth: number,
+): { positions: Map<id, Pos>; labels: GroupLabel[]; totalHeight: number } {
+  const groups = groupItems(nodes, mode);
+  const positions = new Map();
+  const labels: GroupLabel[] = [];
+
+  // Pre-compute grid dimensions per group
+  const groupMeta = groups.map(([name, items]) => {
+    const avgSize = items.reduce((s, n) => s + getSize(n) * GROUPED_BUBBLE_SCALE, 0) / items.length;
+    const step = avgSize + gap;
+    const cols = Math.ceil(Math.sqrt(items.length * 1.3));
+    const rows = Math.ceil(items.length / cols);
+    return { name, items, avgSize, gridW: cols * step, gridH: rows * step };
+  });
+
+  // Adaptive column count based on group count
+  const maxCols = groups.length <= 4 ? 2 : groups.length <= 9 ? 3 : 4;
+  const layoutCols = Math.min(maxCols, groups.length);
+  const cellW = (canvasWidth - padX * 2) / layoutCols;
+
+  // Compute max height per layout row (for consistent row spacing)
+  const rowMaxGridH: number[] = Array(layoutRows).fill(0);
+  groupMeta.forEach((g, i) => {
+    const row = Math.floor(i / layoutCols);
+    rowMaxGridH[row] = Math.max(rowMaxGridH[row], g.gridH);
+  });
+
+  // Accumulate Y positions row by row
+  let yAccum = 25;
+  const rowCenterY: number[] = [];
+  for (let r = 0; r < layoutRows; r++) {
+    yAccum += labelHeight;
+    rowCenterY.push(yAccum + rowMaxGridH[r] / 2);
+    yAccum += rowMaxGridH[r] + rowGap;
+  }
+  const totalHeight = yAccum + 20;
+
+  // Place each group
+  groupMeta.forEach((g, i) => {
+    const col = i % layoutCols;
+    const row = Math.floor(i / layoutCols);
+    const cx = padX + cellW * (col + 0.5);
+    const cy = rowCenterY[row];
+
+    labels.push({ name: g.name, x: cx, y: cy - g.gridH / 2 - 14, color, count: g.items.length });
+
+    const grid = packInRect(g.items.length, cx, cy, g.avgSize, gap);
+    g.items.forEach((item, j) => {
+      positions.set(item.id, { ...grid.positions[j], opacity: 0.9, scale: 1 });
+    });
+  });
+
+  return { positions, labels, totalHeight };
+}
+```
+
+**Key technique**: The canvas height is **dynamic** — computed from the actual content. The container's `style.height` reads `totalHeight` so groups never overflow or leave empty space.
+
+### 4. Binary Filter Quadrants
+
+```typescript
+function calculateFilterPositions(mode: string, nodes: Item[], w: number, h: number) {
+  const filter = FILTERS[mode]; // e.g., (item) => item.hasFeature
+  const members = nodes.filter(filter);
+  const nonMembers = nodes.filter(n => !filter(n));
+
+  const positions = new Map();
+
+  // Members: bright, full-size, in the feature's quadrant
+  const memberPositions = packInCircle(members.length, quadrant.cx, quadrant.cy, quadrant.radius);
+  members.forEach((node, i) => {
+    positions.set(node.id, { ...memberPositions[i], opacity: 1, scale: 1 });
+  });
+
+  // Non-members: faded, small, pushed to opposite corner
+  const nonMemberPositions = packInCircle(nonMembers.length, fadedCx, fadedCy, fadedRadius);
+  nonMembers.forEach((node, i) => {
+    positions.set(node.id, { ...nonMemberPositions[i], opacity: 0.12, scale: 0.5 });
+  });
+
+  return positions;
+}
+```
+
+**When**: Showing which items have/don't have a boolean attribute. Members glow in a labeled quadrant; non-members fade to near-invisible in the opposite corner.
+
+### 5. Bubble Component with Spring Animation
+
+```tsx
+<motion.button
+  style={{
+    position: 'absolute',
+    left: x,
+    top: y,
+    width: size,
+    height: size,
+    borderRadius: '50%',
+    backgroundColor: color,
+    transform: 'translate(-50%, -50%)',
+  }}
+  animate={{ left: x, top: y, opacity, scale }}
+  transition={{
+    type: 'spring',
+    stiffness: 300,
+    damping: 25,
+    delay: index * 0.006,  // Staggered animation
+  }}
+  whileHover={{ scale: 1.3, zIndex: 50 }}
+  whileTap={{ scale: 0.9 }}
+/>
+```
+
+**Stagger delay**: `index * 0.006` creates a wave effect (0.9s total for 150 items) where bubbles fly to their positions in sequence rather than all at once.
+
+## Implementation Steps
+
+1. **Define view modes** as a union type with three categories: overview, grouped (genre/author/category), and filter (has/doesn't have feature)
+2. **Create pure layout functions** — each takes `(mode, items, width, height)` and returns `Map<id, {x, y, opacity, scale}>` plus optional labels
+3. **Wrap in `useMemo`** keyed on `[viewMode, items, containerSize]`
+4. **Use `ResizeObserver`** on the canvas container to get responsive dimensions
+5. **Render absolute-positioned Framer Motion elements** with `animate` set to computed coordinates
+6. **Compute dynamic canvas height** for grouped modes — return `totalHeight` from the layout function
+7. **Scale bubbles** in grouped modes (`GROUPED_BUBBLE_SCALE = 0.5`) to prevent overcrowding
+8. **Add group labels** as absolute-positioned divs above each cluster
+
+## When to Use
+
+- Data exploration dashboards with 50-500+ items and multiple grouping modes
+- Bubble charts where items have categorical attributes AND a size metric
+- Any visualization where items must animate between fundamentally different spatial arrangements
+- When you need three+ distinct layout strategies in one component
+
+## When NOT to Use
+
+- Small item counts (<20) — a simple flex-wrap with `layoutId` is simpler (see `framer-motion-layoutid-grouping`)
+- Items that only need to sort within the same grid — CSS `order` + `transition` suffices
+- Graph/network visualizations — use React Flow or D3 force layouts instead
+- Mobile-only UIs — canvas layouts need 700px+ width to be useful
+
+## Common Mistakes
+
+- **Using full emotional tone strings as group keys** — multi-word comma-separated strings create 100+ unique groups. Extract the **primary word** (`tone.split(',')[0].trim()`) to get ~10 meaningful groups.
+- **Circle packing for large groups** — `packInCircle` makes dense groups (70+ items) into an indistinguishable blob. Use `packInRect` for grouped modes where individual items must be selectable.
+- **Fixed canvas height** — a 700px fixed height works for overview/filter but overflows for grouped modes with 10+ groups. Always compute `totalHeight` from content and set `height: Math.max(totalHeight, minHeight)`.
+- **Uniform bubble size in groups** — loses the data dimension. Keep `getSize(item) * GROUPED_BUBBLE_SCALE` so the largest items are still visually prominent within their grid cells.
+- **Forgetting `translate(-50%, -50%)`** — bubble positions are computed as center points. Without centering the transform, bubbles offset by half their diameter.
+- **Too many grid columns** — with 3 groups, use 2 columns (not 3) for breathing room. Adaptive: `groups.length <= 4 ? 2 : groups.length <= 9 ? 3 : 4`.
+
+## Related Skills
+
+- [framer-motion-layoutid-grouping](framer-motion-layoutid-grouping.md) — Flex-wrap approach for smaller collections (<100 items)
+- [domain-specific-layout-algorithms](../patterns-standards/domain-specific-layout-algorithms.md) — Pure-function layout registry pattern
+- [svg-sparkline-no-charting-library](svg-sparkline-no-charting-library.md) — Lightweight data visualization with zero dependencies
+
+## References
+
+- Golden angle distribution: https://en.wikipedia.org/wiki/Golden_angle
+- Framer Motion spring physics: https://www.framer.com/motion/transition/#spring
+- Discovered in: scribe-bible PsalmOverview (150 psalms, 9 view modes, 3 layout algorithms)
+- Evolved through 3 iterations: circle packing → content-derived radius → rectangular grid

package/skills-library/_general/frontend/color-token-migration.md

@@ -0,0 +1,112 @@
+---
+name: color-token-migration
+category: frontend
+version: 1.0.0
+contributed: 2026-03-12
+contributor: claude-mission-control
+last_updated: 2026-03-12
+contributors:
+  - claude-mission-control
+tags: [css, tailwind, design-system, reskin, color-tokens, theming]
+difficulty: medium
+usage_count: 0
+success_rate: 100
+---
+
+# Color Token Migration — Systematic App-Wide Color System Swap
+
+## Problem
+
+Rebranding or reskinning an app requires changing the entire color palette consistently across all components. Direct find-and-replace of hex values is error-prone (same hex used for different purposes), and missing a single reference creates visual inconsistencies.
+
+**Symptoms:**
+- Scattered hardcoded hex values across components
+- Some components still show old brand colors after "reskin"
+- Hover/active states don't match the new palette
+- Glass/blur effects clash with new color scheme
+
+## Solution Pattern
+
+Use **CSS custom properties (tokens)** mapped through Tailwind's config, then change colors in ONE place (the token definitions). For existing apps without tokens, migrate in this order:
+
+1. **Audit:** Extract all unique color values used
+2. **Define tokens:** Create semantic token names (`mc-bg`, `mc-accent`, `mc-success`)
+3. **Replace:** Swap hardcoded values for token references
+4. **Verify:** Visual diff every component
+
+## Code Example
+
+```css
+/* tailwind.config — token definitions (change here = change everywhere) */
+:root {
+  /* Old (indigo) */
+  /* --mc-bg: #09090b; --mc-accent: #6366f1; --mc-success: #22c55e; */
+
+  /* New (purple) */
+  --mc-bg: #0a0a0f;
+  --mc-card: #12121a;
+  --mc-accent: #8b5cf6;
+  --mc-success: #10b981;
+  --mc-text: #e4e4ef;
+  --mc-muted: #8888a0;
+  --mc-border: #2a2a3e;
+  --mc-surface2: #1a1a2e;
+}
+```
+
+```typescript
+// Components use tokens, not hardcoded colors
+<div className="bg-mc-card border-mc-border text-mc-text">
+  <button className="bg-mc-accent hover:bg-mc-accent/80">
+    Action
+  </button>
+</div>
+```
+
+## Migration Checklist
+
+| Token | Purpose | Old | New |
+|-------|---------|-----|-----|
+| mc-bg | Page background | #09090b | #0a0a0f |
+| mc-card | Card/panel background | #18181b | #12121a |
+| mc-accent | Primary brand color | #6366f1 | #8b5cf6 |
+| mc-success | Success indicators | #22c55e | #10b981 |
+| mc-text | Primary text | #fafafa | #e4e4ef |
+| mc-muted | Secondary text | #a1a1aa | #8888a0 |
+| mc-border | Borders/dividers | #27272a | #2a2a3e |
+| mc-surface2 | Elevated surfaces | (new) | #1a1a2e |
+
+## Implementation Steps
+
+1. Grep all unique hex/RGB values: `grep -roh '#[0-9a-fA-F]\{6\}' src/ | sort -u`
+2. Map each to a semantic purpose (background, text, accent, etc.)
+3. Define tokens in CSS custom properties + Tailwind extend
+4. Replace hardcoded values with token classes (component by component)
+5. Also update: glass/blur effects, box-shadows, gradients, inline styles
+6. Remove old glass/blur effects if new design is flat
+
+## When to Use
+
+- App rebranding or reskinning
+- Dark/light mode implementation
+- White-labeling (customer-specific themes)
+- Design system migration (Material → custom)
+
+## When NOT to Use
+
+- Single component color changes (just change the one value)
+- Prototype/MVP stage (premature abstraction)
+- Static sites with no theming needs
+
+## Common Mistakes
+
+- Missing inline `style={{}}` attributes — grep doesn't catch them in JSX
+- Forgetting opacity variants (`bg-mc-accent/10`, `border-mc-border/30`)
+- Not updating gradient definitions (`linear-gradient(135deg, ...)`)
+- Leaving old glow/shadow effects that reference old colors
+- SVG `fill` and `stroke` attributes embedded in component JSX
+
+## References
+
+- Tailwind CSS: "Customizing Colors" — extending with CSS custom properties
+- Contributed from: claude-mission-control (indigo → purple reskin, ~50 files)