From 28b94b211d1d50561a03b7fa66aeb839b2293472 Mon Sep 17 00:00:00 2001
From: Dallas Peters <dallas.peters@rolemodelsoftware.com>
Date: Thu, 5 Feb 2026 10:42:02 -0600
Subject: [PATCH 01/28] Add new commands for Optics design system and update
 package.json

- Introduced commands for checking color contrast, creating components, finding tokens, configuring icons, migrating CSS, and conducting design reviews.
- Added recipes for sidebar and layout customizations with detailed usage examples.
- Updated package.json to remove unnecessary test commands and include new documentation paths.
---
 .claude/commands/check-contrast.md            |  18 +
 .claude/commands/create-component.md          |  18 +
 .claude/commands/find-token.md                |  16 +
 .claude/commands/icons.md                     |  29 ++
 .claude/commands/migrate-css.md               |  29 ++
 .claude/commands/recipe.md                    |  52 +++
 .claude/commands/review.md                    |  17 +
 .claude/commands/validate-optics.md           |  12 +
 editor-configs/cursor-mcp.json                |   9 +
 package.json                                  |  11 +-
 src/index.ts                                  |   5 +-
 src/prompts/configure-icons.ts                |  74 ++++
 src/prompts/use-recipe.ts                     |  47 ++
 .../prompts/configure-icons-prompt.md         |  47 ++
 src/resources/prompts/use-recipe-prompt.md    |  88 ++++
 src/tools/icons.ts                            | 292 +++++++++++++
 src/tools/recipes.ts                          | 408 ++++++++++++++++++
 test-prompts/scaffold-test.md                 | 139 ++++++
 18 files changed, 1303 insertions(+), 8 deletions(-)
 create mode 100644 .claude/commands/check-contrast.md
 create mode 100644 .claude/commands/create-component.md
 create mode 100644 .claude/commands/find-token.md
 create mode 100644 .claude/commands/icons.md
 create mode 100644 .claude/commands/migrate-css.md
 create mode 100644 .claude/commands/recipe.md
 create mode 100644 .claude/commands/review.md
 create mode 100644 .claude/commands/validate-optics.md
 create mode 100644 editor-configs/cursor-mcp.json
 create mode 100644 src/prompts/configure-icons.ts
 create mode 100644 src/prompts/use-recipe.ts
 create mode 100644 src/resources/prompts/configure-icons-prompt.md
 create mode 100644 src/resources/prompts/use-recipe-prompt.md
 create mode 100644 src/tools/icons.ts
 create mode 100644 src/tools/recipes.ts
 create mode 100644 test-prompts/scaffold-test.md

diff --git a/.claude/commands/check-contrast.md b/.claude/commands/check-contrast.md
new file mode 100644
index 0000000..0500de9
--- /dev/null
+++ b/.claude/commands/check-contrast.md
@@ -0,0 +1,18 @@
+# Check Color Contrast
+
+Verify WCAG contrast ratio between two Optics color tokens.
+
+## Instructions
+
+1. Use the `check_contrast` tool from the optics-mcp server
+2. Parse $ARGUMENTS for foreground and background token names
+3. Report the contrast ratio and WCAG compliance (AA/AAA)
+
+## Usage
+
+```
+/check-contrast primary-on-base primary-base
+/check-contrast neutral-on-plus-eight neutral-plus-eight
+```
+
+If tokens aren't found, suggest similar token names using `search_tokens`.
diff --git a/.claude/commands/create-component.md b/.claude/commands/create-component.md
new file mode 100644
index 0000000..8f70c97
--- /dev/null
+++ b/.claude/commands/create-component.md
@@ -0,0 +1,18 @@
+# Create Optics Component
+
+Generate a component styled with Optics design tokens.
+
+## Instructions
+
+Invoke the `create-themed-component` prompt from the optics-mcp server.
+
+**Arguments from $ARGUMENTS:**
+- Component type (e.g., button, card, form, alert)
+- Optional: variant (primary, secondary, danger)
+- Optional: framework (react, vue, svelte, html)
+
+## Example
+
+```
+/create-component button primary react
+```
diff --git a/.claude/commands/find-token.md b/.claude/commands/find-token.md
new file mode 100644
index 0000000..f86da7c
--- /dev/null
+++ b/.claude/commands/find-token.md
@@ -0,0 +1,16 @@
+# Find Optics Token
+
+Search for an Optics design token by name or category.
+
+## Instructions
+
+1. Use the `search_tokens` tool from the optics-mcp server
+2. If $ARGUMENTS contains a category (color, spacing, typography, border, shadow), filter by category
+3. Otherwise, search by name pattern
+4. Return the matching tokens with their values and descriptions
+
+## Examples
+
+- `/find-token primary` → finds all tokens with "primary" in the name
+- `/find-token spacing` → lists all spacing tokens
+- `/find-token plus-five` → finds scale tokens at +5 level
diff --git a/.claude/commands/icons.md b/.claude/commands/icons.md
new file mode 100644
index 0000000..8961b98
--- /dev/null
+++ b/.claude/commands/icons.md
@@ -0,0 +1,29 @@
+# Configure Optics Icons
+
+Select and configure an icon library for your project.
+
+## Instructions
+
+Invoke the `configure-icons` prompt from the optics-mcp server.
+
+**Arguments from $ARGUMENTS:**
+- Library name (material, phosphor, tabler, feather, lucide)
+- Or requirements: "need fill", "need weight", "small bundle"
+
+## Available Libraries
+
+| Library | Fill | Weight | Emphasis | Size | Notes |
+|---------|------|--------|----------|------|-------|
+| Material Symbols | ✓ | ✓ | ✓ | ✓ | Default, full features |
+| Phosphor | ✓ | ✓ | ✗ | ✓ | Has duotone option |
+| Tabler | ✓ | ✗ | ✗ | ✓ | Clean, simple |
+| Feather | ✗ | ✗ | ✗ | ✓ | Minimal, small |
+| Lucide | ✗ | ✗ | ✗ | ✓ | Feather fork, more icons |
+
+## Examples
+
+```
+/icons phosphor
+/icons need fill and duotone
+/icons smallest bundle
+```
diff --git a/.claude/commands/migrate-css.md b/.claude/commands/migrate-css.md
new file mode 100644
index 0000000..0929050
--- /dev/null
+++ b/.claude/commands/migrate-css.md
@@ -0,0 +1,29 @@
+# Migrate to Optics Tokens
+
+Convert hard-coded CSS values to Optics design tokens.
+
+## Instructions
+
+Invoke the `migrate-to-tokens` prompt from the optics-mcp server.
+
+Pass the CSS code from $ARGUMENTS or current selection.
+
+## Example
+
+Input:
+```css
+.button {
+  background: #2563eb;
+  padding: 16px 24px;
+  border-radius: 4px;
+}
+```
+
+Output:
+```css
+.button {
+  background: var(--op-color-primary-base);
+  padding: var(--op-space-medium) var(--op-space-x-large);
+  border-radius: var(--op-radius-medium);
+}
+```
diff --git a/.claude/commands/recipe.md b/.claude/commands/recipe.md
new file mode 100644
index 0000000..8ea8bd5
--- /dev/null
+++ b/.claude/commands/recipe.md
@@ -0,0 +1,52 @@
+# Optics Recipe Command
+
+Use this command to get real-world customization patterns from Optics.
+
+## Usage
+
+Find a recipe that matches your customization needs using the `use-recipe` prompt.
+
+### Arguments
+
+- `slug` - Get a specific recipe (e.g., "sidebar-domains", "layout-app-shell")
+- `category` - Filter by category: layout, sidebar, header, component
+- `query` - Search by keyword
+
+### Examples
+
+Get sidebar customization recipe:
+```
+/recipe slug:sidebar-domains
+```
+
+Browse all sidebar recipes:
+```
+/recipe category:sidebar
+```
+
+Search for dark theme examples:
+```
+/recipe query:dark
+```
+
+## Available Recipes
+
+### Sidebar
+- `sidebar-domains` - Domain registrar with wide drawer and custom footer
+- `sidebar-16six` - Dark purple performance management sidebar
+
+### Layout
+- `layout-app-shell` - Standard app shell with sidebar, header, main area
+
+### Header
+- `aligned-header` - Three-section header with CSS Grid alignment
+
+## What's Included
+
+Each recipe provides:
+
+1. **Description** - Use case and context
+2. **Tokens Used** - Required Optics design tokens
+3. **CSS** - Complete scoped stylesheet
+4. **HTML** - Working markup example
+5. **Docs Link** - Reference to full documentation
diff --git a/.claude/commands/review.md b/.claude/commands/review.md
new file mode 100644
index 0000000..4f2f10d
--- /dev/null
+++ b/.claude/commands/review.md
@@ -0,0 +1,17 @@
+# Design Review
+
+Review code for Optics design system compliance.
+
+## Instructions
+
+Invoke the `design-review` prompt from the optics-mcp server.
+
+Pass the code from $ARGUMENTS or current selection for review.
+
+## What it checks
+
+- Hard-coded values that should use tokens
+- Proper token usage and naming
+- Accessibility (color contrast, focus states)
+- Consistency with Optics patterns
+- Missing or incorrect tokens
diff --git a/.claude/commands/validate-optics.md b/.claude/commands/validate-optics.md
new file mode 100644
index 0000000..2d51e75
--- /dev/null
+++ b/.claude/commands/validate-optics.md
@@ -0,0 +1,12 @@
+# Validate Optics Token Usage
+
+Scan the current file or selection for hard-coded values that should use Optics tokens.
+
+## Instructions
+
+1. Use the `validate_token_usage` tool from the optics-mcp server
+2. Pass the code from $ARGUMENTS or the current file
+3. Report any hard-coded colors, spacing, typography, or other values
+4. Suggest the correct Optics token replacements
+
+If no code is provided, ask the user to select code or specify a file path.
diff --git a/editor-configs/cursor-mcp.json b/editor-configs/cursor-mcp.json
new file mode 100644
index 0000000..b3ef8ac
--- /dev/null
+++ b/editor-configs/cursor-mcp.json
@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "optics": {
+      "command": "npx",
+      "args": ["-y", "@rolemodel/optics-mcp"],
+      "env": {}
+    }
+  }
+}
diff --git a/package.json b/package.json
index 10dc0ca..fb25ab4 100644
--- a/package.json
+++ b/package.json
@@ -14,8 +14,7 @@
     "prepare": "npm run build",
     "watch": "npx tsc --watch",
     "start": "node dist/index.js",
-    "test": "node dist/test.js",
-    "test:interactive": "npm run build && node dist/interactive-client.js"
+    "test": "node dist/test.js"
   },
   "keywords": [
     "mcp",
@@ -53,10 +52,8 @@
     "dist",
     "README.md",
     "LICENSE",
-    "docs/SYSTEM_OVERVIEW.md",
-    "docs/AI_IMPROVEMENTS.md",
-    "docs/WARP.md",
-    "docs/TOOLS.md",
-    "docs/EXAMPLES.md"
+    "docs",
+    "editor-configs",
+    ".claude/commands"
   ]
 }
diff --git a/src/index.ts b/src/index.ts
index 62c88b9..a5ce2d8 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -25,6 +25,7 @@ import { checkTokenContrast, formatContrastResult } from './tools/accessibility.
 import { suggestTokenMigration, formatMigrationSuggestions } from './tools/migration.js';
 import { generateComponentScaffold, formatScaffoldOutput } from './tools/scaffold.js';
 import { generateStickerSheet, formatStickerSheet } from './tools/sticker-sheet.js';
+import { getRecipe, searchRecipes, formatRecipe, formatRecipeList } from './tools/recipes.js';
 
 // Resources
 import * as systemOverview from './resources/system-overview.js';
@@ -143,7 +144,9 @@ const prompts = [
   accessibleColorComboPrompt,
   designReviewPrompt,
   explainTokenSystemPrompt,
-  getTokenReferencePrompt
+  getTokenReferencePrompt,
+  configureIconsPrompt,
+  useRecipePrompt
 ]
 
 prompts.forEach((prompt) => {
diff --git a/src/prompts/configure-icons.ts b/src/prompts/configure-icons.ts
new file mode 100644
index 0000000..fda73dc
--- /dev/null
+++ b/src/prompts/configure-icons.ts
@@ -0,0 +1,74 @@
+import { z } from 'zod'
+import { readResourceFile } from "../_internal/resource-path.js"
+import { iconLibraries, suggestLibrary, formatLibraryComparison, formatIconConfig } from '../tools/icons.js'
+
+type ConfigureIconsPromptArgs = {
+  library?: string
+  needsFill?: boolean
+  needsWeight?: boolean
+  needsEmphasis?: boolean
+  needsDuotone?: boolean
+  preferSmallBundle?: boolean
+}
+
+export const inputSchema = {
+  library: z.string().optional().describe('Icon library name (material, phosphor, tabler, feather, lucide)'),
+  needsFill: z.boolean().optional().describe('Requires fill/outlined toggle'),
+  needsWeight: z.boolean().optional().describe('Requires weight variations'),
+  needsEmphasis: z.boolean().optional().describe('Requires emphasis variations'),
+  needsDuotone: z.boolean().optional().describe('Requires duotone icons'),
+  preferSmallBundle: z.boolean().optional().describe('Prefer smaller bundle size'),
+}
+
+export const metadata = {
+  name: "configure-icons",
+  title: "Configure Icons",
+  description: "Select and configure an icon library for your Optics project",
+  role: "user",
+}
+
+export async function handler(args: ConfigureIconsPromptArgs) {
+  // If specific library requested, return its config
+  if (args.library) {
+    const lib = iconLibraries.find(l =>
+      l.name.toLowerCase().includes(args.library!.toLowerCase()) ||
+      l.prefix.toLowerCase().includes(args.library!.toLowerCase())
+    )
+
+    if (lib) {
+      return formatIconConfig({
+        library: lib.name,
+        name: 'settings' // example icon
+      })
+    }
+  }
+
+  // If requirements specified, suggest libraries
+  if (args.needsFill || args.needsWeight || args.needsEmphasis || args.needsDuotone || args.preferSmallBundle) {
+    const suggestions = suggestLibrary({
+      needsFill: args.needsFill,
+      needsWeight: args.needsWeight,
+      needsEmphasis: args.needsEmphasis,
+      needsDuotone: args.needsDuotone,
+      preferSmallBundle: args.preferSmallBundle,
+    })
+
+    if (suggestions.length === 0) {
+      return `No icon libraries match all your requirements.\n\n${formatLibraryComparison()}`
+    }
+
+    let output = `## Recommended Libraries\n\n`
+    for (const lib of suggestions) {
+      output += `### ${lib.name}\n`
+      output += `- Import: \`${lib.import}\`\n`
+      output += `- Usage: \`${lib.usage}\`\n`
+      if (lib.notes) output += `- Notes: ${lib.notes}\n`
+      output += `\n`
+    }
+    return output
+  }
+
+  // Default: return full comparison from prompt template
+  const promptTemplate = await readResourceFile("prompts/configure-icons-prompt.md")
+  return promptTemplate
+}
diff --git a/src/prompts/use-recipe.ts b/src/prompts/use-recipe.ts
new file mode 100644
index 0000000..e6fe6e8
--- /dev/null
+++ b/src/prompts/use-recipe.ts
@@ -0,0 +1,47 @@
+import { z } from 'zod'
+import { getRecipe, searchRecipes, formatRecipe, formatRecipeList, getRecipeCategories } from '../tools/recipes.js'
+import { readResourceFile } from "../_internal/resource-path.js"
+
+type UseRecipePromptArgs = {
+  slug?: string
+  category?: string
+  query?: string
+}
+
+export const inputSchema = {
+  slug: z.string().optional().describe('Specific recipe slug to retrieve'),
+  category: z.string().optional().describe('Filter by category (layout, sidebar, header, component)'),
+  query: z.string().optional().describe('Search term for recipe name or description'),
+}
+
+export const metadata = {
+  name: "use-recipe",
+  title: "Use Recipe",
+  description: "Get Optics customization recipes with CSS and HTML patterns",
+  role: "user",
+}
+
+export async function handler(args: UseRecipePromptArgs) {
+  // If specific recipe requested
+  if (args.slug) {
+    const recipe = getRecipe(args.slug)
+
+    if (recipe) {
+      return formatRecipe(recipe)
+    }
+
+    // Recipe not found - show available
+    const allRecipes = searchRecipes()
+    return `Recipe not found: ${args.slug}\n\n${formatRecipeList(allRecipes)}`
+  }
+
+  // If searching/filtering
+  if (args.category || args.query) {
+    const results = searchRecipes(args.query, args.category)
+    return formatRecipeList(results)
+  }
+
+  // Default: return overview from template
+  const promptTemplate = await readResourceFile("prompts/use-recipe-prompt.md")
+  return promptTemplate
+}
diff --git a/src/resources/prompts/configure-icons-prompt.md b/src/resources/prompts/configure-icons-prompt.md
new file mode 100644
index 0000000..11f5a17
--- /dev/null
+++ b/src/resources/prompts/configure-icons-prompt.md
@@ -0,0 +1,47 @@
+# Configure Icons
+
+Select and configure an icon library for your Optics project.
+
+## Available Libraries
+
+**Material Symbols** (default)
+- Full variable font: fill, weight, emphasis, size
+- Import: `@import '@rolemodel/optics/dist/css/core/fonts';`
+- Usage: `<span class="icon material-symbols-outlined">settings</span>`
+
+**Phosphor**
+- Supports: fill, weight, size, duotone
+- Import: `@import '@rolemodel/optics/dist/css/addons/fonts/phosphor_icons';`
+- Usage: `<i class="icon ph ph-smiley"></i>`
+
+**Tabler**
+- Supports: size, filled (via `.ti-{name}-filled`)
+- Import: `@import '@rolemodel/optics/dist/css/addons/fonts/tabler_icons';`
+- Usage: `<i class="icon ti ti-settings"></i>`
+
+**Feather**
+- Supports: size only
+- Import: `@import '@rolemodel/optics/dist/css/addons/fonts/feather_icons';`
+- Usage: `<i class="icon fi fi-feather"></i>`
+
+**Lucide**
+- Supports: size only (larger library than Feather)
+- Import: `@import '@rolemodel/optics/dist/css/addons/fonts/lucide_icons';`
+- Usage: `<i class="icon li li-banana"></i>`
+
+## Modifiers
+
+- Size: `.icon--small`, `.icon--medium`, `.icon--large`, `.icon--x-large`
+- Fill: `.icon--filled`, `.icon--outlined`
+- Weight: `.icon--weight-light`, `.icon--weight-normal`, `.icon--weight-semi-bold`, `.icon--weight-bold`
+- Emphasis: `.icon--low-emphasis`, `.icon--normal-emphasis`, `.icon--high-emphasis`
+
+## Selection Guide
+
+| Need | Recommended |
+|------|-------------|
+| Full customization | Material Symbols |
+| Duotone icons | Phosphor |
+| Clean minimal look | Tabler or Feather |
+| Largest icon set | Lucide |
+| Smallest bundle | Feather |
diff --git a/src/resources/prompts/use-recipe-prompt.md b/src/resources/prompts/use-recipe-prompt.md
new file mode 100644
index 0000000..de43bb7
--- /dev/null
+++ b/src/resources/prompts/use-recipe-prompt.md
@@ -0,0 +1,88 @@
+# Optics Recipes
+
+Optics provides real-world customization recipes showing how to extend and customize components for specific use cases.
+
+## Available Categories
+
+- **sidebar** - Custom sidebar configurations with brand colors, drawer modes, and navigation patterns
+- **layout** - App shell layouts combining sidebar, header, and content areas
+- **header** - Header patterns with aligned sections and navigation
+- **component** - Custom component variations and patterns
+
+## Available Recipes
+
+### Sidebar
+
+- **sidebar-domains** - Domain registrar sidebar with wide drawer, no border radius buttons, and custom footer
+- **sidebar-16six** - Dark purple sidebar with custom brand colors for performance management software
+
+### Layout
+
+- **layout-app-shell** - Standard app layout with sidebar, header, and main content area using CSS Grid
+
+### Header
+
+- **aligned-header** - Header with aligned left/center/right sections using CSS Grid
+
+## How to Use
+
+Each recipe includes:
+
+1. **Tokens Used** - Design tokens required for the customization
+2. **CSS** - Scoped CSS that extends Optics base styles
+3. **HTML** - Example markup structure
+
+### Example Usage
+
+To get a specific recipe with full CSS and HTML:
+
+```
+Use get_recipe with slug "sidebar-domains"
+```
+
+To search by category:
+
+```
+Use search_recipes with category "sidebar"
+```
+
+## Key Patterns
+
+### Scoping Customizations
+
+Recipes use modifier classes to scope customizations:
+
+```css
+.sidebar {
+  &.sidebar--domains {
+    /* Domain-specific customizations */
+  }
+}
+```
+
+### Token Overrides
+
+Recipes show how to override private tokens (prefixed with `--_op-`):
+
+```css
+.sidebar--custom {
+  --_op-sidebar-drawer-width: 28rem;
+  --_op-sidebar-background-color: hsl(256deg 66% 15%);
+}
+```
+
+### Composing with Optics Classes
+
+Recipes combine with existing Optics utilities:
+
+```html
+<aside class="sidebar sidebar--custom sidebar--drawer">
+  <div class="sidebar__content stack">
+    <!-- Uses sidebar component + stack layout utility -->
+  </div>
+</aside>
+```
+
+## Docs Reference
+
+Full recipe documentation: https://docs.optics.rolemodel.design/?path=/docs/recipes-custom-sidebar--docs
diff --git a/src/tools/icons.ts b/src/tools/icons.ts
new file mode 100644
index 0000000..106a656
--- /dev/null
+++ b/src/tools/icons.ts
@@ -0,0 +1,292 @@
+/**
+ * Icon Tools for Optics Design System
+ * Supports multiple icon libraries with varying feature sets
+ */
+
+export interface IconLibrary {
+  name: string;
+  prefix: string;
+  import: string;
+  supports: {
+    fill: boolean;
+    weight: boolean;
+    emphasis: boolean;
+    size: boolean;
+    duotone?: boolean;
+  };
+  usage: string;
+  notes?: string;
+}
+
+export interface IconConfig {
+  library: string;
+  name: string;
+  size?: 'small' | 'medium' | 'large' | 'x-large';
+  weight?: 'light' | 'normal' | 'semi-bold' | 'bold' | 'thin';
+  fill?: boolean;
+  emphasis?: 'low' | 'normal' | 'high';
+}
+
+/**
+ * Supported icon libraries in Optics
+ */
+export const iconLibraries: IconLibrary[] = [
+  {
+    name: 'Material Symbols',
+    prefix: 'material-symbols-outlined',
+    import: `@import '@rolemodel/optics/dist/css/core/fonts';`,
+    supports: { fill: true, weight: true, emphasis: true, size: true },
+    usage: '<span class="icon material-symbols-outlined">settings</span>',
+    notes: 'Default icon library. Full variable font support with fill, weight, emphasis, and size.'
+  },
+  {
+    name: 'Phosphor',
+    prefix: 'ph',
+    import: `@import '@rolemodel/optics/dist/css/addons/fonts/phosphor_icons';`,
+    supports: { fill: true, weight: true, emphasis: false, size: true, duotone: true },
+    usage: '<i class="icon ph ph-smiley"></i>',
+    notes: 'Supports .ph-duotone for two-tone icons. Adds .icon--weight-thin. Does not support .icon--weight-semi-bold or emphasis.'
+  },
+  {
+    name: 'Tabler',
+    prefix: 'ti',
+    import: `@import '@rolemodel/optics/dist/css/addons/fonts/tabler_icons';`,
+    supports: { fill: true, weight: false, emphasis: false, size: true },
+    usage: '<i class="icon ti ti-settings"></i>',
+    notes: 'For filled icons, use .ti-{name}-filled instead of .icon--filled modifier.'
+  },
+  {
+    name: 'Feather',
+    prefix: 'fi',
+    import: `@import '@rolemodel/optics/dist/css/addons/fonts/feather_icons';`,
+    supports: { fill: false, weight: false, emphasis: false, size: true },
+    usage: '<i class="icon fi fi-feather"></i>',
+    notes: 'Minimal feature set. CDN does not include all icons. Consider Lucide for more icons.'
+  },
+  {
+    name: 'Lucide',
+    prefix: 'li',
+    import: `@import '@rolemodel/optics/dist/css/addons/fonts/lucide_icons';`,
+    supports: { fill: false, weight: false, emphasis: false, size: true },
+    usage: '<i class="icon li li-banana"></i>',
+    notes: 'Fork of Feather with more icons. Larger library but same limited modifier support.'
+  }
+];
+
+/**
+ * Size modifiers available for icons
+ */
+export const sizeModifiers = {
+  small: 'icon--small',
+  medium: 'icon--medium',
+  large: 'icon--large',
+  'x-large': 'icon--x-large'
+};
+
+/**
+ * Weight modifiers (availability varies by library)
+ */
+export const weightModifiers = {
+  thin: 'icon--weight-thin',       // Phosphor only
+  light: 'icon--weight-light',
+  normal: 'icon--weight-normal',
+  'semi-bold': 'icon--weight-semi-bold',  // Not Phosphor
+  bold: 'icon--weight-bold'
+};
+
+/**
+ * Emphasis modifiers (Material Symbols only)
+ */
+export const emphasisModifiers = {
+  low: 'icon--low-emphasis',
+  normal: 'icon--normal-emphasis',
+  high: 'icon--high-emphasis'
+};
+
+/**
+ * Get library by name
+ */
+export function getLibrary(name: string): IconLibrary | undefined {
+  return iconLibraries.find(lib =>
+    lib.name.toLowerCase() === name.toLowerCase() ||
+    lib.prefix === name.toLowerCase()
+  );
+}
+
+/**
+ * Generate HTML for an icon
+ */
+export function generateIconHTML(config: IconConfig): string {
+  const library = getLibrary(config.library);
+  if (!library) {
+    return `<!-- Unknown library: ${config.library} -->`;
+  }
+
+  const classes = ['icon'];
+
+  // Add library-specific prefix
+  if (library.prefix === 'material-symbols-outlined') {
+    classes.push('material-symbols-outlined');
+  } else {
+    classes.push(library.prefix);
+    classes.push(`${library.prefix}-${config.name}`);
+  }
+
+  // Add size modifier
+  if (config.size && library.supports.size) {
+    classes.push(sizeModifiers[config.size]);
+  }
+
+  // Add weight modifier
+  if (config.weight && library.supports.weight) {
+    classes.push(weightModifiers[config.weight]);
+  }
+
+  // Add fill modifier
+  if (config.fill && library.supports.fill) {
+    if (library.prefix === 'ti') {
+      // Tabler uses different pattern for filled
+      classes[classes.length - 1] = `ti-${config.name}-filled`;
+    } else {
+      classes.push('icon--filled');
+    }
+  }
+
+  // Add emphasis modifier
+  if (config.emphasis && library.supports.emphasis) {
+    classes.push(emphasisModifiers[config.emphasis]);
+  }
+
+  // Generate HTML based on library
+  if (library.prefix === 'material-symbols-outlined') {
+    return `<span class="${classes.join(' ')}">${config.name}</span>`;
+  } else {
+    return `<i class="${classes.join(' ')}"></i>`;
+  }
+}
+
+/**
+ * Generate import statement for a library
+ */
+export function generateImport(libraryName: string): string {
+  const library = getLibrary(libraryName);
+  if (!library) {
+    return `/* Unknown library: ${libraryName} */`;
+  }
+
+  if (library.prefix === 'material-symbols-outlined') {
+    return `/* Material Symbols (default - included with Optics) */
+${library.import}`;
+  }
+
+  return `/* ${library.name} Icons */
+@import '@rolemodel/optics';
+${library.import}`;
+}
+
+/**
+ * Format library comparison for display
+ */
+export function formatLibraryComparison(): string {
+  let output = `# Optics Icon Libraries
+
+| Library | Prefix | Fill | Weight | Emphasis | Size | Notes |
+|---------|--------|------|--------|----------|------|-------|
+`;
+
+  for (const lib of iconLibraries) {
+    const s = lib.supports;
+    output += `| ${lib.name} | \`.${lib.prefix}\` | ${s.fill ? '✓' : '✗'} | ${s.weight ? '✓' : '✗'} | ${s.emphasis ? '✓' : '✗'} | ${s.size ? '✓' : '✗'} | ${lib.notes || ''} |\n`;
+  }
+
+  output += `
+## Usage Examples
+
+`;
+
+  for (const lib of iconLibraries) {
+    output += `### ${lib.name}
+
+\`\`\`css
+${lib.import}
+\`\`\`
+
+\`\`\`html
+${lib.usage}
+\`\`\`
+
+`;
+  }
+
+  return output;
+}
+
+/**
+ * Format icon configuration output
+ */
+export function formatIconConfig(config: IconConfig): string {
+  const library = getLibrary(config.library);
+  if (!library) {
+    return `Unknown library: ${config.library}\n\nAvailable libraries: ${iconLibraries.map(l => l.name).join(', ')}`;
+  }
+
+  const html = generateIconHTML(config);
+  const importStatement = generateImport(config.library);
+
+  let output = `## ${library.name} Icon: ${config.name}
+
+### Import
+
+\`\`\`css
+${importStatement}
+\`\`\`
+
+### HTML
+
+\`\`\`html
+${html}
+\`\`\`
+
+### Configuration
+
+| Option | Value | Supported |
+|--------|-------|-----------|
+| Size | ${config.size || 'medium (default)'} | ${library.supports.size ? '✓' : '✗'} |
+| Weight | ${config.weight || 'normal (default)'} | ${library.supports.weight ? '✓' : '✗'} |
+| Fill | ${config.fill ? 'filled' : 'outlined'} | ${library.supports.fill ? '✓' : '✗'} |
+| Emphasis | ${config.emphasis || 'normal (default)'} | ${library.supports.emphasis ? '✓' : '✗'} |
+`;
+
+  if (library.notes) {
+    output += `\n### Notes\n\n${library.notes}`;
+  }
+
+  return output;
+}
+
+/**
+ * Suggest best library for use case
+ */
+export function suggestLibrary(requirements: {
+  needsFill?: boolean;
+  needsWeight?: boolean;
+  needsEmphasis?: boolean;
+  needsDuotone?: boolean;
+  preferSmallBundle?: boolean;
+}): IconLibrary[] {
+  return iconLibraries.filter(lib => {
+    if (requirements.needsFill && !lib.supports.fill) return false;
+    if (requirements.needsWeight && !lib.supports.weight) return false;
+    if (requirements.needsEmphasis && !lib.supports.emphasis) return false;
+    if (requirements.needsDuotone && !lib.supports.duotone) return false;
+    return true;
+  }).sort((a, b) => {
+    // Prefer libraries with more features unless small bundle needed
+    if (requirements.preferSmallBundle) {
+      const aFeatures = Object.values(a.supports).filter(Boolean).length;
+      const bFeatures = Object.values(b.supports).filter(Boolean).length;
+      return aFeatures - bFeatures;
+    }
+    return 0;
+  });
+}
diff --git a/src/tools/recipes.ts b/src/tools/recipes.ts
new file mode 100644
index 0000000..040da7a
--- /dev/null
+++ b/src/tools/recipes.ts
@@ -0,0 +1,408 @@
+/**
+ * Recipes Tools for Optics Design System
+ * Provides real-world customization examples and patterns
+ */
+
+export interface Recipe {
+  name: string;
+  slug: string;
+  description: string;
+  category: 'layout' | 'sidebar' | 'header' | 'component';
+  docsUrl: string;
+  tokens: string[];
+  css: string;
+  html: string;
+}
+
+/**
+ * Available Optics recipes
+ */
+export const recipes: Recipe[] = [
+  {
+    name: 'Custom Sidebar',
+    slug: 'sidebar-domains',
+    description: 'A sidebar customization for domain registrar apps with wide drawer, no border radius buttons, and custom footer',
+    category: 'sidebar',
+    docsUrl: 'https://docs.optics.rolemodel.design/?path=/docs/recipes-custom-sidebar--docs',
+    tokens: [
+      '--_op-sidebar-drawer-width',
+      '--_op-sidebar-content-spacing',
+      '--_op-sidebar-content-item-spacing',
+      '--op-color-primary-plus-five',
+      '--op-color-primary-on-plus-five',
+      '--op-color-neutral-plus-six',
+      '--op-color-neutral-on-plus-six',
+      '--op-radius-pill',
+      '--op-space-small',
+      '--op-space-large'
+    ],
+    css: `/* Domains Sidebar Example */
+.sidebar {
+  &.sidebar--domains {
+    --_op-sidebar-drawer-width: 28rem;
+    --_op-sidebar-content-spacing: 0;
+    --_op-sidebar-content-item-spacing: 0;
+    box-shadow: none;
+
+    .btn {
+      border-radius: 0;
+
+      &.btn--no-border {
+        box-shadow: none;
+
+        &.btn--active {
+          background-color: var(--op-color-primary-plus-five);
+          color: var(--op-color-primary-on-plus-five);
+        }
+
+        &:hover:not(.btn--active) {
+          background-color: var(--op-color-neutral-plus-six);
+          box-shadow: none;
+          color: var(--op-color-neutral-on-plus-six);
+        }
+      }
+
+      &.btn--pill-right {
+        border-radius: 0 var(--op-radius-pill) var(--op-radius-pill) 0;
+      }
+    }
+
+    .sidebar__footer {
+      display: flex;
+      align-items: center;
+      gap: var(--op-space-small);
+      padding-inline-start: var(--op-space-large);
+    }
+  }
+}`,
+    html: `<aside class="sidebar sidebar--domains sidebar--drawer">
+  <div class="sidebar__content">
+    <button class="btn btn--no-border">
+      <i class="icon ph ph-magnifying-glass"></i>
+      <span>Get a new Domain</span>
+    </button>
+    <button class="btn btn--no-border btn--active">
+      <i class="icon ph ph-list"></i>
+      <span>My domains</span>
+    </button>
+    <button class="btn btn--no-border">
+      <i class="icon ph ph-swap"></i>
+      <span>Transfer</span>
+    </button>
+    <button class="btn btn--no-border">
+      <i class="icon ph ph-credit-card"></i>
+      <span>Billing</span>
+    </button>
+  </div>
+  <div class="sidebar__footer">
+    <i class="icon ph ph-flag"></i>
+    <span>United States (US $)</span>
+  </div>
+</aside>`
+  },
+  {
+    name: 'Custom Sidebar - 16Six Performance',
+    slug: 'sidebar-16six',
+    description: 'A dark purple sidebar with custom brand colors, rail and drawer modes, suitable for performance management software',
+    category: 'sidebar',
+    docsUrl: 'https://docs.optics.rolemodel.design/?path=/docs/recipes-custom-sidebar--docs',
+    tokens: [
+      '--_op-sidebar-background-color',
+      '--_op-sidebar-text-color',
+      '--_op-sidebar-border-color',
+      '--_op-sidebar-rail-width',
+      '--_op-sidebar-drawer-width',
+      '--_op-sidebar-drawer-brand-width',
+      '--_op-sidebar-brand-spacing',
+      '--_op-sidebar-content-item-spacing',
+      '--_op-sidebar-spacing',
+      '--op-space-3x-large',
+      '--op-space-medium',
+      '--op-space-x-small',
+      '--op-font-small'
+    ],
+    css: `/* 16Six Sidebar Example */
+.icon--rotated-135 {
+  rotate: 135deg;
+}
+
+.icon--rotated-90 {
+  rotate: 90deg;
+}
+
+.sidebar {
+  .sidebar__brand {
+    justify-content: center;
+
+    .sidebar__brand-label {
+      display: none;
+    }
+  }
+
+  &.sidebar--16six {
+    --_op-sidebar-background-color: hsl(256deg 66% 15%);
+    --_op-sidebar-text-color: hsl(26deg 100% 95%);
+    --_op-sidebar-border-color: hsl(26deg 100% 95%);
+    --_op-sidebar-rail-width: 6.4rem;
+    --_op-sidebar-drawer-width: 22.4rem;
+    --_op-sidebar-drawer-brand-width: calc(var(--op-space-3x-large) + (2 * var(--op-space-medium)));
+    --_op-sidebar-brand-spacing: var(--op-space-medium) var(--op-space-x-small);
+    --_op-sidebar-content-item-spacing: var(--op-space-x-small);
+    --_op-sidebar-spacing: 0 0 var(--op-space-x-small);
+
+    .sidebar__brand {
+      display: flex;
+      margin: 0;
+      color: inherit;
+      gap: var(--op-space-medium);
+      text-decoration: none;
+
+      svg {
+        inline-size: var(--op-space-3x-large);
+        block-size: var(--op-space-3x-large);
+      }
+
+      .sidebar__brand-label {
+        display: flex;
+        flex-direction: column;
+        font-size: var(--op-font-small);
+      }
+    }
+
+    .btn {
+      &.btn--no-border {
+        background-color: transparent;
+        box-shadow: none;
+        color: var(--_op-sidebar-text-color);
+
+        &.btn--active,
+        &:hover {
+          background-color: hsl(256deg 23% 32%);
+        }
+      }
+    }
+  }
+}`,
+    html: `<aside class="sidebar sidebar--16six sidebar--drawer">
+  <a href="#" class="sidebar__brand">
+    <svg><!-- Logo SVG --></svg>
+    <span class="sidebar__brand-label">
+      <span>16Six</span>
+      <span>RoleModel Software</span>
+    </span>
+  </a>
+  <div class="sidebar__content">
+    <button class="btn btn--no-border btn--active">
+      <i class="icon material-symbols-outlined">home</i>
+      <span>Home</span>
+    </button>
+    <button class="btn btn--no-border">
+      <i class="icon material-symbols-outlined">edit_document</i>
+      <span>Check-ins</span>
+    </button>
+    <button class="btn btn--no-border">
+      <i class="icon material-symbols-outlined">chat</i>
+      <span>1-on-1s</span>
+    </button>
+    <button class="btn btn--no-border">
+      <i class="icon material-symbols-outlined">hand_gesture</i>
+      <span>High Fives</span>
+    </button>
+    <button class="btn btn--no-border">
+      <i class="icon material-symbols-outlined">track_changes</i>
+      <span>Objectives</span>
+    </button>
+  </div>
+  <button class="btn btn--no-border sidebar__collapse">
+    <i class="icon material-symbols-outlined">expand_circle_down</i>
+    <span>Collapse</span>
+  </button>
+</aside>`
+  },
+  {
+    name: 'Layout - App Shell',
+    slug: 'layout-app-shell',
+    description: 'Standard app layout with sidebar, header, and main content area',
+    category: 'layout',
+    docsUrl: 'https://docs.optics.rolemodel.design/?path=/docs/recipes-layout--docs',
+    tokens: [
+      '--op-color-neutral-plus-eight',
+      '--op-color-neutral-on-plus-eight',
+      '--op-space-medium',
+      '--op-space-large'
+    ],
+    css: `/* App Shell Layout */
+.app-shell {
+  display: grid;
+  grid-template-columns: auto 1fr;
+  grid-template-rows: auto 1fr;
+  min-height: 100vh;
+}
+
+.app-shell__sidebar {
+  grid-row: 1 / -1;
+}
+
+.app-shell__header {
+  grid-column: 2;
+}
+
+.app-shell__main {
+  grid-column: 2;
+  padding: var(--op-space-large);
+  background-color: var(--op-color-neutral-plus-eight);
+  color: var(--op-color-neutral-on-plus-eight);
+}`,
+    html: `<div class="app-shell">
+  <aside class="app-shell__sidebar sidebar sidebar--rail">
+    <!-- Sidebar content -->
+  </aside>
+  <header class="app-shell__header">
+    <!-- Header content -->
+  </header>
+  <main class="app-shell__main container">
+    <!-- Main content -->
+  </main>
+</div>`
+  },
+  {
+    name: 'Aligned Header',
+    slug: 'aligned-header',
+    description: 'Header with aligned left/center/right sections',
+    category: 'header',
+    docsUrl: 'https://docs.optics.rolemodel.design/?path=/docs/recipes-aligned-header--docs',
+    tokens: [
+      '--op-space-medium',
+      '--op-space-small'
+    ],
+    css: `/* Aligned Header */
+.header-aligned {
+  display: grid;
+  grid-template-columns: 1fr auto 1fr;
+  align-items: center;
+  gap: var(--op-space-medium);
+  padding: var(--op-space-small) var(--op-space-medium);
+}
+
+.header-aligned__start {
+  justify-self: start;
+}
+
+.header-aligned__center {
+  justify-self: center;
+}
+
+.header-aligned__end {
+  justify-self: end;
+}`,
+    html: `<header class="header-aligned">
+  <div class="header-aligned__start">
+    <a href="#" class="sidebar__brand">Logo</a>
+  </div>
+  <nav class="header-aligned__center">
+    <ul class="cluster">
+      <li><a href="#">Link 1</a></li>
+      <li><a href="#">Link 2</a></li>
+      <li><a href="#">Link 3</a></li>
+    </ul>
+  </nav>
+  <div class="header-aligned__end">
+    <button class="btn btn--primary">Action</button>
+  </div>
+</header>`
+  }
+];
+
+/**
+ * Get recipe by slug
+ */
+export function getRecipe(slug: string): Recipe | undefined {
+  return recipes.find(r => r.slug === slug);
+}
+
+/**
+ * Search recipes by category or keyword
+ */
+export function searchRecipes(query?: string, category?: string): Recipe[] {
+  let results = recipes;
+
+  if (category) {
+    results = results.filter(r => r.category === category);
+  }
+
+  if (query) {
+    const lowerQuery = query.toLowerCase();
+    results = results.filter(r =>
+      r.name.toLowerCase().includes(lowerQuery) ||
+      r.description.toLowerCase().includes(lowerQuery) ||
+      r.slug.toLowerCase().includes(lowerQuery)
+    );
+  }
+
+  return results;
+}
+
+/**
+ * List all recipe categories
+ */
+export function getRecipeCategories(): string[] {
+  return Array.from(new Set(recipes.map(r => r.category)));
+}
+
+/**
+ * Format recipe for display
+ */
+export function formatRecipe(recipe: Recipe): string {
+  return `## ${recipe.name}
+
+${recipe.description}
+
+**Category:** ${recipe.category}
+**Docs:** ${recipe.docsUrl}
+
+### Tokens Used
+
+${recipe.tokens.map(t => `- \`${t}\``).join('\n')}
+
+### CSS
+
+\`\`\`css
+${recipe.css}
+\`\`\`
+
+### HTML
+
+\`\`\`html
+${recipe.html}
+\`\`\`
+`;
+}
+
+/**
+ * Format recipe list for display
+ */
+export function formatRecipeList(recipeList: Recipe[]): string {
+  if (recipeList.length === 0) {
+    return 'No recipes found.\n\nAvailable categories: ' + getRecipeCategories().join(', ');
+  }
+
+  let output = `# Optics Recipes (${recipeList.length})\n\n`;
+
+  const byCategory: Record<string, Recipe[]> = {};
+  for (const recipe of recipeList) {
+    if (!byCategory[recipe.category]) {
+      byCategory[recipe.category] = [];
+    }
+    byCategory[recipe.category].push(recipe);
+  }
+
+  for (const [category, categoryRecipes] of Object.entries(byCategory)) {
+    output += `## ${category.charAt(0).toUpperCase() + category.slice(1)}\n\n`;
+    for (const recipe of categoryRecipes) {
+      output += `- **${recipe.name}** (\`${recipe.slug}\`)\n  ${recipe.description}\n\n`;
+    }
+  }
+
+  output += `\nUse \`get_recipe\` with a slug to get full details.`;
+  return output;
+}
diff --git a/test-prompts/scaffold-test.md b/test-prompts/scaffold-test.md
new file mode 100644
index 0000000..c7fd0ae
--- /dev/null
+++ b/test-prompts/scaffold-test.md
@@ -0,0 +1,139 @@
+# MCP Scaffolding Test Prompt
+
+Use this prompt to test the optics-mcp server. Run it **with** and **without** the MCP enabled to compare results.
+
+---
+
+## Test Prompt
+
+```
+Create a metrics dashboard using the Optics design system.
+
+## Context
+- **Design System**: Optics by RoleModel Software
+- **Docs**: https://docs.optics.rolemodel.design
+- **Token Prefix**: `--op-` (e.g., `--op-color-primary-base`, `--op-space-medium`)
+- **Tech Stack**: Vite + vanilla HTML/CSS/JS
+
+## Requirements
+
+### Layout
+- Sidebar navigation with logo, nav items, and user avatar at bottom
+- Main content area with header and grid of cards
+- Use Optics layout utilities (stack, cluster, split, container)
+
+### Components needed
+- Sidebar with active state styling
+- 4 metric cards showing: Users, Revenue, Orders, Conversion Rate
+- Each card has: icon, label, value, and trend indicator (up/down arrow with percentage)
+- Simple bar chart placeholder area
+- Data table with 5 rows showing recent orders
+
+### Theming
+- Use a custom primary color: `#6366f1` (indigo)
+- Configure the HSL base tokens to enable the full color scale
+- Support automatic dark mode via `prefers-color-scheme`
+
+### Icons
+- Use the Phosphor icon library
+- Icons needed: house, users, currency-dollar, shopping-cart, chart-line, arrow-up, arrow-down, gear, sign-out
+
+## Deliverables
+1. Complete Vite project structure
+2. HTML using Optics component classes and layout utilities
+3. CSS that properly overrides the primary color HSL tokens
+4. Phosphor icons import configured correctly
+5. Should run with `npm run dev`
+```
+
+---
+
+## Success Criteria
+
+### WITHOUT MCP (expect failures)
+
+AI will likely:
+- ❌ Invent layout classes like `.op-sidebar`, `.op-grid`, `.dashboard-container`
+- ❌ Use wrong token names: `--op-primary`, `--op-color-indigo-500`, `--op-spacing-4`
+- ❌ Hardcode the indigo color instead of setting HSL base tokens
+- ❌ Miss the HSL theming system entirely (`--op-color-primary-h`, `-s`, `-l`)
+- ❌ Wrong icon setup: use wrong prefix, wrong import path, or invent classes
+- ❌ Not use `-on-` tokens for text on colored backgrounds
+- ❌ Invent component classes that don't exist in Optics
+
+### WITH MCP (expect success)
+
+AI should:
+- ✅ Use real layout utilities: `.stack`, `.cluster`, `.split`, `.container`
+- ✅ Set HSL tokens correctly: `--op-color-primary-h: 239; --op-color-primary-s: 84%; --op-color-primary-l: 67%;`
+- ✅ Use scale tokens: `--op-color-primary-base`, `--op-color-primary-plus-five`
+- ✅ Use on-tokens: `--op-color-primary-on-base` for text on primary backgrounds
+- ✅ Correct Phosphor setup: `@import '@rolemodel/optics/dist/css/addons/fonts/phosphor_icons';`
+- ✅ Correct icon markup: `<i class="icon ph ph-house"></i>`
+- ✅ Use real spacing: `--op-space-small`, `--op-space-medium`, `--op-space-large`
+- ✅ Use real component patterns from Optics docs
+
+---
+
+## Scoring Rubric
+
+| Category | Criterion | Points |
+|----------|-----------|--------|
+| **Theming** | Sets HSL base tokens (h, s, l) correctly | 15 |
+| | Uses color scale tokens (base, plus-*, minus-*) | 10 |
+| | Uses -on- tokens for text on backgrounds | 10 |
+| | Dark mode works via color-scheme | 5 |
+| **Layout** | Uses real Optics layout utilities | 10 |
+| | Correct container/spacing usage | 5 |
+| **Icons** | Correct Phosphor import path | 10 |
+| | Correct icon markup (`icon ph ph-*`) | 10 |
+| | Uses available modifiers correctly | 5 |
+| **Components** | Card structure follows Optics patterns | 5 |
+| | Table structure follows Optics patterns | 5 |
+| | Sidebar follows Optics patterns | 5 |
+| **Tokens** | No hallucinated token names | 5 |
+| | Uses correct spacing tokens | 5 |
+| | Uses correct typography tokens | 5 |
+| **Total** | | **100** |
+
+---
+
+## Expected Token Usage
+
+### Theming (converting #6366f1 to HSL)
+
+```css
+:root {
+  --op-color-primary-h: 239;
+  --op-color-primary-s: 84%;
+  --op-color-primary-l: 67%;
+}
+```
+
+### Icon Import
+
+```css
+@import '@rolemodel/optics';
+@import '@rolemodel/optics/dist/css/addons/fonts/phosphor_icons';
+```
+
+### Icon Markup
+
+```html
+<i class="icon ph ph-house"></i>
+<i class="icon ph ph-users"></i>
+<i class="icon ph ph-currency-dollar"></i>
+<i class="icon ph ph-arrow-up icon--small"></i>
+```
+
+### Layout Structure
+
+```html
+<div class="split">
+  <aside class="sidebar stack">...</aside>
+  <main class="container stack">
+    <div class="cluster">...</div>
+    <div class="grid">...</div>
+  </main>
+</div>
+```

From b7d824720c90eb19636094452bdb21d1ac6b4ae5 Mon Sep 17 00:00:00 2001
From: Dallas Peters <dallas.peters@rolemodelsoftware.com>
Date: Thu, 5 Feb 2026 10:45:36 -0600
Subject: [PATCH 02/28] Remove MCP Scaffolding Test Prompt file from the
 repository

---
 test-prompts/scaffold-test.md | 139 ----------------------------------
 1 file changed, 139 deletions(-)
 delete mode 100644 test-prompts/scaffold-test.md

diff --git a/test-prompts/scaffold-test.md b/test-prompts/scaffold-test.md
deleted file mode 100644
index c7fd0ae..0000000
--- a/test-prompts/scaffold-test.md
+++ /dev/null
@@ -1,139 +0,0 @@
-# MCP Scaffolding Test Prompt
-
-Use this prompt to test the optics-mcp server. Run it **with** and **without** the MCP enabled to compare results.
-
----
-
-## Test Prompt
-
-```
-Create a metrics dashboard using the Optics design system.
-
-## Context
-- **Design System**: Optics by RoleModel Software
-- **Docs**: https://docs.optics.rolemodel.design
-- **Token Prefix**: `--op-` (e.g., `--op-color-primary-base`, `--op-space-medium`)
-- **Tech Stack**: Vite + vanilla HTML/CSS/JS
-
-## Requirements
-
-### Layout
-- Sidebar navigation with logo, nav items, and user avatar at bottom
-- Main content area with header and grid of cards
-- Use Optics layout utilities (stack, cluster, split, container)
-
-### Components needed
-- Sidebar with active state styling
-- 4 metric cards showing: Users, Revenue, Orders, Conversion Rate
-- Each card has: icon, label, value, and trend indicator (up/down arrow with percentage)
-- Simple bar chart placeholder area
-- Data table with 5 rows showing recent orders
-
-### Theming
-- Use a custom primary color: `#6366f1` (indigo)
-- Configure the HSL base tokens to enable the full color scale
-- Support automatic dark mode via `prefers-color-scheme`
-
-### Icons
-- Use the Phosphor icon library
-- Icons needed: house, users, currency-dollar, shopping-cart, chart-line, arrow-up, arrow-down, gear, sign-out
-
-## Deliverables
-1. Complete Vite project structure
-2. HTML using Optics component classes and layout utilities
-3. CSS that properly overrides the primary color HSL tokens
-4. Phosphor icons import configured correctly
-5. Should run with `npm run dev`
-```
-
----
-
-## Success Criteria
-
-### WITHOUT MCP (expect failures)
-
-AI will likely:
-- ❌ Invent layout classes like `.op-sidebar`, `.op-grid`, `.dashboard-container`
-- ❌ Use wrong token names: `--op-primary`, `--op-color-indigo-500`, `--op-spacing-4`
-- ❌ Hardcode the indigo color instead of setting HSL base tokens
-- ❌ Miss the HSL theming system entirely (`--op-color-primary-h`, `-s`, `-l`)
-- ❌ Wrong icon setup: use wrong prefix, wrong import path, or invent classes
-- ❌ Not use `-on-` tokens for text on colored backgrounds
-- ❌ Invent component classes that don't exist in Optics
-
-### WITH MCP (expect success)
-
-AI should:
-- ✅ Use real layout utilities: `.stack`, `.cluster`, `.split`, `.container`
-- ✅ Set HSL tokens correctly: `--op-color-primary-h: 239; --op-color-primary-s: 84%; --op-color-primary-l: 67%;`
-- ✅ Use scale tokens: `--op-color-primary-base`, `--op-color-primary-plus-five`
-- ✅ Use on-tokens: `--op-color-primary-on-base` for text on primary backgrounds
-- ✅ Correct Phosphor setup: `@import '@rolemodel/optics/dist/css/addons/fonts/phosphor_icons';`
-- ✅ Correct icon markup: `<i class="icon ph ph-house"></i>`
-- ✅ Use real spacing: `--op-space-small`, `--op-space-medium`, `--op-space-large`
-- ✅ Use real component patterns from Optics docs
-
----
-
-## Scoring Rubric
-
-| Category | Criterion | Points |
-|----------|-----------|--------|
-| **Theming** | Sets HSL base tokens (h, s, l) correctly | 15 |
-| | Uses color scale tokens (base, plus-*, minus-*) | 10 |
-| | Uses -on- tokens for text on backgrounds | 10 |
-| | Dark mode works via color-scheme | 5 |
-| **Layout** | Uses real Optics layout utilities | 10 |
-| | Correct container/spacing usage | 5 |
-| **Icons** | Correct Phosphor import path | 10 |
-| | Correct icon markup (`icon ph ph-*`) | 10 |
-| | Uses available modifiers correctly | 5 |
-| **Components** | Card structure follows Optics patterns | 5 |
-| | Table structure follows Optics patterns | 5 |
-| | Sidebar follows Optics patterns | 5 |
-| **Tokens** | No hallucinated token names | 5 |
-| | Uses correct spacing tokens | 5 |
-| | Uses correct typography tokens | 5 |
-| **Total** | | **100** |
-
----
-
-## Expected Token Usage
-
-### Theming (converting #6366f1 to HSL)
-
-```css
-:root {
-  --op-color-primary-h: 239;
-  --op-color-primary-s: 84%;
-  --op-color-primary-l: 67%;
-}
-```
-
-### Icon Import
-
-```css
-@import '@rolemodel/optics';
-@import '@rolemodel/optics/dist/css/addons/fonts/phosphor_icons';
-```
-
-### Icon Markup
-
-```html
-<i class="icon ph ph-house"></i>
-<i class="icon ph ph-users"></i>
-<i class="icon ph ph-currency-dollar"></i>
-<i class="icon ph ph-arrow-up icon--small"></i>
-```
-
-### Layout Structure
-
-```html
-<div class="split">
-  <aside class="sidebar stack">...</aside>
-  <main class="container stack">
-    <div class="cluster">...</div>
-    <div class="grid">...</div>
-  </main>
-</div>
-```

From 774c3d8839009a2912e4efa0b6fa142c87f8b4c9 Mon Sep 17 00:00:00 2001
From: Dallas Peters <dallas.peters@rolemodelsoftware.com>
Date: Thu, 5 Feb 2026 11:02:47 -0600
Subject: [PATCH 03/28] Fix test:interactive

---
 package.json | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/package.json b/package.json
index fb25ab4..b834bc6 100644
--- a/package.json
+++ b/package.json
@@ -14,7 +14,8 @@
     "prepare": "npm run build",
     "watch": "npx tsc --watch",
     "start": "node dist/index.js",
-    "test": "node dist/test.js"
+    "test": "node dist/test.js",
+    "test:interactive": "npm run build && node dist/interactive-client.js"
   },
   "keywords": [
     "mcp",

From ce143cf9adb576723616c640c140c66763085d88 Mon Sep 17 00:00:00 2001
From: Dallas Peters <dallas.peters@rolemodelsoftware.com>
Date: Thu, 5 Feb 2026 13:01:27 -0600
Subject: [PATCH 04/28] Remove .claude specific commands. After further
 research promps should show up in the IDE as commands.

---
 .claude/commands/check-contrast.md   | 18 ----------
 .claude/commands/create-component.md | 18 ----------
 .claude/commands/find-token.md       | 16 ---------
 .claude/commands/icons.md            | 29 ----------------
 .claude/commands/migrate-css.md      | 29 ----------------
 .claude/commands/recipe.md           | 52 ----------------------------
 .claude/commands/review.md           | 17 ---------
 .claude/commands/validate-optics.md  | 12 -------
 src/index.ts                         |  8 +++++
 9 files changed, 8 insertions(+), 191 deletions(-)
 delete mode 100644 .claude/commands/check-contrast.md
 delete mode 100644 .claude/commands/create-component.md
 delete mode 100644 .claude/commands/find-token.md
 delete mode 100644 .claude/commands/icons.md
 delete mode 100644 .claude/commands/migrate-css.md
 delete mode 100644 .claude/commands/recipe.md
 delete mode 100644 .claude/commands/review.md
 delete mode 100644 .claude/commands/validate-optics.md

diff --git a/.claude/commands/check-contrast.md b/.claude/commands/check-contrast.md
deleted file mode 100644
index 0500de9..0000000
--- a/.claude/commands/check-contrast.md
+++ /dev/null
@@ -1,18 +0,0 @@
-# Check Color Contrast
-
-Verify WCAG contrast ratio between two Optics color tokens.
-
-## Instructions
-
-1. Use the `check_contrast` tool from the optics-mcp server
-2. Parse $ARGUMENTS for foreground and background token names
-3. Report the contrast ratio and WCAG compliance (AA/AAA)
-
-## Usage
-
-```
-/check-contrast primary-on-base primary-base
-/check-contrast neutral-on-plus-eight neutral-plus-eight
-```
-
-If tokens aren't found, suggest similar token names using `search_tokens`.
diff --git a/.claude/commands/create-component.md b/.claude/commands/create-component.md
deleted file mode 100644
index 8f70c97..0000000
--- a/.claude/commands/create-component.md
+++ /dev/null
@@ -1,18 +0,0 @@
-# Create Optics Component
-
-Generate a component styled with Optics design tokens.
-
-## Instructions
-
-Invoke the `create-themed-component` prompt from the optics-mcp server.
-
-**Arguments from $ARGUMENTS:**
-- Component type (e.g., button, card, form, alert)
-- Optional: variant (primary, secondary, danger)
-- Optional: framework (react, vue, svelte, html)
-
-## Example
-
-```
-/create-component button primary react
-```
diff --git a/.claude/commands/find-token.md b/.claude/commands/find-token.md
deleted file mode 100644
index f86da7c..0000000
--- a/.claude/commands/find-token.md
+++ /dev/null
@@ -1,16 +0,0 @@
-# Find Optics Token
-
-Search for an Optics design token by name or category.
-
-## Instructions
-
-1. Use the `search_tokens` tool from the optics-mcp server
-2. If $ARGUMENTS contains a category (color, spacing, typography, border, shadow), filter by category
-3. Otherwise, search by name pattern
-4. Return the matching tokens with their values and descriptions
-
-## Examples
-
-- `/find-token primary` → finds all tokens with "primary" in the name
-- `/find-token spacing` → lists all spacing tokens
-- `/find-token plus-five` → finds scale tokens at +5 level
diff --git a/.claude/commands/icons.md b/.claude/commands/icons.md
deleted file mode 100644
index 8961b98..0000000
--- a/.claude/commands/icons.md
+++ /dev/null
@@ -1,29 +0,0 @@
-# Configure Optics Icons
-
-Select and configure an icon library for your project.
-
-## Instructions
-
-Invoke the `configure-icons` prompt from the optics-mcp server.
-
-**Arguments from $ARGUMENTS:**
-- Library name (material, phosphor, tabler, feather, lucide)
-- Or requirements: "need fill", "need weight", "small bundle"
-
-## Available Libraries
-
-| Library | Fill | Weight | Emphasis | Size | Notes |
-|---------|------|--------|----------|------|-------|
-| Material Symbols | ✓ | ✓ | ✓ | ✓ | Default, full features |
-| Phosphor | ✓ | ✓ | ✗ | ✓ | Has duotone option |
-| Tabler | ✓ | ✗ | ✗ | ✓ | Clean, simple |
-| Feather | ✗ | ✗ | ✗ | ✓ | Minimal, small |
-| Lucide | ✗ | ✗ | ✗ | ✓ | Feather fork, more icons |
-
-## Examples
-
-```
-/icons phosphor
-/icons need fill and duotone
-/icons smallest bundle
-```
diff --git a/.claude/commands/migrate-css.md b/.claude/commands/migrate-css.md
deleted file mode 100644
index 0929050..0000000
--- a/.claude/commands/migrate-css.md
+++ /dev/null
@@ -1,29 +0,0 @@
-# Migrate to Optics Tokens
-
-Convert hard-coded CSS values to Optics design tokens.
-
-## Instructions
-
-Invoke the `migrate-to-tokens` prompt from the optics-mcp server.
-
-Pass the CSS code from $ARGUMENTS or current selection.
-
-## Example
-
-Input:
-```css
-.button {
-  background: #2563eb;
-  padding: 16px 24px;
-  border-radius: 4px;
-}
-```
-
-Output:
-```css
-.button {
-  background: var(--op-color-primary-base);
-  padding: var(--op-space-medium) var(--op-space-x-large);
-  border-radius: var(--op-radius-medium);
-}
-```
diff --git a/.claude/commands/recipe.md b/.claude/commands/recipe.md
deleted file mode 100644
index 8ea8bd5..0000000
--- a/.claude/commands/recipe.md
+++ /dev/null
@@ -1,52 +0,0 @@
-# Optics Recipe Command
-
-Use this command to get real-world customization patterns from Optics.
-
-## Usage
-
-Find a recipe that matches your customization needs using the `use-recipe` prompt.
-
-### Arguments
-
-- `slug` - Get a specific recipe (e.g., "sidebar-domains", "layout-app-shell")
-- `category` - Filter by category: layout, sidebar, header, component
-- `query` - Search by keyword
-
-### Examples
-
-Get sidebar customization recipe:
-```
-/recipe slug:sidebar-domains
-```
-
-Browse all sidebar recipes:
-```
-/recipe category:sidebar
-```
-
-Search for dark theme examples:
-```
-/recipe query:dark
-```
-
-## Available Recipes
-
-### Sidebar
-- `sidebar-domains` - Domain registrar with wide drawer and custom footer
-- `sidebar-16six` - Dark purple performance management sidebar
-
-### Layout
-- `layout-app-shell` - Standard app shell with sidebar, header, main area
-
-### Header
-- `aligned-header` - Three-section header with CSS Grid alignment
-
-## What's Included
-
-Each recipe provides:
-
-1. **Description** - Use case and context
-2. **Tokens Used** - Required Optics design tokens
-3. **CSS** - Complete scoped stylesheet
-4. **HTML** - Working markup example
-5. **Docs Link** - Reference to full documentation
diff --git a/.claude/commands/review.md b/.claude/commands/review.md
deleted file mode 100644
index 4f2f10d..0000000
--- a/.claude/commands/review.md
+++ /dev/null
@@ -1,17 +0,0 @@
-# Design Review
-
-Review code for Optics design system compliance.
-
-## Instructions
-
-Invoke the `design-review` prompt from the optics-mcp server.
-
-Pass the code from $ARGUMENTS or current selection for review.
-
-## What it checks
-
-- Hard-coded values that should use tokens
-- Proper token usage and naming
-- Accessibility (color contrast, focus states)
-- Consistency with Optics patterns
-- Missing or incorrect tokens
diff --git a/.claude/commands/validate-optics.md b/.claude/commands/validate-optics.md
deleted file mode 100644
index 2d51e75..0000000
--- a/.claude/commands/validate-optics.md
+++ /dev/null
@@ -1,12 +0,0 @@
-# Validate Optics Token Usage
-
-Scan the current file or selection for hard-coded values that should use Optics tokens.
-
-## Instructions
-
-1. Use the `validate_token_usage` tool from the optics-mcp server
-2. Pass the code from $ARGUMENTS or the current file
-3. Report any hard-coded colors, spacing, typography, or other values
-4. Suggest the correct Optics token replacements
-
-If no code is provided, ask the user to select code or specify a file path.
diff --git a/src/index.ts b/src/index.ts
index a5ce2d8..f4810c6 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -41,6 +41,8 @@ import * as accessibleColorComboPrompt from './prompts/accessible-color-combo.js
 import * as designReviewPrompt from './prompts/design-review.js';
 import * as explainTokenSystemPrompt from './prompts/explain-token-system.js';
 import * as getTokenReferencePrompt from './prompts/get-token-reference.js';
+import * as configureIconsPrompt from './prompts/configure-icons.js';
+import * as useRecipePrompt from './prompts/use-recipe.js';
 
 /**
  * Create and configure the MCP server
@@ -48,6 +50,12 @@ import * as getTokenReferencePrompt from './prompts/get-token-reference.js';
 const server = new McpServer({
   name: 'optics-mcp',
   version: '0.1.0',
+}, {
+  capabilities: {
+    tools: {},
+    prompts: {},
+    resources: {},
+  }
 });
 
 /**

From fa51cf7329a9f1fb1c7ea6aeeb7602554bab1f38 Mon Sep 17 00:00:00 2001
From: Jeremy Walton <jeremy.walton@rolemodelsoftware.com>
Date: Thu, 5 Feb 2026 14:05:33 -0500
Subject: [PATCH 05/28] Extract get token tool to its own file (#19)

---
 src/index.ts                | 52 ++++++++++++++++---------------------
 src/tools/get-token-tool.ts | 30 +++++++++++++++++++++
 src/tools/tool.ts           | 46 ++++++++++++++++++++++++++++++++
 3 files changed, 99 insertions(+), 29 deletions(-)
 create mode 100644 src/tools/get-token-tool.ts
 create mode 100644 src/tools/tool.ts

diff --git a/src/index.ts b/src/index.ts
index f4810c6..fcf20b1 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -44,6 +44,9 @@ import * as getTokenReferencePrompt from './prompts/get-token-reference.js';
 import * as configureIconsPrompt from './prompts/configure-icons.js';
 import * as useRecipePrompt from './prompts/use-recipe.js';
 
+// Tools
+import GetTokenTool from './tools/get-token-tool.js';
+
 /**
  * Create and configure the MCP server
  */
@@ -184,45 +187,36 @@ prompts.forEach((prompt) => {
   )
 })
 
-
 /**
- * Tool: Get Token
+ * Tools
  */
-server.registerTool(
-  'get_token',
-  {
-    title: 'Get Token',
-    description: 'Get detailed information about a specific design token by name',
-    inputSchema: {
-      tokenName: z.string().describe('The name of the design token (e.g., "color-primary", "spacing-md")'),
+
+const tools = [
+  new GetTokenTool(),
+]
+
+tools.forEach((tool) => {
+  server.registerTool(
+    tool.metadata.name,
+    {
+      title: tool.metadata.title,
+      description: tool.metadata.description,
+      inputSchema: tool.inputSchema,
     },
-  },
-  async ({ tokenName }) => {
-    const token = designTokens.find((t) => t.name === tokenName);
+    async (args: any) => {
+      const content = await tool.handler(args)
 
-    if (!token) {
       return {
         content: [
           {
             type: 'text',
-            text: `Token not found: ${tokenName}\n\nAvailable tokens: ${designTokens
-              .map((t) => t.name)
-              .join(', ')}`,
+            text: content,
           },
         ],
-      };
-    }
-
-    return {
-      content: [
-        {
-          type: 'text',
-          text: JSON.stringify(token, null, 2),
-        },
-      ],
-    };
-  }
-);
+      }
+    },
+  )
+})
 
 /**
  * Tool: Search Tokens
diff --git a/src/tools/get-token-tool.ts b/src/tools/get-token-tool.ts
new file mode 100644
index 0000000..58aca64
--- /dev/null
+++ b/src/tools/get-token-tool.ts
@@ -0,0 +1,30 @@
+import { z } from 'zod'
+
+import Tool, { type ToolInputSchema } from './tool.js'
+import { designTokens } from '../optics-data.js'
+
+class GetTokenTool extends Tool {
+  name = 'get_token'
+  title = 'Get Token'
+  description = 'Get detailed information about a specific design token by name'
+
+  inputSchema = {
+    tokenName: z
+      .string()
+      .describe('The name of the design token (e.g., "color-primary", "spacing-md")'),
+  }
+
+  async handler(args: ToolInputSchema): Promise<string> {
+    const { tokenName } = args
+
+    const token = designTokens.find((t) => t.name === tokenName)
+
+    if (!token) {
+      return `Token not found: ${tokenName}\n\nAvailable tokens: ${designTokens.map((t) => t.name).join(', ')}`
+    }
+
+    return JSON.stringify(token, null, 2)
+  }
+}
+
+export default GetTokenTool
diff --git a/src/tools/tool.ts b/src/tools/tool.ts
new file mode 100644
index 0000000..c93af70
--- /dev/null
+++ b/src/tools/tool.ts
@@ -0,0 +1,46 @@
+interface ToolMetadata {
+  name: string
+  title: string
+  description: string
+  uri?: string
+  mimeType?: string
+  role?: string
+}
+
+interface ToolInputSchema {
+  [key: string]: any
+}
+
+class Tool {
+  name: string = '';
+  title: string = '';
+  description: string = '';
+  uri?: string;
+  mimeType?: string;
+  role?: string;
+
+  /**
+   * Example:
+   * { tokenName: z.string().describe('The name of the design token (e.g., "color-primary", "spacing-md")') }
+   */
+  inputSchema: ToolInputSchema = {};
+
+  get metadata(): ToolMetadata {
+    return {
+      name: this.name,
+      title: this.title,
+      description: this.description,
+      ...(this.uri !== undefined && { uri: this.uri }),
+      ...(this.mimeType !== undefined && { mimeType: this.mimeType }),
+      ...(this.role !== undefined && { role: this.role }),
+    }
+  }
+
+  async handler(args: any): Promise<string> {
+    throw new Error('Subclass should override')
+  }
+}
+
+export default Tool
+
+export { ToolMetadata, ToolInputSchema }

From 2af16685b6e8ae12b61dbea1f94eca72471ad7e0 Mon Sep 17 00:00:00 2001
From: Jeremy Walton <jeremy.walton@rolemodelsoftware.com>
Date: Thu, 5 Feb 2026 14:28:17 -0500
Subject: [PATCH 06/28] Extract token usage stats (#20)

---
 src/index.ts                            | 34 ++++++++-----------------
 src/optics-data.ts                      | 17 -------------
 src/test.ts                             | 10 ++++----
 src/tools/get-token-usage-stats-tool.ts | 34 +++++++++++++++++++++++++
 4 files changed, 49 insertions(+), 46 deletions(-)
 create mode 100644 src/tools/get-token-usage-stats-tool.ts

diff --git a/src/index.ts b/src/index.ts
index fcf20b1..0e00d67 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -15,7 +15,6 @@ import {
   designTokens,
   components,
   documentation,
-  getTokenUsageStats,
   getComponentTokenDependencies,
 } from './optics-data.js';
 import { generateTheme } from './tools/theme-generator.js';
@@ -46,6 +45,7 @@ import * as useRecipePrompt from './prompts/use-recipe.js';
 
 // Tools
 import GetTokenTool from './tools/get-token-tool.js';
+import GetTokenUsageStatsTool from './tools/get-token-usage-stats-tool.js';
 
 /**
  * Create and configure the MCP server
@@ -191,8 +191,17 @@ prompts.forEach((prompt) => {
  * Tools
  */
 
+// get_token ✅
+// get_token_usage_stats ✅
+// search_tokens
+// list_components
+// get_component_info
+// get_component_tokens
+// search_documentation
+
 const tools = [
   new GetTokenTool(),
+  new GetTokenUsageStatsTool(),
 ]
 
 tools.forEach((tool) => {
@@ -256,29 +265,6 @@ server.registerTool(
   }
 );
 
-/**
- * Tool: Get Token Usage Stats
- */
-server.registerTool(
-  'get_token_usage_stats',
-  {
-    title: 'Get Token Usage Stats',
-    description: 'Get statistics about design token usage across the system',
-    inputSchema: {},
-  },
-  async () => {
-    const stats = getTokenUsageStats();
-    return {
-      content: [
-        {
-          type: 'text',
-          text: JSON.stringify(stats, null, 2),
-        },
-      ],
-    };
-  }
-);
-
 /**
  * Tool: Get Component Info
  */
diff --git a/src/optics-data.ts b/src/optics-data.ts
index 619b353..a14948b 100644
--- a/src/optics-data.ts
+++ b/src/optics-data.ts
@@ -1575,23 +1575,6 @@ export const documentation: Documentation[] = [
   }
 ];
 
-/**
- * Get token usage statistics
- */
-export function getTokenUsageStats() {
-  const categoryCount: Record<string, number> = {};
-
-  designTokens.forEach(token => {
-    categoryCount[token.category] = (categoryCount[token.category] || 0) + 1;
-  });
-
-  return {
-    totalTokens: designTokens.length,
-    categories: categoryCount,
-    tokens: designTokens
-  };
-}
-
 /**
  * Get component token dependencies
  */
diff --git a/src/test.ts b/src/test.ts
index a84c583..9b0381b 100644
--- a/src/test.ts
+++ b/src/test.ts
@@ -4,7 +4,7 @@
  * Simple test script to verify the Optics MCP server functionality
  */
 
-import { designTokens, components, getTokenUsageStats, getComponentTokenDependencies } from './optics-data.js';
+import { designTokens, components, getComponentTokenDependencies } from './optics-data.js';
 
 console.log('🧪 Testing Optics MCP Server...\n');
 
@@ -21,10 +21,10 @@ console.log(`  Total components: ${components.length}`);
 console.log(`  Components: ${components.map(c => c.name).join(', ')}\n`);
 
 // Test 3: Token Usage Stats
-console.log('✓ Test 3: Token Usage Statistics');
-const stats = getTokenUsageStats();
-console.log(`  Total tokens: ${stats.totalTokens}`);
-console.log(`  Categories:`, stats.categories, '\n');
+// console.log('✓ Test 3: Token Usage Statistics');
+// const stats = getTokenUsageStats();
+// console.log(`  Total tokens: ${stats.totalTokens}`);
+// console.log(`  Categories:`, stats.categories, '\n');
 
 // Test 4: Component Token Dependencies
 console.log('✓ Test 4: Component Token Dependencies');
diff --git a/src/tools/get-token-usage-stats-tool.ts b/src/tools/get-token-usage-stats-tool.ts
new file mode 100644
index 0000000..a7d83a9
--- /dev/null
+++ b/src/tools/get-token-usage-stats-tool.ts
@@ -0,0 +1,34 @@
+import { z } from 'zod'
+
+import Tool, { type ToolInputSchema } from './tool.js'
+import { designTokens } from '../optics-data.js'
+
+class GetTokenUsageStatsTool extends Tool {
+  name = 'get_token_usage_stats'
+  title = 'Get Token Usage Stats'
+  description = 'Get statistics about design token usage across the system'
+
+  inputSchema = {}
+
+  async handler(args: ToolInputSchema): Promise<string> {
+    const stats = this.getTokenUsageStats()
+
+    return JSON.stringify(stats, null, 2)
+  }
+
+  private getTokenUsageStats() {
+    const categoryCount: Record<string, number> = {};
+
+    designTokens.forEach(token => {
+      categoryCount[token.category] = (categoryCount[token.category] || 0) + 1;
+    });
+
+    return {
+      totalTokens: designTokens.length,
+      categories: categoryCount,
+      tokens: designTokens
+    }
+  }
+}
+
+export default GetTokenUsageStatsTool

From 50cd90b77b9ad28d71b3f1ea8b78dc33d0ea52f1 Mon Sep 17 00:00:00 2001
From: Dominic MacAulay <dominic.62502@gmail.com>
Date: Thu, 5 Feb 2026 14:30:53 -0500
Subject: [PATCH 07/28] Extract Search Tokens Tool (#21)

# Conflicts:
#	src/index.ts
---
 src/index.ts                    | 42 +++------------------------------
 src/tools/search-tokens-tool.ts | 41 ++++++++++++++++++++++++++++++++
 2 files changed, 44 insertions(+), 39 deletions(-)
 create mode 100644 src/tools/search-tokens-tool.ts

diff --git a/src/index.ts b/src/index.ts
index 0e00d67..7ab45f4 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -46,6 +46,7 @@ import * as useRecipePrompt from './prompts/use-recipe.js';
 // Tools
 import GetTokenTool from './tools/get-token-tool.js';
 import GetTokenUsageStatsTool from './tools/get-token-usage-stats-tool.js';
+import SearchTokensTool from './tools/search-tokens-tool.js';
 
 /**
  * Create and configure the MCP server
@@ -193,7 +194,7 @@ prompts.forEach((prompt) => {
 
 // get_token ✅
 // get_token_usage_stats ✅
-// search_tokens
+// search_tokens ✅
 // list_components
 // get_component_info
 // get_component_tokens
@@ -202,6 +203,7 @@ prompts.forEach((prompt) => {
 const tools = [
   new GetTokenTool(),
   new GetTokenUsageStatsTool(),
+  new SearchTokensTool(),
 ]
 
 tools.forEach((tool) => {
@@ -227,44 +229,6 @@ tools.forEach((tool) => {
   )
 })
 
-/**
- * Tool: Search Tokens
- */
-server.registerTool(
-  'search_tokens',
-  {
-    title: 'Search Tokens',
-    description: 'Search for design tokens by category or name pattern',
-    inputSchema: {
-      category: z.string().optional().describe('Filter by category (color, spacing, typography, border, shadow)'),
-      namePattern: z.string().optional().describe('Search pattern for token names (case-insensitive)'),
-    },
-  },
-  async ({ category, namePattern }) => {
-    let filtered = designTokens;
-
-    if (category) {
-      filtered = filtered.filter((t) => t.category === category);
-    }
-
-    if (namePattern) {
-      const pattern = namePattern.toLowerCase();
-      filtered = filtered.filter((t) =>
-        t.name.toLowerCase().includes(pattern)
-      );
-    }
-
-    return {
-      content: [
-        {
-          type: 'text',
-          text: JSON.stringify(filtered, null, 2),
-        },
-      ],
-    };
-  }
-);
-
 /**
  * Tool: Get Component Info
  */
diff --git a/src/tools/search-tokens-tool.ts b/src/tools/search-tokens-tool.ts
new file mode 100644
index 0000000..ec35b9e
--- /dev/null
+++ b/src/tools/search-tokens-tool.ts
@@ -0,0 +1,41 @@
+import { z } from 'zod'
+
+import Tool, { type ToolInputSchema } from './tool.js'
+import { designTokens } from '../optics-data.js'
+
+class SearchTokensTool extends Tool {
+  name = 'search_tokens'
+  title = 'Search Tokens'
+  description = 'Search for design tokens by category or name pattern'
+
+  inputSchema = {
+    category: z
+      .string()
+      .optional()
+      .describe('Filter by category (color, spacing, typography, border, shadow)'),
+    namePattern: z
+      .string()
+      .optional()
+      .describe('Search pattern for token names (case-insensitive)')
+  }
+
+  async handler(args: ToolInputSchema): Promise<string> {
+    const { category, namePattern } = args
+    let filtered = designTokens;
+
+    if (category) {
+      filtered = filtered.filter((t) => t.category === category);
+    }
+
+    if (namePattern) {
+      const pattern = namePattern.toLowerCase();
+      filtered = filtered.filter((t) =>
+        t.name.toLowerCase().includes(pattern)
+      );
+    }
+
+    return JSON.stringify(filtered, null, 2)
+  }
+}
+
+export default SearchTokensTool

From c8db4860987b076bb98c8c1047c100191c602f58 Mon Sep 17 00:00:00 2001
From: Jeremy Walton <jeremy.walton@rolemodelsoftware.com>
Date: Thu, 5 Feb 2026 14:38:48 -0500
Subject: [PATCH 08/28] Extract list components (#22)

---
 src/index.ts                      | 32 +++----------------------------
 src/tools/list-components-tool.ts | 24 +++++++++++++++++++++++
 2 files changed, 27 insertions(+), 29 deletions(-)
 create mode 100644 src/tools/list-components-tool.ts

diff --git a/src/index.ts b/src/index.ts
index 7ab45f4..2824241 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -47,6 +47,7 @@ import * as useRecipePrompt from './prompts/use-recipe.js';
 import GetTokenTool from './tools/get-token-tool.js';
 import GetTokenUsageStatsTool from './tools/get-token-usage-stats-tool.js';
 import SearchTokensTool from './tools/search-tokens-tool.js';
+import ListComponentsTool from './tools/list-components-tool.js'
 
 /**
  * Create and configure the MCP server
@@ -195,7 +196,7 @@ prompts.forEach((prompt) => {
 // get_token ✅
 // get_token_usage_stats ✅
 // search_tokens ✅
-// list_components
+// list_components ✅
 // get_component_info
 // get_component_tokens
 // search_documentation
@@ -204,6 +205,7 @@ const tools = [
   new GetTokenTool(),
   new GetTokenUsageStatsTool(),
   new SearchTokensTool(),
+  new ListComponentsTool(),
 ]
 
 tools.forEach((tool) => {
@@ -270,34 +272,6 @@ server.registerTool(
   }
 );
 
-/**
- * Tool: List Components
- */
-server.registerTool(
-  'list_components',
-  {
-    title: 'List Components',
-    description: 'List all available components in the design system',
-    inputSchema: {},
-  },
-  async () => {
-    const componentList = components.map((c) => ({
-      name: c.name,
-      description: c.description,
-      tokenCount: c.tokens.length,
-    }));
-
-    return {
-      content: [
-        {
-          type: 'text',
-          text: JSON.stringify(componentList, null, 2),
-        },
-      ],
-    };
-  }
-);
-
 /**
  * Tool: Get Component Tokens
  */
diff --git a/src/tools/list-components-tool.ts b/src/tools/list-components-tool.ts
new file mode 100644
index 0000000..2490992
--- /dev/null
+++ b/src/tools/list-components-tool.ts
@@ -0,0 +1,24 @@
+import { z } from 'zod'
+
+import Tool, { type ToolInputSchema } from './tool.js'
+import { components } from '../optics-data.js'
+
+class ListComponentsTool extends Tool {
+  name = 'list_components'
+  title = 'List Components'
+  description = 'List all available components in the design system'
+
+  inputSchema = {}
+
+  async handler(args: ToolInputSchema): Promise<string> {
+    const componentList = components.map((c) => ({
+      name: c.name,
+      description: c.description,
+      tokenCount: c.tokens.length,
+    }));
+
+    return JSON.stringify(componentList, null, 2)
+  }
+}
+
+export default ListComponentsTool

From 41601ab4a3320c2b3540a0fdfd67683c36469beb Mon Sep 17 00:00:00 2001
From: Dominic MacAulay <dominic.62502@gmail.com>
Date: Thu, 5 Feb 2026 15:02:58 -0500
Subject: [PATCH 09/28] Extract Get Component Info Tool (#23)

* extract

# Conflicts:
#	src/index.ts

* Remove unneeded import
---
 src/index.ts                         | 46 ++--------------------------
 src/tools/get-component-info-tool.ts | 35 +++++++++++++++++++++
 2 files changed, 38 insertions(+), 43 deletions(-)
 create mode 100644 src/tools/get-component-info-tool.ts

diff --git a/src/index.ts b/src/index.ts
index 2824241..687218b 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -13,7 +13,6 @@ import type { ListPromptsRequestSchema, GetPromptRequestSchema } from "@modelcon
 import { z } from 'zod';
 import {
   designTokens,
-  components,
   documentation,
   getComponentTokenDependencies,
 } from './optics-data.js';
@@ -48,6 +47,7 @@ import GetTokenTool from './tools/get-token-tool.js';
 import GetTokenUsageStatsTool from './tools/get-token-usage-stats-tool.js';
 import SearchTokensTool from './tools/search-tokens-tool.js';
 import ListComponentsTool from './tools/list-components-tool.js'
+import GetComponentInfoTool from './tools/get-component-info-tool.js';
 
 /**
  * Create and configure the MCP server
@@ -197,7 +197,7 @@ prompts.forEach((prompt) => {
 // get_token_usage_stats ✅
 // search_tokens ✅
 // list_components ✅
-// get_component_info
+// get_component_info ✅
 // get_component_tokens
 // search_documentation
 
@@ -206,6 +206,7 @@ const tools = [
   new GetTokenUsageStatsTool(),
   new SearchTokensTool(),
   new ListComponentsTool(),
+  new GetComponentInfoTool(),
 ]
 
 tools.forEach((tool) => {
@@ -231,47 +232,6 @@ tools.forEach((tool) => {
   )
 })
 
-/**
- * Tool: Get Component Info
- */
-server.registerTool(
-  'get_component_info',
-  {
-    title: 'Get Component Info',
-    description: 'Get detailed information about a component including its design token dependencies',
-    inputSchema: {
-      componentName: z.string().describe('The name of the component (e.g., "Button", "Card", "Input")'),
-    },
-  },
-  async ({ componentName }) => {
-    const component = components.find(
-      (c) => c.name.toLowerCase() === componentName.toLowerCase()
-    );
-
-    if (!component) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `Component not found: ${componentName}\n\nAvailable components: ${components
-              .map((c) => c.name)
-              .join(', ')}`,
-          },
-        ],
-      };
-    }
-
-    return {
-      content: [
-        {
-          type: 'text',
-          text: JSON.stringify(component, null, 2),
-        },
-      ],
-    };
-  }
-);
-
 /**
  * Tool: Get Component Tokens
  */
diff --git a/src/tools/get-component-info-tool.ts b/src/tools/get-component-info-tool.ts
new file mode 100644
index 0000000..f0f01da
--- /dev/null
+++ b/src/tools/get-component-info-tool.ts
@@ -0,0 +1,35 @@
+import { z } from 'zod'
+
+import Tool, { type ToolInputSchema } from './tool.js'
+import { components } from '../optics-data.js'
+
+class GetComponentInfoTool extends Tool {
+  name = 'get_component_info'
+  title = 'Get Component Info'
+  description = 'Get detailed information about a component including its design token dependencies'
+
+  inputSchema = {
+    componentName: z
+      .string()
+      .describe('The name of the component (e.g., "Button", "Card", "Input")')
+  }
+
+  async handler(args: ToolInputSchema): Promise<string> {
+    const component = components.find(
+      (c) => c.name.toLowerCase() === args.componentName.toLowerCase()
+    )
+
+    let value = ''
+
+    if (!component) {
+      const availableComponents = components.map((c) => c.name).join(', ')
+      value = `Component not found: ${args.componentName}\n\nAvailable components: ${availableComponents}`
+    } else {
+      value = JSON.stringify(component, null, 2)
+    }
+
+    return value
+  }
+}
+
+export default GetComponentInfoTool

From 7d91eaf152d25fe6461a9ea03bcb4340335abc1f Mon Sep 17 00:00:00 2001
From: Dominic MacAulay <dominic.62502@gmail.com>
Date: Thu, 5 Feb 2026 15:18:24 -0500
Subject: [PATCH 10/28] Extract Get Component Tokens Tool (#24)

* Extract Get Component Tokens Tool

* Address comment
---
 src/index.ts                           | 47 ++---------------------
 src/optics-data.ts                     | 24 ------------
 src/test.ts                            | 14 +++----
 src/tools/get-component-tokens-tool.ts | 52 ++++++++++++++++++++++++++
 4 files changed, 63 insertions(+), 74 deletions(-)
 create mode 100644 src/tools/get-component-tokens-tool.ts

diff --git a/src/index.ts b/src/index.ts
index 687218b..58496c9 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -11,11 +11,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import type { ListPromptsRequestSchema, GetPromptRequestSchema } from "@modelcontextprotocol/sdk/types"
 import { z } from 'zod';
-import {
-  designTokens,
-  documentation,
-  getComponentTokenDependencies,
-} from './optics-data.js';
+import { designTokens, documentation } from './optics-data.js';
 import { generateTheme } from './tools/theme-generator.js';
 import { validateTokenUsage, formatValidationReport } from './tools/validate.js';
 import { replaceHardCodedValues, formatReplacementSuggestions } from './tools/replace.js';
@@ -48,6 +44,7 @@ import GetTokenUsageStatsTool from './tools/get-token-usage-stats-tool.js';
 import SearchTokensTool from './tools/search-tokens-tool.js';
 import ListComponentsTool from './tools/list-components-tool.js'
 import GetComponentInfoTool from './tools/get-component-info-tool.js';
+import GetComponentTokensTool from './tools/get-component-tokens-tool.js';
 
 /**
  * Create and configure the MCP server
@@ -198,7 +195,7 @@ prompts.forEach((prompt) => {
 // search_tokens ✅
 // list_components ✅
 // get_component_info ✅
-// get_component_tokens
+// get_component_tokens ✅
 // search_documentation
 
 const tools = [
@@ -207,6 +204,7 @@ const tools = [
   new SearchTokensTool(),
   new ListComponentsTool(),
   new GetComponentInfoTool(),
+  new GetComponentTokensTool(),
 ]
 
 tools.forEach((tool) => {
@@ -232,43 +230,6 @@ tools.forEach((tool) => {
   )
 })
 
-/**
- * Tool: Get Component Tokens
- */
-server.registerTool(
-  'get_component_tokens',
-  {
-    title: 'Get Component Tokens',
-    description: 'Get all design tokens used by a specific component',
-    inputSchema: {
-      componentName: z.string().describe('The name of the component'),
-    },
-  },
-  async ({ componentName }) => {
-    const deps = getComponentTokenDependencies(componentName);
-
-    if (!deps) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `Component not found: ${componentName}`,
-          },
-        ],
-      };
-    }
-
-    return {
-      content: [
-        {
-          type: 'text',
-          text: JSON.stringify(deps, null, 2),
-        },
-      ],
-    };
-  }
-);
-
 /**
  * Tool: Search Documentation
  */
diff --git a/src/optics-data.ts b/src/optics-data.ts
index a14948b..95ff948 100644
--- a/src/optics-data.ts
+++ b/src/optics-data.ts
@@ -1574,27 +1574,3 @@ export const documentation: Documentation[] = [
     tokens: []
   }
 ];
-
-/**
- * Get component token dependencies
- */
-export function getComponentTokenDependencies(componentName: string) {
-  const component = components.find(c =>
-    c.name.toLowerCase() === componentName.toLowerCase()
-  );
-
-  if (!component) {
-    return null;
-  }
-
-  const tokenDetails = component.tokens.map(tokenName =>
-    designTokens.find(t => t.name === tokenName)
-  ).filter((token): token is DesignToken => token !== undefined);
-
-  return {
-    component: component.name,
-    description: component.description,
-    tokenCount: component.tokens.length,
-    tokens: tokenDetails
-  };
-}
diff --git a/src/test.ts b/src/test.ts
index 9b0381b..f4b6237 100644
--- a/src/test.ts
+++ b/src/test.ts
@@ -4,7 +4,7 @@
  * Simple test script to verify the Optics MCP server functionality
  */
 
-import { designTokens, components, getComponentTokenDependencies } from './optics-data.js';
+import { designTokens, components } from './optics-data.js';
 
 console.log('🧪 Testing Optics MCP Server...\n');
 
@@ -27,12 +27,12 @@ console.log(`  Components: ${components.map(c => c.name).join(', ')}\n`);
 // console.log(`  Categories:`, stats.categories, '\n');
 
 // Test 4: Component Token Dependencies
-console.log('✓ Test 4: Component Token Dependencies');
-const buttonDeps = getComponentTokenDependencies('Button');
-if (buttonDeps) {
-  console.log(`  ${buttonDeps.component}: ${buttonDeps.tokenCount} tokens`);
-  console.log(`  First token: ${buttonDeps.tokens[0]?.name}\n`);
-}
+// console.log('✓ Test 4: Component Token Dependencies');
+// const buttonDeps = getComponentTokenDependencies('Button');
+// if (buttonDeps) {
+//   console.log(`  ${buttonDeps.component}: ${buttonDeps.tokenCount} tokens`);
+//   console.log(`  First token: ${buttonDeps.tokens[0]?.name}\n`);
+// }
 
 // Test 5: Search functionality
 console.log('✓ Test 5: Token Search');
diff --git a/src/tools/get-component-tokens-tool.ts b/src/tools/get-component-tokens-tool.ts
new file mode 100644
index 0000000..eb5f115
--- /dev/null
+++ b/src/tools/get-component-tokens-tool.ts
@@ -0,0 +1,52 @@
+import { z } from 'zod'
+
+import Tool, { type ToolInputSchema } from './tool.js'
+import { components, designTokens, type DesignToken } from '../optics-data.js'
+
+class GetComponentTokensTool extends Tool {
+  name = 'get_component_tokens'
+  title = 'Get Component Tokens'
+  description = 'Get all design tokens used by a specific component'
+
+  inputSchema = {
+    componentName: z
+      .string()
+      .describe('The name of the component (e.g., "Button", "Card", "Input")')
+  }
+
+  async handler(args: ToolInputSchema): Promise<string> {
+    const dependencies = this.getComponentTokenDependencies(args.componentName);
+
+    let value = ''
+
+    if (!dependencies) {
+      const availableComponents = components.map((c) => c.name).join(', ')
+      value = `Component not found: ${args.componentName}\n\nAvailable components: ${availableComponents}`
+    } else {
+      value = JSON.stringify(dependencies, null, 2)
+    }
+
+    return value
+  }
+
+  private getComponentTokenDependencies(componentName: string) {
+    const component = components.find(c =>
+      c.name.toLowerCase() === componentName.toLowerCase()
+    );
+
+    if (!component) return null
+
+    const tokenDetails = component.tokens.map(tokenName =>
+      designTokens.find(t => t.name.replace(/^--op/, 'op') === tokenName.replace(/^--op/, 'op'))
+    ).filter((token): token is DesignToken => token !== undefined);
+
+    return {
+      component: component.name,
+      description: component.description,
+      tokenCount: component.tokens.length,
+      tokens: tokenDetails
+    };
+  }
+}
+
+export default GetComponentTokensTool

From 10c01d41e56107157d84cffad4e230dcd8c5ad8a Mon Sep 17 00:00:00 2001
From: Dominic MacAulay <dominic.62502@gmail.com>
Date: Thu, 5 Feb 2026 15:22:59 -0500
Subject: [PATCH 11/28] Extract Search Documentation Tool (#25)

* Extract Search Documentation Tool

# Conflicts:
#	src/index.ts

* Remove checklist
---
 src/index.ts                           | 43 ++------------------------
 src/tools/search-documentation-tool.ts | 30 ++++++++++++++++++
 2 files changed, 33 insertions(+), 40 deletions(-)
 create mode 100644 src/tools/search-documentation-tool.ts

diff --git a/src/index.ts b/src/index.ts
index 58496c9..bd9150f 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -11,7 +11,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import type { ListPromptsRequestSchema, GetPromptRequestSchema } from "@modelcontextprotocol/sdk/types"
 import { z } from 'zod';
-import { designTokens, documentation } from './optics-data.js';
+import { designTokens } from './optics-data.js';
 import { generateTheme } from './tools/theme-generator.js';
 import { validateTokenUsage, formatValidationReport } from './tools/validate.js';
 import { replaceHardCodedValues, formatReplacementSuggestions } from './tools/replace.js';
@@ -45,6 +45,7 @@ import SearchTokensTool from './tools/search-tokens-tool.js';
 import ListComponentsTool from './tools/list-components-tool.js'
 import GetComponentInfoTool from './tools/get-component-info-tool.js';
 import GetComponentTokensTool from './tools/get-component-tokens-tool.js';
+import SearchDocumentationTool from './tools/search-documentation-tool.js';
 
 /**
  * Create and configure the MCP server
@@ -190,14 +191,6 @@ prompts.forEach((prompt) => {
  * Tools
  */
 
-// get_token ✅
-// get_token_usage_stats ✅
-// search_tokens ✅
-// list_components ✅
-// get_component_info ✅
-// get_component_tokens ✅
-// search_documentation
-
 const tools = [
   new GetTokenTool(),
   new GetTokenUsageStatsTool(),
@@ -205,6 +198,7 @@ const tools = [
   new ListComponentsTool(),
   new GetComponentInfoTool(),
   new GetComponentTokensTool(),
+  new SearchDocumentationTool()
 ]
 
 tools.forEach((tool) => {
@@ -230,37 +224,6 @@ tools.forEach((tool) => {
   )
 })
 
-/**
- * Tool: Search Documentation
- */
-server.registerTool(
-  'search_documentation',
-  {
-    title: 'Search Documentation',
-    description: 'Search through Optics documentation',
-    inputSchema: {
-      query: z.string().describe('Search query for documentation content'),
-    },
-  },
-  async ({ query }) => {
-    const results = documentation.filter(
-      (doc) =>
-        doc.title.toLowerCase().includes(query.toLowerCase()) ||
-        doc.content.toLowerCase().includes(query.toLowerCase()) ||
-        doc.section.toLowerCase().includes(query.toLowerCase())
-    );
-
-    return {
-      content: [
-        {
-          type: 'text',
-          text: JSON.stringify(results, null, 2),
-        },
-      ],
-    };
-  }
-);
-
 /**
  * Tool: Generate Theme
  */
diff --git a/src/tools/search-documentation-tool.ts b/src/tools/search-documentation-tool.ts
new file mode 100644
index 0000000..25f2366
--- /dev/null
+++ b/src/tools/search-documentation-tool.ts
@@ -0,0 +1,30 @@
+import { z } from 'zod'
+
+import Tool, { type ToolInputSchema } from './tool.js'
+import { documentation } from '../optics-data.js'
+
+class SearchDocumentationTool extends Tool {
+  name = 'search_documentation'
+  title = 'Search Documentation'
+  description = 'Search through Optics documentation'
+
+  inputSchema = {
+    query: z
+      .string()
+      .describe('Search query for documentation content')
+  }
+
+  async handler(args: ToolInputSchema): Promise<string> {
+    const { query } = args
+    const results = documentation.filter(
+      (doc) =>
+        doc.title.toLowerCase().includes(query.toLowerCase()) ||
+        doc.content.toLowerCase().includes(query.toLowerCase()) ||
+        doc.section.toLowerCase().includes(query.toLowerCase())
+    )
+
+    return JSON.stringify(results, null, 2)
+  }
+}
+
+export default SearchDocumentationTool

From d83afa4ad9cedc8b82dc5a7b39b15aa9d9db89da Mon Sep 17 00:00:00 2001
From: Jeremy Walton <jeremy.walton@rolemodelsoftware.com>
Date: Thu, 5 Feb 2026 15:40:15 -0500
Subject: [PATCH 12/28] Extract the replace hard coded values tool (#26)

* extract it

* Remove old tool
---
 src/index.ts                                |  32 +-----
 src/tools/replace-hard-coded-values-tool.ts | 111 ++++++++++++++++++++
 src/tools/replace.ts                        | 101 ------------------
 3 files changed, 115 insertions(+), 129 deletions(-)
 create mode 100644 src/tools/replace-hard-coded-values-tool.ts
 delete mode 100644 src/tools/replace.ts

diff --git a/src/index.ts b/src/index.ts
index bd9150f..390ee64 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -14,7 +14,7 @@ import { z } from 'zod';
 import { designTokens } from './optics-data.js';
 import { generateTheme } from './tools/theme-generator.js';
 import { validateTokenUsage, formatValidationReport } from './tools/validate.js';
-import { replaceHardCodedValues, formatReplacementSuggestions } from './tools/replace.js';
+
 import { checkTokenContrast, formatContrastResult } from './tools/accessibility.js';
 import { suggestTokenMigration, formatMigrationSuggestions } from './tools/migration.js';
 import { generateComponentScaffold, formatScaffoldOutput } from './tools/scaffold.js';
@@ -46,6 +46,7 @@ import ListComponentsTool from './tools/list-components-tool.js'
 import GetComponentInfoTool from './tools/get-component-info-tool.js';
 import GetComponentTokensTool from './tools/get-component-tokens-tool.js';
 import SearchDocumentationTool from './tools/search-documentation-tool.js';
+import ReplaceHardCodedValuesTool from './tools/replace-hard-coded-values-tool.js';
 
 /**
  * Create and configure the MCP server
@@ -198,7 +199,8 @@ const tools = [
   new ListComponentsTool(),
   new GetComponentInfoTool(),
   new GetComponentTokensTool(),
-  new SearchDocumentationTool()
+  new SearchDocumentationTool(),
+  new ReplaceHardCodedValuesTool()
 ]
 
 tools.forEach((tool) => {
@@ -284,33 +286,7 @@ server.registerTool(
   }
 );
 
-/**
- * Tool: Replace Hard-Coded Values
- */
-server.registerTool(
-  'replace_hard_coded_values',
-  {
-    title: 'Replace Hard-Coded Values',
-    description: 'Replace hard-coded values with design tokens',
-    inputSchema: {
-      code: z.string().describe('Code containing hard-coded values'),
-      autofix: z.boolean().optional().describe('Whether to automatically fix the code (default: false)'),
-    },
-  },
-  async ({ code, autofix }) => {
-    const result = replaceHardCodedValues(code, designTokens, autofix ?? false);
-    const formatted = formatReplacementSuggestions(result);
 
-    return {
-      content: [
-        {
-          type: 'text',
-          text: formatted,
-        },
-      ],
-    };
-  }
-);
 
 /**
  * Tool: Check Contrast
diff --git a/src/tools/replace-hard-coded-values-tool.ts b/src/tools/replace-hard-coded-values-tool.ts
new file mode 100644
index 0000000..e682977
--- /dev/null
+++ b/src/tools/replace-hard-coded-values-tool.ts
@@ -0,0 +1,111 @@
+import { z } from 'zod'
+import Tool from './tool.js'
+import { designTokens, type DesignToken } from '../optics-data.js'
+import { extractAllValues, findMatchingToken } from '../utils/css-parser.js'
+
+interface ReplacementSuggestion {
+  original: string
+  replacement: string
+  tokenName: string
+  property?: string
+}
+
+interface ReplacementResult {
+  originalCode: string
+  fixedCode: string
+  replacements: ReplacementSuggestion[]
+  replacementCount: number
+}
+
+class ReplaceHardCodedValuesTool extends Tool {
+  name = 'replace_hard_coded_values'
+  title = 'Replace Hard-Coded Values'
+  description = 'Replace hard-coded values with design tokens'
+
+  inputSchema = {
+    code: z.string().describe('Code containing hard-coded values'),
+    autofix: z.boolean().optional().describe('Whether to automatically fix the code (default: false)'),
+  }
+
+  async handler(args: any): Promise<string> {
+    const { code, autofix } = args
+    const result = this.replaceHardCodedValues(code, designTokens, autofix ?? false)
+    return this.formatReplacementSuggestions(result)
+  }
+
+  private replaceHardCodedValues(
+    code: string,
+    tokens: DesignToken[],
+    autofix: boolean = false
+  ): ReplacementResult {
+    const extractedValues = extractAllValues(code)
+    const replacements: ReplacementSuggestion[] = []
+    let fixedCode = code
+
+    for (const value of extractedValues) {
+      const matchingToken = findMatchingToken(value.value, tokens)
+
+      if (matchingToken) {
+        const replacement = `var(--${matchingToken})`
+        replacements.push({
+          original: value.value,
+          replacement,
+          tokenName: matchingToken,
+          property: value.property,
+        })
+
+        if (autofix) {
+          fixedCode = fixedCode.replace(
+            new RegExp(this.escapeRegex(value.value), 'g'),
+            replacement
+          )
+        }
+      }
+    }
+
+    return {
+      originalCode: code,
+      fixedCode: autofix ? fixedCode : code,
+      replacements,
+      replacementCount: replacements.length,
+    }
+  }
+
+  private escapeRegex(str: string): string {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  }
+
+  private formatReplacementSuggestions(result: ReplacementResult): string {
+    const lines: string[] = [
+      '# Token Replacement Suggestions',
+      '',
+      `**Replacements Found**: ${result.replacementCount}`,
+      '',
+    ]
+
+    if (result.replacements.length > 0) {
+      lines.push('## Suggested Replacements')
+      lines.push('')
+
+      for (const rep of result.replacements) {
+        lines.push(`- Replace \`${rep.original}\` with \`${rep.replacement}\``)
+        lines.push(`  Token: ${rep.tokenName}`)
+        if (rep.property) lines.push(`  Property: ${rep.property}`)
+        lines.push('')
+      }
+
+      if (result.fixedCode !== result.originalCode) {
+        lines.push('## Fixed Code')
+        lines.push('```css')
+        lines.push(result.fixedCode)
+        lines.push('```')
+      }
+    } else {
+      lines.push('✓ No replacements needed!')
+    }
+
+    return lines.join('\n')
+  }
+}
+
+export default ReplaceHardCodedValuesTool
diff --git a/src/tools/replace.ts b/src/tools/replace.ts
deleted file mode 100644
index 1a57179..0000000
--- a/src/tools/replace.ts
+++ /dev/null
@@ -1,101 +0,0 @@
-/**
- * Token replacement tool
- * Replaces hard-coded values with design tokens
- */
-
-import { DesignToken } from '../optics-data.js';
-import { extractAllValues, findMatchingToken } from '../utils/css-parser.js';
-
-export interface ReplacementSuggestion {
-  original: string;
-  replacement: string;
-  tokenName: string;
-  property?: string;
-}
-
-export interface ReplacementResult {
-  originalCode: string;
-  fixedCode: string;
-  replacements: ReplacementSuggestion[];
-  replacementCount: number;
-}
-
-/**
- * Replace hard-coded values with tokens
- */
-export function replaceHardCodedValues(
-  code: string,
-  tokens: DesignToken[],
-  autofix: boolean = false
-): ReplacementResult {
-  const extractedValues = extractAllValues(code);
-  const replacements: ReplacementSuggestion[] = [];
-  let fixedCode = code;
-  
-  for (const value of extractedValues) {
-    const matchingToken = findMatchingToken(value.value, tokens);
-    
-    if (matchingToken) {
-      const replacement = `var(--${matchingToken})`;
-      replacements.push({
-        original: value.value,
-        replacement,
-        tokenName: matchingToken,
-        property: value.property
-      });
-      
-      if (autofix) {
-        fixedCode = fixedCode.replace(
-          new RegExp(escapeRegex(value.value), 'g'),
-          replacement
-        );
-      }
-    }
-  }
-  
-  return {
-    originalCode: code,
-    fixedCode: autofix ? fixedCode : code,
-    replacements,
-    replacementCount: replacements.length
-  };
-}
-
-function escapeRegex(str: string): string {
-  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-
-/**
- * Format replacement suggestions
- */
-export function formatReplacementSuggestions(result: ReplacementResult): string {
-  const lines: string[] = [
-    '# Token Replacement Suggestions',
-    '',
-    `**Replacements Found**: ${result.replacementCount}`,
-    ''
-  ];
-  
-  if (result.replacements.length > 0) {
-    lines.push('## Suggested Replacements');
-    lines.push('');
-    
-    for (const rep of result.replacements) {
-      lines.push(`- Replace \`${rep.original}\` with \`${rep.replacement}\``);
-      lines.push(`  Token: ${rep.tokenName}`);
-      if (rep.property) lines.push(`  Property: ${rep.property}`);
-      lines.push('');
-    }
-    
-    if (result.fixedCode !== result.originalCode) {
-      lines.push('## Fixed Code');
-      lines.push('```css');
-      lines.push(result.fixedCode);
-      lines.push('```');
-    }
-  } else {
-    lines.push('✓ No replacements needed!');
-  }
-  
-  return lines.join('\n');
-}

From 79fb28c4786db5286bc9dddf073e560c16985bd6 Mon Sep 17 00:00:00 2001
From: Dominic MacAulay <dominic.62502@gmail.com>
Date: Thu, 5 Feb 2026 16:54:26 -0500
Subject: [PATCH 13/28] Extract remaining tools (#27)

* Create read tool file method

* extract the theme generator

* Finish tool class extractions

* Extract md files

* specifiy import type

* update type

* removed unused parameter

* removed useless variable stuff
---
 src/_internal/resource-path.ts                |   9 +-
 src/index.ts                                  | 222 +---------
 src/tools/accessibility.ts                    | 148 -------
 src/tools/check-contrast-error.md             |   7 +
 src/tools/check-contrast-result.md            |   9 +
 src/tools/check-contrast-tool.ts              | 148 +++++++
 src/tools/generate-component-scaffold-tool.ts | 216 ++++++++++
 .../generate-component-scaffold-usage.md      |  23 ++
 .../generate-sticker-sheet-instructions.md    |  22 +
 ...heet.ts => generate-sticker-sheet-tool.ts} | 309 +++++++-------
 src/tools/generate-theme-instructions.md      |  63 +++
 src/tools/generate-theme-output.md            |  24 ++
 src/tools/generate-theme-tool.ts              | 286 +++++++++++++
 src/tools/migration.ts                        | 149 -------
 src/tools/replace-hard-coded-values-tool.ts   |   4 +-
 src/tools/scaffold.ts                         | 208 ----------
 src/tools/suggest-token-migration-header.md   |   5 +
 src/tools/suggest-token-migration-none.md     |   6 +
 src/tools/suggest-token-migration-tool.ts     | 169 ++++++++
 src/tools/theme-generator.ts                  | 387 ------------------
 src/tools/validate-token-usage-header.md      |   7 +
 src/tools/validate-token-usage-tool.ts        | 138 +++++++
 src/tools/validate-token-usage-valid.md       |   7 +
 src/tools/validate.ts                         | 121 ------
 24 files changed, 1303 insertions(+), 1384 deletions(-)
 delete mode 100644 src/tools/accessibility.ts
 create mode 100644 src/tools/check-contrast-error.md
 create mode 100644 src/tools/check-contrast-result.md
 create mode 100644 src/tools/check-contrast-tool.ts
 create mode 100644 src/tools/generate-component-scaffold-tool.ts
 create mode 100644 src/tools/generate-component-scaffold-usage.md
 create mode 100644 src/tools/generate-sticker-sheet-instructions.md
 rename src/tools/{sticker-sheet.ts => generate-sticker-sheet-tool.ts} (67%)
 create mode 100644 src/tools/generate-theme-instructions.md
 create mode 100644 src/tools/generate-theme-output.md
 create mode 100644 src/tools/generate-theme-tool.ts
 delete mode 100644 src/tools/migration.ts
 delete mode 100644 src/tools/scaffold.ts
 create mode 100644 src/tools/suggest-token-migration-header.md
 create mode 100644 src/tools/suggest-token-migration-none.md
 create mode 100644 src/tools/suggest-token-migration-tool.ts
 delete mode 100644 src/tools/theme-generator.ts
 create mode 100644 src/tools/validate-token-usage-header.md
 create mode 100644 src/tools/validate-token-usage-tool.ts
 create mode 100644 src/tools/validate-token-usage-valid.md
 delete mode 100644 src/tools/validate.ts

diff --git a/src/_internal/resource-path.ts b/src/_internal/resource-path.ts
index 1393076..8cc1ca6 100644
--- a/src/_internal/resource-path.ts
+++ b/src/_internal/resource-path.ts
@@ -16,4 +16,11 @@ const readPromptFile = async (filename: string): Promise<string> => {
   return readFileSync(filePath, 'utf-8')
 }
 
-export { readResourceFile, readPromptFile }
+const readToolFile = async (filename: string): Promise<string> => {
+  const currentDir = dirname(fileURLToPath(import.meta.url))
+  const filePath = join(currentDir, '..', 'tools', filename)
+
+  return readFileSync(filePath, 'utf-8')
+}
+
+export { readResourceFile, readPromptFile, readToolFile }
diff --git a/src/index.ts b/src/index.ts
index 390ee64..623480f 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -12,14 +12,6 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import type { ListPromptsRequestSchema, GetPromptRequestSchema } from "@modelcontextprotocol/sdk/types"
 import { z } from 'zod';
 import { designTokens } from './optics-data.js';
-import { generateTheme } from './tools/theme-generator.js';
-import { validateTokenUsage, formatValidationReport } from './tools/validate.js';
-
-import { checkTokenContrast, formatContrastResult } from './tools/accessibility.js';
-import { suggestTokenMigration, formatMigrationSuggestions } from './tools/migration.js';
-import { generateComponentScaffold, formatScaffoldOutput } from './tools/scaffold.js';
-import { generateStickerSheet, formatStickerSheet } from './tools/sticker-sheet.js';
-import { getRecipe, searchRecipes, formatRecipe, formatRecipeList } from './tools/recipes.js';
 
 // Resources
 import * as systemOverview from './resources/system-overview.js';
@@ -35,8 +27,6 @@ import * as accessibleColorComboPrompt from './prompts/accessible-color-combo.js
 import * as designReviewPrompt from './prompts/design-review.js';
 import * as explainTokenSystemPrompt from './prompts/explain-token-system.js';
 import * as getTokenReferencePrompt from './prompts/get-token-reference.js';
-import * as configureIconsPrompt from './prompts/configure-icons.js';
-import * as useRecipePrompt from './prompts/use-recipe.js';
 
 // Tools
 import GetTokenTool from './tools/get-token-tool.js';
@@ -46,7 +36,13 @@ import ListComponentsTool from './tools/list-components-tool.js'
 import GetComponentInfoTool from './tools/get-component-info-tool.js';
 import GetComponentTokensTool from './tools/get-component-tokens-tool.js';
 import SearchDocumentationTool from './tools/search-documentation-tool.js';
+import GenerateThemeTool from './tools/generate-theme-tool.js';
+import ValidateTokenUsageTool from './tools/validate-token-usage-tool.js';
 import ReplaceHardCodedValuesTool from './tools/replace-hard-coded-values-tool.js';
+import CheckContrastTool from './tools/check-contrast-tool.js';
+import SuggestTokenMigrationTool from './tools/suggest-token-migration-tool.js';
+import GenerateComponentScaffoldTool from './tools/generate-component-scaffold-tool.js';
+import GenerateStickerSheetTool from './tools/generate-sticker-sheet-tool.js';
 
 /**
  * Create and configure the MCP server
@@ -54,12 +50,6 @@ import ReplaceHardCodedValuesTool from './tools/replace-hard-coded-values-tool.j
 const server = new McpServer({
   name: 'optics-mcp',
   version: '0.1.0',
-}, {
-  capabilities: {
-    tools: {},
-    prompts: {},
-    resources: {},
-  }
 });
 
 /**
@@ -156,9 +146,7 @@ const prompts = [
   accessibleColorComboPrompt,
   designReviewPrompt,
   explainTokenSystemPrompt,
-  getTokenReferencePrompt,
-  configureIconsPrompt,
-  useRecipePrompt
+  getTokenReferencePrompt
 ]
 
 prompts.forEach((prompt) => {
@@ -200,7 +188,13 @@ const tools = [
   new GetComponentInfoTool(),
   new GetComponentTokensTool(),
   new SearchDocumentationTool(),
-  new ReplaceHardCodedValuesTool()
+  new GenerateThemeTool(),
+  new ValidateTokenUsageTool(),
+  new ReplaceHardCodedValuesTool(),
+  new CheckContrastTool(),
+  new SuggestTokenMigrationTool(),
+  new GenerateComponentScaffoldTool(),
+  new GenerateStickerSheetTool()
 ]
 
 tools.forEach((tool) => {
@@ -226,194 +220,6 @@ tools.forEach((tool) => {
   )
 })
 
-/**
- * Tool: Generate Theme
- */
-server.registerTool(
-  'generate_theme',
-  {
-    title: 'Generate Theme',
-    description: 'Generate a custom Optics theme with CSS variable overrides',
-    inputSchema: {
-      brandName: z.string().describe('Name of the brand/theme (e.g., "Acme Corp")'),
-      primary: z.string().describe('Primary brand color (hex, e.g., "#0066CC")'),
-      secondary: z.string().optional().describe('Secondary color (hex, optional)'),
-    },
-  },
-  async ({ brandName, primary, secondary }) => {
-    const brandColors = {
-      primary,
-      secondary,
-    };
-
-    const theme = generateTheme(brandName, brandColors);
-
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `# ${brandName} Theme Generated\n\n## CSS Variables\n\n\`\`\`css\n${theme.cssVariables}\n\`\`\`\n\n## Figma Variables\n\nSave this as \`figma-variables.json\`:\n\n\`\`\`json\n${theme.figmaVariables}\n\`\`\`\n\n## Summary\n\n- **Total tokens**: ${theme.tokens.length}\n- **Colors**: ${theme.tokens.filter(t => t.category === 'color').length}\n- **Typography**: ${theme.tokens.filter(t => t.category === 'typography').length}\n- **Spacing**: ${theme.tokens.filter(t => t.category === 'spacing').length}\n\n${theme.documentation}`,
-        },
-      ],
-    };
-  }
-);
-
-/**
- * Tool: Validate Token Usage
- */
-server.registerTool(
-  'validate_token_usage',
-  {
-    title: 'Validate Token Usage',
-    description: 'Validate code for hard-coded values that should use design tokens',
-    inputSchema: {
-      code: z.string().describe('CSS or component code to validate'),
-    },
-  },
-  async ({ code }) => {
-    const report = validateTokenUsage(code, designTokens);
-    const formatted = formatValidationReport(report);
-
-    return {
-      content: [
-        {
-          type: 'text',
-          text: formatted,
-        },
-      ],
-    };
-  }
-);
-
-
-
-/**
- * Tool: Check Contrast
- */
-server.registerTool(
-  'check_contrast',
-  {
-    title: 'Check Contrast',
-    description: 'Check WCAG contrast ratio between two color tokens',
-    inputSchema: {
-      foregroundToken: z.string().describe('Foreground color token name'),
-      backgroundToken: z.string().describe('Background color token name'),
-    },
-  },
-  async ({ foregroundToken, backgroundToken }) => {
-    const result = checkTokenContrast(foregroundToken, backgroundToken, designTokens);
-    const formatted = formatContrastResult(result);
-
-    return {
-      content: [
-        {
-          type: 'text',
-          text: formatted,
-        },
-      ],
-    };
-  }
-);
-
-/**
- * Tool: Suggest Token Migration
- */
-server.registerTool(
-  'suggest_token_migration',
-  {
-    title: 'Suggest Token Migration',
-    description: 'Suggest design tokens for a hard-coded value',
-    inputSchema: {
-      value: z.string().describe('Hard-coded value to find tokens for (e.g., "#0066CC", "16px")'),
-      category: z.string().optional().describe('Optional category filter (color, spacing, typography)'),
-    },
-  },
-  async ({ value, category }) => {
-    const suggestion = suggestTokenMigration(value, designTokens, category);
-    const formatted = formatMigrationSuggestions(suggestion);
-
-    return {
-      content: [
-        {
-          type: 'text',
-          text: formatted,
-        },
-      ],
-    };
-  }
-);
-
-/**
- * Tool: Generate Component Scaffold
- */
-server.registerTool(
-  'generate_component_scaffold',
-  {
-    title: 'Generate Component Scaffold',
-    description: 'Generate a React component scaffold with proper token usage',
-    inputSchema: {
-      componentName: z.string().describe('Name of the component (e.g., "Alert", "Card")'),
-      description: z.string().describe('Brief description of the component'),
-      tokens: z.array(z.string()).describe('List of token names the component should use'),
-    },
-  },
-  async ({ componentName, description, tokens }) => {
-    const scaffold = generateComponentScaffold(
-      componentName,
-      description,
-      tokens,
-      designTokens
-    );
-    const formatted = formatScaffoldOutput(scaffold);
-
-    return {
-      content: [
-        {
-          type: 'text',
-          text: formatted,
-        },
-      ],
-    };
-  }
-);
-
-/**
- * Tool: Generate Sticker Sheet
- */
-server.registerTool(
-  'generate_sticker_sheet',
-  {
-    title: 'Generate Sticker Sheet',
-    description: 'Generate a visual style guide with color swatches and component examples',
-    inputSchema: {
-      framework: z.enum(['react', 'vue', 'svelte', 'html']).optional().describe('Target framework (default: react)'),
-      includeColors: z.boolean().optional().describe('Include color swatches (default: true)'),
-      includeTypography: z.boolean().optional().describe('Include typography specimens (default: true)'),
-      includeComponents: z.boolean().optional().describe('Include component examples (default: true)'),
-    },
-  },
-  async ({ framework, includeColors, includeTypography, includeComponents }) => {
-    const options = {
-      framework: framework ?? 'react',
-      includeColors: includeColors ?? true,
-      includeTypography: includeTypography ?? true,
-      includeComponents: includeComponents ?? true,
-    };
-    const sheet = generateStickerSheet(designTokens, components, options);
-    const formatted = formatStickerSheet(sheet);
-
-    return {
-      content: [
-        {
-          type: 'text',
-          text: formatted,
-        },
-      ],
-    };
-  }
-);
-
 /**
  * Start the server
  */
diff --git a/src/tools/accessibility.ts b/src/tools/accessibility.ts
deleted file mode 100644
index 5a44602..0000000
--- a/src/tools/accessibility.ts
+++ /dev/null
@@ -1,148 +0,0 @@
-/**
- * Accessibility checker tool
- * Validates WCAG contrast ratios for token combinations
- */
-
-import { DesignToken } from '../optics-data.js';
-import { checkContrast, ContrastResult } from '../utils/color.js';
-
-export interface ContrastCheckResult {
-  foregroundToken: string;
-  backgroundToken: string;
-  foregroundValue: string;
-  backgroundValue: string;
-  contrast: ContrastResult | null;
-  passes: boolean;
-  recommendation?: string;
-}
-
-/**
- * Check contrast between two tokens
- */
-export function checkTokenContrast(
-  foregroundToken: string,
-  backgroundToken: string,
-  tokens: DesignToken[]
-): ContrastCheckResult {
-  const fgToken = tokens.find(t => t.name === foregroundToken);
-  const bgToken = tokens.find(t => t.name === backgroundToken);
-  
-  if (!fgToken || !bgToken) {
-    return {
-      foregroundToken,
-      backgroundToken,
-      foregroundValue: '',
-      backgroundValue: '',
-      contrast: null,
-      passes: false,
-      recommendation: 'Token not found'
-    };
-  }
-  
-  const contrast = checkContrast(fgToken.value, bgToken.value);
-  
-  if (!contrast) {
-    return {
-      foregroundToken,
-      backgroundToken,
-      foregroundValue: fgToken.value,
-      backgroundValue: bgToken.value,
-      contrast: null,
-      passes: false,
-      recommendation: 'Unable to calculate contrast (non-color tokens?)'
-    };
-  }
-  
-  const passes = contrast.wcagAA;
-  let recommendation = '';
-  
-  if (!passes) {
-    recommendation = findBetterTokenCombination(fgToken, tokens, bgToken.value);
-  }
-  
-  return {
-    foregroundToken,
-    backgroundToken,
-    foregroundValue: fgToken.value,
-    backgroundValue: bgToken.value,
-    contrast,
-    passes,
-    recommendation
-  };
-}
-
-/**
- * Find better token combination with sufficient contrast
- */
-function findBetterTokenCombination(
-  currentToken: DesignToken,
-  allTokens: DesignToken[],
-  backgroundValue: string
-): string {
-  const colorTokens = allTokens.filter(t => t.category === 'color');
-  
-  for (const token of colorTokens) {
-    const contrast = checkContrast(token.value, backgroundValue);
-    if (contrast && contrast.wcagAA) {
-      return `Try using ${token.name} (${token.value}) for better contrast`;
-    }
-  }
-  
-  return 'No alternative tokens found with sufficient contrast';
-}
-
-/**
- * Format contrast check result
- */
-export function formatContrastResult(result: ContrastCheckResult): string {
-  const lines: string[] = [
-    '# Contrast Check Result',
-    '',
-    `**Foreground**: ${result.foregroundToken} (\`${result.foregroundValue}\`)`,
-    `**Background**: ${result.backgroundToken} (\`${result.backgroundValue}\`)`,
-    ''
-  ];
-  
-  if (result.contrast) {
-    lines.push(`**Contrast Ratio**: ${result.contrast.ratio}:1`);
-    lines.push(`**WCAG AA**: ${result.contrast.wcagAA ? '✓ Pass' : '✗ Fail'}`);
-    lines.push(`**WCAG AAA**: ${result.contrast.wcagAAA ? '✓ Pass' : '✗ Fail'}`);
-    lines.push(`**Score**: ${result.contrast.score}`);
-    lines.push('');
-    
-    if (!result.passes && result.recommendation) {
-      lines.push('## Recommendation');
-      lines.push(result.recommendation);
-    }
-  } else {
-    lines.push('✗ Unable to calculate contrast');
-    if (result.recommendation) {
-      lines.push(`**Reason**: ${result.recommendation}`);
-    }
-  }
-  
-  return lines.join('\n');
-}
-
-/**
- * Check all color token combinations for a given background
- */
-export function checkAllCombinations(
-  backgroundToken: string,
-  tokens: DesignToken[]
-): ContrastCheckResult[] {
-  const bgToken = tokens.find(t => t.name === backgroundToken);
-  if (!bgToken) return [];
-  
-  const colorTokens = tokens.filter(t => t.category === 'color' && t.name !== backgroundToken);
-  const results: ContrastCheckResult[] = [];
-  
-  for (const fgToken of colorTokens) {
-    results.push(checkTokenContrast(fgToken.name, backgroundToken, tokens));
-  }
-  
-  return results.sort((a, b) => {
-    if (!a.contrast || !b.contrast) return 0;
-    return b.contrast.ratio - a.contrast.ratio;
-  });
-}
diff --git a/src/tools/check-contrast-error.md b/src/tools/check-contrast-error.md
new file mode 100644
index 0000000..fbaecf2
--- /dev/null
+++ b/src/tools/check-contrast-error.md
@@ -0,0 +1,7 @@
+# Contrast Check Result
+
+**Foreground**: {{foregroundToken}} (`{{foregroundValue}}`)
+**Background**: {{backgroundToken}} (`{{backgroundValue}}`)
+
+✗ Unable to calculate contrast
+**Reason**: {{reason}}
diff --git a/src/tools/check-contrast-result.md b/src/tools/check-contrast-result.md
new file mode 100644
index 0000000..06f3fab
--- /dev/null
+++ b/src/tools/check-contrast-result.md
@@ -0,0 +1,9 @@
+# Contrast Check Result
+
+**Foreground**: {{foregroundToken}} (`{{foregroundValue}}`)
+**Background**: {{backgroundToken}} (`{{backgroundValue}}`)
+
+**Contrast Ratio**: {{contrastRatio}}:1
+**WCAG AA**: {{wcagAA}}
+**WCAG AAA**: {{wcagAAA}}
+**Score**: {{score}}
diff --git a/src/tools/check-contrast-tool.ts b/src/tools/check-contrast-tool.ts
new file mode 100644
index 0000000..40f9db2
--- /dev/null
+++ b/src/tools/check-contrast-tool.ts
@@ -0,0 +1,148 @@
+/**
+ * Check Contrast Tool
+ * Validates WCAG contrast ratios for token combinations
+ */
+
+import { z } from 'zod';
+import Tool, { type ToolInputSchema } from './tool.js';
+import { designTokens, type DesignToken } from '../optics-data.js';
+import { checkContrast, type ContrastResult } from '../utils/color.js';
+import { readToolFile } from '../_internal/resource-path.js';
+
+export interface ContrastCheckResult {
+  foregroundToken: string;
+  backgroundToken: string;
+  foregroundValue: string;
+  backgroundValue: string;
+  contrast: ContrastResult | null;
+  passes: boolean;
+  recommendation?: string;
+}
+
+class CheckContrastTool extends Tool {
+  name = 'check_contrast';
+  title = 'Check Contrast';
+  description = 'Check WCAG contrast ratio between two color tokens';
+
+  inputSchema = {
+    foregroundToken: z.string().describe('Foreground color token name'),
+    backgroundToken: z.string().describe('Background color token name'),
+  };
+
+  async handler(args: ToolInputSchema): Promise<string> {
+    const { foregroundToken, backgroundToken } = args;
+    const result = this.checkTokenContrast(foregroundToken, backgroundToken, designTokens);
+    const formatted = await this.formatContrastResult(result);
+
+    return formatted;
+  }
+
+  /**
+   * Check contrast between two tokens
+   */
+  private checkTokenContrast(
+    foregroundToken: string,
+    backgroundToken: string,
+    tokens: DesignToken[]
+  ): ContrastCheckResult {
+    const fgToken = tokens.find(t => t.name === foregroundToken);
+    const bgToken = tokens.find(t => t.name === backgroundToken);
+
+    if (!fgToken || !bgToken) {
+      return {
+        foregroundToken,
+        backgroundToken,
+        foregroundValue: '',
+        backgroundValue: '',
+        contrast: null,
+        passes: false,
+        recommendation: 'Token not found'
+      };
+    }
+
+    const contrast = checkContrast(fgToken.value, bgToken.value);
+
+    if (!contrast) {
+      return {
+        foregroundToken,
+        backgroundToken,
+        foregroundValue: fgToken.value,
+        backgroundValue: bgToken.value,
+        contrast: null,
+        passes: false,
+        recommendation: 'Unable to calculate contrast (non-color tokens?)'
+      };
+    }
+
+    const passes = contrast.wcagAA;
+    let recommendation = '';
+
+    if (!passes) {
+      recommendation = this.findBetterTokenCombination(fgToken, tokens, bgToken.value);
+    }
+
+    return {
+      foregroundToken,
+      backgroundToken,
+      foregroundValue: fgToken.value,
+      backgroundValue: bgToken.value,
+      contrast,
+      passes,
+      recommendation
+    };
+  }
+
+  /**
+   * Find better token combination with sufficient contrast
+   */
+  private findBetterTokenCombination(
+    currentToken: DesignToken,
+    allTokens: DesignToken[],
+    backgroundValue: string
+  ): string {
+    const colorTokens = allTokens.filter(t => t.category === 'color');
+
+    for (const token of colorTokens) {
+      const contrast = checkContrast(token.value, backgroundValue);
+      if (contrast && contrast.wcagAA) {
+        return `Try using ${token.name} (${token.value}) for better contrast`;
+      }
+    }
+
+    return 'No alternative tokens found with sufficient contrast';
+  }
+
+  /**
+   * Format contrast check result
+   */
+  private async formatContrastResult(result: ContrastCheckResult): Promise<string> {
+    if (result.contrast) {
+      const template = await readToolFile('check-contrast-result.md');
+      let output = template
+        .replace('{{foregroundToken}}', result.foregroundToken)
+        .replace('{{foregroundValue}}', result.foregroundValue)
+        .replace('{{backgroundToken}}', result.backgroundToken)
+        .replace('{{backgroundValue}}', result.backgroundValue)
+        .replace('{{contrastRatio}}', result.contrast.ratio.toString())
+        .replace('{{wcagAA}}', result.contrast.wcagAA ? '✓ Pass' : '✗ Fail')
+        .replace('{{wcagAAA}}', result.contrast.wcagAAA ? '✓ Pass' : '✗ Fail')
+        .replace('{{score}}', result.contrast.score);
+
+      if (!result.passes && result.recommendation) {
+        output += '\n\n## Recommendation\n' + result.recommendation;
+      }
+
+      return output;
+    } else {
+      const template = await readToolFile('check-contrast-error.md');
+      return template
+        .replace('{{foregroundToken}}', result.foregroundToken)
+        .replace('{{foregroundValue}}', result.foregroundValue)
+        .replace('{{backgroundToken}}', result.backgroundToken)
+        .replace('{{backgroundValue}}', result.backgroundValue)
+        .replace('{{reason}}', result.recommendation || 'Unknown error');
+    }
+  }
+}
+
+export default CheckContrastTool;
diff --git a/src/tools/generate-component-scaffold-tool.ts b/src/tools/generate-component-scaffold-tool.ts
new file mode 100644
index 0000000..2aae030
--- /dev/null
+++ b/src/tools/generate-component-scaffold-tool.ts
@@ -0,0 +1,216 @@
+/**
+ * Generate Component Scaffold Tool
+ * Generates component templates with proper token usage
+ */
+
+import { z } from 'zod';
+import Tool, { type ToolInputSchema } from './tool.js';
+import { designTokens, type DesignToken } from '../optics-data.js';
+import { readToolFile } from '../_internal/resource-path.js';
+
+export interface ComponentScaffold {
+  name: string;
+  typescript: string;
+  css: string;
+  usage: string;
+}
+
+class GenerateComponentScaffoldTool extends Tool {
+  name = 'generate_component_scaffold';
+  title = 'Generate Component Scaffold';
+  description = 'Generate a React component scaffold with proper token usage';
+
+  inputSchema = {
+    componentName: z.string().describe('Name of the component (e.g., "Alert", "Card")'),
+    description: z.string().describe('Brief description of the component'),
+    tokens: z.array(z.string()).describe('List of token names the component should use'),
+  };
+
+  async handler(args: ToolInputSchema): Promise<string> {
+    const { componentName, description, tokens } = args;
+    const scaffold = await this.generateComponentScaffold(
+      componentName,
+      description,
+      tokens,
+      designTokens
+    );
+    const formatted = this.formatScaffoldOutput(scaffold);
+
+    return formatted;
+  }
+
+  /**
+   * Generate component scaffold
+   */
+  private async generateComponentScaffold(
+    componentName: string,
+    description: string,
+    requiredTokens: string[],
+    allTokens: DesignToken[]
+  ): Promise<ComponentScaffold> {
+    const validTokens = requiredTokens.filter(tokenName =>
+      allTokens.some(t => t.name === tokenName)
+    );
+
+    const typescript = this.generateTypeScriptComponent(componentName, description, validTokens);
+    const css = this.generateCSSModule(componentName, validTokens, allTokens);
+    const usage = await this.generateUsageExample(componentName);
+
+    return {
+      name: componentName,
+      typescript,
+      css,
+      usage
+    };
+  }
+
+  /**
+   * Generate TypeScript component
+   */
+  private generateTypeScriptComponent(
+    name: string,
+    description: string,
+    tokens: string[]
+  ): string {
+    const lines: string[] = [
+      `/**`,
+      ` * ${name} Component`,
+      ` * ${description}`,
+      ` * `,
+      ` * Design tokens used:`,
+      ...tokens.map(t => ` * - ${t}`),
+      ` */`,
+      ``,
+      `import React from 'react';`,
+      `import styles from './${name}.module.css';`,
+      ``,
+      `export interface ${name}Props {`,
+      `  children: React.ReactNode;`,
+      `  className?: string;`,
+      `}`,
+      ``,
+      `export const ${name}: React.FC<${name}Props> = ({ children, className }) => {`,
+      `  return (`,
+      `    <div className={\`\${styles.${name.toLowerCase()}} \${className || ''}\`}>`,
+      `      {children}`,
+      `    </div>`,
+      `  );`,
+      `};`
+    ];
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Generate CSS module
+   */
+  private generateCSSModule(
+    name: string,
+    tokenNames: string[],
+    allTokens: DesignToken[]
+  ): string {
+    const lines: string[] = [
+      `/**`,
+      ` * ${name} Component Styles`,
+      ` * Uses Optics design tokens for consistent styling`,
+      ` */`,
+      ``,
+      `.${name.toLowerCase()} {`
+    ];
+
+    // Group tokens by category
+    const colorTokens = tokenNames.filter(t => allTokens.find(token => token.name === t && token.category === 'color'));
+    const spacingTokens = tokenNames.filter(t => allTokens.find(token => token.name === t && token.category === 'spacing'));
+    const typographyTokens = tokenNames.filter(t => allTokens.find(token => token.name === t && token.category === 'typography'));
+    const borderTokens = tokenNames.filter(t => allTokens.find(token => token.name === t && token.category === 'border'));
+    const shadowTokens = tokenNames.filter(t => allTokens.find(token => token.name === t && token.category === 'shadow'));
+
+    // Add color properties
+    if (colorTokens.length > 0) {
+      lines.push(`  /* Colors */`);
+      if (colorTokens.some(t => t.includes('background'))) {
+        const bgToken = colorTokens.find(t => t.includes('background'));
+        lines.push(`  background-color: var(--${bgToken});`);
+      }
+      if (colorTokens.some(t => t.includes('text') || t.includes('color-primary'))) {
+        const textToken = colorTokens.find(t => t.includes('text')) || colorTokens[0];
+        lines.push(`  color: var(--${textToken});`);
+      }
+    }
+
+    // Add spacing
+    if (spacingTokens.length > 0) {
+      lines.push(`  /* Spacing */`);
+      const paddingToken = spacingTokens[0];
+      lines.push(`  padding: var(--${paddingToken});`);
+    }
+
+    // Add typography
+    if (typographyTokens.length > 0) {
+      lines.push(`  /* Typography */`);
+      typographyTokens.forEach(token => {
+        if (token.includes('font-size')) {
+          lines.push(`  font-size: var(--${token});`);
+        } else if (token.includes('font-weight')) {
+          lines.push(`  font-weight: var(--${token});`);
+        } else if (token.includes('line-height')) {
+          lines.push(`  line-height: var(--${token});`);
+        } else if (token.includes('font-family')) {
+          lines.push(`  font-family: var(--${token});`);
+        }
+      });
+    }
+
+    // Add borders
+    if (borderTokens.length > 0) {
+      lines.push(`  /* Borders */`);
+      lines.push(`  border-radius: var(--${borderTokens[0]});`);
+    }
+
+    // Add shadows
+    if (shadowTokens.length > 0) {
+      lines.push(`  /* Elevation */`);
+      lines.push(`  box-shadow: var(--${shadowTokens[0]});`);
+    }
+
+    lines.push(`}`);
+    lines.push(``);
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Generate usage example
+   */
+  private async generateUsageExample(name: string): Promise<string> {
+    const template = await readToolFile('generate-component-scaffold-usage.md');
+
+    return template.replace(/{{componentName}}/g, name);
+  }
+
+  /**
+   * Format scaffold output
+   */
+  private formatScaffoldOutput(scaffold: ComponentScaffold): string {
+    const lines: string[] = [
+      `# ${scaffold.name} Component Scaffold`,
+      ``,
+      `## TypeScript Component`,
+      `\`\`\`typescript`,
+      scaffold.typescript,
+      `\`\`\``,
+      ``,
+      `## CSS Module`,
+      `\`\`\`css`,
+      scaffold.css,
+      `\`\`\``,
+      ``,
+      `## Usage`,
+      scaffold.usage
+    ];
+
+    return lines.join('\n');
+  }
+}
+
+export default GenerateComponentScaffoldTool;
diff --git a/src/tools/generate-component-scaffold-usage.md b/src/tools/generate-component-scaffold-usage.md
new file mode 100644
index 0000000..8c8abec
--- /dev/null
+++ b/src/tools/generate-component-scaffold-usage.md
@@ -0,0 +1,23 @@
+# {{componentName}} Usage
+
+## Import
+
+```typescript
+import { {{componentName}} } from './components/{{componentName}}';
+```
+
+## Basic Usage
+
+```tsx
+<{{componentName}}>
+  Your content here
+</{{componentName}}>
+```
+
+## With Custom ClassName
+
+```tsx
+<{{componentName}} className="custom-class">
+  Your content here
+</{{componentName}}>
+```
diff --git a/src/tools/generate-sticker-sheet-instructions.md b/src/tools/generate-sticker-sheet-instructions.md
new file mode 100644
index 0000000..f3dfd40
--- /dev/null
+++ b/src/tools/generate-sticker-sheet-instructions.md
@@ -0,0 +1,22 @@
+# Optics Sticker Sheet - {{framework}}
+
+This sticker sheet provides a visual reference for all Optics design tokens and components.
+
+## Usage
+
+1. Copy the component code below into your {{framework}} project
+2. Copy the CSS styles into your stylesheet
+3. Import and use the components in your app
+4. Replace placeholders with actual component implementations
+
+## Files Generated
+
+- **Component Code**: Ready-to-use {{framework}} components
+- **Styles**: CSS using Optics design tokens
+- **Examples**: Visual specimens of colors, typography, and components
+
+## Next Steps
+
+- Customize the examples to match your specific components
+- Add interactive states (hover, focus, disabled)
+- Include additional token categories as needed
diff --git a/src/tools/sticker-sheet.ts b/src/tools/generate-sticker-sheet-tool.ts
similarity index 67%
rename from src/tools/sticker-sheet.ts
rename to src/tools/generate-sticker-sheet-tool.ts
index 7f1e3c5..723b67c 100644
--- a/src/tools/sticker-sheet.ts
+++ b/src/tools/generate-sticker-sheet-tool.ts
@@ -1,9 +1,12 @@
 /**
- * Sticker sheet generator
+ * Generate Sticker Sheet Tool
  * Generates visual style guide with color swatches and component examples
  */
 
-import { DesignToken, Component } from '../optics-data.js';
+import { z } from 'zod';
+import Tool, { type ToolInputSchema } from './tool.js';
+import { designTokens, components, type DesignToken, type Component } from '../optics-data.js';
+import { readToolFile } from '../_internal/resource-path.js';
 
 export type FrameworkType = 'react' | 'vue' | 'svelte' | 'html';
 
@@ -11,7 +14,6 @@ export interface StickerSheetOptions {
   framework?: FrameworkType;
   includeColors?: boolean;
   includeTypography?: boolean;
-  includeSpacing?: boolean;
   includeComponents?: boolean;
 }
 
@@ -22,32 +24,58 @@ export interface StickerSheet {
   instructions: string;
 }
 
-/**
- * Generate color swatch component
- */
-function generateColorSwatches(tokens: DesignToken[], framework: FrameworkType): string {
-  const colors = tokens.filter(t => t.category === 'color');
-  
-  const swatchesData = colors.map(token => ({
-    name: token.name,
-    value: token.value,
-    hsl: token.name.startsWith('color-') ? `var(--op-${token.name.replace('color-', '')}-h) var(--op-${token.name.replace('color-', '')}-s) var(--op-${token.name.replace('color-', '')}-l)` : token.value
-  }));
-  
-  switch (framework) {
-    case 'react':
-      return `
+class GenerateStickerSheetTool extends Tool {
+  name = 'generate_sticker_sheet';
+  title = 'Generate Sticker Sheet';
+  description = 'Generate a visual style guide with color swatches and component examples';
+
+  inputSchema = {
+    framework: z.enum(['react', 'vue', 'svelte', 'html']).optional().describe('Target framework (default: react)'),
+    includeColors: z.boolean().optional().describe('Include color swatches (default: true)'),
+    includeTypography: z.boolean().optional().describe('Include typography specimens (default: true)'),
+    includeComponents: z.boolean().optional().describe('Include component examples (default: true)'),
+  };
+
+  async handler(args: ToolInputSchema): Promise<string> {
+    const { framework, includeColors, includeTypography, includeComponents } = args;
+    const options = {
+      framework: framework ?? 'react',
+      includeColors: includeColors ?? true,
+      includeTypography: includeTypography ?? true,
+      includeComponents: includeComponents ?? true,
+    };
+    const sheet = await this.generateStickerSheet(designTokens, components, options);
+    const formatted = this.formatStickerSheet(sheet);
+
+    return formatted;
+  }
+
+  /**
+   * Generate color swatch component
+   */
+  private generateColorSwatches(tokens: DesignToken[], framework: FrameworkType): string {
+    const colors = tokens.filter(t => t.category === 'color');
+
+    const swatchesData = colors.map(token => ({
+      name: token.name,
+      value: token.value,
+      hsl: token.name.startsWith('color-') ? `var(--op-${token.name.replace('color-', '')}-h) var(--op-${token.name.replace('color-', '')}-s) var(--op-${token.name.replace('color-', '')}-l)` : token.value
+    }));
+
+    switch (framework) {
+      case 'react':
+        return `
 export function ColorSwatches() {
   const colors = ${JSON.stringify(swatchesData, null, 2)};
-  
+
   return (
     <div className="color-swatches">
       <h2>Color Palette</h2>
       <div className="swatch-grid">
         {colors.map(color => (
           <div key={color.name} className="swatch-card">
-            <div 
-              className="swatch-preview" 
+            <div
+              className="swatch-preview"
               style={{ backgroundColor: color.value }}
             />
             <div className="swatch-info">
@@ -61,15 +89,15 @@ export function ColorSwatches() {
   );
 }`;
 
-    case 'vue':
-      return `
+      case 'vue':
+        return `
 <template>
   <div class="color-swatches">
     <h2>Color Palette</h2>
     <div class="swatch-grid">
       <div v-for="color in colors" :key="color.name" class="swatch-card">
-        <div 
-          class="swatch-preview" 
+        <div
+          class="swatch-preview"
           :style="{ backgroundColor: color.value }"
         />
         <div class="swatch-info">
@@ -85,8 +113,8 @@ export function ColorSwatches() {
 const colors = ${JSON.stringify(swatchesData, null, 2)};
 </script>`;
 
-    case 'svelte':
-      return `
+      case 'svelte':
+        return `
 <script>
   const colors = ${JSON.stringify(swatchesData, null, 2)};
 </script>
@@ -96,8 +124,8 @@ const colors = ${JSON.stringify(swatchesData, null, 2)};
   <div class="swatch-grid">
     {#each colors as color}
       <div class="swatch-card">
-        <div 
-          class="swatch-preview" 
+        <div
+          class="swatch-preview"
           style="background-color: {color.value}"
         />
         <div class="swatch-info">
@@ -109,8 +137,8 @@ const colors = ${JSON.stringify(swatchesData, null, 2)};
   </div>
 </div>`;
 
-    case 'html':
-      return `
+      case 'html':
+        return `
 <div class="color-swatches">
   <h2>Color Palette</h2>
   <div class="swatch-grid">
@@ -124,19 +152,19 @@ const colors = ${JSON.stringify(swatchesData, null, 2)};
     </div>`).join('\n    ')}
   </div>
 </div>`;
+    }
   }
-}
 
-/**
- * Generate typography specimens
- */
-function generateTypographySpecimens(tokens: DesignToken[], framework: FrameworkType): string {
-  const fontSizes = tokens.filter(t => t.name.includes('font-size'));
-  const fontWeights = tokens.filter(t => t.name.includes('font-weight'));
-  
-  switch (framework) {
-    case 'react':
-      return `
+  /**
+   * Generate typography specimens
+   */
+  private generateTypographySpecimens(tokens: DesignToken[], framework: FrameworkType): string {
+    const fontSizes = tokens.filter(t => t.name.includes('font-size'));
+    const fontWeights = tokens.filter(t => t.name.includes('font-weight'));
+
+    switch (framework) {
+      case 'react':
+        return `
 export function TypographySpecimens() {
   return (
     <div className="typography-specimens">
@@ -146,7 +174,7 @@ export function TypographySpecimens() {
         <span className="type-label">${token.name}</span>
         <span className="type-sample">The quick brown fox jumps over the lazy dog</span>
       </div>`).join('\n      ')}
-      
+
       <h2>Font Weights</h2>
       ${fontWeights.slice(0, 4).map(token => `
       <p style={{ fontWeight: 'var(--${token.name})' }}>
@@ -156,8 +184,8 @@ export function TypographySpecimens() {
   );
 }`;
 
-    case 'vue':
-      return `
+      case 'vue':
+        return `
 <template>
   <div class="typography-specimens">
     <h2>Typography Scale</h2>
@@ -166,7 +194,7 @@ export function TypographySpecimens() {
       <span class="type-label">${token.name}</span>
       <span class="type-sample">The quick brown fox jumps over the lazy dog</span>
     </div>`).join('\n    ')}
-    
+
     <h2>Font Weights</h2>
     ${fontWeights.slice(0, 4).map(token => `
     <p :style="{ fontWeight: 'var(--${token.name})' }">
@@ -175,8 +203,8 @@ export function TypographySpecimens() {
   </div>
 </template>`;
 
-    case 'svelte':
-      return `
+      case 'svelte':
+        return `
 <div class="typography-specimens">
   <h2>Typography Scale</h2>
   ${fontSizes.map(token => `
@@ -184,7 +212,7 @@ export function TypographySpecimens() {
     <span class="type-label">${token.name}</span>
     <span class="type-sample">The quick brown fox jumps over the lazy dog</span>
   </div>`).join('\n  ')}
-  
+
   <h2>Font Weights</h2>
   ${fontWeights.slice(0, 4).map(token => `
   <p style="font-weight: var(--${token.name})">
@@ -192,8 +220,8 @@ export function TypographySpecimens() {
   </p>`).join('\n  ')}
 </div>`;
 
-    case 'html':
-      return `
+      case 'html':
+        return `
 <div class="typography-specimens">
   <h2>Typography Scale</h2>
   ${fontSizes.map(token => `
@@ -201,23 +229,23 @@ export function TypographySpecimens() {
     <span class="type-label">${token.name}</span>
     <span class="type-sample">The quick brown fox jumps over the lazy dog</span>
   </div>`).join('\n  ')}
-  
+
   <h2>Font Weights</h2>
   ${fontWeights.slice(0, 4).map(token => `
   <p style="font-weight: var(--${token.name})">
     ${token.name}: The quick brown fox jumps over the lazy dog
   </p>`).join('\n  ')}
 </div>`;
+    }
   }
-}
 
-/**
- * Generate component examples
- */
-function generateComponentExamples(components: Component[], framework: FrameworkType): string {
-  switch (framework) {
-    case 'react':
-      return `
+  /**
+   * Generate component examples
+   */
+  private generateComponentExamples(components: Component[], framework: FrameworkType): string {
+    switch (framework) {
+      case 'react':
+        return `
 export function ComponentExamples() {
   return (
     <div className="component-examples">
@@ -241,31 +269,8 @@ export function ComponentExamples() {
   );
 }`;
 
-    case 'vue':
-      return `
-<template>
-  <div class="component-examples">
-    <h2>Components</h2>
-    ${components.map(comp => `
-    <div class="component-example">
-      <h3>${comp.name}</h3>
-      <p class="component-description">${comp.description}</p>
-      <div class="component-demo">
-        <!-- Add your ${comp.name} component here -->
-        <div class="placeholder">${comp.name} Demo</div>
-      </div>
-      <div class="component-tokens">
-        <strong>Uses tokens:</strong>
-        <ul>
-          ${comp.tokens.slice(0, 5).map(t => `<li><code>${t}</code></li>`).join('\n          ')}
-        </ul>
-      </div>
-    </div>`).join('\n    ')}
-  </div>
-</template>`;
-
-    default:
-      return `
+      default:
+        return `
 <div class="component-examples">
   <h2>Components</h2>
   ${components.map(comp => `
@@ -284,14 +289,14 @@ export function ComponentExamples() {
     </div>
   </div>`).join('\n  ')}
 </div>`;
+    }
   }
-}
 
-/**
- * Generate CSS styles for sticker sheet
- */
-function generateStyles(): string {
-  return `
+  /**
+   * Generate CSS styles for sticker sheet
+   */
+  private generateStyles(): string {
+    return `
 /* Sticker Sheet Styles */
 .color-swatches,
 .typography-specimens,
@@ -414,78 +419,58 @@ h2 {
   border-radius: var(--op-radius-small, 2px);
 }
 `;
-}
-
-/**
- * Generate complete sticker sheet
- */
-export function generateStickerSheet(
-  tokens: DesignToken[],
-  components: Component[],
-  options: StickerSheetOptions = {}
-): StickerSheet {
-  const {
-    framework = 'react',
-    includeColors = true,
-    includeTypography = true,
-    includeComponents = true
-  } = options;
-  
-  const sections: string[] = [];
-  
-  if (includeColors) {
-    sections.push(generateColorSwatches(tokens, framework));
-  }
-  
-  if (includeTypography) {
-    sections.push(generateTypographySpecimens(tokens, framework));
-  }
-  
-  if (includeComponents) {
-    sections.push(generateComponentExamples(components, framework));
   }
-  
-  const code = sections.join('\n\n');
-  const styles = generateStyles();
-  
-  const instructions = `
-# Optics Sticker Sheet - ${framework.toUpperCase()}
-
-This sticker sheet provides a visual reference for all Optics design tokens and components.
-
-## Usage
-
-1. Copy the component code below into your ${framework} project
-2. Copy the CSS styles into your stylesheet
-3. Import and use the components in your app
-4. Replace placeholders with actual component implementations
 
-## Files Generated
-
-- **Component Code**: Ready-to-use ${framework} components
-- **Styles**: CSS using Optics design tokens
-- **Examples**: Visual specimens of colors, typography, and components
-
-## Next Steps
-
-- Customize the examples to match your specific components
-- Add interactive states (hover, focus, disabled)
-- Include additional token categories as needed
-`;
-  
-  return {
-    framework,
-    code,
-    styles,
-    instructions
-  };
-}
+  /**
+   * Generate complete sticker sheet
+   */
+  private async generateStickerSheet(
+    tokens: DesignToken[],
+    components: Component[],
+    options: StickerSheetOptions = {}
+  ): Promise<StickerSheet> {
+    const {
+      framework = 'react',
+      includeColors = true,
+      includeTypography = true,
+      includeComponents = true
+    } = options;
+
+    const sections: string[] = [];
+
+    if (includeColors) {
+      sections.push(this.generateColorSwatches(tokens, framework));
+    }
+
+    if (includeTypography) {
+      sections.push(this.generateTypographySpecimens(tokens, framework));
+    }
+
+    if (includeComponents) {
+      sections.push(this.generateComponentExamples(components, framework));
+    }
+
+    const code = sections.join('\n\n');
+    const styles = this.generateStyles();
+
+    const template = await readToolFile('generate-sticker-sheet-instructions.md');
+    const instructions = template
+      .replace('{{framework}}', framework.toUpperCase())
+      .replace(/{{framework}}/g, framework);
+
+    return {
+      framework,
+      code,
+      styles,
+      instructions
+    };
+  }
 
-/**
- * Format sticker sheet output for display
- */
-export function formatStickerSheet(sheet: StickerSheet): string {
-  return `${sheet.instructions}
+  /**
+   * Format sticker sheet output for display
+   */
+  private formatStickerSheet(sheet: StickerSheet): string {
+    return `${sheet.instructions}
 
 ## Component Code (${sheet.framework})
 
@@ -499,4 +484,8 @@ ${sheet.code}
 ${sheet.styles}
 \`\`\`
 `;
+  }
+
 }
+
+export default GenerateStickerSheetTool;
diff --git a/src/tools/generate-theme-instructions.md b/src/tools/generate-theme-instructions.md
new file mode 100644
index 0000000..ff891d2
--- /dev/null
+++ b/src/tools/generate-theme-instructions.md
@@ -0,0 +1,63 @@
+# {{themeName}} Theme
+
+## Overview
+This theme was generated by Optics MCP and uses the Optics Design System tokens.
+
+## Step 1: Install Optics Design System
+
+### Option A: Via npm (Recommended)
+```bash
+npm install @rolemodel/optics
+```
+
+Then import in your CSS:
+```css
+@import "@rolemodel/optics/dist/optics.css";
+```
+
+### Option B: Via CDN (jsDelivr)
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@rolemodel/optics@latest/dist/optics.css">
+```
+
+### Option C: Via unpkg
+```html
+<link rel="stylesheet" href="https://unpkg.com/@rolemodel/optics@latest/dist/optics.css">
+```
+
+## Step 2: Add Your Custom Theme Overrides
+
+Create a `theme.css` file with the custom HSL color values below and load it AFTER Optics:
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@rolemodel/optics@latest/dist/optics.css">
+<link rel="stylesheet" href="./theme.css">
+```
+
+## Token Summary
+
+{{tokenSummary}}
+
+## Step 3: Using Optics Components
+
+**IMPORTANT:** Optics has pre-built components with specific HTML structure and CSS classes.
+
+Do NOT make up CSS classes. Use the actual Optics components and their documentation:
+
+**Component Documentation:** https://docs.optics.rolemodel.design
+
+Your custom theme will automatically apply to all Optics components through the HSL base values.
+
+### Example: Using an Optics Button
+Refer to the Optics documentation for the actual button HTML structure and CSS classes.
+Your theme colors will apply automatically through the `--op-color-primary-*` variables.
+
+### Figma Variables
+Import the `figma-variables.json` file into Figma:
+1. Open your Figma file
+2. Go to Variables panel
+3. Import → Select `figma-variables.json`
+
+## Token Categories
+
+{{tokenCategories}}
diff --git a/src/tools/generate-theme-output.md b/src/tools/generate-theme-output.md
new file mode 100644
index 0000000..a34d95a
--- /dev/null
+++ b/src/tools/generate-theme-output.md
@@ -0,0 +1,24 @@
+# {{brandName}} Theme Generated
+
+## CSS Variables
+
+```css
+{{cssVariables}}
+```
+
+## Figma Variables
+
+Save this as `figma-variables.json`:
+
+```json
+{{figmaVariables}}
+```
+
+## Summary
+
+- **Total tokens**: {{totalTokens}}
+- **Colors**: {{colorTokens}}
+- **Typography**: {{typographyTokens}}
+- **Spacing**: {{spacingTokens}}
+
+{{documentation}}
diff --git a/src/tools/generate-theme-tool.ts b/src/tools/generate-theme-tool.ts
new file mode 100644
index 0000000..a0cafe6
--- /dev/null
+++ b/src/tools/generate-theme-tool.ts
@@ -0,0 +1,286 @@
+/**
+ * Theme generator tool
+ * Generates complete theme with CSS variables and Figma Variables JSON
+ * Uses actual Optics tokens, only customizing HSL color base values
+ */
+
+import { z } from 'zod';
+import Tool, { type ToolInputSchema } from './tool.js';
+import { designTokens, type DesignToken } from '../optics-data.js';
+import { generateFigmaVariablesJSON } from '../utils/figma-tokens.js';
+import { readToolFile } from '../_internal/resource-path.js';
+
+interface BrandColors {
+  primary?: string;        // Main brand color (hex) - converted to --op-color-primary-h/s/l
+  neutral?: string;        // Neutral color (hex) - converted to --op-color-neutral-h/s/l
+  'alerts-warning'?: string;  // Warning color (hex)
+  'alerts-danger'?: string;   // Error color (hex)
+  'alerts-info'?: string;     // Info color (hex)
+  'alerts-notice'?: string;   // Success color (hex)
+}
+
+interface GeneratedTheme {
+  cssVariables: string;
+  figmaVariables: string;
+  tokens: DesignToken[];
+  documentation: string;
+}
+
+class GenerateThemeTool extends Tool {
+  name = 'generate_theme'
+  title = 'Generate Theme'
+  description = 'Generate a complete theme with CSS variables and Figma Variables JSON using Optics design tokens'
+
+  inputSchema = {
+    brandName: z
+      .string()
+      .describe('The name of the brand/theme (e.g., "Acme Corp")'),
+    primary: z
+      .string()
+      .describe('Primary brand color (hex, e.g., "#FF5733")'),
+    neutral: z
+      .string()
+      .optional()
+      .describe('Neutral color (hex, optional)')
+  }
+
+  async handler(args: ToolInputSchema): Promise<string> {
+    const brandColors: BrandColors = {
+      primary: args.primary,
+      neutral: args.neutral
+    };
+    const theme = await this.generateTheme(args.brandName, brandColors);
+
+    // Load markdown template and replace placeholders
+    let output = await readToolFile('generate-theme-output.md');
+
+    output = output
+      .replace('{{brandName}}', args.brandName)
+      .replace('{{cssVariables}}', theme.cssVariables)
+      .replace('{{figmaVariables}}', theme.figmaVariables)
+      .replace('{{totalTokens}}', String(theme.tokens.length))
+      .replace('{{colorTokens}}', String(theme.tokens.filter(t => t.category === 'color').length))
+      .replace('{{typographyTokens}}', String(theme.tokens.filter(t => t.category === 'typography').length))
+      .replace('{{spacingTokens}}', String(theme.tokens.filter(t => t.category === 'spacing').length))
+      .replace('{{documentation}}', theme.documentation);
+
+    return output;
+  }
+
+  /**
+   * Optics color families that can be themed
+   * Each accepts a hex color that will be converted to HSL base values
+   */
+
+  /**
+   * Generate Optics HSL color tokens from brand colors
+   * Each color family gets h/s/l base values that drive the scale system
+   */
+  private generateColorTokens(brandColors: BrandColors): DesignToken[] {
+    const tokens: DesignToken[] = [];
+
+    // Default Optics colors if not provided
+    const defaults: BrandColors = {
+      primary: '#2D6FDB',      // Optics default primary
+      neutral: '#757882',      // Optics default neutral
+      'alerts-warning': '#FFD93D',
+      'alerts-danger': '#FF6B94',
+      'alerts-info': '#2D6FDB',
+      'alerts-notice': '#6ACF71'
+    };
+
+    const colors = { ...defaults, ...brandColors };
+
+    // Generate HSL base values for each color family
+    for (const [family, hex] of Object.entries(colors)) {
+      if (!hex) continue;
+
+      const hsl = this.hexToHSL(hex);
+
+      tokens.push({
+        name: `op-color-${family}-h`,
+        value: String(hsl.h),
+        category: 'color',
+        description: `${family} color hue (HSL) - drives all ${family} scale tokens`
+      });
+
+      tokens.push({
+        name: `op-color-${family}-s`,
+        value: `${hsl.s}%`,
+        category: 'color',
+        description: `${family} color saturation (HSL)`
+      });
+
+      tokens.push({
+        name: `op-color-${family}-l`,
+        value: `${hsl.l}%`,
+        category: 'color',
+        description: `${family} color lightness (HSL)`
+      });
+    }
+
+    return tokens;
+  }
+
+  /**
+   * Convert hex to HSL
+   */
+  private hexToHSL(hex: string): { h: number; s: number; l: number } {
+    // Remove # if present
+    hex = hex.replace('#', '');
+
+    // Convert to RGB first
+    const r = parseInt(hex.substring(0, 2), 16) / 255;
+    const g = parseInt(hex.substring(2, 4), 16) / 255;
+    const b = parseInt(hex.substring(4, 6), 16) / 255;
+
+    const max = Math.max(r, g, b);
+    const min = Math.min(r, g, b);
+    let h = 0;
+    let s = 0;
+    const l = (max + min) / 2;
+
+    if (max !== min) {
+      const d = max - min;
+      s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+
+      switch (max) {
+        case r: h = ((g - b) / d + (g < b ? 6 : 0)) / 6; break;
+        case g: h = ((b - r) / d + 2) / 6; break;
+        case b: h = ((r - g) / d + 4) / 6; break;
+      }
+    }
+
+    return {
+      h: Math.round(h * 360),
+      s: Math.round(s * 100),
+      l: Math.round(l * 100)
+    };
+  }
+
+  /**
+   * Generate CSS variables from tokens using HSL for colors
+   */
+  private generateCSSVariables(tokens: DesignToken[], themeName: string = 'default'): string {
+    const lines: string[] = [
+      `/* ${themeName} Theme - Generated by Optics MCP */`,
+      `/* HSL tokens for easy theming */`,
+      `:root {`
+    ];
+
+    // Group tokens by category
+    const grouped: Record<string, DesignToken[]> = {};
+    tokens.forEach(token => {
+      if (!grouped[token.category]) grouped[token.category] = [];
+      grouped[token.category].push(token);
+    });
+
+    // Output color tokens - they're already in HSL format
+    if (grouped['color']) {
+      lines.push(`  /* Colors (HSL) */`);
+      for (const token of grouped['color']) {
+        // Tokens are already properly formatted (either HSL base values or full color values)
+        lines.push(`  --${token.name}: ${token.value};`);
+      }
+      lines.push('');
+    }
+
+    // Output non-color tokens normally
+    for (const [category, categoryTokens] of Object.entries(grouped)) {
+      if (category === 'color') continue; // Already handled
+
+      lines.push(`  /* ${category.charAt(0).toUpperCase() + category.slice(1)} */`);
+      for (const token of categoryTokens) {
+        lines.push(`  --${token.name}: ${token.value};`);
+      }
+      lines.push('');
+    }
+
+    lines.push('}');
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Generate theme documentation
+   */
+  private async generateDocumentation(themeName: string, tokens: DesignToken[]): Promise<string> {
+    // Load documentation template
+    let documentation = await readToolFile('generate-theme-instructions.md');
+
+    // Generate token summary
+    const stats = tokens.reduce((acc, token) => {
+      acc[token.category] = (acc[token.category] || 0) + 1;
+      return acc;
+    }, {} as Record<string, number>);
+
+    const tokenSummary = Object.entries(stats)
+      .map(([category, count]) => `- **${category}**: ${count} tokens`)
+      .join('\n');
+
+    // Generate token categories table
+    const grouped: Record<string, DesignToken[]> = {};
+    tokens.forEach(token => {
+      if (!grouped[token.category]) grouped[token.category] = [];
+      grouped[token.category].push(token);
+    });
+
+    const tokenCategories = Object.entries(grouped)
+      .map(([category, categoryTokens]) => {
+        const lines = [
+          `### ${category.charAt(0).toUpperCase() + category.slice(1)}`,
+          '',
+          '| Token Name | Value | Description |',
+          '|------------|-------|-------------|'
+        ];
+
+        for (const token of categoryTokens) {
+          lines.push(`| \`${token.name}\` | \`${token.value}\` | ${token.description || ''} |`);
+        }
+
+        return lines.join('\n');
+      })
+      .join('\n\n');
+
+    // Replace placeholders
+    documentation = documentation
+      .replace('{{themeName}}', themeName)
+      .replace('{{tokenSummary}}', tokenSummary)
+      .replace('{{tokenCategories}}', tokenCategories);
+
+    return documentation;
+  }
+
+  /**
+   * Main theme generation function
+   * Uses all standard Optics tokens, only customizing the HSL color base values
+   */
+  private async generateTheme(brandName: string, brandColors: BrandColors): Promise<GeneratedTheme> {
+    // Start with all standard Optics tokens
+    let tokens: DesignToken[] = [...designTokens];
+
+    // Override HSL color base values if custom colors provided
+    if (Object.keys(brandColors).length > 0) {
+      const customColorTokens = this.generateColorTokens(brandColors);
+
+      // Replace the HSL base tokens with custom ones
+      tokens = tokens.map(token => {
+        const customToken = customColorTokens.find(ct => ct.name === token.name);
+        return customToken || token;
+      });
+    }
+
+    const cssVariables = this.generateCSSVariables(tokens, brandName);
+    const figmaVariables = generateFigmaVariablesJSON(tokens, { collectionName: `${brandName} Design System` });
+    const documentation = await this.generateDocumentation(brandName, tokens);
+
+    return {
+      cssVariables,
+      figmaVariables,
+      tokens,
+      documentation
+    };
+  }
+}
+
+export default GenerateThemeTool;
diff --git a/src/tools/migration.ts b/src/tools/migration.ts
deleted file mode 100644
index d6b5477..0000000
--- a/src/tools/migration.ts
+++ /dev/null
@@ -1,149 +0,0 @@
-/**
- * Token migration helper
- * Suggests token migrations for hard-coded values or deprecated tokens
- */
-
-import { DesignToken } from '../optics-data.js';
-
-export interface MigrationSuggestion {
-  inputValue: string;
-  suggestedTokens: Array<{
-    tokenName: string;
-    tokenValue: string;
-    category: string;
-    similarity: number;
-    reason: string;
-  }>;
-}
-
-/**
- * Suggest token migration for a hard-coded value
- */
-export function suggestTokenMigration(
-  oldValue: string,
-  tokens: DesignToken[],
-  category?: string
-): MigrationSuggestion {
-  const suggestions: MigrationSuggestion['suggestedTokens'] = [];
-  
-  const candidateTokens = category
-    ? tokens.filter(t => t.category === category)
-    : tokens;
-  
-  // Analyze the value type
-  const valueType = detectValueType(oldValue);
-  
-  for (const token of candidateTokens) {
-    const tokenType = detectValueType(token.value);
-    
-    if (valueType === tokenType) {
-      const similarity = calculateSimilarity(oldValue, token.value, valueType);
-      
-      if (similarity > 0.5) {
-        suggestions.push({
-          tokenName: token.name,
-          tokenValue: token.value,
-          category: token.category,
-          similarity,
-          reason: generateMigrationReason(oldValue, token, similarity)
-        });
-      }
-    }
-  }
-  
-  // Sort by similarity
-  suggestions.sort((a, b) => b.similarity - a.similarity);
-  
-  return {
-    inputValue: oldValue,
-    suggestedTokens: suggestions.slice(0, 5) // Top 5 suggestions
-  };
-}
-
-/**
- * Detect value type (color, spacing, font-size, etc.)
- */
-function detectValueType(value: string): string {
-  if (/^#[0-9a-fA-F]{3,6}$/.test(value) || /^rgba?\(/.test(value)) return 'color';
-  if (/^\d+px$/.test(value)) return 'pixels';
-  if (/^\d+rem$/.test(value)) return 'rem';
-  if (/^\d+em$/.test(value)) return 'em';
-  if (/^[34567]00$/.test(value)) return 'font-weight';
-  if (/^\d+(\.\d+)?$/.test(value)) return 'number';
-  if (/box-shadow|shadow/i.test(value)) return 'shadow';
-  return 'string';
-}
-
-/**
- * Calculate similarity between values
- */
-function calculateSimilarity(value1: string, value2: string, type: string): number {
-  if (type === 'color') {
-    // Exact match for colors
-    return value1.toLowerCase() === value2.toLowerCase() ? 1 : 0;
-  }
-  
-  if (type === 'pixels' || type === 'rem' || type === 'em') {
-    const num1 = parseFloat(value1);
-    const num2 = parseFloat(value2);
-    const diff = Math.abs(num1 - num2);
-    const max = Math.max(num1, num2);
-    return Math.max(0, 1 - (diff / max));
-  }
-  
-  if (type === 'font-weight') {
-    const num1 = parseInt(value1);
-    const num2 = parseInt(value2);
-    return num1 === num2 ? 1 : 0.5;
-  }
-  
-  // String similarity (basic)
-  return value1 === value2 ? 1 : 0.3;
-}
-
-/**
- * Generate migration reason
- */
-function generateMigrationReason(oldValue: string, token: DesignToken, similarity: number): string {
-  if (similarity === 1) {
-    return 'Exact match';
-  }
-  if (similarity > 0.9) {
-    return 'Very close match';
-  }
-  if (similarity > 0.7) {
-    return 'Close match';
-  }
-  return 'Similar value';
-}
-
-/**
- * Format migration suggestions
- */
-export function formatMigrationSuggestions(suggestion: MigrationSuggestion): string {
-  const lines: string[] = [
-    '# Token Migration Suggestions',
-    '',
-    `**Input Value**: \`${suggestion.inputValue}\``,
-    ''
-  ];
-  
-  if (suggestion.suggestedTokens.length > 0) {
-    lines.push('## Suggested Tokens');
-    lines.push('');
-    
-    for (const token of suggestion.suggestedTokens) {
-      lines.push(`### ${token.tokenName}`);
-      lines.push(`- **Value**: \`${token.tokenValue}\``);
-      lines.push(`- **Category**: ${token.category}`);
-      lines.push(`- **Similarity**: ${Math.round(token.similarity * 100)}%`);
-      lines.push(`- **Reason**: ${token.reason}`);
-      lines.push('');
-    }
-  } else {
-    lines.push('No suitable tokens found for this value.');
-    lines.push('Consider adding a new token to your design system.');
-  }
-  
-  return lines.join('\n');
-}
diff --git a/src/tools/replace-hard-coded-values-tool.ts b/src/tools/replace-hard-coded-values-tool.ts
index e682977..b714b18 100644
--- a/src/tools/replace-hard-coded-values-tool.ts
+++ b/src/tools/replace-hard-coded-values-tool.ts
@@ -1,5 +1,5 @@
 import { z } from 'zod'
-import Tool from './tool.js'
+import Tool, { type ToolInputSchema } from './tool.js'
 import { designTokens, type DesignToken } from '../optics-data.js'
 import { extractAllValues, findMatchingToken } from '../utils/css-parser.js'
 
@@ -27,7 +27,7 @@ class ReplaceHardCodedValuesTool extends Tool {
     autofix: z.boolean().optional().describe('Whether to automatically fix the code (default: false)'),
   }
 
-  async handler(args: any): Promise<string> {
+  async handler(args: ToolInputSchema): Promise<string> {
     const { code, autofix } = args
     const result = this.replaceHardCodedValues(code, designTokens, autofix ?? false)
     return this.formatReplacementSuggestions(result)
diff --git a/src/tools/scaffold.ts b/src/tools/scaffold.ts
deleted file mode 100644
index ccef209..0000000
--- a/src/tools/scaffold.ts
+++ /dev/null
@@ -1,208 +0,0 @@
-/**
- * Component scaffold generator
- * Generates component templates with proper token usage
- */
-
-import { DesignToken } from '../optics-data.js';
-
-export interface ComponentScaffold {
-  name: string;
-  typescript: string;
-  css: string;
-  usage: string;
-}
-
-/**
- * Generate component scaffold
- */
-export function generateComponentScaffold(
-  componentName: string,
-  description: string,
-  requiredTokens: string[],
-  allTokens: DesignToken[]
-): ComponentScaffold {
-  const validTokens = requiredTokens.filter(tokenName =>
-    allTokens.some(t => t.name === tokenName)
-  );
-  
-  const typescript = generateTypeScriptComponent(componentName, description, validTokens);
-  const css = generateCSSModule(componentName, validTokens, allTokens);
-  const usage = generateUsageExample(componentName);
-  
-  return {
-    name: componentName,
-    typescript,
-    css,
-    usage
-  };
-}
-
-/**
- * Generate TypeScript component
- */
-function generateTypeScriptComponent(
-  name: string,
-  description: string,
-  tokens: string[]
-): string {
-  const lines: string[] = [
-    `/**`,
-    ` * ${name} Component`,
-    ` * ${description}`,
-    ` * `,
-    ` * Design tokens used:`,
-    ...tokens.map(t => ` * - ${t}`),
-    ` */`,
-    ``,
-    `import React from 'react';`,
-    `import styles from './${name}.module.css';`,
-    ``,
-    `export interface ${name}Props {`,
-    `  children: React.ReactNode;`,
-    `  className?: string;`,
-    `}`,
-    ``,
-    `export const ${name}: React.FC<${name}Props> = ({ children, className }) => {`,
-    `  return (`,
-    `    <div className={\`\${styles.${name.toLowerCase()}} \${className || ''}\`}>`,
-    `      {children}`,
-    `    </div>`,
-    `  );`,
-    `};`
-  ];
-  
-  return lines.join('\n');
-}
-
-/**
- * Generate CSS module
- */
-function generateCSSModule(
-  name: string,
-  tokenNames: string[],
-  allTokens: DesignToken[]
-): string {
-  const lines: string[] = [
-    `/**`,
-    ` * ${name} Component Styles`,
-    ` * Uses Optics design tokens for consistent styling`,
-    ` */`,
-    ``,
-    `.${name.toLowerCase()} {`
-  ];
-  
-  // Group tokens by category
-  const colorTokens = tokenNames.filter(t => allTokens.find(token => token.name === t && token.category === 'color'));
-  const spacingTokens = tokenNames.filter(t => allTokens.find(token => token.name === t && token.category === 'spacing'));
-  const typographyTokens = tokenNames.filter(t => allTokens.find(token => token.name === t && token.category === 'typography'));
-  const borderTokens = tokenNames.filter(t => allTokens.find(token => token.name === t && token.category === 'border'));
-  const shadowTokens = tokenNames.filter(t => allTokens.find(token => token.name === t && token.category === 'shadow'));
-  
-  // Add color properties
-  if (colorTokens.length > 0) {
-    lines.push(`  /* Colors */`);
-    if (colorTokens.some(t => t.includes('background'))) {
-      const bgToken = colorTokens.find(t => t.includes('background'));
-      lines.push(`  background-color: var(--${bgToken});`);
-    }
-    if (colorTokens.some(t => t.includes('text') || t.includes('color-primary'))) {
-      const textToken = colorTokens.find(t => t.includes('text')) || colorTokens[0];
-      lines.push(`  color: var(--${textToken});`);
-    }
-  }
-  
-  // Add spacing
-  if (spacingTokens.length > 0) {
-    lines.push(`  /* Spacing */`);
-    const paddingToken = spacingTokens[0];
-    lines.push(`  padding: var(--${paddingToken});`);
-  }
-  
-  // Add typography
-  if (typographyTokens.length > 0) {
-    lines.push(`  /* Typography */`);
-    typographyTokens.forEach(token => {
-      if (token.includes('font-size')) {
-        lines.push(`  font-size: var(--${token});`);
-      } else if (token.includes('font-weight')) {
-        lines.push(`  font-weight: var(--${token});`);
-      } else if (token.includes('line-height')) {
-        lines.push(`  line-height: var(--${token});`);
-      } else if (token.includes('font-family')) {
-        lines.push(`  font-family: var(--${token});`);
-      }
-    });
-  }
-  
-  // Add borders
-  if (borderTokens.length > 0) {
-    lines.push(`  /* Borders */`);
-    lines.push(`  border-radius: var(--${borderTokens[0]});`);
-  }
-  
-  // Add shadows
-  if (shadowTokens.length > 0) {
-    lines.push(`  /* Elevation */`);
-    lines.push(`  box-shadow: var(--${shadowTokens[0]});`);
-  }
-  
-  lines.push(`}`);
-  lines.push(``);
-  
-  return lines.join('\n');
-}
-
-/**
- * Generate usage example
- */
-function generateUsageExample(name: string): string {
-  const lines: string[] = [
-    `# ${name} Usage`,
-    ``,
-    `## Import`,
-    `\`\`\`typescript`,
-    `import { ${name} } from './components/${name}';`,
-    `\`\`\``,
-    ``,
-    `## Basic Usage`,
-    `\`\`\`tsx`,
-    `<${name}>`,
-    `  Your content here`,
-    `</${name}>`,
-    `\`\`\``,
-    ``,
-    `## With Custom ClassName`,
-    `\`\`\`tsx`,
-    `<${name} className="custom-class">`,
-    `  Your content here`,
-    `</${name}>`,
-    `\`\`\``,
-    ``
-  ];
-  
-  return lines.join('\n');
-}
-
-/**
- * Format scaffold output
- */
-export function formatScaffoldOutput(scaffold: ComponentScaffold): string {
-  const lines: string[] = [
-    `# ${scaffold.name} Component Scaffold`,
-    ``,
-    `## TypeScript Component`,
-    `\`\`\`typescript`,
-    scaffold.typescript,
-    `\`\`\``,
-    ``,
-    `## CSS Module`,
-    `\`\`\`css`,
-    scaffold.css,
-    `\`\`\``,
-    ``,
-    `## Usage`,
-    scaffold.usage
-  ];
-  
-  return lines.join('\n');
-}
diff --git a/src/tools/suggest-token-migration-header.md b/src/tools/suggest-token-migration-header.md
new file mode 100644
index 0000000..20db436
--- /dev/null
+++ b/src/tools/suggest-token-migration-header.md
@@ -0,0 +1,5 @@
+# Token Migration Suggestions
+
+**Input Value**: `{{inputValue}}`
+
+## Suggested Tokens
diff --git a/src/tools/suggest-token-migration-none.md b/src/tools/suggest-token-migration-none.md
new file mode 100644
index 0000000..c0a5d3c
--- /dev/null
+++ b/src/tools/suggest-token-migration-none.md
@@ -0,0 +1,6 @@
+# Token Migration Suggestions
+
+**Input Value**: `{{inputValue}}`
+
+No suitable tokens found for this value.
+Consider adding a new token to your design system.
diff --git a/src/tools/suggest-token-migration-tool.ts b/src/tools/suggest-token-migration-tool.ts
new file mode 100644
index 0000000..e40a945
--- /dev/null
+++ b/src/tools/suggest-token-migration-tool.ts
@@ -0,0 +1,169 @@
+/**
+ * Suggest Token Migration Tool
+ * Suggests token migrations for hard-coded values or deprecated tokens
+ */
+
+import { z } from 'zod';
+import Tool, { type ToolInputSchema } from './tool.js';
+import { designTokens, type DesignToken } from '../optics-data.js';
+import { readToolFile } from '../_internal/resource-path.js';
+
+export interface MigrationSuggestion {
+  inputValue: string;
+  suggestedTokens: Array<{
+    tokenName: string;
+    tokenValue: string;
+    category: string;
+    similarity: number;
+    reason: string;
+  }>;
+}
+
+class SuggestTokenMigrationTool extends Tool {
+  name = 'suggest_token_migration';
+  title = 'Suggest Token Migration';
+  description = 'Suggest design tokens for a hard-coded value';
+
+  inputSchema = {
+    value: z.string().describe('Hard-coded value to find tokens for (e.g., "#0066CC", "16px")'),
+    category: z.string().optional().describe('Optional category filter (color, spacing, typography)'),
+  };
+
+  async handler(args: ToolInputSchema): Promise<string> {
+    const { value, category } = args;
+    const suggestion = this.suggestTokenMigration(value, designTokens, category);
+    const formatted = await this.formatMigrationSuggestions(suggestion);
+
+    return formatted;
+  }
+
+  /**
+   * Suggest token migration for a hard-coded value
+   */
+  private suggestTokenMigration(
+    oldValue: string,
+    tokens: DesignToken[],
+    category?: string
+  ): MigrationSuggestion {
+    const suggestions: MigrationSuggestion['suggestedTokens'] = [];
+
+    const candidateTokens = category
+      ? tokens.filter(t => t.category === category)
+      : tokens;
+
+    // Analyze the value type
+    const valueType = this.detectValueType(oldValue);
+
+    for (const token of candidateTokens) {
+      const tokenType = this.detectValueType(token.value);
+
+      if (valueType === tokenType) {
+        const similarity = this.calculateSimilarity(oldValue, token.value, valueType);
+
+        if (similarity > 0.5) {
+          suggestions.push({
+            tokenName: token.name,
+            tokenValue: token.value,
+            category: token.category,
+            similarity,
+            reason: this.generateMigrationReason(oldValue, token, similarity)
+          });
+        }
+      }
+    }
+
+    // Sort by similarity
+    suggestions.sort((a, b) => b.similarity - a.similarity);
+
+    return {
+      inputValue: oldValue,
+      suggestedTokens: suggestions.slice(0, 5) // Top 5 suggestions
+    };
+  }
+
+  /**
+   * Detect value type (color, spacing, font-size, etc.)
+   */
+  private detectValueType(value: string): string {
+    if (/^#[0-9a-fA-F]{3,6}$/.test(value) || /^rgba?\(/.test(value)) return 'color';
+    if (/^\d+px$/.test(value)) return 'pixels';
+    if (/^\d+rem$/.test(value)) return 'rem';
+    if (/^\d+em$/.test(value)) return 'em';
+    if (/^[34567]00$/.test(value)) return 'font-weight';
+    if (/^\d+(\.\d+)?$/.test(value)) return 'number';
+    if (/box-shadow|shadow/i.test(value)) return 'shadow';
+    return 'string';
+  }
+
+  /**
+   * Calculate similarity between values
+   */
+  private calculateSimilarity(value1: string, value2: string, type: string): number {
+    if (type === 'color') {
+      // Exact match for colors
+      return value1.toLowerCase() === value2.toLowerCase() ? 1 : 0;
+    }
+
+    if (type === 'pixels' || type === 'rem' || type === 'em') {
+      const num1 = parseFloat(value1);
+      const num2 = parseFloat(value2);
+      const diff = Math.abs(num1 - num2);
+      const max = Math.max(num1, num2);
+      return Math.max(0, 1 - (diff / max));
+    }
+
+    if (type === 'font-weight') {
+      const num1 = parseInt(value1);
+      const num2 = parseInt(value2);
+      return num1 === num2 ? 1 : 0.5;
+    }
+
+    // String similarity (basic)
+    return value1 === value2 ? 1 : 0.3;
+  }
+
+  /**
+   * Generate migration reason
+   */
+  private generateMigrationReason(oldValue: string, token: DesignToken, similarity: number): string {
+    if (similarity === 1) {
+      return 'Exact match';
+    }
+    if (similarity > 0.9) {
+      return 'Very close match';
+    }
+    if (similarity > 0.7) {
+      return 'Close match';
+    }
+    return 'Similar value';
+  }
+
+  /**
+   * Format migration suggestions
+   */
+  private async formatMigrationSuggestions(suggestion: MigrationSuggestion): Promise<string> {
+    if (suggestion.suggestedTokens.length === 0) {
+      const template = await readToolFile('suggest-token-migration-none.md');
+      return template.replace('{{inputValue}}', suggestion.inputValue);
+    }
+
+    const template = await readToolFile('suggest-token-migration-header.md');
+    const lines: string[] = [
+      template.replace('{{inputValue}}', suggestion.inputValue),
+      ''
+    ];
+
+    for (const token of suggestion.suggestedTokens) {
+      lines.push(`### ${token.tokenName}`);
+      lines.push(`- **Value**: \`${token.tokenValue}\``);
+      lines.push(`- **Category**: ${token.category}`);
+      lines.push(`- **Similarity**: ${Math.round(token.similarity * 100)}%`);
+      lines.push(`- **Reason**: ${token.reason}`);
+      lines.push('');
+    }
+
+    return lines.join('\n');
+  }
+}
+
+export default SuggestTokenMigrationTool;
diff --git a/src/tools/theme-generator.ts b/src/tools/theme-generator.ts
deleted file mode 100644
index 6330266..0000000
--- a/src/tools/theme-generator.ts
+++ /dev/null
@@ -1,387 +0,0 @@
-/**
- * Theme generator tool
- * Generates complete theme with CSS variables and Figma Variables JSON
- * Uses actual Optics tokens, only customizing HSL color base values
- */
-
-import { DesignToken, designTokens } from '../optics-data.js';
-import { generateFigmaVariablesJSON } from '../utils/figma-tokens.js';
-
-/**
- * Optics color families that can be themed
- * Each accepts a hex color that will be converted to HSL base values
- */
-export interface BrandColors {
-  primary?: string;        // Main brand color (hex) - converted to --op-color-primary-h/s/l
-  neutral?: string;        // Neutral/gray color (hex) - converted to --op-color-neutral-h/s/l  
-  'alerts-warning'?: string;  // Warning color (hex)
-  'alerts-danger'?: string;   // Error color (hex)
-  'alerts-info'?: string;     // Info color (hex)
-  'alerts-notice'?: string;   // Success color (hex)
-}
-
-export interface ThemeOptions {
-  includeDarkMode?: boolean;
-  includeSemanticColors?: boolean;
-  includeTypography?: boolean;
-  includeSpacing?: boolean;
-  includeBorders?: boolean;
-  includeShadows?: boolean;
-}
-
-export interface GeneratedTheme {
-  cssVariables: string;
-  figmaVariables: string;
-  tokens: DesignToken[];
-  documentation: string;
-}
-
-/**
- * Generate spacing tokens using base-8 system
- */
-function generateSpacingTokens(): DesignToken[] {
-  const spacingScale = [
-    { name: 'xs', value: '4px' },
-    { name: 'sm', value: '8px' },
-    { name: 'md', value: '16px' },
-    { name: 'lg', value: '24px' },
-    { name: 'xl', value: '32px' },
-    { name: '2xl', value: '48px' }
-  ];
-  
-  return spacingScale.map(({ name, value }) => ({
-    name: `spacing-${name}`,
-    value,
-    category: 'spacing',
-    description: `Spacing ${name} - ${value}`
-  }));
-}
-
-/**
- * Generate typography tokens
- */
-function generateTypographyTokens(): DesignToken[] {
-  return [
-    {
-      name: 'font-family-base',
-      value: '"Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif',
-      category: 'typography',
-      description: 'Base font family for body text'
-    },
-    {
-      name: 'font-family-heading',
-      value: '"Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif',
-      category: 'typography',
-      description: 'Font family for headings'
-    },
-    {
-      name: 'font-family-mono',
-      value: '"SF Mono", "Monaco", "Consolas", monospace',
-      category: 'typography',
-      description: 'Monospace font family for code'
-    },
-    { name: 'font-size-xs', value: '12px', category: 'typography', description: 'Extra small font size' },
-    { name: 'font-size-sm', value: '14px', category: 'typography', description: 'Small font size' },
-    { name: 'font-size-md', value: '16px', category: 'typography', description: 'Medium font size (base)' },
-    { name: 'font-size-lg', value: '18px', category: 'typography', description: 'Large font size' },
-    { name: 'font-size-xl', value: '20px', category: 'typography', description: 'Extra large font size' },
-    { name: 'font-size-2xl', value: '24px', category: 'typography', description: '2X large font size' },
-    { name: 'font-size-3xl', value: '32px', category: 'typography', description: '3X large font size' },
-    { name: 'font-weight-normal', value: '400', category: 'typography', description: 'Normal font weight' },
-    { name: 'font-weight-medium', value: '500', category: 'typography', description: 'Medium font weight' },
-    { name: 'font-weight-semibold', value: '600', category: 'typography', description: 'Semibold font weight' },
-    { name: 'font-weight-bold', value: '700', category: 'typography', description: 'Bold font weight' },
-    { name: 'line-height-tight', value: '1.25', category: 'typography', description: 'Tight line height for headings' },
-    { name: 'line-height-normal', value: '1.5', category: 'typography', description: 'Normal line height for body text' },
-    { name: 'line-height-relaxed', value: '1.75', category: 'typography', description: 'Relaxed line height for long-form content' }
-  ];
-}
-
-/**
- * Generate border tokens
- */
-function generateBorderTokens(): DesignToken[] {
-  return [
-    { name: 'border-radius-sm', value: '4px', category: 'border', description: 'Small border radius' },
-    { name: 'border-radius-md', value: '8px', category: 'border', description: 'Medium border radius' },
-    { name: 'border-radius-lg', value: '12px', category: 'border', description: 'Large border radius' },
-    { name: 'border-radius-full', value: '9999px', category: 'border', description: 'Full border radius for circular elements' }
-  ];
-}
-
-/**
- * Generate shadow tokens
- */
-function generateShadowTokens(): DesignToken[] {
-  return [
-    { name: 'shadow-sm', value: '0 1px 2px 0 rgba(0, 0, 0, 0.05)', category: 'shadow', description: 'Small shadow for subtle elevation' },
-    { name: 'shadow-md', value: '0 4px 6px -1px rgba(0, 0, 0, 0.1)', category: 'shadow', description: 'Medium shadow for cards and panels' },
-    { name: 'shadow-lg', value: '0 10px 15px -3px rgba(0, 0, 0, 0.1)', category: 'shadow', description: 'Large shadow for modals and popovers' }
-  ];
-}
-
-/**
- * Generate Optics HSL color tokens from brand colors
- * Each color family gets h/s/l base values that drive the scale system
- */
-function generateColorTokens(brandColors: BrandColors): DesignToken[] {
-  const tokens: DesignToken[] = [];
-  
-  // Default Optics colors if not provided
-  const defaults: BrandColors = {
-    primary: '#2D6FDB',      // Optics default primary
-    neutral: '#757882',      // Optics default neutral
-    'alerts-warning': '#FFD93D',
-    'alerts-danger': '#FF6B94',
-    'alerts-info': '#2D6FDB',
-    'alerts-notice': '#6ACF71'
-  };
-  
-  const colors = { ...defaults, ...brandColors };
-  
-  // Generate HSL base values for each color family
-  for (const [family, hex] of Object.entries(colors)) {
-    if (!hex) continue;
-    
-    const hsl = hexToHSL(hex);
-    const familyName = family === 'primary' || family === 'neutral' ? family : family;
-    
-    tokens.push({
-      name: `op-color-${familyName}-h`,
-      value: String(hsl.h),
-      category: 'color',
-      description: `${familyName} color hue (HSL) - drives all ${familyName} scale tokens`
-    });
-    
-    tokens.push({
-      name: `op-color-${familyName}-s`,
-      value: `${hsl.s}%`,
-      category: 'color',
-      description: `${familyName} color saturation (HSL)`
-    });
-    
-    tokens.push({
-      name: `op-color-${familyName}-l`,
-      value: `${hsl.l}%`,
-      category: 'color',
-      description: `${familyName} color lightness (HSL)`
-    });
-  }
-  
-  return tokens;
-}
-
-/**
- * Convert hex to HSL
- */
-function hexToHSL(hex: string): { h: number; s: number; l: number } {
-  // Remove # if present
-  hex = hex.replace('#', '');
-  
-  // Convert to RGB first
-  const r = parseInt(hex.substring(0, 2), 16) / 255;
-  const g = parseInt(hex.substring(2, 4), 16) / 255;
-  const b = parseInt(hex.substring(4, 6), 16) / 255;
-  
-  const max = Math.max(r, g, b);
-  const min = Math.min(r, g, b);
-  let h = 0;
-  let s = 0;
-  const l = (max + min) / 2;
-  
-  if (max !== min) {
-    const d = max - min;
-    s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
-    
-    switch (max) {
-      case r: h = ((g - b) / d + (g < b ? 6 : 0)) / 6; break;
-      case g: h = ((b - r) / d + 2) / 6; break;
-      case b: h = ((r - g) / d + 4) / 6; break;
-    }
-  }
-  
-  return {
-    h: Math.round(h * 360),
-    s: Math.round(s * 100),
-    l: Math.round(l * 100)
-  };
-}
-
-/**
- * Generate CSS variables from tokens using HSL for colors
- */
-function generateCSSVariables(tokens: DesignToken[], themeName: string = 'default'): string {
-  const lines: string[] = [
-    `/* ${themeName} Theme - Generated by Optics MCP */`,
-    `/* HSL tokens for easy theming */`,
-    `:root {`
-  ];
-  
-  // Group tokens by category
-  const grouped: Record<string, DesignToken[]> = {};
-  tokens.forEach(token => {
-    if (!grouped[token.category]) grouped[token.category] = [];
-    grouped[token.category].push(token);
-  });
-  
-  // Output color tokens - they're already in HSL format
-  if (grouped['color']) {
-    lines.push(`  /* Colors (HSL) */`);
-    for (const token of grouped['color']) {
-      // Tokens are already properly formatted (either HSL base values or full color values)
-      lines.push(`  --${token.name}: ${token.value};`);
-    }
-    lines.push('');
-  }
-  
-  // Output non-color tokens normally
-  for (const [category, categoryTokens] of Object.entries(grouped)) {
-    if (category === 'color') continue; // Already handled
-    
-    lines.push(`  /* ${category.charAt(0).toUpperCase() + category.slice(1)} */`);
-    for (const token of categoryTokens) {
-      lines.push(`  --${token.name}: ${token.value};`);
-    }
-    lines.push('');
-  }
-  
-  lines.push('}');
-  
-  return lines.join('\n');
-}
-
-/**
- * Generate theme documentation
- */
-function generateDocumentation(themeName: string, tokens: DesignToken[]): string {
-  const stats = tokens.reduce((acc, token) => {
-    acc[token.category] = (acc[token.category] || 0) + 1;
-    return acc;
-  }, {} as Record<string, number>);
-  
-  const lines: string[] = [
-    `# ${themeName} Theme`,
-    '',
-    '## Overview',
-    'This theme was generated by Optics MCP and uses the Optics Design System tokens.',
-    '',
-    '## Step 1: Install Optics Design System',
-    '',
-    '### Option A: Via npm (Recommended)',
-    '```bash',
-    'npm install @rolemodel/optics',
-    '```',
-    '',
-    'Then import in your CSS:',
-    '```css',
-    '@import "@rolemodel/optics/dist/optics.css";',
-    '```',
-    '',
-    '### Option B: Via CDN (jsDelivr)',
-    '```html',
-    '<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@rolemodel/optics@latest/dist/optics.css">',
-    '```',
-    '',
-    '### Option C: Via unpkg',
-    '```html',
-    '<link rel="stylesheet" href="https://unpkg.com/@rolemodel/optics@latest/dist/optics.css">',
-    '```',
-    '',
-    '## Step 2: Add Your Custom Theme Overrides',
-    '',
-    'Create a `theme.css` file with the custom HSL color values below and load it AFTER Optics:',
-    '',
-    '```html',
-    '<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@rolemodel/optics@latest/dist/optics.css">',
-    '<link rel="stylesheet" href="./theme.css">',
-    '```',
-    '',
-    '## Token Summary',
-    ''
-  ];
-  
-  for (const [category, count] of Object.entries(stats)) {
-    lines.push(`- **${category}**: ${count} tokens`);
-  }
-  
-  lines.push('');
-  lines.push('## Step 3: Using Optics Components');
-  lines.push('');
-  lines.push('**IMPORTANT:** Optics has pre-built components with specific HTML structure and CSS classes.');
-  lines.push('');
-  lines.push('Do NOT make up CSS classes. Use the actual Optics components and their documentation:');
-  lines.push('');
-  lines.push('**Component Documentation:** https://docs.optics.rolemodel.design');
-  lines.push('');
-  lines.push('Your custom theme will automatically apply to all Optics components through the HSL base values.');
-  lines.push('');
-  lines.push('### Example: Using an Optics Button');
-  lines.push('Refer to the Optics documentation for the actual button HTML structure and CSS classes.');
-  lines.push('Your theme colors will apply automatically through the `--op-color-primary-*` variables.');
-  lines.push('');
-  lines.push('### Figma Variables');
-  lines.push('Import the `figma-variables.json` file into Figma:');
-  lines.push('1. Open your Figma file');
-  lines.push('2. Go to Variables panel');
-  lines.push('3. Import → Select `figma-variables.json`');
-  lines.push('');
-  lines.push('## Token Categories');
-  lines.push('');
-  
-  // Group tokens by category for documentation
-  const grouped: Record<string, DesignToken[]> = {};
-  tokens.forEach(token => {
-    if (!grouped[token.category]) grouped[token.category] = [];
-    grouped[token.category].push(token);
-  });
-  
-  for (const [category, categoryTokens] of Object.entries(grouped)) {
-    lines.push(`### ${category.charAt(0).toUpperCase() + category.slice(1)}`);
-    lines.push('');
-    lines.push('| Token Name | Value | Description |');
-    lines.push('|------------|-------|-------------|');
-    for (const token of categoryTokens) {
-      lines.push(`| \`${token.name}\` | \`${token.value}\` | ${token.description || ''} |`);
-    }
-    lines.push('');
-  }
-  
-  return lines.join('\n');
-}
-
-/**
- * Main theme generation function
- * Uses all standard Optics tokens, only customizing the HSL color base values
- */
-export function generateTheme(
-  brandName: string,
-  brandColors: BrandColors,
-  options: ThemeOptions = {}
-): GeneratedTheme {
-  // Start with all standard Optics tokens
-  let tokens: DesignToken[] = [...designTokens];
-  
-  // Override HSL color base values if custom colors provided
-  if (Object.keys(brandColors).length > 0) {
-    const customColorTokens = generateColorTokens(brandColors);
-    
-    // Replace the HSL base tokens with custom ones
-    tokens = tokens.map(token => {
-      const customToken = customColorTokens.find(ct => ct.name === token.name);
-      return customToken || token;
-    });
-  }
-  
-  const cssVariables = generateCSSVariables(tokens, brandName);
-  const figmaVariables = generateFigmaVariablesJSON(tokens, {
-    collectionName: `${brandName} Design System`
-  });
-  const documentation = generateDocumentation(brandName, tokens);
-  
-  return {
-    cssVariables,
-    figmaVariables,
-    tokens,
-    documentation
-  };
-}
diff --git a/src/tools/validate-token-usage-header.md b/src/tools/validate-token-usage-header.md
new file mode 100644
index 0000000..6ccc5b4
--- /dev/null
+++ b/src/tools/validate-token-usage-header.md
@@ -0,0 +1,7 @@
+# Token Validation Report
+
+**Status**: {{status}}
+**Issues**: {{issueCount}}
+**Values Checked**: {{totalChecked}}
+
+## Issues
diff --git a/src/tools/validate-token-usage-tool.ts b/src/tools/validate-token-usage-tool.ts
new file mode 100644
index 0000000..20e10d0
--- /dev/null
+++ b/src/tools/validate-token-usage-tool.ts
@@ -0,0 +1,138 @@
+/**
+ * Validate Token Usage Tool
+ * Validates code for hard-coded values that should use design tokens
+ */
+
+import { z } from 'zod';
+import Tool, { type ToolInputSchema } from './tool.js';
+import { designTokens, type DesignToken } from '../optics-data.js';
+import { extractAllValues, findMatchingToken, type CSSValue } from '../utils/css-parser.js';
+import { readToolFile } from '../_internal/resource-path.js';
+
+export interface ValidationIssue {
+  type: 'hard-coded-value' | 'missing-token' | 'deprecated-token';
+  value: string;
+  line?: number;
+  property?: string;
+  suggestion?: string;
+  severity: 'error' | 'warning' | 'info';
+}
+
+export interface ValidationReport {
+  valid: boolean;
+  issueCount: number;
+  issues: ValidationIssue[];
+  summary: {
+    hardCodedValues: number;
+    missingTokens: number;
+    totalChecked: number;
+  };
+}
+
+class ValidateTokenUsageTool extends Tool {
+  name = 'validate_token_usage';
+  title = 'Validate Token Usage';
+  description = 'Validate code for hard-coded values that should use design tokens';
+
+  inputSchema = {
+    code: z.string().describe('CSS or component code to validate'),
+  };
+
+  async handler(args: ToolInputSchema): Promise<string> {
+    const report = this.validateTokenUsage(args.code, designTokens);
+    const formatted = await this.formatValidationReport(report);
+
+    return formatted;
+  }
+
+  /**
+   * Validate token usage in code
+   */
+  private validateTokenUsage(code: string, tokens: DesignToken[]): ValidationReport {
+    const issues: ValidationIssue[] = [];
+    const extractedValues = extractAllValues(code);
+
+    for (const value of extractedValues) {
+      const matchingToken = findMatchingToken(value.value, tokens);
+
+      if (!matchingToken) {
+        issues.push({
+          type: 'hard-coded-value',
+          value: value.value,
+          property: value.property,
+          line: value.line,
+          suggestion: this.suggestTokenForValue(value, tokens),
+          severity: 'warning'
+        });
+      }
+    }
+
+    const hardCodedValues = issues.filter(i => i.type === 'hard-coded-value').length;
+
+    return {
+      valid: issues.length === 0,
+      issueCount: issues.length,
+      issues,
+      summary: {
+        hardCodedValues,
+        missingTokens: 0,
+        totalChecked: extractedValues.length
+      }
+    };
+  }
+
+  /**
+   * Suggest appropriate token for a hard-coded value
+   */
+  private suggestTokenForValue(value: CSSValue, tokens: DesignToken[]): string {
+    const categoryTokens = tokens.filter(t => {
+      if (value.type === 'color') return t.category === 'color';
+      if (value.type === 'spacing') return t.category === 'spacing';
+      if (value.type === 'font-size') return t.name.includes('font-size');
+      if (value.type === 'font-weight') return t.name.includes('font-weight');
+      if (value.type === 'border-radius') return t.category === 'border';
+      if (value.type === 'shadow') return t.category === 'shadow';
+      return false;
+    });
+
+    if (categoryTokens.length === 0) {
+      return 'No matching tokens found';
+    }
+
+    // Find closest match
+    const closest = categoryTokens[0];
+    return `Consider using token: ${closest.name} (${closest.value})`;
+  }
+
+  /**
+   * Generate validation report as formatted text
+   */
+  private async formatValidationReport(report: ValidationReport): Promise<string> {
+    if (report.issues.length === 0) {
+      const template = await readToolFile('validate-token-usage-valid.md');
+      return template.replace('{{totalChecked}}', report.summary.totalChecked.toString());
+    }
+
+    const template = await readToolFile('validate-token-usage-header.md');
+    const status = report.valid ? '✓ Valid' : '✗ Issues Found';
+    const lines: string[] = [
+      template
+        .replace('{{status}}', status)
+        .replace('{{issueCount}}', report.issueCount.toString())
+        .replace('{{totalChecked}}', report.summary.totalChecked.toString()),
+      ''
+    ];
+
+    for (const issue of report.issues) {
+      lines.push(`### ${issue.type}`);
+      lines.push(`- **Value**: \`${issue.value}\``);
+      if (issue.property) lines.push(`- **Property**: \`${issue.property}\``);
+      if (issue.suggestion) lines.push(`- **Suggestion**: ${issue.suggestion}`);
+      lines.push('');
+    }
+
+    return lines.join('\n');
+  }
+}
+
+export default ValidateTokenUsageTool;
diff --git a/src/tools/validate-token-usage-valid.md b/src/tools/validate-token-usage-valid.md
new file mode 100644
index 0000000..eaa5b43
--- /dev/null
+++ b/src/tools/validate-token-usage-valid.md
@@ -0,0 +1,7 @@
+# Token Validation Report
+
+**Status**: ✓ Valid
+**Issues**: 0
+**Values Checked**: {{totalChecked}}
+
+✓ No issues found! All values use design tokens.
diff --git a/src/tools/validate.ts b/src/tools/validate.ts
deleted file mode 100644
index 7699f2f..0000000
--- a/src/tools/validate.ts
+++ /dev/null
@@ -1,121 +0,0 @@
-/**
- * Token validation tool
- * Validates token usage in code and suggests improvements
- */
-
-import { DesignToken } from '../optics-data.js';
-import { extractAllValues, findMatchingToken, CSSValue } from '../utils/css-parser.js';
-
-export interface ValidationIssue {
-  type: 'hard-coded-value' | 'missing-token' | 'deprecated-token';
-  value: string;
-  line?: number;
-  property?: string;
-  suggestion?: string;
-  severity: 'error' | 'warning' | 'info';
-}
-
-export interface ValidationReport {
-  valid: boolean;
-  issueCount: number;
-  issues: ValidationIssue[];
-  summary: {
-    hardCodedValues: number;
-    missingTokens: number;
-    totalChecked: number;
-  };
-}
-
-/**
- * Validate token usage in code
- */
-export function validateTokenUsage(
-  code: string,
-  tokens: DesignToken[],
-  context?: string
-): ValidationReport {
-  const issues: ValidationIssue[] = [];
-  const extractedValues = extractAllValues(code);
-  
-  for (const value of extractedValues) {
-    const matchingToken = findMatchingToken(value.value, tokens);
-    
-    if (!matchingToken) {
-      issues.push({
-        type: 'hard-coded-value',
-        value: value.value,
-        property: value.property,
-        line: value.line,
-        suggestion: suggestTokenForValue(value, tokens),
-        severity: 'warning'
-      });
-    }
-  }
-  
-  const hardCodedValues = issues.filter(i => i.type === 'hard-coded-value').length;
-  
-  return {
-    valid: issues.length === 0,
-    issueCount: issues.length,
-    issues,
-    summary: {
-      hardCodedValues,
-      missingTokens: 0,
-      totalChecked: extractedValues.length
-    }
-  };
-}
-
-/**
- * Suggest appropriate token for a hard-coded value
- */
-function suggestTokenForValue(value: CSSValue, tokens: DesignToken[]): string {
-  const categoryTokens = tokens.filter(t => {
-    if (value.type === 'color') return t.category === 'color';
-    if (value.type === 'spacing') return t.category === 'spacing';
-    if (value.type === 'font-size') return t.name.includes('font-size');
-    if (value.type === 'font-weight') return t.name.includes('font-weight');
-    if (value.type === 'border-radius') return t.category === 'border';
-    if (value.type === 'shadow') return t.category === 'shadow';
-    return false;
-  });
-  
-  if (categoryTokens.length === 0) {
-    return 'No matching tokens found';
-  }
-  
-  // Find closest match
-  const closest = categoryTokens[0];
-  return `Consider using token: ${closest.name} (${closest.value})`;
-}
-
-/**
- * Generate validation report as formatted text
- */
-export function formatValidationReport(report: ValidationReport): string {
-  const lines: string[] = [
-    '# Token Validation Report',
-    '',
-    `**Status**: ${report.valid ? '✓ Valid' : '✗ Issues Found'}`,
-    `**Issues**: ${report.issueCount}`,
-    `**Values Checked**: ${report.summary.totalChecked}`,
-    ''
-  ];
-  
-  if (report.issues.length > 0) {
-    lines.push('## Issues');
-    lines.push('');
-    
-    for (const issue of report.issues) {
-      lines.push(`### ${issue.type}`);
-      lines.push(`- **Value**: \`${issue.value}\``);
-      if (issue.property) lines.push(`- **Property**: \`${issue.property}\``);
-      if (issue.suggestion) lines.push(`- **Suggestion**: ${issue.suggestion}`);
-      lines.push('');
-    }
-  } else {
-    lines.push('✓ No issues found! All values use design tokens.');
-  }
-  
-  return lines.join('\n');
-}

From 6e042a8aaf4d486d27ab3be39c6090e43718bfa2 Mon Sep 17 00:00:00 2001
From: Dallas Peters <dallaspeters@gmail.com>
Date: Thu, 5 Feb 2026 21:58:56 +0000
Subject: [PATCH 14/28] Add sync-optics-data script

Extracts tokens and components from Optics source repo.
Generates optics-data.ts with 29 real components.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 scripts/sync-optics-data.ts | 872 ++++++++++++++++++++++++++++++++++++
 scripts/tsconfig.json       |  13 +
 2 files changed, 885 insertions(+)
 create mode 100644 scripts/sync-optics-data.ts
 create mode 100644 scripts/tsconfig.json

diff --git a/scripts/sync-optics-data.ts b/scripts/sync-optics-data.ts
new file mode 100644
index 0000000..3bd75f1
--- /dev/null
+++ b/scripts/sync-optics-data.ts
@@ -0,0 +1,872 @@
+#!/usr/bin/env npx ts-node
+
+/**
+ * Sync Optics Data Script
+ * Run: npm run sync-data
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+
+// ESM compatibility
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Configuration
+const OPTICS_PACKAGE = '@rolemodel/optics';
+const OPTICS_SOURCE_REPO = path.join(__dirname, '../../optics'); // Assumes optics repo is sibling
+const OUTPUT_FILE = path.join(__dirname, '../src/optics-data.ts');
+
+// Token categories matching Optics Storybook
+type TokenCategory =
+  | 'animation'
+  | 'border'
+  | 'breakpoint'
+  | 'color'
+  | 'encoded-image'
+  | 'input'
+  | 'opacity'
+  | 'shadow'
+  | 'sizing'
+  | 'spacing'
+  | 'typography'
+  | 'z-index';
+
+interface DesignToken {
+  name: string;
+  cssVar: string;
+  value: string;
+  category: TokenCategory;
+  description: string;
+}
+
+interface CSSPattern {
+  name: string;
+  description: string;
+  className: string;
+  type: 'component' | 'layout' | 'utility';
+  modifiers: string[];
+  elements: string[];
+  exampleHtml: string;
+  docsUrl: string;
+}
+
+interface Documentation {
+  section: string;
+  title: string;
+  content: string;
+  tokens: string[];
+}
+
+// ============================================================================
+// Find Optics paths
+// ============================================================================
+
+function findOpticsPackage(): string | null {
+  const possiblePaths = [
+    path.join(__dirname, '../node_modules', OPTICS_PACKAGE),
+    path.join(__dirname, '../../node_modules', OPTICS_PACKAGE),
+  ];
+
+  for (const p of possiblePaths) {
+    if (fs.existsSync(p)) {
+      return p;
+    }
+  }
+  return null;
+}
+
+function findOpticsSourceRepo(): string | null {
+  if (fs.existsSync(OPTICS_SOURCE_REPO) && fs.existsSync(path.join(OPTICS_SOURCE_REPO, 'src/stories'))) {
+    return OPTICS_SOURCE_REPO;
+  }
+  return null;
+}
+
+// ============================================================================
+// Token Extraction from tokens.json
+// ============================================================================
+
+function flattenTokens(obj: any, prefix: string = ''): DesignToken[] {
+  const tokens: DesignToken[] = [];
+
+  for (const [key, value] of Object.entries(obj)) {
+    const name = prefix ? `${prefix}-${key}` : key;
+
+    if (typeof value === 'string') {
+      const category = categorizeToken(name);
+      tokens.push({
+        name,
+        cssVar: `--op-${name}`,
+        value,
+        category,
+        description: generateTokenDescription(name, category),
+      });
+    } else if (typeof value === 'object' && value !== null) {
+      tokens.push(...flattenTokens(value, name));
+    }
+  }
+
+  return tokens;
+}
+
+function categorizeToken(name: string): TokenCategory {
+  if (name.includes('z-index') || name.startsWith('z-')) return 'z-index';
+  if (name.startsWith('animation-') || name.startsWith('transition-') || name.startsWith('duration-') || name.startsWith('easing-')) return 'animation';
+  if (name.startsWith('radius-') || name.startsWith('border-')) return 'border';
+  if (name.startsWith('breakpoint-') || name.startsWith('screen-')) return 'breakpoint';
+  if (name.startsWith('input-')) return 'input';
+  if (name.startsWith('opacity-') || name.includes('-opacity')) return 'opacity';
+  if (name.startsWith('shadow-') || name.includes('-shadow')) return 'shadow';
+  if (name.startsWith('size-') || name.includes('-width') || name.includes('-height')) return 'sizing';
+  if (name.startsWith('space-') || name.startsWith('gap-')) return 'spacing';
+  if (name.startsWith('font-') || name.startsWith('line-height') || name.startsWith('letter-') || name.startsWith('text-')) return 'typography';
+  if (name.startsWith('encoded-') || name.startsWith('image-')) return 'encoded-image';
+  if (name.startsWith('color-') || name.includes('-color-') || name.includes('-on-') || name.includes('-base') || name.includes('-plus-') || name.includes('-minus-')) return 'color';
+  return 'sizing';
+}
+
+function generateTokenDescription(name: string, category: TokenCategory): string {
+  if (category === 'color') {
+    if (name.includes('-on-')) {
+      const parts = name.split('-on-');
+      return `Text color for use ON ${parts[1]} background. MUST be paired with matching background color.`;
+    }
+    if (name.endsWith('-h')) return `Hue component (HSL) for ${name.replace('-h', '')}`;
+    if (name.endsWith('-s')) return `Saturation component (HSL) for ${name.replace('-s', '')}`;
+    if (name.endsWith('-l')) return `Lightness component (HSL) for ${name.replace('-l', '')}`;
+  }
+  return `${category} token: ${name}`;
+}
+
+// ============================================================================
+// CSS Token Extraction from dist CSS (fallback)
+// ============================================================================
+
+function extractTokensFromCSS(cssContent: string): DesignToken[] {
+  const tokens: DesignToken[] = [];
+  const customPropRegex = /--op-([a-z0-9-]+):\s*([^;]+);/g;
+  let match;
+
+  while ((match = customPropRegex.exec(cssContent)) !== null) {
+    const name = match[1];
+    const value = match[2].trim();
+    const category = categorizeToken(name);
+
+    tokens.push({
+      name,
+      cssVar: `--op-${name}`,
+      value,
+      category,
+      description: generateTokenDescription(name, category),
+    });
+  }
+
+  return tokens;
+}
+
+// ============================================================================
+// CSS Class Extraction for validation
+// ============================================================================
+
+function extractCSSClasses(cssContent: string): Set<string> {
+  const classes = new Set<string>();
+  const classRegex = /\.([a-z][a-z0-9_-]*)/g;
+  let match;
+
+  while ((match = classRegex.exec(cssContent)) !== null) {
+    classes.add(match[1]);
+  }
+
+  return classes;
+}
+
+// ============================================================================
+// Storybook MDX Parsing
+// ============================================================================
+
+interface ClassDoc {
+  className: string;
+  description: string;
+  isModifier: boolean;
+  baseClass?: string;
+}
+
+function parseComponentMdx(mdxPath: string, componentName: string): {
+  componentDescription: string;
+  classes: ClassDoc[];
+} {
+  const content = fs.readFileSync(mdxPath, 'utf-8');
+
+  // Extract description (first paragraph after # ComponentName)
+  const descMatch = content.match(new RegExp(`# ${componentName}[\\s\\S]*?\\n\\n([^#\\n<][^\\n]+)`));
+  const componentDescription = descMatch ? descMatch[1].trim() : '';
+
+  // Extract ALL class documentation: `.class-name` Description text
+  const classes: ClassDoc[] = [];
+  const classDocRegex = /`\.([a-z][a-z0-9_-]*(?:--[a-z0-9-]+)?)`\s+([^`\n]+)/g;
+  let classMatch;
+
+  while ((classMatch = classDocRegex.exec(content)) !== null) {
+    const className = classMatch[1];
+    const description = classMatch[2].trim();
+    const isModifier = className.includes('--');
+    const baseClass = isModifier ? className.split('--')[0] : undefined;
+
+    classes.push({ className, description, isModifier, baseClass });
+  }
+
+  return { componentDescription, classes };
+}
+
+function getBaseClasses(classes: ClassDoc[]): string[] {
+  // Get unique base classes (non-modifiers)
+  const baseClasses = classes
+    .filter(c => !c.isModifier)
+    .map(c => c.className);
+  return [...new Set(baseClasses)];
+}
+
+// ============================================================================
+// Storybook Stories Parsing
+// ============================================================================
+
+function parseStoriesFile(storiesPath: string): { variants: string[]; sizes: string[] } {
+  const content = fs.readFileSync(storiesPath, 'utf-8');
+
+  // Extract variant options
+  const variantMatch = content.match(/variant:\s*\{[^}]*options:\s*\[([^\]]+)\]/);
+  const variants = variantMatch
+    ? variantMatch[1].split(',').map(v => v.trim().replace(/['"]/g, ''))
+    : [];
+
+  // Extract size options
+  const sizeMatch = content.match(/size:\s*\{[^}]*options:\s*\[([^\]]+)\]/);
+  const sizes = sizeMatch
+    ? sizeMatch[1].split(',').map(s => s.trim().replace(/['"]/g, ''))
+    : [];
+
+  return { variants, sizes };
+}
+
+// ============================================================================
+// Scrape Components from Storybook Source
+// NOTE: Requires the Optics git repo to be cloned at ../../optics
+// Storybook files are NOT included in the npm package
+// ============================================================================
+
+function scrapeComponentsFromStorybook(sourceRepo: string, opticsPackagePath: string, validClasses: Set<string>): CSSPattern[] {
+  const patterns: CSSPattern[] = [];
+  const componentsDir = path.join(sourceRepo, 'src/stories/Components');
+  const cssComponentsDir = path.join(opticsPackagePath, 'dist/css/components');
+
+  const processDirectory = (dir: string, type: 'component' | 'layout' | 'utility') => {
+    if (!fs.existsSync(dir)) return;
+
+    const items = fs.readdirSync(dir);
+
+    for (const item of items) {
+      const itemPath = path.join(dir, item);
+      if (!fs.statSync(itemPath).isDirectory()) continue;
+
+      const mdxPath = path.join(itemPath, `${item}.mdx`);
+      const storiesPath = path.join(itemPath, `${item}.stories.js`);
+
+      if (!fs.existsSync(mdxPath)) continue;
+
+      console.log(`   Parsing ${item}...`);
+
+      // Parse MDX for ALL class documentation
+      const mdxData = parseComponentMdx(mdxPath, item);
+      const baseClasses = getBaseClasses(mdxData.classes);
+
+      // Parse stories for variants
+      const storiesData = fs.existsSync(storiesPath) ? parseStoriesFile(storiesPath) : { variants: [], sizes: [] };
+
+      // For multi-class components (like Form), use primary class, store all classes
+      if (baseClasses.length > 1) {
+        // Use first class as primary, collect all modifiers/elements across all base classes
+        const primaryClass = baseClasses[0];
+        const allModifiers: string[] = [];
+        const allElements: string[] = [];
+
+        for (const baseClass of baseClasses) {
+          if (!validClasses.has(baseClass)) continue;
+
+          // Collect modifiers
+          const mods = Array.from(validClasses).filter(c => c.startsWith(`${baseClass}--`));
+          allModifiers.push(...mods);
+
+          // Collect elements
+          const elems = Array.from(validClasses).filter(c => c.startsWith(`${baseClass}__`));
+          allElements.push(...elems);
+        }
+
+        patterns.push({
+          name: item,
+          description: mdxData.componentDescription || `${item} component`,
+          className: primaryClass,
+          type,
+          modifiers: [...new Set(allModifiers)].sort(),
+          elements: [...new Set([...baseClasses.slice(1), ...allElements])].sort(), // Include other base classes as "elements"
+          exampleHtml: generateExampleHtml(primaryClass, [], allElements),
+          docsUrl: `https://docs.optics.rolemodel.design/?path=/docs/components-${item.toLowerCase()}--docs`,
+        });
+      } else {
+        // Single base class component - use first base class or derive from component name
+        const className = baseClasses[0] || deriveClassName(item, validClasses);
+        if (!className || !validClasses.has(className)) {
+          console.log(`     ⚠️  No valid base class found for ${item}`);
+          continue;
+        }
+
+        // Build modifiers list from MDX and validate against actual CSS
+        let modifiers = mdxData.classes
+          .filter(c => c.isModifier)
+          .map(c => c.className)
+          .filter(m => validClasses.has(m));
+
+        // Add variant-based modifiers from stories
+        for (const variant of storiesData.variants) {
+          if (variant !== 'default') {
+            const modClass = `${className}--${variant}`;
+            if (validClasses.has(modClass) && !modifiers.includes(modClass)) {
+              modifiers.push(modClass);
+            }
+          }
+        }
+
+        // Add size-based modifiers from stories
+        for (const size of storiesData.sizes) {
+          const sizeClass = `${className}--${size}`;
+          if (validClasses.has(sizeClass) && !modifiers.includes(sizeClass)) {
+            modifiers.push(sizeClass);
+          }
+        }
+
+        // Also find modifiers from CSS
+        const cssModifiers = Array.from(validClasses)
+          .filter(c => c.startsWith(`${className}--`));
+
+        modifiers = [...new Set([...modifiers, ...cssModifiers])].sort();
+
+        // Extract elements (BEM __element classes)
+        const elements = Array.from(validClasses)
+          .filter(c => c.startsWith(`${className}__`))
+          .sort();
+
+        patterns.push({
+          name: item,
+          description: mdxData.componentDescription || `${item} component`,
+          className,
+          type,
+          modifiers,
+          elements,
+          exampleHtml: generateExampleHtml(className, modifiers, elements),
+          docsUrl: `https://docs.optics.rolemodel.design/?path=/docs/${type === 'component' ? 'components' : type === 'layout' ? 'layout' : 'utilities'}-${item.toLowerCase()}--docs`,
+        });
+      }
+    }
+  };
+
+  // Helper to derive class name from component name
+  function deriveClassName(componentName: string, validClasses: Set<string>): string | null {
+    // Try common patterns
+    const patterns = [
+      componentName.toLowerCase(),
+      componentName.toLowerCase().replace(/([A-Z])/g, '-$1').toLowerCase().replace(/^-/, ''),
+      componentName.replace(/([A-Z])/g, '-$1').toLowerCase().replace(/^-/, ''),
+    ];
+
+    for (const pattern of patterns) {
+      if (validClasses.has(pattern)) return pattern;
+    }
+
+    // Try finding a class that starts with component name
+    const prefix = componentName.toLowerCase();
+    for (const cls of validClasses) {
+      if (cls.startsWith(prefix) && !cls.includes('--') && !cls.includes('__')) {
+        return cls;
+      }
+    }
+
+    return null;
+  }
+
+  processDirectory(componentsDir, 'component');
+  // Skip utilities - they're CSS helpers, not components
+
+  // Add layout utilities manually (op-stack, op-cluster, op-split)
+  const layoutPatterns = ['op-stack', 'op-cluster', 'op-split'];
+  for (const className of layoutPatterns) {
+    if (validClasses.has(className)) {
+      patterns.push({
+        name: className.replace('op-', '').charAt(0).toUpperCase() + className.replace('op-', '').slice(1),
+        description: `Layout utility: ${className}`,
+        className,
+        type: 'layout',
+        modifiers: [],
+        elements: [],
+        exampleHtml: `<div class="${className}">...</div>`,
+        docsUrl: `https://docs.optics.rolemodel.design/?path=/docs/layout-${className.replace('op-', '')}--docs`,
+      });
+    }
+  }
+
+  // Add data-attribute patterns (Tooltip, etc.)
+  patterns.push(...extractDataAttributePatterns(cssComponentsDir));
+
+  return patterns;
+}
+
+// Extract patterns that use data attributes instead of classes (e.g., Tooltip)
+function extractDataAttributePatterns(componentsDir: string): CSSPattern[] {
+  const patterns: CSSPattern[] = [];
+
+  if (!fs.existsSync(componentsDir)) return patterns;
+
+  const dataAttrComponents: Record<string, { attr: string; description: string; positions?: string[] }> = {
+    'tooltip.css': {
+      attr: 'data-tooltip-text',
+      description: 'CSS-only tooltip using data attributes',
+      positions: ['top', 'bottom', 'left', 'right']
+    }
+  };
+
+  for (const [cssFile, config] of Object.entries(dataAttrComponents)) {
+    const cssPath = path.join(componentsDir, cssFile);
+    if (!fs.existsSync(cssPath)) continue;
+
+    const name = cssFile.replace('.css', '').split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join('');
+
+    patterns.push({
+      name,
+      description: config.description,
+      className: `[${config.attr}]`,
+      type: 'component',
+      modifiers: config.positions?.map(p => `[data-tooltip-position="${p}"]`) || [],
+      elements: [],
+      exampleHtml: `<button ${config.attr}="Tooltip text" data-tooltip-position="top">Hover me</button>`,
+      docsUrl: `https://docs.optics.rolemodel.design/?path=/docs/components-${cssFile.replace('.css', '')}--docs`,
+    });
+  }
+
+  return patterns;
+}
+
+function generateExampleHtml(className: string, modifiers: string[], elements: string[]): string {
+  if (elements.length > 0) {
+    const elementsHtml = elements
+      .slice(0, 3)
+      .map(el => `  <div class="${el}">...</div>`)
+      .join('\n');
+    return `<div class="${className}">\n${elementsHtml}\n</div>`;
+  }
+
+  if (className === 'btn') {
+    return `<button class="btn btn--primary">Button</button>`;
+  }
+
+  return `<div class="${className}">...</div>`;
+}
+
+// ============================================================================
+// Derive Components from CSS Files (when Storybook not available)
+// Uses the component CSS files in dist/css/components/ from npm package
+// ============================================================================
+
+function deriveComponentsFromCSS(opticsPath: string, validClasses: Set<string>): CSSPattern[] {
+  const patterns: CSSPattern[] = [];
+  const componentsDir = path.join(opticsPath, 'dist/css/components');
+
+  if (!fs.existsSync(componentsDir)) {
+    console.log('   ⚠️  Components CSS directory not found');
+    return patterns;
+  }
+
+  const cssFiles = fs.readdirSync(componentsDir).filter(f => f.endsWith('.css') && f !== 'index.css');
+
+  for (const cssFile of cssFiles) {
+    const cssPath = path.join(componentsDir, cssFile);
+    const cssContent = fs.readFileSync(cssPath, 'utf-8');
+
+    // Extract all classes from this CSS file
+    const fileClasses = new Set<string>();
+    const classRegex = /\.([a-z][a-z0-9_-]*)/g;
+    let match;
+    while ((match = classRegex.exec(cssContent)) !== null) {
+      fileClasses.add(match[1]);
+    }
+
+    // Find base classes (no -- or __)
+    const baseClasses = Array.from(fileClasses).filter(c => !c.includes('--') && !c.includes('__'));
+
+    // Group classes by their base
+    for (const baseClass of baseClasses) {
+      if (!validClasses.has(baseClass)) continue;
+
+      // Skip if we already have this base class
+      if (patterns.some(p => p.className === baseClass)) continue;
+
+      // Find modifiers and elements for this base class
+      const modifiers = Array.from(fileClasses)
+        .filter(c => c.startsWith(`${baseClass}--`))
+        .sort();
+
+      const elements = Array.from(fileClasses)
+        .filter(c => c.startsWith(`${baseClass}__`))
+        .sort();
+
+      // Generate readable name from class
+      const name = baseClass
+        .split('-')
+        .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+        .join('');
+
+      // Generate description from CSS file header comment if available
+      const headerMatch = cssContent.match(/\/\*\*?\s*\n?\s*\*?\s*([^*\n]+)/);
+      const description = headerMatch ? headerMatch[1].trim() : `${name} component`;
+
+      patterns.push({
+        name,
+        description,
+        className: baseClass,
+        type: 'component',
+        modifiers,
+        elements,
+        exampleHtml: generateExampleHtml(baseClass, modifiers, elements),
+        docsUrl: `https://docs.optics.rolemodel.design/?path=/docs/components-${cssFile.replace('.css', '')}--docs`,
+      });
+    }
+  }
+
+  // Add layout utilities (these are in core/utilities, not components)
+  const layoutPatterns = ['op-stack', 'op-cluster', 'op-split'];
+  for (const className of layoutPatterns) {
+    if (validClasses.has(className)) {
+      const name = className.replace('op-', '').charAt(0).toUpperCase() + className.replace('op-', '').slice(1);
+      patterns.push({
+        name,
+        description: `Layout utility: ${className}`,
+        className,
+        type: 'layout',
+        modifiers: Array.from(validClasses).filter(c => c.startsWith(`${className}--`)),
+        elements: [],
+        exampleHtml: `<div class="${className}">...</div>`,
+        docsUrl: `https://docs.optics.rolemodel.design/?path=/docs/layout-${className.replace('op-', '')}--docs`,
+      });
+    }
+  }
+
+  return patterns;
+}
+
+// ============================================================================
+// Documentation - Preserve existing documentation from optics-data.ts
+// ============================================================================
+
+interface ExistingDoc {
+  section: string;
+  title: string;
+  content: string;
+  tokens?: string[];
+}
+
+function readExistingDocumentation(): ExistingDoc[] {
+  // Read existing optics-data.ts to preserve manually written documentation
+  if (!fs.existsSync(OUTPUT_FILE)) {
+    return getDefaultDocumentation();
+  }
+
+  const content = fs.readFileSync(OUTPUT_FILE, 'utf-8');
+
+  // Extract documentation array from file
+  const docMatch = content.match(/export const documentation: Documentation\[\] = \[([\s\S]*?)\];(?=\s*$|\s*\/\/|\s*export)/);
+  if (!docMatch) {
+    return getDefaultDocumentation();
+  }
+
+  try {
+    // Parse the documentation array (it's JSON-like)
+    const docArrayStr = '[' + docMatch[1] + ']';
+    // Remove trailing commas before parsing
+    const cleanedStr = docArrayStr.replace(/,(\s*[\]}])/g, '$1');
+    return JSON.parse(cleanedStr);
+  } catch {
+    console.log('   ⚠️  Could not parse existing documentation, using defaults');
+    return getDefaultDocumentation();
+  }
+}
+
+function getDefaultDocumentation(): ExistingDoc[] {
+  return [
+    {
+      section: 'overview',
+      title: 'Optics Overview',
+      content: 'Optics is a CSS-only design system. It provides CSS custom properties (tokens) and utility classes - NOT JavaScript components. Use the provided CSS classes and tokens; do not write custom CSS for patterns that already exist.'
+    },
+    {
+      section: 'color-pairing',
+      title: 'Color Pairing Rule',
+      content: 'CRITICAL: Background and text colors must ALWAYS be paired. Never use --op-color-{family}-{scale} without also setting color to --op-color-{family}-on-{scale}. The "on" tokens are calculated for proper contrast against their matching background.'
+    },
+    {
+      section: 'color-system',
+      title: 'HSL Color System',
+      content: 'Optics uses HSL-based colors defined by -h (hue), -s (saturation), -l (lightness) tokens. A full scale is generated from plus-max (lightest) to minus-max (darkest). Each scale step has a matching "on-" token for text.'
+    },
+    {
+      section: 'use-existing',
+      title: 'Use Existing Classes',
+      content: 'Don\'t write custom CSS for components that already exist. Use .btn for buttons, .card for cards, .op-stack/.op-cluster/.op-split for layouts. Only write custom CSS when truly extending the system.'
+    }
+  ];
+}
+
+function getDocumentation(tokens: DesignToken[]): Documentation[] {
+  // Preserve existing manually-written documentation
+  const existing = readExistingDocumentation();
+
+  // Add tokens field based on section content
+  return existing.map((doc: ExistingDoc): Documentation => {
+    let sectionTokens: string[] = [];
+
+    // Auto-populate tokens based on section type
+    if (doc.section === 'color-system' || doc.section === 'color-pairing') {
+      sectionTokens = tokens.filter((t: DesignToken) => t.category === 'color').map((t: DesignToken) => t.name);
+    } else if (doc.section === 'spacing') {
+      sectionTokens = tokens.filter((t: DesignToken) => t.category === 'spacing').map((t: DesignToken) => t.name);
+    } else if (doc.section === 'typography') {
+      sectionTokens = tokens.filter((t: DesignToken) => t.category === 'typography').map((t: DesignToken) => t.name);
+    }
+
+    return {
+      section: doc.section,
+      title: doc.title,
+      content: doc.content,
+      tokens: doc.tokens || sectionTokens
+    };
+  });
+}
+
+// ============================================================================
+// Output Generation
+// ============================================================================
+
+function generateOutputFile(
+  tokens: DesignToken[],
+  patterns: CSSPattern[],
+  docs: Documentation[],
+  version: string
+): string {
+  const tokenCategories = Array.from(new Set(tokens.map(t => t.category))).sort();
+
+  return `/**
+ * Optics Design System Data
+ * AUTO-GENERATED - Run: npm run sync-data
+ * Version: ${version} | Generated: ${new Date().toISOString()}
+ */
+
+export type TokenCategory = ${tokenCategories.map(c => `'${c}'`).join(' | ')};
+
+export interface DesignToken {
+  name: string;
+  cssVar: string;
+  value: string;
+  category: TokenCategory;
+  description: string;
+}
+
+export interface CSSPattern {
+  name: string;
+  description: string;
+  className: string;
+  type: 'component' | 'layout' | 'utility';
+  modifiers: string[];
+  elements: string[];
+  exampleHtml: string;
+  docsUrl: string;
+}
+
+export interface Component extends CSSPattern {
+  tokens: string[];
+  usage: string;
+  examples: string[];
+}
+
+export interface Documentation {
+  section: string;
+  title: string;
+  content: string;
+  tokens: string[];
+}
+
+export const designTokens: DesignToken[] = ${JSON.stringify(tokens, null, 2)};
+
+export const cssPatterns: CSSPattern[] = ${JSON.stringify(patterns, null, 2)};
+
+// Backwards compatibility: components alias with extended interface
+export const components: Component[] = cssPatterns.map(p => ({
+  ...p,
+  tokens: p.modifiers,
+  usage: p.description,
+  examples: p.exampleHtml ? [p.exampleHtml] : [],
+}));
+
+export const documentation: Documentation[] = ${JSON.stringify(docs, null, 2)};
+`;
+}
+
+// ============================================================================
+// Main
+// ============================================================================
+
+async function main() {
+  console.log('🔄 Syncing Optics data...\n');
+
+  // Find Optics package
+  const opticsPath = findOpticsPackage();
+  if (!opticsPath) {
+    console.error('❌ Could not find @rolemodel/optics package');
+    console.error('   Run: npm install @rolemodel/optics');
+    process.exit(1);
+  }
+  console.log(`📦 Found Optics package at: ${opticsPath}`);
+
+  // Find Optics source repo
+  const sourceRepo = findOpticsSourceRepo();
+  if (sourceRepo) {
+    console.log(`📂 Found Optics source repo at: ${sourceRepo}`);
+  } else {
+    console.log(`⚠️  Optics source repo not found at ${OPTICS_SOURCE_REPO}`);
+    console.log('   Component data will use fallback patterns');
+  }
+
+  // Read package version
+  const packageJson = JSON.parse(fs.readFileSync(path.join(opticsPath, 'package.json'), 'utf-8'));
+  const version = packageJson.version;
+  console.log(`📌 Version: ${version}\n`);
+
+  // 1. Extract tokens from tokens.json if available
+  let allTokens: DesignToken[] = [];
+  const tokensJsonPath = path.join(opticsPath, 'dist/tokens/tokens.json');
+
+  if (fs.existsSync(tokensJsonPath)) {
+    console.log('📊 Parsing tokens.json...');
+    const tokensJson = JSON.parse(fs.readFileSync(tokensJsonPath, 'utf-8'));
+    allTokens = flattenTokens(tokensJson.op || tokensJson);
+    console.log(`   ✓ Found ${allTokens.length} tokens from tokens.json`);
+  } else {
+    // Fallback: parse CSS files
+    console.log('📄 Parsing CSS files for tokens...');
+    const cssDistPath = path.join(opticsPath, 'dist/css');
+
+    const findCSSFiles = (dir: string): string[] => {
+      const files: string[] = [];
+      if (!fs.existsSync(dir)) return files;
+
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          files.push(...findCSSFiles(fullPath));
+        } else if (entry.name.endsWith('.css')) {
+          files.push(fullPath);
+        }
+      }
+      return files;
+    };
+
+    const cssFiles = findCSSFiles(cssDistPath);
+    for (const cssFile of cssFiles) {
+      const content = fs.readFileSync(cssFile, 'utf-8');
+      allTokens.push(...extractTokensFromCSS(content));
+    }
+
+    // Dedupe
+    const seenTokens = new Set<string>();
+    allTokens = allTokens.filter(t => {
+      if (seenTokens.has(t.name)) return false;
+      seenTokens.add(t.name);
+      return true;
+    });
+    console.log(`   ✓ Found ${allTokens.length} tokens from CSS`);
+  }
+
+  // 2. Extract valid CSS classes for validation
+  console.log('\n🎨 Extracting CSS classes for validation...');
+  let validClasses = new Set<string>();
+  const cssDistPath = path.join(opticsPath, 'dist/css');
+
+  const findCSSFiles = (dir: string): string[] => {
+    const files: string[] = [];
+    if (!fs.existsSync(dir)) return files;
+
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        files.push(...findCSSFiles(fullPath));
+      } else if (entry.name.endsWith('.css')) {
+        files.push(fullPath);
+      }
+    }
+    return files;
+  };
+
+  const cssFiles = findCSSFiles(cssDistPath);
+  for (const cssFile of cssFiles) {
+    const content = fs.readFileSync(cssFile, 'utf-8');
+    const classes = extractCSSClasses(content);
+    classes.forEach(c => validClasses.add(c));
+  }
+  console.log(`   ✓ Found ${validClasses.size} valid CSS classes`);
+
+  // 3. Scrape components from Storybook source or derive from CSS
+  let patterns: CSSPattern[] = [];
+
+  if (sourceRepo) {
+    console.log('\n📖 Scraping components from Storybook source...');
+    patterns = scrapeComponentsFromStorybook(sourceRepo, opticsPath, validClasses);
+    console.log(`   ✓ Found ${patterns.length} components`);
+  } else {
+    console.log('\n📄 Deriving components from CSS files in npm package...');
+    console.log('   (For richer documentation, clone https://github.com/RoleModel/optics to ../../optics)');
+    patterns = deriveComponentsFromCSS(opticsPath, validClasses);
+    console.log(`   ✓ Derived ${patterns.length} components from CSS`);
+  }
+
+  // 4. Get documentation
+  console.log('\n📚 Loading documentation...');
+  const docs = getDocumentation(allTokens);
+  console.log(`   ✓ ${docs.length} documentation sections`);
+
+  // 5. Generate output
+  console.log('\n✍️  Generating optics-data.ts...');
+  const output = generateOutputFile(allTokens, patterns, docs, version);
+  fs.writeFileSync(OUTPUT_FILE, output);
+  console.log(`   ✓ Written to ${OUTPUT_FILE}`);
+
+  // Summary
+  const byCategory: Record<string, number> = {};
+  allTokens.forEach(t => {
+    byCategory[t.category] = (byCategory[t.category] || 0) + 1;
+  });
+
+  console.log('\n✅ Sync complete!');
+  console.log(`   - Optics v${version}`);
+  console.log(`   - ${allTokens.length} tokens across ${Object.keys(byCategory).length} categories`);
+  console.log(`   - ${patterns.length} CSS patterns`);
+  console.log(`   - ${docs.length} documentation sections`);
+
+  console.log('\n   Token categories:');
+  Object.entries(byCategory).sort().forEach(([cat, count]) => {
+    console.log(`     - ${cat}: ${count}`);
+  });
+}
+
+main().catch(err => {
+  console.error('Error:', err);
+  process.exit(1);
+});
diff --git a/scripts/tsconfig.json b/scripts/tsconfig.json
new file mode 100644
index 0000000..885e347
--- /dev/null
+++ b/scripts/tsconfig.json
@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "lib": ["ES2022"],
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true
+  },
+  "include": ["*.ts"]
+}

From a4db52a0e189aefa883d3683d9b9b3c73a153750 Mon Sep 17 00:00:00 2001
From: Dallas Peters <dallaspeters@gmail.com>
Date: Thu, 5 Feb 2026 21:59:02 +0000
Subject: [PATCH 15/28] Add component-tokens utility

Helper to get token dependencies for components.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 src/utils/component-tokens.ts | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)
 create mode 100644 src/utils/component-tokens.ts

diff --git a/src/utils/component-tokens.ts b/src/utils/component-tokens.ts
new file mode 100644
index 0000000..d1d7029
--- /dev/null
+++ b/src/utils/component-tokens.ts
@@ -0,0 +1,29 @@
+/**
+ * Component token dependency utilities
+ */
+
+import { components, designTokens, type DesignToken } from '../optics-data.js';
+
+/**
+ * Get component token dependencies
+ */
+export function getComponentTokenDependencies(componentName: string) {
+  const component = components.find(c =>
+    c.name.toLowerCase() === componentName.toLowerCase()
+  );
+
+  if (!component) {
+    return null;
+  }
+
+  const tokenDetails = component.tokens.map((tokenName: string) =>
+    designTokens.find(t => t.name === tokenName)
+  ).filter((token): token is DesignToken => token !== undefined);
+
+  return {
+    component: component.name,
+    description: component.description,
+    tokenCount: component.tokens.length,
+    tokens: tokenDetails
+  };
+}

From b38e9277bace50640c1f7f453abe7ffbe18065aa Mon Sep 17 00:00:00 2001
From: Dallas Peters <dallaspeters@gmail.com>
Date: Thu, 5 Feb 2026 21:59:08 +0000
Subject: [PATCH 16/28] Regenerate optics-data with 29 components

Replaces 152 bloated entries with actual components:
- 26 from Storybook (Accordion through Tooltip)
- 3 layout utilities (Stack, Cluster, Split)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 src/optics-data.ts | 2537 ++++++++++++++++++++++----------------------
 1 file changed, 1278 insertions(+), 1259 deletions(-)

diff --git a/src/optics-data.ts b/src/optics-data.ts
index 95ff948..7673be6 100644
--- a/src/optics-data.ts
+++ b/src/optics-data.ts
@@ -1,1576 +1,1595 @@
 /**
  * Optics Design System Data
- * This file contains the core design tokens, components, and documentation
- * structure for the Optics design system.
+ * AUTO-GENERATED - Run: npm run sync-data
+ * Version: 2.3.0 | Generated: 2026-02-05T21:51:53.056Z
  */
 
+export type TokenCategory = 'animation' | 'border' | 'breakpoint' | 'color' | 'encoded-image' | 'input' | 'opacity' | 'shadow' | 'sizing' | 'spacing' | 'typography' | 'z-index';
+
 export interface DesignToken {
   name: string;
+  cssVar: string;
   value: string;
-  category: string;
-  description?: string;
+  category: TokenCategory;
+  description: string;
 }
 
-export interface Component {
+export interface CSSPattern {
   name: string;
   description: string;
+  className: string;
+  type: 'component' | 'layout' | 'utility';
+  modifiers: string[];
+  elements: string[];
+  exampleHtml: string;
+  docsUrl: string;
+}
+
+export interface Component extends CSSPattern {
   tokens: string[];
   usage: string;
-  examples?: string[];
+  examples: string[];
 }
 
 export interface Documentation {
   section: string;
   title: string;
   content: string;
-  tokens?: string[];
+  tokens: string[];
 }
 
-/**
- * Design Tokens - Core visual design elements from Optics Design System
- * Source: https://docs.optics.rolemodel.design
- */
 export const designTokens: DesignToken[] = [
-  // Base Color HSL Values (These are the foundation - all other colors are derived from these)
   {
-    name: 'op-color-primary-h',
-    value: '216',
-    category: 'color',
-    description: 'Primary color hue (HSL)'
+    "name": "color-white",
+    "cssVar": "--op-color-white",
+    "value": "hsl(0deg 100% 100%)",
+    "category": "color",
+    "description": "color token: color-white"
   },
   {
-    name: 'op-color-primary-s',
-    value: '58%',
-    category: 'color',
-    description: 'Primary color saturation (HSL)'
+    "name": "color-black",
+    "cssVar": "--op-color-black",
+    "value": "hsl(0deg 0% 0%)",
+    "category": "color",
+    "description": "color token: color-black"
   },
   {
-    name: 'op-color-primary-l',
-    value: '48%',
-    category: 'color',
-    description: 'Primary color lightness (HSL)'
+    "name": "color-primary-h",
+    "cssVar": "--op-color-primary-h",
+    "value": "216",
+    "category": "color",
+    "description": "Hue component (HSL) for color-primary"
   },
   {
-    name: 'op-color-neutral-h',
-    value: '216',
-    category: 'color',
-    description: 'Neutral color hue (HSL, inherits from primary)'
+    "name": "color-primary-s",
+    "cssVar": "--op-color-primary-s",
+    "value": "58%",
+    "category": "color",
+    "description": "Saturation component (HSL) for color-primary"
   },
   {
-    name: 'op-color-neutral-s',
-    value: '4%',
-    category: 'color',
-    description: 'Neutral color saturation (HSL)'
+    "name": "color-primary-l",
+    "cssVar": "--op-color-primary-l",
+    "value": "48%",
+    "category": "color",
+    "description": "Lightness component (HSL) for color-primary"
   },
   {
-    name: 'op-color-neutral-l',
-    value: '48%',
-    category: 'color',
-    description: 'Neutral color lightness (HSL)'
+    "name": "color-primary-original",
+    "cssVar": "--op-color-primary-original",
+    "value": "hsl(var(--op-color-primary-h) var(--op-color-primary-s) var(--op-color-primary-l))",
+    "category": "color",
+    "description": "color token: color-primary-original"
   },
-  // Alert Colors HSL
   {
-    name: 'op-color-alerts-warning-h',
-    value: '47',
-    category: 'color',
-    description: 'Warning alert hue (HSL)'
+    "name": "color-neutral-h",
+    "cssVar": "--op-color-neutral-h",
+    "value": "var(--op-color-primary-h)",
+    "category": "color",
+    "description": "Hue component (HSL) for color-neutral"
   },
   {
-    name: 'op-color-alerts-warning-s',
-    value: '100%',
-    category: 'color',
-    description: 'Warning alert saturation (HSL)'
+    "name": "color-neutral-s",
+    "cssVar": "--op-color-neutral-s",
+    "value": "4%",
+    "category": "color",
+    "description": "Saturation component (HSL) for color-neutral"
   },
   {
-    name: 'op-color-alerts-warning-l',
-    value: '61%',
-    category: 'color',
-    description: 'Warning alert lightness (HSL)'
+    "name": "color-neutral-l",
+    "cssVar": "--op-color-neutral-l",
+    "value": "var(--op-color-primary-l)",
+    "category": "color",
+    "description": "Lightness component (HSL) for color-neutral"
   },
   {
-    name: 'op-color-alerts-danger-h',
-    value: '0',
-    category: 'color',
-    description: 'Danger alert hue (HSL)'
+    "name": "color-neutral-original",
+    "cssVar": "--op-color-neutral-original",
+    "value": "hsl(var(--op-color-neutral-h) var(--op-color-neutral-s) var(--op-color-neutral-l))",
+    "category": "color",
+    "description": "color token: color-neutral-original"
   },
   {
-    name: 'op-color-alerts-danger-s',
-    value: '99%',
-    category: 'color',
-    description: 'Danger alert saturation (HSL)'
+    "name": "color-alerts-warning-h",
+    "cssVar": "--op-color-alerts-warning-h",
+    "value": "47",
+    "category": "color",
+    "description": "Hue component (HSL) for color-alerts-warning"
   },
   {
-    name: 'op-color-alerts-danger-l',
-    value: '76%',
-    category: 'color',
-    description: 'Danger alert lightness (HSL)'
+    "name": "color-alerts-warning-s",
+    "cssVar": "--op-color-alerts-warning-s",
+    "value": "100%",
+    "category": "color",
+    "description": "Saturation component (HSL) for color-alerts-warning"
   },
   {
-    name: 'op-color-alerts-info-h',
-    value: '216',
-    category: 'color',
-    description: 'Info alert hue (HSL)'
+    "name": "color-alerts-warning-l",
+    "cssVar": "--op-color-alerts-warning-l",
+    "value": "61%",
+    "category": "color",
+    "description": "Lightness component (HSL) for color-alerts-warning"
   },
   {
-    name: 'op-color-alerts-info-s',
-    value: '58%',
-    category: 'color',
-    description: 'Info alert saturation (HSL)'
+    "name": "color-alerts-warning-original",
+    "cssVar": "--op-color-alerts-warning-original",
+    "value": "hsl(var(--op-color-alerts-warning-h) var(--op-color-alerts-warning-s) var(--op-color-alerts-warning-l))",
+    "category": "color",
+    "description": "color token: color-alerts-warning-original"
   },
   {
-    name: 'op-color-alerts-info-l',
-    value: '48%',
-    category: 'color',
-    description: 'Info alert lightness (HSL)'
+    "name": "color-alerts-danger-h",
+    "cssVar": "--op-color-alerts-danger-h",
+    "value": "0",
+    "category": "color",
+    "description": "Hue component (HSL) for color-alerts-danger"
   },
   {
-    name: 'op-color-alerts-notice-h',
-    value: '130',
-    category: 'color',
-    description: 'Notice alert hue (HSL)'
+    "name": "color-alerts-danger-s",
+    "cssVar": "--op-color-alerts-danger-s",
+    "value": "99%",
+    "category": "color",
+    "description": "Saturation component (HSL) for color-alerts-danger"
   },
   {
-    name: 'op-color-alerts-notice-s',
-    value: '61%',
-    category: 'color',
-    description: 'Notice alert saturation (HSL)'
+    "name": "color-alerts-danger-l",
+    "cssVar": "--op-color-alerts-danger-l",
+    "value": "76%",
+    "category": "color",
+    "description": "Lightness component (HSL) for color-alerts-danger"
   },
   {
-    name: 'op-color-alerts-notice-l',
-    value: '64%',
-    category: 'color',
-    description: 'Notice alert lightness (HSL)'
+    "name": "color-alerts-danger-original",
+    "cssVar": "--op-color-alerts-danger-original",
+    "value": "hsl(var(--op-color-alerts-danger-h) var(--op-color-alerts-danger-s) var(--op-color-alerts-danger-l))",
+    "category": "color",
+    "description": "color token: color-alerts-danger-original"
   },
-  // Primary Color Scale - Main Scale
-  // Note: Same pattern applies to neutral, alerts-warning, alerts-danger, alerts-info, alerts-notice
   {
-    name: 'op-color-primary-plus-max',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 100%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 12%))',
-    category: 'color',
-    description: 'Primary color lightest - light mode: 100%, dark mode: 12%'
+    "name": "color-alerts-info-h",
+    "cssVar": "--op-color-alerts-info-h",
+    "value": "216",
+    "category": "color",
+    "description": "Hue component (HSL) for color-alerts-info"
   },
   {
-    name: 'op-color-primary-plus-eight',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 98%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 14%))',
-    category: 'color',
-    description: 'Primary color scale +8'
+    "name": "color-alerts-info-s",
+    "cssVar": "--op-color-alerts-info-s",
+    "value": "58%",
+    "category": "color",
+    "description": "Saturation component (HSL) for color-alerts-info"
   },
   {
-    name: 'op-color-primary-plus-seven',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 96%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 16%))',
-    category: 'color',
-    description: 'Primary color scale +7'
+    "name": "color-alerts-info-l",
+    "cssVar": "--op-color-alerts-info-l",
+    "value": "48%",
+    "category": "color",
+    "description": "Lightness component (HSL) for color-alerts-info"
   },
   {
-    name: 'op-color-primary-plus-six',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 94%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 20%))',
-    category: 'color',
-    description: 'Primary color scale +6'
+    "name": "color-alerts-info-original",
+    "cssVar": "--op-color-alerts-info-original",
+    "value": "hsl(var(--op-color-alerts-info-h) var(--op-color-alerts-info-s) var(--op-color-alerts-info-l))",
+    "category": "color",
+    "description": "color token: color-alerts-info-original"
   },
   {
-    name: 'op-color-primary-plus-five',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 90%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 24%))',
-    category: 'color',
-    description: 'Primary color scale +5'
+    "name": "color-alerts-notice-h",
+    "cssVar": "--op-color-alerts-notice-h",
+    "value": "130",
+    "category": "color",
+    "description": "Hue component (HSL) for color-alerts-notice"
   },
   {
-    name: 'op-color-primary-plus-four',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 84%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 26%))',
-    category: 'color',
-    description: 'Primary color scale +4'
+    "name": "color-alerts-notice-s",
+    "cssVar": "--op-color-alerts-notice-s",
+    "value": "61%",
+    "category": "color",
+    "description": "Saturation component (HSL) for color-alerts-notice"
   },
   {
-    name: 'op-color-primary-plus-three',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 70%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 29%))',
-    category: 'color',
-    description: 'Primary color scale +3'
+    "name": "color-alerts-notice-l",
+    "cssVar": "--op-color-alerts-notice-l",
+    "value": "64%",
+    "category": "color",
+    "description": "Lightness component (HSL) for color-alerts-notice"
   },
   {
-    name: 'op-color-primary-plus-two',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 64%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 32%))',
-    category: 'color',
-    description: 'Primary color scale +2'
+    "name": "color-alerts-notice-original",
+    "cssVar": "--op-color-alerts-notice-original",
+    "value": "hsl(var(--op-color-alerts-notice-h) var(--op-color-alerts-notice-s) var(--op-color-alerts-notice-l))",
+    "category": "color",
+    "description": "color token: color-alerts-notice-original"
   },
   {
-    name: 'op-color-primary-plus-one',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 45%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 35%))',
-    category: 'color',
-    description: 'Primary color scale +1'
+    "name": "color-border",
+    "cssVar": "--op-color-border",
+    "value": "var(--op-color-neutral-plus-five)",
+    "category": "color",
+    "description": "color token: color-border"
   },
   {
-    name: 'op-color-primary-base',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 40%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 38%))',
-    category: 'color',
-    description: 'Primary color base'
+    "name": "color-background",
+    "cssVar": "--op-color-background",
+    "value": "var(--op-color-neutral-plus-eight)",
+    "category": "color",
+    "description": "color token: color-background"
   },
   {
-    name: 'op-color-primary-minus-one',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 36%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 40%))',
-    category: 'color',
-    description: 'Primary color scale -1'
+    "name": "color-on-background",
+    "cssVar": "--op-color-on-background",
+    "value": "var(--op-color-neutral-on-plus-eight)",
+    "category": "color",
+    "description": "Text color for use ON background background. MUST be paired with matching background color."
   },
   {
-    name: 'op-color-primary-minus-two',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 32%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 45%))',
-    category: 'color',
-    description: 'Primary color scale -2'
+    "name": "opacity-none",
+    "cssVar": "--op-opacity-none",
+    "value": "0",
+    "category": "opacity",
+    "description": "opacity token: opacity-none"
   },
   {
-    name: 'op-color-primary-minus-three',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 28%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 48%))',
-    category: 'color',
-    description: 'Primary color scale -3'
+    "name": "opacity-overlay",
+    "cssVar": "--op-opacity-overlay",
+    "value": "0.2",
+    "category": "opacity",
+    "description": "opacity token: opacity-overlay"
   },
   {
-    name: 'op-color-primary-minus-four',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 24%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 52%))',
-    category: 'color',
-    description: 'Primary color scale -4'
+    "name": "opacity-disabled",
+    "cssVar": "--op-opacity-disabled",
+    "value": "0.4",
+    "category": "opacity",
+    "description": "opacity token: opacity-disabled"
   },
   {
-    name: 'op-color-primary-minus-five',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 20%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 64%))',
-    category: 'color',
-    description: 'Primary color scale -5'
+    "name": "opacity-half",
+    "cssVar": "--op-opacity-half",
+    "value": "0.5",
+    "category": "opacity",
+    "description": "opacity token: opacity-half"
   },
   {
-    name: 'op-color-primary-minus-six',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 16%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 72%))',
-    category: 'color',
-    description: 'Primary color scale -6'
+    "name": "opacity-full",
+    "cssVar": "--op-opacity-full",
+    "value": "1",
+    "category": "opacity",
+    "description": "opacity token: opacity-full"
   },
   {
-    name: 'op-color-primary-minus-seven',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 8%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 80%))',
-    category: 'color',
-    description: 'Primary color scale -7'
+    "name": "breakpoint-x-small",
+    "cssVar": "--op-breakpoint-x-small",
+    "value": "512px",
+    "category": "breakpoint",
+    "description": "breakpoint token: breakpoint-x-small"
   },
   {
-    name: 'op-color-primary-minus-eight',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 4%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 88%))',
-    category: 'color',
-    description: 'Primary color scale -8'
+    "name": "breakpoint-small",
+    "cssVar": "--op-breakpoint-small",
+    "value": "768px",
+    "category": "breakpoint",
+    "description": "breakpoint token: breakpoint-small"
   },
   {
-    name: 'op-color-primary-minus-max',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 0%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 100%))',
-    category: 'color',
-    description: 'Primary color darkest - light mode: 0%, dark mode: 100%'
+    "name": "breakpoint-medium",
+    "cssVar": "--op-breakpoint-medium",
+    "value": "1024px",
+    "category": "breakpoint",
+    "description": "breakpoint token: breakpoint-medium"
   },
-
-  // Primary Color Scale - "On" Scale (for text/content colors that appear on the main scale colors)
-  // Note: Each has a base and "-alt" variant. Same pattern applies to neutral, alerts-warning, alerts-danger, alerts-info, alerts-notice
   {
-    name: 'op-color-primary-on-plus-max',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 0%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 100%))',
-    category: 'color',
-    description: 'Text color for primary-plus-max backgrounds'
+    "name": "breakpoint-large",
+    "cssVar": "--op-breakpoint-large",
+    "value": "1280px",
+    "category": "breakpoint",
+    "description": "breakpoint token: breakpoint-large"
   },
   {
-    name: 'op-color-primary-on-plus-max-alt',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 20%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 78%))',
-    category: 'color',
-    description: 'Alt text color for primary-plus-max backgrounds'
+    "name": "breakpoint-x-large",
+    "cssVar": "--op-breakpoint-x-large",
+    "value": "1440px",
+    "category": "breakpoint",
+    "description": "breakpoint token: breakpoint-x-large"
   },
   {
-    name: 'op-color-primary-on-plus-eight',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 4%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 88%))',
-    category: 'color',
-    description: 'Text color for primary-plus-eight backgrounds'
+    "name": "radius-small",
+    "cssVar": "--op-radius-small",
+    "value": "2px",
+    "category": "border",
+    "description": "border token: radius-small"
   },
   {
-    name: 'op-color-primary-on-plus-eight-alt',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 24%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 70%))',
-    category: 'color',
-    description: 'Alt text color for primary-plus-eight backgrounds'
+    "name": "radius-medium",
+    "cssVar": "--op-radius-medium",
+    "value": "4px",
+    "category": "border",
+    "description": "border token: radius-medium"
   },
   {
-    name: 'op-color-primary-on-plus-seven',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 8%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 80%))',
-    category: 'color',
-    description: 'Text color for primary-plus-seven backgrounds'
+    "name": "radius-large",
+    "cssVar": "--op-radius-large",
+    "value": "8px",
+    "category": "border",
+    "description": "border token: radius-large"
   },
   {
-    name: 'op-color-primary-on-plus-seven-alt',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 28%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 64%))',
-    category: 'color',
-    description: 'Alt text color for primary-plus-seven backgrounds'
+    "name": "radius-x-large",
+    "cssVar": "--op-radius-x-large",
+    "value": "12px",
+    "category": "border",
+    "description": "border token: radius-x-large"
   },
   {
-    name: 'op-color-primary-on-plus-six',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 16%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 72%))',
-    category: 'color',
-    description: 'Text color for primary-plus-six backgrounds'
+    "name": "radius-2x-large",
+    "cssVar": "--op-radius-2x-large",
+    "value": "16px",
+    "category": "border",
+    "description": "border token: radius-2x-large"
   },
   {
-    name: 'op-color-primary-on-plus-six-alt',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 26%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 96%))',
-    category: 'color',
-    description: 'Alt text color for primary-plus-six backgrounds'
+    "name": "radius-circle",
+    "cssVar": "--op-radius-circle",
+    "value": "50%",
+    "category": "border",
+    "description": "border token: radius-circle"
   },
   {
-    name: 'op-color-primary-on-plus-five',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 20%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 72%))',
-    category: 'color',
-    description: 'Text color for primary-plus-five backgrounds'
+    "name": "radius-pill",
+    "cssVar": "--op-radius-pill",
+    "value": "9999px",
+    "category": "border",
+    "description": "border token: radius-pill"
   },
   {
-    name: 'op-color-primary-on-plus-five-alt',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 40%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 86%))',
-    category: 'color',
-    description: 'Alt text color for primary-plus-five backgrounds'
+    "name": "border-width",
+    "cssVar": "--op-border-width",
+    "value": "1px",
+    "category": "border",
+    "description": "border token: border-width"
   },
   {
-    name: 'op-color-primary-on-plus-four',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 24%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 80%))',
-    category: 'color',
-    description: 'Text color for primary-plus-four backgrounds'
+    "name": "border-width-large",
+    "cssVar": "--op-border-width-large",
+    "value": "2px",
+    "category": "border",
+    "description": "border token: border-width-large"
   },
   {
-    name: 'op-color-primary-on-plus-four-alt',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 4%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 92%))',
-    category: 'color',
-    description: 'Alt text color for primary-plus-four backgrounds'
+    "name": "border-width-x-large",
+    "cssVar": "--op-border-width-x-large",
+    "value": "4px",
+    "category": "border",
+    "description": "border token: border-width-x-large"
   },
   {
-    name: 'op-color-primary-on-plus-three',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 20%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 78%))',
-    category: 'color',
-    description: 'Text color for primary-plus-three backgrounds'
+    "name": "border-none",
+    "cssVar": "--op-border-none",
+    "value": "0 0 0 0",
+    "category": "border",
+    "description": "border token: border-none"
   },
   {
-    name: 'op-color-primary-on-plus-three-alt',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 10%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 98%))',
-    category: 'color',
-    description: 'Alt text color for primary-plus-three backgrounds'
+    "name": "border-all",
+    "cssVar": "--op-border-all",
+    "value": "0 0 0 var(--op-border-width)",
+    "category": "border",
+    "description": "border token: border-all"
   },
   {
-    name: 'op-color-primary-on-plus-two',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 16%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 80%))',
-    category: 'color',
-    description: 'Text color for primary-plus-two backgrounds'
+    "name": "border-top",
+    "cssVar": "--op-border-top",
+    "value": "0 calc(-1 * var(--op-border-width)) 0 0",
+    "category": "border",
+    "description": "border token: border-top"
   },
   {
-    name: 'op-color-primary-on-plus-two-alt',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 6%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 92%))',
-    category: 'color',
-    description: 'Alt text color for primary-plus-two backgrounds'
+    "name": "border-right",
+    "cssVar": "--op-border-right",
+    "value": "var(--op-border-width) 0 0 0",
+    "category": "border",
+    "description": "border token: border-right"
   },
   {
-    name: 'op-color-primary-on-plus-one',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 100%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 80%))',
-    category: 'color',
-    description: 'Text color for primary-plus-one backgrounds'
+    "name": "border-bottom",
+    "cssVar": "--op-border-bottom",
+    "value": "0 var(--op-border-width) 0 0",
+    "category": "border",
+    "description": "border token: border-bottom"
   },
   {
-    name: 'op-color-primary-on-plus-one-alt',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 95%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 98%))',
-    category: 'color',
-    description: 'Alt text color for primary-plus-one backgrounds'
+    "name": "border-left",
+    "cssVar": "--op-border-left",
+    "value": "calc(-1 * var(--op-border-width)) 0 0 0",
+    "category": "border",
+    "description": "border token: border-left"
   },
   {
-    name: 'op-color-primary-on-base',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 100%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 100%))',
-    category: 'color',
-    description: 'Text color for primary-base backgrounds'
+    "name": "border-y",
+    "cssVar": "--op-border-y",
+    "value": "var(--op-border-top) var(--op-color-border), var(--op-border-bottom) var(--op-color-border)",
+    "category": "border",
+    "description": "border token: border-y"
   },
   {
-    name: 'op-color-primary-on-base-alt',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 88%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 84%))',
-    category: 'color',
-    description: 'Alt text color for primary-base backgrounds'
+    "name": "border-x",
+    "cssVar": "--op-border-x",
+    "value": "var(--op-border-left) var(--op-color-border), var(--op-border-right) var(--op-color-border)",
+    "category": "border",
+    "description": "border token: border-x"
   },
   {
-    name: 'op-color-primary-on-minus-one',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 94%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 98%))',
-    category: 'color',
-    description: 'Text color for primary-minus-one backgrounds'
+    "name": "font-scale-unit",
+    "cssVar": "--op-font-scale-unit",
+    "value": "1rem",
+    "category": "typography",
+    "description": "typography token: font-scale-unit"
   },
   {
-    name: 'op-color-primary-on-minus-one-alt',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 82%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 90%))',
-    category: 'color',
-    description: 'Alt text color for primary-minus-one backgrounds'
+    "name": "font-2x-small",
+    "cssVar": "--op-font-2x-small",
+    "value": "calc(var(--op-font-scale-unit) * 1)",
+    "category": "typography",
+    "description": "typography token: font-2x-small"
   },
   {
-    name: 'op-color-primary-on-minus-two',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 90%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 98%))',
-    category: 'color',
-    description: 'Text color for primary-minus-two backgrounds'
+    "name": "font-x-small",
+    "cssVar": "--op-font-x-small",
+    "value": "calc(var(--op-font-scale-unit) * 1.2)",
+    "category": "typography",
+    "description": "typography token: font-x-small"
   },
   {
-    name: 'op-color-primary-on-minus-two-alt',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 78%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 92%))',
-    category: 'color',
-    description: 'Alt text color for primary-minus-two backgrounds'
+    "name": "font-small",
+    "cssVar": "--op-font-small",
+    "value": "calc(var(--op-font-scale-unit) * 1.4)",
+    "category": "typography",
+    "description": "typography token: font-small"
   },
   {
-    name: 'op-color-primary-on-minus-three',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 86%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 98%))',
-    category: 'color',
-    description: 'Text color for primary-minus-three backgrounds'
+    "name": "font-medium",
+    "cssVar": "--op-font-medium",
+    "value": "calc(var(--op-font-scale-unit) * 1.6)",
+    "category": "typography",
+    "description": "typography token: font-medium"
   },
   {
-    name: 'op-color-primary-on-minus-three-alt',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 74%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 96%))',
-    category: 'color',
-    description: 'Alt text color for primary-minus-three backgrounds'
+    "name": "font-large",
+    "cssVar": "--op-font-large",
+    "value": "calc(var(--op-font-scale-unit) * 1.8)",
+    "category": "typography",
+    "description": "typography token: font-large"
   },
   {
-    name: 'op-color-primary-on-minus-four',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 84%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 2%))',
-    category: 'color',
-    description: 'Text color for primary-minus-four backgrounds'
+    "name": "font-x-large",
+    "cssVar": "--op-font-x-large",
+    "value": "calc(var(--op-font-scale-unit) * 2)",
+    "category": "typography",
+    "description": "typography token: font-x-large"
   },
   {
-    name: 'op-color-primary-on-minus-four-alt',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 72%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 2%))',
-    category: 'color',
-    description: 'Alt text color for primary-minus-four backgrounds'
+    "name": "font-2x-large",
+    "cssVar": "--op-font-2x-large",
+    "value": "calc(var(--op-font-scale-unit) * 2.4)",
+    "category": "typography",
+    "description": "typography token: font-2x-large"
   },
   {
-    name: 'op-color-primary-on-minus-five',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 88%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 2%))',
-    category: 'color',
-    description: 'Text color for primary-minus-five backgrounds'
+    "name": "font-3x-large",
+    "cssVar": "--op-font-3x-large",
+    "value": "calc(var(--op-font-scale-unit) * 2.8)",
+    "category": "typography",
+    "description": "typography token: font-3x-large"
   },
   {
-    name: 'op-color-primary-on-minus-five-alt',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 78%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 20%))',
-    category: 'color',
-    description: 'Alt text color for primary-minus-five backgrounds'
+    "name": "font-4x-large",
+    "cssVar": "--op-font-4x-large",
+    "value": "calc(var(--op-font-scale-unit) * 3.2)",
+    "category": "typography",
+    "description": "typography token: font-4x-large"
   },
   {
-    name: 'op-color-primary-on-minus-six',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 94%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 8%))',
-    category: 'color',
-    description: 'Text color for primary-minus-six backgrounds'
+    "name": "font-5x-large",
+    "cssVar": "--op-font-5x-large",
+    "value": "calc(var(--op-font-scale-unit) * 3.6)",
+    "category": "typography",
+    "description": "typography token: font-5x-large"
   },
   {
-    name: 'op-color-primary-on-minus-six-alt',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 82%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 26%))',
-    category: 'color',
-    description: 'Alt text color for primary-minus-six backgrounds'
+    "name": "font-6x-large",
+    "cssVar": "--op-font-6x-large",
+    "value": "calc(var(--op-font-scale-unit) * 4.8)",
+    "category": "typography",
+    "description": "typography token: font-6x-large"
   },
   {
-    name: 'op-color-primary-on-minus-seven',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 96%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 8%))',
-    category: 'color',
-    description: 'Text color for primary-minus-seven backgrounds'
+    "name": "font-weight-thin",
+    "cssVar": "--op-font-weight-thin",
+    "value": "100",
+    "category": "typography",
+    "description": "typography token: font-weight-thin"
   },
   {
-    name: 'op-color-primary-on-minus-seven-alt',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 84%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 34%))',
-    category: 'color',
-    description: 'Alt text color for primary-minus-seven backgrounds'
+    "name": "font-weight-extra-light",
+    "cssVar": "--op-font-weight-extra-light",
+    "value": "200",
+    "category": "typography",
+    "description": "typography token: font-weight-extra-light"
   },
   {
-    name: 'op-color-primary-on-minus-eight',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 98%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 4%))',
-    category: 'color',
-    description: 'Text color for primary-minus-eight backgrounds'
+    "name": "font-weight-light",
+    "cssVar": "--op-font-weight-light",
+    "value": "300",
+    "category": "typography",
+    "description": "typography token: font-weight-light"
   },
   {
-    name: 'op-color-primary-on-minus-eight-alt',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 86%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 38%))',
-    category: 'color',
-    description: 'Alt text color for primary-minus-eight backgrounds'
+    "name": "font-weight-normal",
+    "cssVar": "--op-font-weight-normal",
+    "value": "400",
+    "category": "typography",
+    "description": "typography token: font-weight-normal"
   },
   {
-    name: 'op-color-primary-on-minus-max',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 100%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 0%))',
-    category: 'color',
-    description: 'Text color for primary-minus-max backgrounds'
+    "name": "font-weight-medium",
+    "cssVar": "--op-font-weight-medium",
+    "value": "500",
+    "category": "typography",
+    "description": "typography token: font-weight-medium"
   },
   {
-    name: 'op-color-primary-on-minus-max-alt',
-    value: 'light-dark(hsl(var(--op-color-primary-h) var(--op-color-primary-s) 88%), hsl(var(--op-color-primary-h) var(--op-color-primary-s) 38%))',
-    category: 'color',
-    description: 'Alt text color for primary-minus-max backgrounds'
+    "name": "font-weight-semi-bold",
+    "cssVar": "--op-font-weight-semi-bold",
+    "value": "600",
+    "category": "typography",
+    "description": "typography token: font-weight-semi-bold"
   },
-
-  // Core semantic colors (most commonly used)
   {
-    name: 'op-color-white',
-    value: 'hsl(0deg 100% 100%)',
-    category: 'color',
-    description: 'Pure white'
+    "name": "font-weight-bold",
+    "cssVar": "--op-font-weight-bold",
+    "value": "700",
+    "category": "typography",
+    "description": "typography token: font-weight-bold"
   },
   {
-    name: 'op-color-black',
-    value: 'hsl(0deg 0% 0%)',
-    category: 'color',
-    description: 'Pure black'
+    "name": "font-weight-extra-bold",
+    "cssVar": "--op-font-weight-extra-bold",
+    "value": "800",
+    "category": "typography",
+    "description": "typography token: font-weight-extra-bold"
   },
-
-  // Spacing Tokens
   {
-    name: 'op-space-scale-unit',
-    value: '1rem',
-    category: 'spacing',
-    description: 'Base unit for spacing scale (10px)'
+    "name": "font-weight-black",
+    "cssVar": "--op-font-weight-black",
+    "value": "900",
+    "category": "typography",
+    "description": "typography token: font-weight-black"
   },
   {
-    name: 'op-space-3x-small',
-    value: 'calc(var(--op-space-scale-unit) * 0.2)',
-    category: 'spacing',
-    description: '2px spacing'
+    "name": "font-family",
+    "cssVar": "--op-font-family",
+    "value": "'Noto Sans', sans-serif",
+    "category": "typography",
+    "description": "typography token: font-family"
   },
   {
-    name: 'op-space-2x-small',
-    value: 'calc(var(--op-space-scale-unit) * 0.4)',
-    category: 'spacing',
-    description: '4px spacing'
+    "name": "line-height-none",
+    "cssVar": "--op-line-height-none",
+    "value": "0",
+    "category": "sizing",
+    "description": "sizing token: line-height-none"
   },
   {
-    name: 'op-space-x-small',
-    value: 'calc(var(--op-space-scale-unit) * 0.8)',
-    category: 'spacing',
-    description: '8px spacing'
+    "name": "line-height-densest",
+    "cssVar": "--op-line-height-densest",
+    "value": "1",
+    "category": "sizing",
+    "description": "sizing token: line-height-densest"
   },
   {
-    name: 'op-space-small',
-    value: 'calc(var(--op-space-scale-unit) * 1.2)',
-    category: 'spacing',
-    description: '12px spacing'
+    "name": "line-height-denser",
+    "cssVar": "--op-line-height-denser",
+    "value": "1.15",
+    "category": "sizing",
+    "description": "sizing token: line-height-denser"
   },
   {
-    name: 'op-space-medium',
-    value: 'calc(var(--op-space-scale-unit) * 1.6)',
-    category: 'spacing',
-    description: '16px spacing'
+    "name": "line-height-dense",
+    "cssVar": "--op-line-height-dense",
+    "value": "1.3",
+    "category": "sizing",
+    "description": "sizing token: line-height-dense"
   },
   {
-    name: 'op-space-large',
-    value: 'calc(var(--op-space-scale-unit) * 2)',
-    category: 'spacing',
-    description: '20px spacing'
+    "name": "line-height-base",
+    "cssVar": "--op-line-height-base",
+    "value": "1.5",
+    "category": "sizing",
+    "description": "sizing token: line-height-base"
   },
   {
-    name: 'op-space-x-large',
-    value: 'calc(var(--op-space-scale-unit) * 2.4)',
-    category: 'spacing',
-    description: '24px spacing'
+    "name": "line-height-loose",
+    "cssVar": "--op-line-height-loose",
+    "value": "1.6",
+    "category": "sizing",
+    "description": "sizing token: line-height-loose"
   },
   {
-    name: 'op-space-2x-large',
-    value: 'calc(var(--op-space-scale-unit) * 2.8)',
-    category: 'spacing',
-    description: '28px spacing'
+    "name": "line-height-looser",
+    "cssVar": "--op-line-height-looser",
+    "value": "1.7",
+    "category": "sizing",
+    "description": "sizing token: line-height-looser"
   },
   {
-    name: 'op-space-3x-large',
-    value: 'calc(var(--op-space-scale-unit) * 4)',
-    category: 'spacing',
-    description: '40px spacing'
+    "name": "line-height-loosest",
+    "cssVar": "--op-line-height-loosest",
+    "value": "1.8",
+    "category": "sizing",
+    "description": "sizing token: line-height-loosest"
   },
   {
-    name: 'op-space-4x-large',
-    value: 'calc(var(--op-space-scale-unit) * 8)',
-    category: 'spacing',
-    description: '80px spacing'
+    "name": "letter-spacing-navigation",
+    "cssVar": "--op-letter-spacing-navigation",
+    "value": "0.01rem",
+    "category": "typography",
+    "description": "typography token: letter-spacing-navigation"
   },
-
-  // Typography Tokens - Font Family
   {
-    name: 'op-font-family',
-    value: "'Noto Sans', 'Noto Serif', sans-serif",
-    category: 'typography',
-    description: 'Font family for all text'
-  },
-
-  // Font Sizes
-  {
-    name: 'op-font-scale-unit',
-    value: '1rem',
-    category: 'typography',
-    description: 'Base unit for font scale (10px)'
-  },
-  {
-    name: 'op-font-2x-small',
-    value: 'calc(var(--op-font-scale-unit) * 1)',
-    category: 'typography',
-    description: '10px font size'
+    "name": "letter-spacing-label",
+    "cssVar": "--op-letter-spacing-label",
+    "value": "0.04rem",
+    "category": "typography",
+    "description": "typography token: letter-spacing-label"
   },
   {
-    name: 'op-font-x-small',
-    value: 'calc(var(--op-font-scale-unit) * 1.2)',
-    category: 'typography',
-    description: '12px font size'
+    "name": "transition-accordion",
+    "cssVar": "--op-transition-accordion",
+    "value": "rotate 120ms ease-in",
+    "category": "animation",
+    "description": "animation token: transition-accordion"
   },
   {
-    name: 'op-font-small',
-    value: 'calc(var(--op-font-scale-unit) * 1.4)',
-    category: 'typography',
-    description: '14px font size'
+    "name": "transition-input",
+    "cssVar": "--op-transition-input",
+    "value": "all 120ms ease-in",
+    "category": "animation",
+    "description": "animation token: transition-input"
   },
   {
-    name: 'op-font-medium',
-    value: 'calc(var(--op-font-scale-unit) * 1.6)',
-    category: 'typography',
-    description: '16px font size'
+    "name": "transition-sidebar",
+    "cssVar": "--op-transition-sidebar",
+    "value": "all 200ms ease-in-out",
+    "category": "animation",
+    "description": "animation token: transition-sidebar"
   },
   {
-    name: 'op-font-large',
-    value: 'calc(var(--op-font-scale-unit) * 1.8)',
-    category: 'typography',
-    description: '18px font size'
+    "name": "transition-modal",
+    "cssVar": "--op-transition-modal",
+    "value": "all var(--op-transition-modal-time) ease-in",
+    "category": "animation",
+    "description": "animation token: transition-modal"
   },
   {
-    name: 'op-font-x-large',
-    value: 'calc(var(--op-font-scale-unit) * 2)',
-    category: 'typography',
-    description: '20px font size'
+    "name": "transition-panel",
+    "cssVar": "--op-transition-panel",
+    "value": "right 400ms ease-in",
+    "category": "animation",
+    "description": "animation token: transition-panel"
   },
   {
-    name: 'op-font-2x-large',
-    value: 'calc(var(--op-font-scale-unit) * 2.4)',
-    category: 'typography',
-    description: '24px font size'
+    "name": "transition-tooltip",
+    "cssVar": "--op-transition-tooltip",
+    "value": "all 300ms ease-in 300ms",
+    "category": "animation",
+    "description": "animation token: transition-tooltip"
   },
   {
-    name: 'op-font-3x-large',
-    value: 'calc(var(--op-font-scale-unit) * 2.8)',
-    category: 'typography',
-    description: '28px font size'
+    "name": "animation-flash",
+    "cssVar": "--op-animation-flash",
+    "value": "rm-slide-in-out-flash 5s normal forwards",
+    "category": "animation",
+    "description": "animation token: animation-flash"
   },
   {
-    name: 'op-font-4x-large',
-    value: 'calc(var(--op-font-scale-unit) * 3.2)',
-    category: 'typography',
-    description: '32px font size'
+    "name": "encoded-images-dropdown-arrow",
+    "cssVar": "--op-encoded-images-dropdown-arrow",
+    "value": "url('data",
+    "category": "encoded-image",
+    "description": "encoded-image token: encoded-images-dropdown-arrow"
   },
   {
-    name: 'op-font-5x-large',
-    value: 'calc(var(--op-font-scale-unit) * 3.6)',
-    category: 'typography',
-    description: '36px font size'
+    "name": "size-unit",
+    "cssVar": "--op-size-unit",
+    "value": "0.4rem",
+    "category": "sizing",
+    "description": "sizing token: size-unit"
   },
   {
-    name: 'op-font-6x-large',
-    value: 'calc(var(--op-font-scale-unit) * 4.8)',
-    category: 'typography',
-    description: '48px font size'
+    "name": "space-scale-unit",
+    "cssVar": "--op-space-scale-unit",
+    "value": "1rem",
+    "category": "spacing",
+    "description": "spacing token: space-scale-unit"
   },
-
-  // Font Weights
   {
-    name: 'op-font-weight-thin',
-    value: '100',
-    category: 'typography',
-    description: 'Thin font weight'
+    "name": "space-3x-small",
+    "cssVar": "--op-space-3x-small",
+    "value": "calc(var(--op-space-scale-unit) * 0.2)",
+    "category": "spacing",
+    "description": "spacing token: space-3x-small"
   },
   {
-    name: 'op-font-weight-extra-light',
-    value: '200',
-    category: 'typography',
-    description: 'Extra light font weight'
+    "name": "space-2x-small",
+    "cssVar": "--op-space-2x-small",
+    "value": "calc(var(--op-space-scale-unit) * 0.4)",
+    "category": "spacing",
+    "description": "spacing token: space-2x-small"
   },
   {
-    name: 'op-font-weight-light',
-    value: '300',
-    category: 'typography',
-    description: 'Light font weight'
+    "name": "space-x-small",
+    "cssVar": "--op-space-x-small",
+    "value": "calc(var(--op-space-scale-unit) * 0.8)",
+    "category": "spacing",
+    "description": "spacing token: space-x-small"
   },
   {
-    name: 'op-font-weight-normal',
-    value: '400',
-    category: 'typography',
-    description: 'Normal font weight'
+    "name": "space-small",
+    "cssVar": "--op-space-small",
+    "value": "calc(var(--op-space-scale-unit) * 1.2)",
+    "category": "spacing",
+    "description": "spacing token: space-small"
   },
   {
-    name: 'op-font-weight-medium',
-    value: '500',
-    category: 'typography',
-    description: 'Medium font weight'
+    "name": "space-medium",
+    "cssVar": "--op-space-medium",
+    "value": "calc(var(--op-space-scale-unit) * 1.6)",
+    "category": "spacing",
+    "description": "spacing token: space-medium"
   },
   {
-    name: 'op-font-weight-semi-bold',
-    value: '600',
-    category: 'typography',
-    description: 'Semi-bold font weight'
+    "name": "space-large",
+    "cssVar": "--op-space-large",
+    "value": "calc(var(--op-space-scale-unit) * 2)",
+    "category": "spacing",
+    "description": "spacing token: space-large"
   },
   {
-    name: 'op-font-weight-bold',
-    value: '700',
-    category: 'typography',
-    description: 'Bold font weight'
+    "name": "space-x-large",
+    "cssVar": "--op-space-x-large",
+    "value": "calc(var(--op-space-scale-unit) * 2.4)",
+    "category": "spacing",
+    "description": "spacing token: space-x-large"
   },
   {
-    name: 'op-font-weight-extra-bold',
-    value: '800',
-    category: 'typography',
-    description: 'Extra bold font weight'
+    "name": "space-2x-large",
+    "cssVar": "--op-space-2x-large",
+    "value": "calc(var(--op-space-scale-unit) * 2.8)",
+    "category": "spacing",
+    "description": "spacing token: space-2x-large"
   },
   {
-    name: 'op-font-weight-black',
-    value: '900',
-    category: 'typography',
-    description: 'Black font weight'
+    "name": "space-3x-large",
+    "cssVar": "--op-space-3x-large",
+    "value": "calc(var(--op-space-scale-unit) * 4)",
+    "category": "spacing",
+    "description": "spacing token: space-3x-large"
   },
-
-  // Line Heights
   {
-    name: 'op-line-height-none',
-    value: '0',
-    category: 'typography',
-    description: 'No line height'
+    "name": "space-4x-large",
+    "cssVar": "--op-space-4x-large",
+    "value": "calc(var(--op-space-scale-unit) * 8)",
+    "category": "spacing",
+    "description": "spacing token: space-4x-large"
   },
   {
-    name: 'op-line-height-densest',
-    value: '1',
-    category: 'typography',
-    description: 'Densest line height'
+    "name": "shadow-x-small",
+    "cssVar": "--op-shadow-x-small",
+    "value": "0 1px 3px hsl(0deg 0% 0% / 15%), 0 1px 2px hsl(0deg 0% 0% / 30%)",
+    "category": "shadow",
+    "description": "shadow token: shadow-x-small"
   },
   {
-    name: 'op-line-height-denser',
-    value: '1.15',
-    category: 'typography',
-    description: 'Denser line height'
+    "name": "shadow-small",
+    "cssVar": "--op-shadow-small",
+    "value": "0 2px 6px hsl(0deg 0% 0% / 15%), 0 1px 2px hsl(0deg 0% 0% / 30%)",
+    "category": "shadow",
+    "description": "shadow token: shadow-small"
   },
   {
-    name: 'op-line-height-dense',
-    value: '1.3',
-    category: 'typography',
-    description: 'Dense line height'
+    "name": "shadow-medium",
+    "cssVar": "--op-shadow-medium",
+    "value": "0 4px 8px hsl(0deg 0% 0% / 15%), 0 1px 3px hsl(0deg 0% 0% / 30%)",
+    "category": "shadow",
+    "description": "shadow token: shadow-medium"
   },
   {
-    name: 'op-line-height-base',
-    value: '1.5',
-    category: 'typography',
-    description: 'Base line height'
+    "name": "shadow-large",
+    "cssVar": "--op-shadow-large",
+    "value": "0 6px 10px hsl(0deg 0% 0% / 15%), 0 2px 3px hsl(0deg 0% 0% / 30%)",
+    "category": "shadow",
+    "description": "shadow token: shadow-large"
   },
   {
-    name: 'op-line-height-loose',
-    value: '1.6',
-    category: 'typography',
-    description: 'Loose line height'
+    "name": "shadow-x-large",
+    "cssVar": "--op-shadow-x-large",
+    "value": "0 8px 12px hsl(0deg 0% 0% / 15%), 0 4px 4px hsl(0deg 0% 0% / 30%)",
+    "category": "shadow",
+    "description": "shadow token: shadow-x-large"
   },
   {
-    name: 'op-line-height-looser',
-    value: '1.7',
-    category: 'typography',
-    description: 'Looser line height'
+    "name": "z-index-header",
+    "cssVar": "--op-z-index-header",
+    "value": "500",
+    "category": "z-index",
+    "description": "z-index token: z-index-header"
   },
   {
-    name: 'op-line-height-loosest',
-    value: '1.8',
-    category: 'typography',
-    description: 'Loosest line height'
+    "name": "z-index-footer",
+    "cssVar": "--op-z-index-footer",
+    "value": "500",
+    "category": "z-index",
+    "description": "z-index token: z-index-footer"
   },
-
-  // Letter Spacing
   {
-    name: 'op-letter-spacing-navigation',
-    value: '0.01rem',
-    category: 'typography',
-    description: 'Letter spacing for navigation'
+    "name": "z-index-sidebar",
+    "cssVar": "--op-z-index-sidebar",
+    "value": "700",
+    "category": "z-index",
+    "description": "z-index token: z-index-sidebar"
   },
   {
-    name: 'op-letter-spacing-label',
-    value: '0.04rem',
-    category: 'typography',
-    description: 'Letter spacing for labels'
+    "name": "z-index-dialog",
+    "cssVar": "--op-z-index-dialog",
+    "value": "800",
+    "category": "z-index",
+    "description": "z-index token: z-index-dialog"
   },
-
-  // Border Radius Tokens
   {
-    name: 'op-radius-small',
-    value: '2px',
-    category: 'border',
-    description: 'Small border radius'
+    "name": "z-index-dialog-backdrop",
+    "cssVar": "--op-z-index-dialog-backdrop",
+    "value": "801",
+    "category": "z-index",
+    "description": "z-index token: z-index-dialog-backdrop"
   },
   {
-    name: 'op-radius-medium',
-    value: '4px',
-    category: 'border',
-    description: 'Medium border radius'
+    "name": "z-index-dialog-content",
+    "cssVar": "--op-z-index-dialog-content",
+    "value": "802",
+    "category": "z-index",
+    "description": "z-index token: z-index-dialog-content"
   },
   {
-    name: 'op-radius-large',
-    value: '8px',
-    category: 'border',
-    description: 'Large border radius'
+    "name": "z-index-dropdown",
+    "cssVar": "--op-z-index-dropdown",
+    "value": "900",
+    "category": "z-index",
+    "description": "z-index token: z-index-dropdown"
   },
   {
-    name: 'op-radius-x-large',
-    value: '12px',
-    category: 'border',
-    description: 'Extra large border radius'
+    "name": "z-index-alert-group",
+    "cssVar": "--op-z-index-alert-group",
+    "value": "950",
+    "category": "z-index",
+    "description": "z-index token: z-index-alert-group"
   },
   {
-    name: 'op-radius-2x-large',
-    value: '16px',
-    category: 'border',
-    description: '2X large border radius'
+    "name": "z-index-tooltip",
+    "cssVar": "--op-z-index-tooltip",
+    "value": "1000",
+    "category": "z-index",
+    "description": "z-index token: z-index-tooltip"
   },
   {
-    name: 'op-radius-circle',
-    value: '50%',
-    category: 'border',
-    description: 'Circular border radius'
+    "name": "input-height-small",
+    "cssVar": "--op-input-height-small",
+    "value": "2.8rem",
+    "category": "input",
+    "description": "input token: input-height-small"
   },
   {
-    name: 'op-radius-pill',
-    value: '9999px',
-    category: 'border',
-    description: 'Pill-shaped border radius'
-  },
-
-  // Border Width Tokens
-  {
-    name: 'op-border-width',
-    value: '1px',
-    category: 'border',
-    description: 'Standard border width'
-  },
-  {
-    name: 'op-border-width-large',
-    value: '2px',
-    category: 'border',
-    description: 'Large border width'
-  },
-  {
-    name: 'op-border-width-x-large',
-    value: '4px',
-    category: 'border',
-    description: 'Extra large border width'
-  },
-
-  // Shadow Tokens
-  {
-    name: 'op-shadow-x-small',
-    value: '0 1px 2px hsl(0deg 0% 0% / 3%), 0 1px 3px hsl(0deg 0% 0% / 15%)',
-    category: 'shadow',
-    description: 'Extra small shadow'
-  },
-  {
-    name: 'op-shadow-small',
-    value: '0 1px 2px hsl(0deg 0% 0% / 3%), 0 2px 6px hsl(0deg 0% 0% / 15%)',
-    category: 'shadow',
-    description: 'Small shadow'
-  },
-  {
-    name: 'op-shadow-medium',
-    value: '0 4px 8px hsl(0deg 0% 0% / 15%), 0 1px 3px hsl(0deg 0% 0% / 3%)',
-    category: 'shadow',
-    description: 'Medium shadow'
-  },
-  {
-    name: 'op-shadow-large',
-    value: '0 6px 10px hsl(0deg 0% 0% / 15%), 0 2px 3px hsl(0deg 0% 0% / 3%)',
-    category: 'shadow',
-    description: 'Large shadow'
-  },
-  {
-    name: 'op-shadow-x-large',
-    value: '0 8px 12px hsl(0deg 0% 0% / 15%), 0 4px 4px hsl(0deg 0% 0% / 3%)',
-    category: 'shadow',
-    description: 'Extra large shadow'
-  },
-
-  // Opacity Tokens
-  {
-    name: 'op-opacity-none',
-    value: '0',
-    category: 'color',
-    description: 'No opacity'
+    "name": "input-height-medium",
+    "cssVar": "--op-input-height-medium",
+    "value": "3.6rem",
+    "category": "input",
+    "description": "input token: input-height-medium"
   },
   {
-    name: 'op-opacity-overlay',
-    value: '0.2',
-    category: 'color',
-    description: 'Overlay opacity'
+    "name": "input-height-large",
+    "cssVar": "--op-input-height-large",
+    "value": "4rem",
+    "category": "input",
+    "description": "input token: input-height-large"
   },
   {
-    name: 'op-opacity-disabled',
-    value: '0.4',
-    category: 'color',
-    description: 'Disabled opacity'
+    "name": "input-height-x-large",
+    "cssVar": "--op-input-height-x-large",
+    "value": "8.4rem",
+    "category": "input",
+    "description": "input token: input-height-x-large"
   },
   {
-    name: 'op-opacity-half',
-    value: '0.5',
-    category: 'color',
-    description: 'Half opacity'
+    "name": "input-inner-focus",
+    "cssVar": "--op-input-inner-focus",
+    "value": "inset 0 0 0 var(--op-border-width-large)",
+    "category": "input",
+    "description": "input token: input-inner-focus"
   },
   {
-    name: 'op-opacity-full',
-    value: '1',
-    category: 'color',
-    description: 'Full opacity'
+    "name": "input-outer-focus",
+    "cssVar": "--op-input-outer-focus",
+    "value": "0 0 0 var(--op-border-width-x-large)",
+    "category": "input",
+    "description": "input token: input-outer-focus"
   }
 ];
 
-/**
- * Components - Reusable UI components with their design token usage
- * Real components from the Optics Design System
- */
-export const components: Component[] = [
-  {
-    name: 'Accordion',
-    description: 'Collapsible content panel with expand/collapse animation',
-    tokens: [
-      '--op-color-neutral-on-plus-max',
-      '--op-font-weight-semi-bold',
-      '--op-font-x-large',
-      '--op-font-x-small',
-      '--op-mso-optical-sizing',
-      '--op-size-unit',
-      '--op-space-2x-small',
-      '--op-transition-accordion'
+export const cssPatterns: CSSPattern[] = [
+  {
+    "name": "Accordion",
+    "description": "Accordion classes are built on the `details` and `summary` html elements. They provide consistent and composable styling for disclosure widgets.",
+    "className": "accordion",
+    "type": "component",
+    "modifiers": [
+      "accordion--disable-animation"
     ],
-    usage: 'See https://docs.optics.rolemodel.design for component usage and examples',
-    examples: []
-  },
-  {
-    name: 'Alert',
-    description: 'Notification component for displaying important messages (warning, danger, info, notice)',
-    tokens: [
-      '--op-animation-flash',
-      '--op-border-all',
-      '--op-color-alerts-danger-base',
-      '--op-color-alerts-danger-on-base',
-      '--op-color-alerts-danger-on-base-alt',
-      '--op-color-alerts-danger-on-plus-eight',
-      '--op-color-alerts-danger-on-plus-eight-alt',
-      '--op-color-alerts-danger-on-plus-five',
-      '--op-color-alerts-danger-on-plus-five-alt',
-      '--op-color-alerts-danger-plus-eight',
-      '--op-color-alerts-danger-plus-five',
-      '--op-color-alerts-info-base',
-      '--op-color-alerts-info-on-base',
-      '--op-color-alerts-info-on-base-alt',
-      '--op-color-alerts-info-on-plus-eight',
-      '--op-color-alerts-info-on-plus-eight-alt',
-      '--op-color-alerts-info-on-plus-five',
-      '--op-color-alerts-info-on-plus-five-alt',
-      '--op-color-alerts-info-plus-eight',
-      '--op-color-alerts-info-plus-five',
-      '--op-color-alerts-notice-base',
-      '--op-color-alerts-notice-on-base',
-      '--op-color-alerts-notice-on-base-alt',
-      '--op-color-alerts-notice-on-plus-eight',
-      '--op-color-alerts-notice-on-plus-eight-alt',
-      '--op-color-alerts-notice-on-plus-five',
-      '--op-color-alerts-notice-on-plus-five-alt',
-      '--op-color-alerts-notice-plus-eight',
-      '--op-color-alerts-notice-plus-five',
-      '--op-color-alerts-warning-base',
-      '--op-color-alerts-warning-on-base',
-      '--op-color-alerts-warning-on-base-alt',
-      '--op-color-alerts-warning-on-plus-eight',
-      '--op-color-alerts-warning-on-plus-eight-alt',
-      '--op-color-alerts-warning-on-plus-five',
-      '--op-color-alerts-warning-on-plus-five-alt',
-      '--op-color-alerts-warning-plus-eight',
-      '--op-color-alerts-warning-plus-five',
-      '--op-font-medium',
-      '--op-font-small',
-      '--op-font-weight-medium',
-      '--op-line-height-dense',
-      '--op-radius-medium',
-      '--op-space-2x-small',
-      '--op-space-large',
-      '--op-space-medium',
-      '--op-space-small',
-      '--op-space-x-small',
-      '--op-z-index-alert-group'
+    "elements": [
+      "accordion__label",
+      "accordion__marker"
     ],
-    usage: 'See https://docs.optics.rolemodel.design for component usage and examples',
-    examples: []
-  },
-  {
-    name: 'Avatar',
-    description: 'User profile picture component with multiple sizes and states',
-    tokens: [
-      '--op-border-width',
-      '--op-border-width-large',
-      '--op-color-neutral-base',
-      '--op-color-neutral-minus-max',
-      '--op-color-primary-base',
-      '--op-color-primary-plus-one',
-      '--op-opacity-disabled',
-      '--op-opacity-overlay',
-      '--op-radius-circle',
-      '--op-size-unit'
+    "exampleHtml": "<div class=\"accordion\">\n  <div class=\"accordion__label\">...</div>\n  <div class=\"accordion__marker\">...</div>\n</div>",
+    "docsUrl": "https://docs.optics.rolemodel.design/?path=/docs/components-accordion--docs"
+  },
+  {
+    "name": "Alert",
+    "description": "Alert classes can be used to create a highlighted message or callout in your application.",
+    "className": "alert",
+    "type": "component",
+    "modifiers": [
+      "alert--alert",
+      "alert--danger",
+      "alert--filled",
+      "alert--flash",
+      "alert--info",
+      "alert--muted",
+      "alert--notice",
+      "alert--warning"
     ],
-    usage: 'See https://docs.optics.rolemodel.design for component usage and examples',
-    examples: []
-  },
-  {
-    name: 'Badge',
-    description: 'Small status indicator or label with multiple color variants',
-    tokens: [
-      '--op-border-width-large',
-      '--op-color-alerts-danger-base',
-      '--op-color-alerts-danger-on-base',
-      '--op-color-alerts-info-base',
-      '--op-color-alerts-info-on-base',
-      '--op-color-alerts-notice-base',
-      '--op-color-alerts-notice-on-base',
-      '--op-color-alerts-warning-base',
-      '--op-color-alerts-warning-on-base',
-      '--op-color-neutral-base',
-      '--op-color-neutral-on-base',
-      '--op-color-neutral-plus-max',
-      '--op-color-primary-base',
-      '--op-color-primary-on-base',
-      '--op-font-small',
-      '--op-font-weight-bold',
-      '--op-font-x-small',
-      '--op-letter-spacing-label',
-      '--op-line-height-dense',
-      '--op-radius-medium',
-      '--op-radius-pill',
-      '--op-space-2x-small',
-      '--op-space-x-small'
+    "elements": [
+      "alert__description",
+      "alert__icon",
+      "alert__messages",
+      "alert__title"
     ],
-    usage: 'See https://docs.optics.rolemodel.design for component usage and examples',
-    examples: []
-  },
-  {
-    name: 'Breadcrumbs',
-    description: 'Navigation component showing the current page location in the site hierarchy',
-    tokens: [
-      '--op-font-small',
-      '--op-font-weight-bold',
-      '--op-font-x-small',
-      '--op-space-x-small'
+    "exampleHtml": "<div class=\"alert\">\n  <div class=\"alert__description\">...</div>\n  <div class=\"alert__icon\">...</div>\n  <div class=\"alert__messages\">...</div>\n</div>",
+    "docsUrl": "https://docs.optics.rolemodel.design/?path=/docs/components-alert--docs"
+  },
+  {
+    "name": "Avatar",
+    "description": "Avatar classes can be used on `a` or `div` html elements with an `img` within it. They provide consistent and composable styling for application avatars or profile pictures.",
+    "className": "avatar",
+    "type": "component",
+    "modifiers": [
+      "avatar--disabled",
+      "avatar--large",
+      "avatar--medium",
+      "avatar--small"
+    ],
+    "elements": [],
+    "exampleHtml": "<div class=\"avatar\">...</div>",
+    "docsUrl": "https://docs.optics.rolemodel.design/?path=/docs/components-avatar--docs"
+  },
+  {
+    "name": "Badge",
+    "description": "The Badge component is similar to the Tag component, however it has a different semantic purpose. Badge is intended to be used for notification and information where Tag is intended to be used for interaction and input. See [Tag](?path=/docs/components-tag--docs) for details on its usage.",
+    "className": "badge",
+    "type": "component",
+    "modifiers": [
+      "badge--danger",
+      "badge--info",
+      "badge--notice",
+      "badge--notification-left",
+      "badge--notification-right",
+      "badge--pill",
+      "badge--primary",
+      "badge--warning",
+      "btn--with-badge"
+    ],
+    "elements": [],
+    "exampleHtml": "<div class=\"badge\">...</div>",
+    "docsUrl": "https://docs.optics.rolemodel.design/?path=/docs/components-badge--docs"
+  },
+  {
+    "name": "Breadcrumbs",
+    "description": "The breadcrumbs component is used to show the user's current location in a hierarchy of pages.",
+    "className": "breadcrumbs",
+    "type": "component",
+    "modifiers": [
+      "breadcrumbs--large",
+      "breadcrumbs--small"
     ],
-    usage: 'See https://docs.optics.rolemodel.design for component usage and examples',
-    examples: []
-  },
-  {
-    name: 'Button',
-    description: 'Interactive button component with multiple variants (primary, secondary, etc.) and states',
-    tokens: [
-      '--op-border-all',
-      '--op-color-alerts-danger-base',
-      '--op-color-alerts-danger-minus-two',
-      '--op-color-alerts-danger-on-base',
-      '--op-color-alerts-danger-on-minus-two',
-      '--op-color-alerts-danger-on-plus-five',
-      '--op-color-alerts-danger-plus-five',
-      '--op-color-alerts-danger-plus-three',
-      '--op-color-alerts-warning-base',
-      '--op-color-alerts-warning-minus-two',
-      '--op-color-alerts-warning-on-base',
-      '--op-color-alerts-warning-on-minus-two',
-      '--op-color-alerts-warning-on-plus-five',
-      '--op-color-alerts-warning-plus-five',
-      '--op-color-alerts-warning-plus-three',
-      '--op-color-neutral-on-plus-eight',
-      '--op-color-neutral-plus-eight',
-      '--op-color-neutral-plus-four',
-      '--op-color-primary-base',
-      '--op-color-primary-minus-five',
-      '--op-color-primary-on-base',
-      '--op-color-primary-on-minus-five',
-      '--op-color-primary-on-plus-eight',
-      '--op-color-primary-on-plus-five',
-      '--op-color-primary-on-plus-max',
-      '--op-color-primary-on-plus-one',
-      '--op-color-primary-plus-eight',
-      '--op-color-primary-plus-five',
-      '--op-color-primary-plus-one',
-      '--op-color-primary-plus-three',
-      '--op-color-primary-plus-two',
-      '--op-font-small',
-      '--op-font-weight-normal',
-      '--op-font-x-small',
-      '--op-input-focus-danger',
-      '--op-input-focus-primary',
-      '--op-input-focus-warning',
-      '--op-input-height-large',
-      '--op-input-height-medium',
-      '--op-input-height-small',
-      '--op-opacity-disabled',
-      '--op-radius-medium',
-      '--op-radius-pill',
-      '--op-space-3x-small',
-      '--op-space-small',
-      '--op-space-x-small',
-      '--op-transition-input'
+    "elements": [
+      "breadcrumbs__link",
+      "breadcrumbs__separator",
+      "breadcrumbs__text"
     ],
-    usage: 'See https://docs.optics.rolemodel.design for component usage and examples',
-    examples: []
+    "exampleHtml": "<div class=\"breadcrumbs\">\n  <div class=\"breadcrumbs__link\">...</div>\n  <div class=\"breadcrumbs__text\">...</div>\n</div>",
+    "docsUrl": "https://docs.optics.rolemodel.design/?path=/docs/components-breadcrumbs--docs"
+  },
+  {
+    "name": "Button",
+    "description": "Button classes can be used on `button` or `a` html elements. They provide consistent and composable styling that should address most applications basic needs.",
+    "className": "btn",
+    "type": "component",
+    "modifiers": [
+      "btn--active",
+      "btn--delete",
+      "btn--destructive",
+      "btn--disabled",
+      "btn--icon",
+      "btn--icon-with-label",
+      "btn--large",
+      "btn--medium",
+      "btn--no-border",
+      "btn--pill",
+      "btn--primary",
+      "btn--small",
+      "btn--warning",
+      "btn--with-badge"
+    ],
+    "elements": [],
+    "exampleHtml": "<button class=\"btn btn--primary\">Button</button>",
+    "docsUrl": "https://docs.optics.rolemodel.design/?path=/docs/components-button--docs"
+  },
+  {
+    "name": "ButtonGroup",
+    "description": "ButtonGroup component",
+    "className": "btn-group",
+    "type": "component",
+    "modifiers": [],
+    "elements": [
+      "btn-group-toolbar"
+    ],
+    "exampleHtml": "<div class=\"btn-group\">...</div>",
+    "docsUrl": "https://docs.optics.rolemodel.design/?path=/docs/components-buttongroup--docs"
+  },
+  {
+    "name": "Card",
+    "description": "Card classes can be used to denote bordered sections of an application. They provide simple styles to create sections or \"cards\" for your interface. They can also be used as a starting point for \"row\" or list styles.",
+    "className": "card",
+    "type": "component",
+    "modifiers": [
+      "card--condensed",
+      "card--padded",
+      "card--shadow-large",
+      "card--shadow-medium",
+      "card--shadow-small",
+      "card--shadow-x-large",
+      "card--shadow-x-small"
+    ],
+    "elements": [
+      "card__body",
+      "card__footer",
+      "card__header"
+    ],
+    "exampleHtml": "<div class=\"card\">\n  <div class=\"card__header\">...</div>\n  <div class=\"card__body\">...</div>\n  <div class=\"card__footer\">...</div>\n</div>",
+    "docsUrl": "https://docs.optics.rolemodel.design/?path=/docs/components-card--docs"
   },
   {
-    name: 'ButtonGroup',
-    description: 'Container for grouping related buttons together',
-    tokens: [
-      '--op-btn-group-active-z-index',
-      '--op-btn-group-focus-z-index',
-      '--op-btn-group-hover-z-index'
+    "name": "ConfirmDialog",
+    "description": "ConfirmDialog component",
+    "className": "confirm-dialog-wrapper",
+    "type": "component",
+    "modifiers": [
+      "confirm-dialog-wrapper--active"
     ],
-    usage: 'See https://docs.optics.rolemodel.design for component usage and examples',
-    examples: []
-  },
-  {
-    name: 'Card',
-    description: 'Container component for grouping related content with optional header, body, and footer',
-    tokens: [
-      '--op-border-all',
-      '--op-color-background',
-      '--op-color-border',
-      '--op-color-on-background',
-      '--op-font-medium',
-      '--op-line-height-base',
-      '--op-radius-medium',
-      '--op-shadow-large',
-      '--op-shadow-medium',
-      '--op-shadow-small',
-      '--op-shadow-x-large',
-      '--op-shadow-x-small',
-      '--op-space-medium',
-      '--op-space-scale-unit'
+    "elements": [
+      "confirm-dialog",
+      "confirm-dialog-wrapper__backdrop",
+      "confirm-dialog__body",
+      "confirm-dialog__footer",
+      "confirm-dialog__header"
     ],
-    usage: 'See https://docs.optics.rolemodel.design for component usage and examples',
-    examples: []
-  },
-  {
-    name: 'ConfirmDialog',
-    description: 'Modal dialog for confirming user actions',
-    tokens: [
-      '--op-border-all',
-      '--op-color-background',
-      '--op-color-black',
-      '--op-color-border',
-      '--op-color-on-background',
-      '--op-font-large',
-      '--op-font-medium',
-      '--op-font-weight-semi-bold',
-      '--op-line-height-base',
-      '--op-opacity-full',
-      '--op-opacity-half',
-      '--op-opacity-none',
-      '--op-radius-medium',
-      '--op-size-unit',
-      '--op-space-medium',
-      '--op-transition-modal',
-      '--op-z-index-dialog',
-      '--op-z-index-dialog-backdrop',
-      '--op-z-index-dialog-content'
+    "exampleHtml": "<div class=\"confirm-dialog-wrapper\">\n  <div class=\"confirm-dialog-wrapper__backdrop\">...</div>\n  <div class=\"confirm-dialog__header\">...</div>\n  <div class=\"confirm-dialog__body\">...</div>\n</div>",
+    "docsUrl": "https://docs.optics.rolemodel.design/?path=/docs/components-confirmdialog--docs"
+  },
+  {
+    "name": "ContentHeader",
+    "description": "ContentHeader component",
+    "className": "content-header",
+    "type": "component",
+    "modifiers": [],
+    "elements": [
+      "content-header__aside",
+      "content-header__context",
+      "content-header__details",
+      "content-header__subline",
+      "content-header__title",
+      "context-header__aside",
+      "context-header__context",
+      "context-header__details",
+      "context-header__subline"
     ],
-    usage: 'See https://docs.optics.rolemodel.design for component usage and examples',
-    examples: []
-  },
-  {
-    name: 'Border',
-    description: 'Visual separator between content sections',
-    tokens: [
-      '--op-border-width',
-      '--op-border-width-large',
-      '--op-border-width-x-large',
-      '--op-color-border',
-      '--op-space-2x-small',
-      '--op-space-large',
-      '--op-space-medium',
-      '--op-space-x-small'
+    "exampleHtml": "<div class=\"content-header\">\n  <div class=\"content-header__details\">...</div>\n  <div class=\"content-header__context\">...</div>\n  <div class=\"content-header__title\">...</div>\n</div>",
+    "docsUrl": "https://docs.optics.rolemodel.design/?path=/docs/components-contentheader--docs"
+  },
+  {
+    "name": "Divider",
+    "description": "Divider classes can be used to create horizontal or vertical visual divides between content.",
+    "className": "divider",
+    "type": "component",
+    "modifiers": [
+      "divider--large",
+      "divider--medium",
+      "divider--small",
+      "divider--spacing-large",
+      "divider--spacing-medium",
+      "divider--spacing-small",
+      "divider--vertical"
     ],
-    usage: 'See https://docs.optics.rolemodel.design for component usage and examples',
-    examples: []
-  },
-  {
-    name: 'Form',
-    description: 'Form input components including text inputs, textareas, selects, and labels',
-    tokens: [
-      '--op-border-all',
-      '--op-border-bottom',
-      '--op-color-alerts-danger-base',
-      '--op-color-alerts-danger-minus-three',
-      '--op-color-alerts-danger-minus-two',
-      '--op-color-alerts-danger-on-plus-eight',
-      '--op-color-alerts-danger-on-plus-seven',
-      '--op-color-alerts-danger-plus-eight',
-      '--op-color-alerts-danger-plus-seven',
-      '--op-color-neutral-on-plus-eight',
-      '--op-color-neutral-plus-eight',
-      '--op-color-neutral-plus-four',
-      '--op-color-on-background',
-      '--op-color-primary-base',
-      '--op-color-primary-on-plus-eight',
-      '--op-color-primary-on-plus-max',
-      '--op-color-primary-on-plus-seven',
-      '--op-color-primary-plus-eight',
-      '--op-color-primary-plus-seven',
-      '--op-color-primary-plus-three',
-      '--op-color-primary-plus-two',
-      '--op-encoded-images-dropdown-arrow',
-      '--op-encoded-images-dropdown-arrow-width',
-      '--op-font-medium',
-      '--op-font-small',
-      '--op-font-weight-bold',
-      '--op-font-weight-normal',
-      '--op-font-x-small',
-      '--op-input-focus-danger',
-      '--op-input-focus-primary',
-      '--op-input-height-large',
-      '--op-input-height-medium',
-      '--op-input-height-small',
-      '--op-letter-spacing-label',
-      '--op-line-height-base',
-      '--op-opacity-disabled',
-      '--op-radius-large',
-      '--op-radius-medium',
-      '--op-space-2x-small',
-      '--op-space-3x-large',
-      '--op-space-large',
-      '--op-space-medium',
-      '--op-space-small',
-      '--op-space-x-large',
-      '--op-space-x-small',
-      '--op-transition-input'
+    "elements": [],
+    "exampleHtml": "<div class=\"divider\">...</div>",
+    "docsUrl": "https://docs.optics.rolemodel.design/?path=/docs/components-divider--docs"
+  },
+  {
+    "name": "Form",
+    "description": "Form classes can be used on a variety of `inputs` or `select` HTML elements.",
+    "className": "form-label",
+    "type": "component",
+    "modifiers": [
+      "form-control--large",
+      "form-control--medium",
+      "form-control--no-border",
+      "form-control--small",
+      "form-group--error",
+      "form-group--inline"
     ],
-    usage: 'See https://docs.optics.rolemodel.design for component usage and examples',
-    examples: []
-  },
-  {
-    name: 'Icon',
-    description: 'Material Symbols icon component',
-    tokens: [
-      '--op-font-2x-large',
-      '--op-font-3x-large',
-      '--op-font-large',
-      '--op-font-medium',
-      '--op-font-small',
-      '--op-font-weight-bold',
-      '--op-font-weight-light',
-      '--op-font-weight-normal',
-      '--op-font-weight-semi-bold',
-      '--op-line-height-densest',
-      '--op-mso-fill',
-      '--op-mso-grade',
-      '--op-mso-optical-sizing',
-      '--op-mso-weight'
+    "elements": [
+      "form-control",
+      "form-error",
+      "form-error-summary",
+      "form-group",
+      "form-hint"
     ],
-    usage: 'See https://docs.optics.rolemodel.design for component usage and examples',
-    examples: []
-  },
-  {
-    name: 'Modal',
-    description: 'Dialog component for focused interactions and content overlays',
-    tokens: [
-      '--op-border-all',
-      '--op-color-background',
-      '--op-color-black',
-      '--op-color-border',
-      '--op-color-on-background',
-      '--op-font-large',
-      '--op-font-medium',
-      '--op-font-weight-semi-bold',
-      '--op-line-height-base',
-      '--op-opacity-full',
-      '--op-opacity-half',
-      '--op-opacity-none',
-      '--op-radius-medium',
-      '--op-size-unit',
-      '--op-space-medium',
-      '--op-space-small',
-      '--op-transition-modal',
-      '--op-z-index-dialog',
-      '--op-z-index-dialog-backdrop',
-      '--op-z-index-dialog-content'
+    "exampleHtml": "<div class=\"form-label\">...</div>",
+    "docsUrl": "https://docs.optics.rolemodel.design/?path=/docs/components-form--docs"
+  },
+  {
+    "name": "Icon",
+    "description": "Icon classes are built on top of [Google's Material Symbols Icon Font](https://fonts.google.com/icons). They provide a way to integrate iconography into your application in a flexible and customizable way.",
+    "className": "ph",
+    "type": "component",
+    "modifiers": [
+      "icon--filled",
+      "icon--high-emphasis",
+      "icon--large",
+      "icon--low-emphasis",
+      "icon--medium",
+      "icon--normal-emphasis",
+      "icon--outlined",
+      "icon--small",
+      "icon--weight-bold",
+      "icon--weight-light",
+      "icon--weight-normal",
+      "icon--weight-semi-bold",
+      "icon--weight-thin",
+      "icon--x-large"
     ],
-    usage: 'See https://docs.optics.rolemodel.design for component usage and examples',
-    examples: []
-  },
-  {
-    name: 'Navbar',
-    description: 'Top navigation bar component',
-    tokens: [
-      '--op-border-bottom',
-      '--op-color-neutral-on-plus-eight',
-      '--op-color-neutral-plus-eight',
-      '--op-color-neutral-plus-four',
-      '--op-color-primary-on-plus-six',
-      '--op-color-primary-plus-four',
-      '--op-color-primary-plus-six',
-      '--op-size-unit',
-      '--op-space-2x-small',
-      '--op-space-small',
-      '--op-space-x-large',
-      '--op-space-x-small'
+    "elements": [
+      "fi",
+      "icon",
+      "li",
+      "ph-duotone",
+      "ti"
     ],
-    usage: 'See https://docs.optics.rolemodel.design for component usage and examples',
-    examples: []
+    "exampleHtml": "<div class=\"ph\">...</div>",
+    "docsUrl": "https://docs.optics.rolemodel.design/?path=/docs/components-icon--docs"
   },
   {
-    name: 'Pagination',
-    description: 'Navigation component for paginated content',
-    tokens: [
-      '--op-space-x-small'
+    "name": "Modal",
+    "description": "The Modal classes can be used for styling a custom modal. This can be used alongside the Rails configuration and Javascript implemented by [RoleModel Rails Modal](https://github.com/RoleModel/rolemodel_rails/tree/master/lib/generators/rolemodel/modals)",
+    "className": "modal-wrapper",
+    "type": "component",
+    "modifiers": [
+      "modal-wrapper--active"
+    ],
+    "elements": [
+      "modal",
+      "modal-wrapper__backdrop",
+      "modal__body",
+      "modal__footer",
+      "modal__header"
+    ],
+    "exampleHtml": "<div class=\"modal-wrapper\">\n  <div class=\"modal-wrapper__backdrop\">...</div>\n  <div class=\"modal__header\">...</div>\n  <div class=\"modal__body\">...</div>\n</div>",
+    "docsUrl": "https://docs.optics.rolemodel.design/?path=/docs/components-modal--docs"
+  },
+  {
+    "name": "Navbar",
+    "description": "Navbar classes provide simple styling for a navigation header.",
+    "className": "navbar",
+    "type": "component",
+    "modifiers": [
+      "navbar--primary",
+      "navbar__content--justify-center",
+      "navbar__content--justify-end",
+      "navbar__content--justify-start"
+    ],
+    "elements": [
+      "navbar__brand",
+      "navbar__content",
+      "navbar__content--justify-center",
+      "navbar__content--justify-end",
+      "navbar__content--justify-start"
+    ],
+    "exampleHtml": "<div class=\"navbar\">\n  <div class=\"navbar__brand\">...</div>\n  <div class=\"navbar__content\">...</div>\n  <div class=\"navbar__content--justify-start\">...</div>\n</div>",
+    "docsUrl": "https://docs.optics.rolemodel.design/?path=/docs/components-navbar--docs"
+  },
+  {
+    "name": "Pagination",
+    "description": "Pagination is used to navigate through a series of pages, typically when dealing with tabular data.",
+    "className": "pagination",
+    "type": "component",
+    "modifiers": [],
+    "elements": [
+      "pagination__divider"
+    ],
+    "exampleHtml": "<div class=\"pagination\">\n  <div class=\"pagination__divider\">...</div>\n</div>",
+    "docsUrl": "https://docs.optics.rolemodel.design/?path=/docs/components-pagination--docs"
+  },
+  {
+    "name": "SegmentedControl",
+    "description": "Styles are built on css variables scoped to the segmented control.",
+    "className": "segmented-control",
+    "type": "component",
+    "modifiers": [
+      "segmented-control--full-width",
+      "segmented-control--large",
+      "segmented-control--medium",
+      "segmented-control--small"
+    ],
+    "elements": [
+      "segmented-control__input",
+      "segmented-control__label"
+    ],
+    "exampleHtml": "<div class=\"segmented-control\">\n  <div class=\"segmented-control__input\">...</div>\n  <div class=\"segmented-control__label\">...</div>\n</div>",
+    "docsUrl": "https://docs.optics.rolemodel.design/?path=/docs/components-segmentedcontrol--docs"
+  },
+  {
+    "name": "SidePanel",
+    "description": "Side Panel classes provide simple styling for a panel of sections with a scrollable body.",
+    "className": "side-panel",
+    "type": "component",
+    "modifiers": [
+      "side-panel--border-left",
+      "side-panel--border-right",
+      "side-panel__footer--padded",
+      "side-panel__footer--padded-x",
+      "side-panel__footer--padded-y",
+      "side-panel__section--padded",
+      "side-panel__section--padded-x",
+      "side-panel__section--padded-y"
+    ],
+    "elements": [
+      "side-panel__body",
+      "side-panel__body--padded",
+      "side-panel__body--padded-x",
+      "side-panel__body--padded-y",
+      "side-panel__footer",
+      "side-panel__footer--padded",
+      "side-panel__footer--padded-x",
+      "side-panel__footer--padded-y",
+      "side-panel__header",
+      "side-panel__header--padded",
+      "side-panel__header--padded-x",
+      "side-panel__header--padded-y",
+      "side-panel__section",
+      "side-panel__section--padded",
+      "side-panel__section--padded-x",
+      "side-panel__section--padded-y"
+    ],
+    "exampleHtml": "<div class=\"side-panel\">\n  <div class=\"side-panel__header\">...</div>\n  <div class=\"side-panel__header--padded\">...</div>\n  <div class=\"side-panel__header--padded-x\">...</div>\n</div>",
+    "docsUrl": "https://docs.optics.rolemodel.design/?path=/docs/components-sidepanel--docs"
+  },
+  {
+    "name": "Sidebar",
+    "description": "Sidebar classes provide simple styling for a navigation sidebar drawer, compact, or rail.",
+    "className": "sidebar",
+    "type": "component",
+    "modifiers": [
+      "sidebar--compact",
+      "sidebar--drawer",
+      "sidebar--padded",
+      "sidebar--primary",
+      "sidebar--rail",
+      "sidebar__content--center",
+      "sidebar__content--end",
+      "sidebar__content--start"
     ],
-    usage: 'See https://docs.optics.rolemodel.design for component usage and examples',
-    examples: []
-  },
-  {
-    name: 'SidePanel',
-    description: 'Sliding panel from the side of the screen',
-    tokens: [
-      '--op-border-left',
-      '--op-border-right',
-      '--op-border-x',
-      '--op-color-background',
-      '--op-color-border',
-      '--op-color-on-background',
-      '--op-size-unit',
-      '--op-space-medium'
+    "elements": [
+      "icon-with-label",
+      "sidebar__brand",
+      "sidebar__content",
+      "sidebar__content--center",
+      "sidebar__content--end",
+      "sidebar__content--start"
     ],
-    usage: 'See https://docs.optics.rolemodel.design for component usage and examples',
-    examples: []
-  },
-  {
-    name: 'Sidebar',
-    description: 'Side navigation panel component',
-    tokens: [
-      '--op-border-right',
-      '--op-color-neutral-on-plus-eight',
-      '--op-color-neutral-plus-eight',
-      '--op-color-neutral-plus-four',
-      '--op-color-primary-on-plus-six',
-      '--op-color-primary-plus-four',
-      '--op-color-primary-plus-six',
-      '--op-size-unit',
-      '--op-space-2x-large',
-      '--op-space-2x-small',
-      '--op-space-3x-small',
-      '--op-space-medium',
-      '--op-space-small',
-      '--op-space-x-small',
-      '--op-transition-sidebar'
+    "exampleHtml": "<div class=\"sidebar\">\n  <div class=\"sidebar__brand\">...</div>\n  <div class=\"sidebar__content\">...</div>\n  <div class=\"sidebar__content--start\">...</div>\n</div>",
+    "docsUrl": "https://docs.optics.rolemodel.design/?path=/docs/components-sidebar--docs"
+  },
+  {
+    "name": "Spinner",
+    "description": "Spinners are CSS loading indicators that should be shown when retrieving data or performing slow computations.",
+    "className": "spinner",
+    "type": "component",
+    "modifiers": [
+      "spinner--large",
+      "spinner--medium",
+      "spinner--small",
+      "spinner--x-small"
     ],
-    usage: 'See https://docs.optics.rolemodel.design for component usage and examples',
-    examples: []
-  },
-  {
-    name: 'Spinner',
-    description: 'Loading indicator component',
-    tokens: [
-      '--op-border-width',
-      '--op-border-width-large',
-      '--op-border-width-x-large',
-      '--op-color-neutral-plus-four',
-      '--op-color-primary-base',
-      '--op-size-unit'
+    "elements": [],
+    "exampleHtml": "<div class=\"spinner\">...</div>",
+    "docsUrl": "https://docs.optics.rolemodel.design/?path=/docs/components-spinner--docs"
+  },
+  {
+    "name": "Switch",
+    "description": "Switch classes can be used to create a stylized checkbox or boolean input.",
+    "className": "switch",
+    "type": "component",
+    "modifiers": [
+      "switch--large",
+      "switch--small"
     ],
-    usage: 'See https://docs.optics.rolemodel.design for component usage and examples',
-    examples: []
-  },
-  {
-    name: 'Switch',
-    description: 'Toggle switch component',
-    tokens: [
-      '--op-border-all',
-      '--op-border-width-large',
-      '--op-color-neutral-base',
-      '--op-color-neutral-plus-eight',
-      '--op-color-neutral-plus-five',
-      '--op-color-neutral-plus-three',
-      '--op-color-primary-base',
-      '--op-color-primary-minus-three',
-      '--op-color-primary-minus-two',
-      '--op-color-primary-plus-five',
-      '--op-color-primary-plus-six',
-      '--op-opacity-disabled',
-      '--op-radius-circle',
-      '--op-radius-pill',
-      '--op-size-unit',
-      '--op-space-2x-small',
-      '--op-space-x-small',
-      '--op-transition-input'
+    "elements": [],
+    "exampleHtml": "<div class=\"switch\">...</div>",
+    "docsUrl": "https://docs.optics.rolemodel.design/?path=/docs/components-switch--docs"
+  },
+  {
+    "name": "Tab",
+    "description": "Tab classes provide simple styling for a tab group navigation.",
+    "className": "tab-group",
+    "type": "component",
+    "modifiers": [
+      "tab--active",
+      "tab--disabled",
+      "tab--large",
+      "tab--small"
     ],
-    usage: 'See https://docs.optics.rolemodel.design for component usage and examples',
-    examples: []
-  },
-  {
-    name: 'Tab',
-    description: 'Tabbed interface component',
-    tokens: [
-      '--op-border-width-large',
-      '--op-border-width-x-large',
-      '--op-color-background',
-      '--op-color-on-background',
-      '--op-color-primary-base',
-      '--op-color-primary-on-plus-seven',
-      '--op-color-primary-plus-one',
-      '--op-color-primary-plus-seven',
-      '--op-font-small',
-      '--op-font-x-small',
-      '--op-input-focus-primary',
-      '--op-opacity-disabled',
-      '--op-space-2x-small',
-      '--op-space-3x-small',
-      '--op-space-medium',
-      '--op-space-small',
-      '--op-space-x-small'
+    "elements": [
+      "tab"
     ],
-    usage: 'See https://docs.optics.rolemodel.design for component usage and examples',
-    examples: []
-  },
-  {
-    name: 'Table',
-    description: 'Data table component for displaying structured information',
-    tokens: [
-      '--op-border-all',
-      '--op-border-top',
-      '--op-color-alerts-danger-on-plus-seven',
-      '--op-color-alerts-danger-plus-seven',
-      '--op-color-border',
-      '--op-color-neutral-on-plus-eight',
-      '--op-color-neutral-on-plus-max',
-      '--op-color-neutral-on-plus-seven',
-      '--op-color-neutral-plus-eight',
-      '--op-color-neutral-plus-max',
-      '--op-color-neutral-plus-seven',
-      '--op-color-primary-on-plus-seven',
-      '--op-color-primary-plus-seven',
-      '--op-font-small',
-      '--op-font-weight-semi-bold',
-      '--op-radius-medium',
-      '--op-size-unit',
-      '--op-space-2x-small',
-      '--op-space-small'
+    "exampleHtml": "<div class=\"tab-group\">...</div>",
+    "docsUrl": "https://docs.optics.rolemodel.design/?path=/docs/components-tab--docs"
+  },
+  {
+    "name": "Table",
+    "description": "Table classes provide simple styling for tables and their content.",
+    "className": "table",
+    "type": "component",
+    "modifiers": [
+      "table--auto-layout",
+      "table--comfortable-density",
+      "table--compact-density",
+      "table--container",
+      "table--danger",
+      "table--default-density",
+      "table--even-striped",
+      "table--fixed-layout",
+      "table--odd-striped",
+      "table--primary",
+      "table--sticky-footer",
+      "table--sticky-header"
     ],
-    usage: 'See https://docs.optics.rolemodel.design for component usage and examples',
-    examples: []
-  },
-  {
-    name: 'Tag',
-    description: 'Small label component for categorizing or tagging content',
-    tokens: [
-      '--op-color-alerts-danger-base',
-      '--op-color-alerts-danger-minus-three',
-      '--op-color-alerts-danger-on-base',
-      '--op-color-alerts-danger-on-minus-three',
-      '--op-color-alerts-info-base',
-      '--op-color-alerts-info-minus-three',
-      '--op-color-alerts-info-on-base',
-      '--op-color-alerts-info-on-minus-three',
-      '--op-color-alerts-notice-base',
-      '--op-color-alerts-notice-minus-three',
-      '--op-color-alerts-notice-on-base',
-      '--op-color-alerts-notice-on-minus-three',
-      '--op-color-alerts-warning-base',
-      '--op-color-alerts-warning-minus-three',
-      '--op-color-alerts-warning-on-base',
-      '--op-color-alerts-warning-on-minus-three',
-      '--op-color-neutral-base',
-      '--op-color-neutral-minus-three',
-      '--op-color-neutral-on-base',
-      '--op-color-neutral-on-minus-three',
-      '--op-color-neutral-on-plus-four',
-      '--op-color-neutral-plus-four',
-      '--op-color-primary-base',
-      '--op-color-primary-minus-three',
-      '--op-color-primary-on-base',
-      '--op-color-primary-on-minus-three',
-      '--op-font-medium',
-      '--op-font-weight-bold',
-      '--op-font-x-small',
-      '--op-input-focus-danger',
-      '--op-input-focus-info',
-      '--op-input-focus-neutral',
-      '--op-input-focus-notice',
-      '--op-input-focus-primary',
-      '--op-input-focus-warning',
-      '--op-letter-spacing-label',
-      '--op-line-height-dense',
-      '--op-radius-pill',
-      '--op-space-2x-small'
+    "elements": [
+      "table-container"
     ],
-    usage: 'See https://docs.optics.rolemodel.design for component usage and examples',
-    examples: []
-  },
-  {
-    name: 'TextPair',
-    description: 'Component for displaying label-value pairs',
-    tokens: [
-      '--op-font-large',
-      '--op-font-medium',
-      '--op-font-small',
-      '--op-font-weight-normal',
-      '--op-font-weight-semi-bold',
-      '--op-line-height-dense',
-      '--op-space-x-small'
+    "exampleHtml": "<div class=\"table\">...</div>",
+    "docsUrl": "https://docs.optics.rolemodel.design/?path=/docs/components-table--docs"
+  },
+  {
+    "name": "Tag",
+    "description": "The tag component can be applied to an element with a button within it. The Tag component is similar to the Badge component, however it has a different semantic purpose. Tag is intended to be used for interaction and input where Badge is intended to be used for Notification and Information. See [Badge](?path=/docs/components-badge--docs) for details on its usage.",
+    "className": "tag",
+    "type": "component",
+    "modifiers": [
+      "tag--danger",
+      "tag--info",
+      "tag--notice",
+      "tag--primary",
+      "tag--read-only",
+      "tag--warning"
     ],
-    usage: 'See https://docs.optics.rolemodel.design for component usage and examples',
-    examples: []
-  },
-  {
-    name: 'Tooltip',
-    description: 'Contextual information component that appears on hover or focus',
-    tokens: [
-      '--op-color-neutral-minus-max',
-      '--op-color-neutral-on-minus-max',
-      '--op-font-family',
-      '--op-font-small',
-      '--op-opacity-full',
-      '--op-opacity-none',
-      '--op-radius-medium',
-      '--op-size-unit',
-      '--op-space-medium',
-      '--op-space-small',
-      '--op-space-x-small',
-      '--op-transition-tooltip',
-      '--op-z-index-tooltip'
+    "elements": [
+      "tag__label"
     ],
-    usage: 'See https://docs.optics.rolemodel.design for component usage and examples',
-    examples: []
+    "exampleHtml": "<div class=\"tag\">\n  <div class=\"tag__label\">...</div>\n</div>",
+    "docsUrl": "https://docs.optics.rolemodel.design/?path=/docs/components-tag--docs"
+  },
+  {
+    "name": "TextPair",
+    "description": "TextPair component",
+    "className": "text-pair",
+    "type": "component",
+    "modifiers": [
+      "text-pair--inline",
+      "text-pair__subtitle--large",
+      "text-pair__subtitle--medium",
+      "text-pair__subtitle--small",
+      "text-pair__title--large",
+      "text-pair__title--medium",
+      "text-pair__title--small"
+    ],
+    "elements": [
+      "text-pair__subtitle",
+      "text-pair__subtitle--large",
+      "text-pair__subtitle--medium",
+      "text-pair__subtitle--small",
+      "text-pair__title",
+      "text-pair__title--large",
+      "text-pair__title--medium",
+      "text-pair__title--small"
+    ],
+    "exampleHtml": "<div class=\"text-pair\">\n  <div class=\"text-pair__title\">...</div>\n  <div class=\"text-pair__title--small\">...</div>\n  <div class=\"text-pair__title--medium\">...</div>\n</div>",
+    "docsUrl": "https://docs.optics.rolemodel.design/?path=/docs/components-textpair--docs"
+  },
+  {
+    "name": "Stack",
+    "description": "Layout utility: op-stack",
+    "className": "op-stack",
+    "type": "layout",
+    "modifiers": [],
+    "elements": [],
+    "exampleHtml": "<div class=\"op-stack\">...</div>",
+    "docsUrl": "https://docs.optics.rolemodel.design/?path=/docs/layout-stack--docs"
+  },
+  {
+    "name": "Cluster",
+    "description": "Layout utility: op-cluster",
+    "className": "op-cluster",
+    "type": "layout",
+    "modifiers": [],
+    "elements": [],
+    "exampleHtml": "<div class=\"op-cluster\">...</div>",
+    "docsUrl": "https://docs.optics.rolemodel.design/?path=/docs/layout-cluster--docs"
+  },
+  {
+    "name": "Split",
+    "description": "Layout utility: op-split",
+    "className": "op-split",
+    "type": "layout",
+    "modifiers": [],
+    "elements": [],
+    "exampleHtml": "<div class=\"op-split\">...</div>",
+    "docsUrl": "https://docs.optics.rolemodel.design/?path=/docs/layout-split--docs"
+  },
+  {
+    "name": "Tooltip",
+    "description": "CSS-only tooltip using data attributes",
+    "className": "[data-tooltip-text]",
+    "type": "component",
+    "modifiers": [
+      "[data-tooltip-position=\"top\"]",
+      "[data-tooltip-position=\"bottom\"]",
+      "[data-tooltip-position=\"left\"]",
+      "[data-tooltip-position=\"right\"]"
+    ],
+    "elements": [],
+    "exampleHtml": "<button data-tooltip-text=\"Tooltip text\" data-tooltip-position=\"top\">Hover me</button>",
+    "docsUrl": "https://docs.optics.rolemodel.design/?path=/docs/components-tooltip--docs"
   }
 ];
 
-/**
- * Documentation - Organized documentation sections
- */
+// Backwards compatibility: components alias with extended interface
+export const components: Component[] = cssPatterns.map(p => ({
+  ...p,
+  tokens: p.modifiers,
+  usage: p.description,
+  examples: p.exampleHtml ? [p.exampleHtml] : [],
+}));
+
 export const documentation: Documentation[] = [
   {
-    section: 'introduction',
-    title: 'Introduction to Optics',
-    content: 'Optics is a comprehensive design system that provides a consistent visual language and component library for building user interfaces. It includes design tokens, components, patterns, and guidelines to ensure consistency across all RoleModel products.',
-    tokens: []
-  },
-  {
-    section: 'getting-started',
-    title: 'Getting Started',
-    content: 'To get started with Optics, install the design system package and import the tokens and components you need. The system is built with modularity in mind, allowing you to use only what you need.',
-    tokens: []
-  },
-  {
-    section: 'design-tokens',
-    title: 'Design Tokens',
-    content: 'Design tokens are the visual design atoms of the design system — specifically, they are named entities that store visual design attributes. They are used in place of hard-coded values to ensure consistency and enable theming.',
-    tokens: designTokens.map(t => t.name)
-  },
-  {
-    section: 'color-system',
-    title: 'Color System',
-    content: 'The Optics color system provides a comprehensive palette designed for accessibility and visual harmony. Use semantic color tokens (primary, secondary, success, danger, warning, info) rather than specific color values.',
-    tokens: designTokens.filter(t => t.category === 'color').map(t => t.name)
-  },
-  {
-    section: 'spacing',
-    title: 'Spacing System',
-    content: 'Consistent spacing creates visual rhythm and helps users understand relationships between elements. Optics uses a base-8 spacing system with tokens ranging from xs (4px) to 2xl (48px).',
-    tokens: designTokens.filter(t => t.category === 'spacing').map(t => t.name)
-  },
-  {
-    section: 'typography',
-    title: 'Typography',
-    content: 'Typography is crucial for creating clear information hierarchy and readability. Optics provides font family, size, weight, and line height tokens to ensure consistent text styling.',
-    tokens: designTokens.filter(t => t.category === 'typography').map(t => t.name)
-  },
-  {
-    section: 'components',
-    title: 'Components',
-    content: 'Optics components are reusable UI elements built with design tokens. Each component follows accessibility best practices and includes comprehensive documentation on usage and token application.',
-    tokens: []
-  },
-  {
-    section: 'accessibility',
-    title: 'Accessibility Guidelines',
-    content: 'Accessibility is a core principle of Optics. All components meet WCAG 2.1 AA standards. Ensure proper color contrast, keyboard navigation, and screen reader support when using Optics components.',
-    tokens: []
+    "section": "overview",
+    "title": "Optics Overview",
+    "content": "Optics is a CSS-only design system. It provides CSS custom properties (tokens) and utility classes - NOT JavaScript components. Use the provided CSS classes and tokens; do not write custom CSS for patterns that already exist.",
+    "tokens": []
+  },
+  {
+    "section": "color-pairing",
+    "title": "Color Pairing Rule",
+    "content": "CRITICAL: Background and text colors must ALWAYS be paired. Never use --op-color-{family}-{scale} without also setting color to --op-color-{family}-on-{scale}. The \"on\" tokens are calculated for proper contrast against their matching background.",
+    "tokens": [
+      "color-white",
+      "color-black",
+      "color-primary-h",
+      "color-primary-s",
+      "color-primary-l",
+      "color-primary-original",
+      "color-neutral-h",
+      "color-neutral-s",
+      "color-neutral-l",
+      "color-neutral-original",
+      "color-alerts-warning-h",
+      "color-alerts-warning-s",
+      "color-alerts-warning-l",
+      "color-alerts-warning-original",
+      "color-alerts-danger-h",
+      "color-alerts-danger-s",
+      "color-alerts-danger-l",
+      "color-alerts-danger-original",
+      "color-alerts-info-h",
+      "color-alerts-info-s",
+      "color-alerts-info-l",
+      "color-alerts-info-original",
+      "color-alerts-notice-h",
+      "color-alerts-notice-s",
+      "color-alerts-notice-l",
+      "color-alerts-notice-original",
+      "color-border",
+      "color-background",
+      "color-on-background"
+    ]
+  },
+  {
+    "section": "color-system",
+    "title": "HSL Color System",
+    "content": "Optics uses HSL-based colors defined by -h (hue), -s (saturation), -l (lightness) tokens. A full scale is generated from plus-max (lightest) to minus-max (darkest). Each scale step has a matching \"on-\" token for text.",
+    "tokens": [
+      "color-white",
+      "color-black",
+      "color-primary-h",
+      "color-primary-s",
+      "color-primary-l",
+      "color-primary-original",
+      "color-neutral-h",
+      "color-neutral-s",
+      "color-neutral-l",
+      "color-neutral-original",
+      "color-alerts-warning-h",
+      "color-alerts-warning-s",
+      "color-alerts-warning-l",
+      "color-alerts-warning-original",
+      "color-alerts-danger-h",
+      "color-alerts-danger-s",
+      "color-alerts-danger-l",
+      "color-alerts-danger-original",
+      "color-alerts-info-h",
+      "color-alerts-info-s",
+      "color-alerts-info-l",
+      "color-alerts-info-original",
+      "color-alerts-notice-h",
+      "color-alerts-notice-s",
+      "color-alerts-notice-l",
+      "color-alerts-notice-original",
+      "color-border",
+      "color-background",
+      "color-on-background"
+    ]
+  },
+  {
+    "section": "use-existing",
+    "title": "Use Existing Classes",
+    "content": "Don't write custom CSS for components that already exist. Use .btn for buttons, .card for cards, .op-stack/.op-cluster/.op-split for layouts. Only write custom CSS when truly extending the system.",
+    "tokens": []
   }
 ];

From e3ba6df506dfb9702e4e0ce5c6f277290f87e9e6 Mon Sep 17 00:00:00 2001
From: Dallas Peters <dallaspeters@gmail.com>
Date: Thu, 5 Feb 2026 21:59:22 +0000
Subject: [PATCH 17/28] Add sync-data npm script and dev dependencies

- Add npm run sync-data command
- Add @rolemodel/optics and ts-node as dev deps

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 package-lock.json | 216 ++++++++++++++++++++++++++++++++++++++++++++++
 package.json      |   5 +-
 2 files changed, 220 insertions(+), 1 deletion(-)

diff --git a/package-lock.json b/package-lock.json
index cc3e0e5..ddbdd5e 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -16,14 +16,29 @@
         "optics-mcp": "dist/index.js"
       },
       "devDependencies": {
+        "@rolemodel/optics": "^2.3.0",
         "@types/node": "^20.10.0",
         "esbuild": "^0.27.2",
+        "ts-node": "^10.9.2",
         "typescript": "^5.9.3"
       },
       "engines": {
         "node": ">=24.13.0"
       }
     },
+    "node_modules/@cspotcode/source-map-support": {
+      "version": "0.8.1",
+      "resolved": "https://registry.npmjs.org/@cspotcode/source-map-support/-/source-map-support-0.8.1.tgz",
+      "integrity": "sha512-IchNf6dN4tHoMFIn/7OE8LWZ19Y6q/67Bmf6vnGREv8RSbBVb9LPJxEcnwrcwX6ixSvaiGoomAUvu4YSxXrVgw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/trace-mapping": "0.3.9"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
     "node_modules/@esbuild/aix-ppc64": {
       "version": "0.27.2",
       "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.27.2.tgz",
@@ -478,6 +493,34 @@
         "hono": "^4"
       }
     },
+    "node_modules/@jridgewell/resolve-uri": {
+      "version": "3.1.2",
+      "resolved": "https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz",
+      "integrity": "sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.0.0"
+      }
+    },
+    "node_modules/@jridgewell/sourcemap-codec": {
+      "version": "1.5.5",
+      "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.5.tgz",
+      "integrity": "sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@jridgewell/trace-mapping": {
+      "version": "0.3.9",
+      "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.9.tgz",
+      "integrity": "sha512-3Belt6tdc8bPgAtbcmdtNJlirVoTmEb5e2gC94PnkwEW9jI6CAHUeoG85tjWP5WquqfavoMtMwiG4P926ZKKuQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/resolve-uri": "^3.0.3",
+        "@jridgewell/sourcemap-codec": "^1.4.10"
+      }
+    },
     "node_modules/@modelcontextprotocol/sdk": {
       "version": "1.26.0",
       "resolved": "https://registry.npmjs.org/@modelcontextprotocol/sdk/-/sdk-1.26.0.tgz",
@@ -517,12 +560,59 @@
         }
       }
     },
+    "node_modules/@rolemodel/optics": {
+      "version": "2.3.0",
+      "resolved": "https://registry.npmjs.org/@rolemodel/optics/-/optics-2.3.0.tgz",
+      "integrity": "sha512-retjCKOscYSvLAh9aWRDPGnZRmP6+pc2yZNivU2WRFrp2FeaLfcw9g5oKvw9Lv03yEXL1dT1yQ6bUXeFjp7jkA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "modern-css-reset": "^1.4.0"
+      },
+      "peerDependencies": {
+        "tom-select": "^2.0.0"
+      },
+      "peerDependenciesMeta": {
+        "tom-select": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@tsconfig/node10": {
+      "version": "1.0.12",
+      "resolved": "https://registry.npmjs.org/@tsconfig/node10/-/node10-1.0.12.tgz",
+      "integrity": "sha512-UCYBaeFvM11aU2y3YPZ//O5Rhj+xKyzy7mvcIoAjASbigy8mHMryP5cK7dgjlz2hWxh1g5pLw084E0a/wlUSFQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@tsconfig/node12": {
+      "version": "1.0.11",
+      "resolved": "https://registry.npmjs.org/@tsconfig/node12/-/node12-1.0.11.tgz",
+      "integrity": "sha512-cqefuRsh12pWyGsIoBKJA9luFu3mRxCA+ORZvA4ktLSzIuCUtWVxGIuXigEwO5/ywWFMZ2QEGKWvkZG1zDMTag==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@tsconfig/node14": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/@tsconfig/node14/-/node14-1.0.3.tgz",
+      "integrity": "sha512-ysT8mhdixWK6Hw3i1V2AeRqZ5WfXg1G43mqoYlM2nc6388Fq5jcXyr5mRsqViLx/GJYdoL0bfXD8nmF+Zn/Iow==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@tsconfig/node16": {
+      "version": "1.0.4",
+      "resolved": "https://registry.npmjs.org/@tsconfig/node16/-/node16-1.0.4.tgz",
+      "integrity": "sha512-vxhUy4J8lyeyinH7Azl1pdd43GJhZH/tP2weN8TntQblOY+A0XbT8DJk1/oCPuOOyg/Ja757rG0CgHcWC8OfMA==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/node": {
       "version": "20.19.31",
       "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.31.tgz",
       "integrity": "sha512-5jsi0wpncvTD33Sh1UCgacK37FFwDn+EG7wCmEvs62fCvBL+n8/76cAYDok21NF6+jaVWIqKwCZyX7Vbu8eB3A==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "undici-types": "~6.21.0"
       }
@@ -539,6 +629,32 @@
         "node": ">= 0.6"
       }
     },
+    "node_modules/acorn": {
+      "version": "8.15.0",
+      "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.15.0.tgz",
+      "integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "acorn": "bin/acorn"
+      },
+      "engines": {
+        "node": ">=0.4.0"
+      }
+    },
+    "node_modules/acorn-walk": {
+      "version": "8.3.4",
+      "resolved": "https://registry.npmjs.org/acorn-walk/-/acorn-walk-8.3.4.tgz",
+      "integrity": "sha512-ueEepnujpqee2o5aIYnvHU6C0A42MNdsIDeqy5BydrkuC5R1ZuUFnm27EeFJGoEHJQgn3uleRvmTXaJgfXbt4g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "acorn": "^8.11.0"
+      },
+      "engines": {
+        "node": ">=0.4.0"
+      }
+    },
     "node_modules/ajv": {
       "version": "8.17.1",
       "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.17.1.tgz",
@@ -572,6 +688,13 @@
         }
       }
     },
+    "node_modules/arg": {
+      "version": "4.1.3",
+      "resolved": "https://registry.npmjs.org/arg/-/arg-4.1.3.tgz",
+      "integrity": "sha512-58S9QDqG0Xx27YwPSt9fJxivjYl432YCwfDMfZ+71RAqUrZef7LrKQZ3LHLOwCS4FLNBplP533Zx895SeOCHvA==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/body-parser": {
       "version": "2.2.2",
       "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-2.2.2.tgz",
@@ -683,6 +806,13 @@
         "url": "https://opencollective.com/express"
       }
     },
+    "node_modules/create-require": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/create-require/-/create-require-1.1.1.tgz",
+      "integrity": "sha512-dcKFX3jn0MpIaXjisoRvexIJVEKzaq7z2rZKxf+MSr9TkdmHmsU4m2lcLojrj/FHl8mk5VxMmYA+ftRkP/3oKQ==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/cross-spawn": {
       "version": "7.0.6",
       "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz",
@@ -721,6 +851,16 @@
         "node": ">= 0.8"
       }
     },
+    "node_modules/diff": {
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/diff/-/diff-4.0.4.tgz",
+      "integrity": "sha512-X07nttJQkwkfKfvTPG/KSnE2OMdcUCao6+eXF3wmnIQRn2aPAHH3VxDbDOdegkd6JbPsXqShpvEOHfAT+nCNwQ==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=0.3.1"
+      }
+    },
     "node_modules/dunder-proto": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/dunder-proto/-/dunder-proto-1.0.1.tgz",
@@ -1141,6 +1281,13 @@
       "integrity": "sha512-fQhoXdcvc3V28x7C7BMs4P5+kNlgUURe2jmUT1T//oBRMDrqy1QPelJimwZGo7Hg9VPV3EQV5Bnq4hbFy2vetA==",
       "license": "BSD-2-Clause"
     },
+    "node_modules/make-error": {
+      "version": "1.3.6",
+      "resolved": "https://registry.npmjs.org/make-error/-/make-error-1.3.6.tgz",
+      "integrity": "sha512-s8UhlNe7vPKomQhC1qFelMokr/Sc3AgNbso3n74mVPA5LTZwkB9NlXf4XPamLxJE8h0gh73rM94xvwRT2CVInw==",
+      "dev": true,
+      "license": "ISC"
+    },
     "node_modules/math-intrinsics": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/math-intrinsics/-/math-intrinsics-1.1.0.tgz",
@@ -1191,6 +1338,13 @@
         "url": "https://opencollective.com/express"
       }
     },
+    "node_modules/modern-css-reset": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/modern-css-reset/-/modern-css-reset-1.4.0.tgz",
+      "integrity": "sha512-0crZmSFmrxkI7159rvQWjpDhy0u4+Awg/iOycJdlVn0RSeft/a+6BrQHR3IqvmdK25sqt0o6Z5Ap7cWgUee2rw==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/ms": {
       "version": "2.1.3",
       "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
@@ -1508,6 +1662,50 @@
         "node": ">=0.6"
       }
     },
+    "node_modules/ts-node": {
+      "version": "10.9.2",
+      "resolved": "https://registry.npmjs.org/ts-node/-/ts-node-10.9.2.tgz",
+      "integrity": "sha512-f0FFpIdcHgn8zcPSbf1dRevwt047YMnaiJM3u2w2RewrB+fob/zePZcrOyQoLMMO7aBIddLcQIEK5dYjkLnGrQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@cspotcode/source-map-support": "^0.8.0",
+        "@tsconfig/node10": "^1.0.7",
+        "@tsconfig/node12": "^1.0.7",
+        "@tsconfig/node14": "^1.0.0",
+        "@tsconfig/node16": "^1.0.2",
+        "acorn": "^8.4.1",
+        "acorn-walk": "^8.1.1",
+        "arg": "^4.1.0",
+        "create-require": "^1.1.0",
+        "diff": "^4.0.1",
+        "make-error": "^1.1.1",
+        "v8-compile-cache-lib": "^3.0.1",
+        "yn": "3.1.1"
+      },
+      "bin": {
+        "ts-node": "dist/bin.js",
+        "ts-node-cwd": "dist/bin-cwd.js",
+        "ts-node-esm": "dist/bin-esm.js",
+        "ts-node-script": "dist/bin-script.js",
+        "ts-node-transpile-only": "dist/bin-transpile.js",
+        "ts-script": "dist/bin-script-deprecated.js"
+      },
+      "peerDependencies": {
+        "@swc/core": ">=1.2.50",
+        "@swc/wasm": ">=1.2.50",
+        "@types/node": "*",
+        "typescript": ">=2.7"
+      },
+      "peerDependenciesMeta": {
+        "@swc/core": {
+          "optional": true
+        },
+        "@swc/wasm": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/type-is": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/type-is/-/type-is-2.0.1.tgz",
@@ -1527,6 +1725,7 @@
       "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
       "dev": true,
       "license": "Apache-2.0",
+      "peer": true,
       "bin": {
         "tsc": "bin/tsc",
         "tsserver": "bin/tsserver"
@@ -1550,6 +1749,13 @@
         "node": ">= 0.8"
       }
     },
+    "node_modules/v8-compile-cache-lib": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/v8-compile-cache-lib/-/v8-compile-cache-lib-3.0.1.tgz",
+      "integrity": "sha512-wa7YjyUGfNZngI/vtK0UHAN+lgDCxBPCylVXGp0zu59Fz5aiGtNXaq3DhIov063MorB+VfufLh3JlF2KdTK3xg==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/vary": {
       "version": "1.1.2",
       "resolved": "https://registry.npmjs.org/vary/-/vary-1.1.2.tgz",
@@ -1579,6 +1785,16 @@
       "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz",
       "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ=="
     },
+    "node_modules/yn": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/yn/-/yn-3.1.1.tgz",
+      "integrity": "sha512-Ux4ygGWsu2c7isFWe8Yu1YluJmqVhxqK2cLXNQA5AcC3QfbGNpM7fu0Y8b/z16pXLnFxZYvWhd3fhBY9DLmC6Q==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/zod": {
       "version": "3.25.76",
       "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz",
diff --git a/package.json b/package.json
index b834bc6..f5167b4 100644
--- a/package.json
+++ b/package.json
@@ -15,7 +15,8 @@
     "watch": "npx tsc --watch",
     "start": "node dist/index.js",
     "test": "node dist/test.js",
-    "test:interactive": "npm run build && node dist/interactive-client.js"
+    "test:interactive": "npm run build && node dist/interactive-client.js",
+    "sync-data": "npx ts-node scripts/sync-optics-data.ts"
   },
   "keywords": [
     "mcp",
@@ -42,8 +43,10 @@
     "zod": "^3.25.76"
   },
   "devDependencies": {
+    "@rolemodel/optics": "^2.3.0",
     "@types/node": "^20.10.0",
     "esbuild": "^0.27.2",
+    "ts-node": "^10.9.2",
     "typescript": "^5.9.3"
   },
   "engines": {

From e0263fac16c696ec6ef4d7c4d8d0eba628c28570 Mon Sep 17 00:00:00 2001
From: Dallas Peters <dallaspeters@gmail.com>
Date: Thu, 5 Feb 2026 21:59:40 +0000
Subject: [PATCH 18/28] Add critical color pairing and component usage docs

Document the two most common AI mistakes:
- Not pairing background/text colors
- Writing custom CSS instead of using existing components

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 src/resources/00-system-overview.md | 126 ++++++++++++++++++++++++++++
 1 file changed, 126 insertions(+)

diff --git a/src/resources/00-system-overview.md b/src/resources/00-system-overview.md
index c5f8fd0..80489c4 100644
--- a/src/resources/00-system-overview.md
+++ b/src/resources/00-system-overview.md
@@ -269,6 +269,132 @@ When you call `get_component_info` for "Button", you'll see tokens like:
 }
 ```
 
+## ⚠️ CRITICAL: Color Pairing Rule
+
+**This is the #1 rule AI gets wrong. Read carefully.**
+
+In Optics, background colors and text colors are ALWAYS paired. You cannot use one without the other.
+
+### The Rule
+
+| When you set... | You MUST also set... |
+|-----------------|----------------------|
+| `background-color: var(--op-color-primary-base)` | `color: var(--op-color-primary-on-base)` |
+| `background-color: var(--op-color-danger-minus-1)` | `color: var(--op-color-danger-on-minus-1)` |
+| `color: var(--op-color-neutral-on-plus-eight)` | `background-color: var(--op-color-neutral-plus-eight)` |
+
+### Why?
+
+The `-on-` tokens are calculated for proper contrast against their matching background. Using them separately:
+- Breaks accessibility
+- Creates unreadable text
+- Defeats the purpose of the system
+
+### ❌ WRONG - Unpaired Colors
+
+```css
+/* Missing the text color! */
+.card {
+  background-color: var(--op-color-primary-base);
+}
+
+/* Missing the background! */
+.label {
+  color: var(--op-color-danger-on-base);
+}
+
+/* Using mismatched tokens! */
+.badge {
+  background-color: var(--op-color-primary-base);
+  color: var(--op-color-danger-on-base);  /* WRONG - mismatched family */
+}
+```
+
+### ✅ CORRECT - Paired Colors
+
+```css
+.card {
+  background-color: var(--op-color-primary-base);
+  color: var(--op-color-primary-on-base);
+}
+
+.label {
+  background-color: var(--op-color-danger-base);
+  color: var(--op-color-danger-on-base);
+}
+
+.badge-light {
+  background-color: var(--op-color-primary-plus-five);
+  color: var(--op-color-primary-on-plus-five);
+}
+```
+
+### The Pattern
+
+For ANY color usage:
+1. Pick your background: `--op-color-{family}-{scale}`
+2. Add matching text: `--op-color-{family}-on-{scale}`
+3. For secondary text, use: `--op-color-{family}-on-{scale}-alt`
+
+**Never use background colors alone. Never use text colors alone. They are a pair.**
+
+---
+
+## ⚠️ CRITICAL: Use Existing Components
+
+**Don't write CSS for things that already exist.**
+
+Optics has pre-built components with established class names. AI should use these, not create new ones.
+
+### ❌ WRONG - Writing New CSS
+
+```css
+/* DON'T DO THIS - buttons already exist */
+.my-button {
+  padding: var(--op-space-small) var(--op-space-medium);
+  background-color: var(--op-color-primary-base);
+  color: var(--op-color-primary-on-base);
+  border-radius: var(--op-radius-medium);
+}
+
+/* DON'T DO THIS - cards already exist */
+.custom-card {
+  padding: var(--op-space-large);
+  background: var(--op-color-neutral-plus-eight);
+  border-radius: var(--op-radius-large);
+  box-shadow: var(--op-shadow-medium);
+}
+```
+
+### ✅ CORRECT - Use Existing Classes
+
+```html
+<!-- Use Optics button classes -->
+<button class="btn btn--primary">Click me</button>
+
+<!-- Use Optics card classes -->
+<div class="card">
+  <div class="card__content">...</div>
+</div>
+```
+
+### When to Write Custom CSS
+
+Only write custom CSS when:
+1. **Extending** an existing component with a modifier (following BEM conventions)
+2. Creating something that **truly doesn't exist** in Optics
+3. Overriding specific tokens for **theming purposes**
+
+### Before Writing CSS, Ask:
+
+1. Does this component exist in Optics? → Check https://docs.optics.rolemodel.design
+2. Can I use existing utility classes? → `.stack`, `.cluster`, `.split`, etc.
+3. Am I just recreating something that exists? → Use the existing class
+
+**The whole point of a design system is to NOT write custom CSS for common patterns.**
+
+---
+
 ## 🚨 Common Mistakes
 
 ### Mistake 1: Looking for Simple Color Names

From da3ad8cfa9b158b57b05171a1c33599b5e71f066 Mon Sep 17 00:00:00 2001
From: Dallas Peters <dallaspeters@gmail.com>
Date: Thu, 5 Feb 2026 22:10:52 +0000
Subject: [PATCH 19/28] Fix DesignToken interface compatibility in
 generate-theme-tool

Add missing cssVar property to generated tokens.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 src/tools/generate-theme-tool.ts | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/src/tools/generate-theme-tool.ts b/src/tools/generate-theme-tool.ts
index a0cafe6..bda7e1e 100644
--- a/src/tools/generate-theme-tool.ts
+++ b/src/tools/generate-theme-tool.ts
@@ -99,6 +99,7 @@ class GenerateThemeTool extends Tool {
 
       tokens.push({
         name: `op-color-${family}-h`,
+        cssVar: `--op-color-${family}-h`,
         value: String(hsl.h),
         category: 'color',
         description: `${family} color hue (HSL) - drives all ${family} scale tokens`
@@ -106,6 +107,7 @@ class GenerateThemeTool extends Tool {
 
       tokens.push({
         name: `op-color-${family}-s`,
+        cssVar: `--op-color-${family}-s`,
         value: `${hsl.s}%`,
         category: 'color',
         description: `${family} color saturation (HSL)`
@@ -113,6 +115,7 @@ class GenerateThemeTool extends Tool {
 
       tokens.push({
         name: `op-color-${family}-l`,
+        cssVar: `--op-color-${family}-l`,
         value: `${hsl.l}%`,
         category: 'color',
         description: `${family} color lightness (HSL)`

From d3f91bee4f4ffbc9e6a1e54ad40d2e854b77e455 Mon Sep 17 00:00:00 2001
From: Dallas Peters <dallaspeters@gmail.com>
Date: Sat, 7 Feb 2026 14:29:53 -0600
Subject: [PATCH 20/28] Enhance Optics with new prompts and tools for component
 building and theme creation

- Introduced new prompts: build-component, create-brand-theme, and review-code.
- Added tools for color validation, redundant CSS detection, and HSL token calculation.
- Updated resource paths for prompts and tools to include a templates directory.
- Enhanced existing prompts with detailed instructions and usage guidelines.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 src/_internal/resource-path.ts                |   4 +-
 src/index.ts                                  |  49 ++-
 .../accessible-color-combo-prompt.md          |   0
 .../_templates/build-component-prompt.md      |  48 +++
 .../_templates/create-brand-theme-prompt.md   |  49 +++
 .../create-themed-component-prompt.md         |   0
 .../{ => _templates}/design-review-prompt.md  |   0
 .../explain-token-system-prompt.md            |   0
 .../get-token-reference-prompt.md             |   0
 .../get-token-reference-border.md             |   0
 .../get-token-reference-shadow.md             |   0
 .../get-token-reference-spacing.md            |   0
 .../get-token-reference-typography.md         |   0
 .../migrate-to-tokens-prompt.md               |   0
 src/prompts/_templates/review-code-prompt.md  |  57 +++
 src/prompts/building/build-component.ts       | 113 ++++++
 src/prompts/review/review-code.ts             |  61 ++++
 src/prompts/theming/create-brand-theme.ts     |  97 +++++
 .../{ => _templates}/check-contrast-error.md  |   0
 .../{ => _templates}/check-contrast-result.md |   0
 .../_templates/detect-redundant-css-result.md |  14 +
 .../generate-component-scaffold-usage.md      |   0
 .../generate-sticker-sheet-instructions.md    |   0
 .../generate-theme-instructions.md            |   0
 .../{ => _templates}/generate-theme-output.md |   0
 .../_templates/get-color-scale-result.md      |  14 +
 .../_templates/get-component-html-result.md   |  23 ++
 .../_templates/get-layout-utility-result.md   |  22 ++
 .../suggest-token-migration-header.md         |   0
 .../suggest-token-migration-none.md           |   0
 .../validate-color-pairing-error.md           |  11 +
 .../validate-color-pairing-result.md          |  16 +
 .../validate-token-usage-header.md            |   0
 .../validate-token-usage-valid.md             |   0
 .../calculation/calculate-contrast-tool.ts    | 149 ++++++++
 .../calculation/calculate-hsl-tokens-tool.ts  | 266 ++++++++++++++
 .../data-retrieval/get-color-scale-tool.ts    | 241 +++++++++++++
 .../data-retrieval/get-component-html-tool.ts | 150 ++++++++
 .../data-retrieval/get-layout-utility-tool.ts | 202 +++++++++++
 .../validation/detect-redundant-css-tool.ts   | 332 ++++++++++++++++++
 .../validation/validate-color-pairing-tool.ts | 240 +++++++++++++
 41 files changed, 2150 insertions(+), 8 deletions(-)
 rename src/prompts/{ => _templates}/accessible-color-combo-prompt.md (100%)
 create mode 100644 src/prompts/_templates/build-component-prompt.md
 create mode 100644 src/prompts/_templates/create-brand-theme-prompt.md
 rename src/prompts/{ => _templates}/create-themed-component-prompt.md (100%)
 rename src/prompts/{ => _templates}/design-review-prompt.md (100%)
 rename src/prompts/{ => _templates}/explain-token-system-prompt.md (100%)
 rename src/prompts/{ => _templates}/get-token-reference-prompt.md (100%)
 rename src/prompts/{ => _templates}/get_token_reference_prompt_partials/get-token-reference-border.md (100%)
 rename src/prompts/{ => _templates}/get_token_reference_prompt_partials/get-token-reference-shadow.md (100%)
 rename src/prompts/{ => _templates}/get_token_reference_prompt_partials/get-token-reference-spacing.md (100%)
 rename src/prompts/{ => _templates}/get_token_reference_prompt_partials/get-token-reference-typography.md (100%)
 rename src/prompts/{ => _templates}/migrate-to-tokens-prompt.md (100%)
 create mode 100644 src/prompts/_templates/review-code-prompt.md
 create mode 100644 src/prompts/building/build-component.ts
 create mode 100644 src/prompts/review/review-code.ts
 create mode 100644 src/prompts/theming/create-brand-theme.ts
 rename src/tools/{ => _templates}/check-contrast-error.md (100%)
 rename src/tools/{ => _templates}/check-contrast-result.md (100%)
 create mode 100644 src/tools/_templates/detect-redundant-css-result.md
 rename src/tools/{ => _templates}/generate-component-scaffold-usage.md (100%)
 rename src/tools/{ => _templates}/generate-sticker-sheet-instructions.md (100%)
 rename src/tools/{ => _templates}/generate-theme-instructions.md (100%)
 rename src/tools/{ => _templates}/generate-theme-output.md (100%)
 create mode 100644 src/tools/_templates/get-color-scale-result.md
 create mode 100644 src/tools/_templates/get-component-html-result.md
 create mode 100644 src/tools/_templates/get-layout-utility-result.md
 rename src/tools/{ => _templates}/suggest-token-migration-header.md (100%)
 rename src/tools/{ => _templates}/suggest-token-migration-none.md (100%)
 create mode 100644 src/tools/_templates/validate-color-pairing-error.md
 create mode 100644 src/tools/_templates/validate-color-pairing-result.md
 rename src/tools/{ => _templates}/validate-token-usage-header.md (100%)
 rename src/tools/{ => _templates}/validate-token-usage-valid.md (100%)
 create mode 100644 src/tools/calculation/calculate-contrast-tool.ts
 create mode 100644 src/tools/calculation/calculate-hsl-tokens-tool.ts
 create mode 100644 src/tools/data-retrieval/get-color-scale-tool.ts
 create mode 100644 src/tools/data-retrieval/get-component-html-tool.ts
 create mode 100644 src/tools/data-retrieval/get-layout-utility-tool.ts
 create mode 100644 src/tools/validation/detect-redundant-css-tool.ts
 create mode 100644 src/tools/validation/validate-color-pairing-tool.ts

diff --git a/src/_internal/resource-path.ts b/src/_internal/resource-path.ts
index 8cc1ca6..12569e1 100644
--- a/src/_internal/resource-path.ts
+++ b/src/_internal/resource-path.ts
@@ -11,14 +11,14 @@ const readResourceFile = async (filename: string): Promise<string> => {
 
 const readPromptFile = async (filename: string): Promise<string> => {
   const currentDir = dirname(fileURLToPath(import.meta.url))
-  const filePath = join(currentDir, '..', 'prompts', filename)
+  const filePath = join(currentDir, '..', 'prompts', '_templates', filename)
 
   return readFileSync(filePath, 'utf-8')
 }
 
 const readToolFile = async (filename: string): Promise<string> => {
   const currentDir = dirname(fileURLToPath(import.meta.url))
-  const filePath = join(currentDir, '..', 'tools', filename)
+  const filePath = join(currentDir, '..', 'tools', '_templates', filename)
 
   return readFileSync(filePath, 'utf-8')
 }
diff --git a/src/index.ts b/src/index.ts
index 623480f..e127eb6 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -12,7 +12,6 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import type { ListPromptsRequestSchema, GetPromptRequestSchema } from "@modelcontextprotocol/sdk/types"
 import { z } from 'zod';
 import { designTokens } from './optics-data.js';
-
 // Resources
 import * as systemOverview from './resources/system-overview.js';
 import * as documentationSection from './resources/documentation/section.js';
@@ -20,19 +19,26 @@ import * as allTokens from './resources/tokens/all.js';
 import * as categoryTokens from './resources/tokens/category.js';
 import * as allComponents from './resources/components/all.js';
 
-// Prompts
+// Prompts - Original
 import * as createThemedComponentPrompt from './prompts/create-themed-component.js';
 import * as migrateToTokensPrompt from './prompts/migrate-to-tokens.js';
 import * as accessibleColorComboPrompt from './prompts/accessible-color-combo.js';
 import * as designReviewPrompt from './prompts/design-review.js';
 import * as explainTokenSystemPrompt from './prompts/explain-token-system.js';
 import * as getTokenReferencePrompt from './prompts/get-token-reference.js';
+import * as configureIconsPrompt from './prompts/configure-icons.js';
+import * as useRecipePrompt from './prompts/use-recipe.js';
+
+// Prompts - New (Phase 1)
+import * as buildComponentPrompt from './prompts/building/build-component.js';
+import * as createBrandThemePrompt from './prompts/theming/create-brand-theme.js';
+import * as reviewCodePrompt from './prompts/review/review-code.js';
 
-// Tools
+// Tools - Original
 import GetTokenTool from './tools/get-token-tool.js';
 import GetTokenUsageStatsTool from './tools/get-token-usage-stats-tool.js';
 import SearchTokensTool from './tools/search-tokens-tool.js';
-import ListComponentsTool from './tools/list-components-tool.js'
+import ListComponentsTool from './tools/list-components-tool.js';
 import GetComponentInfoTool from './tools/get-component-info-tool.js';
 import GetComponentTokensTool from './tools/get-component-tokens-tool.js';
 import SearchDocumentationTool from './tools/search-documentation-tool.js';
@@ -44,12 +50,27 @@ import SuggestTokenMigrationTool from './tools/suggest-token-migration-tool.js';
 import GenerateComponentScaffoldTool from './tools/generate-component-scaffold-tool.js';
 import GenerateStickerSheetTool from './tools/generate-sticker-sheet-tool.js';
 
+// Tools - New (Phase 1)
+import ValidateColorPairingTool from './tools/validation/validate-color-pairing-tool.js';
+import DetectRedundantCssTool from './tools/validation/detect-redundant-css-tool.js';
+import GetComponentHtmlTool from './tools/data-retrieval/get-component-html-tool.js';
+import GetLayoutUtilityTool from './tools/data-retrieval/get-layout-utility-tool.js';
+import GetColorScaleTool from './tools/data-retrieval/get-color-scale-tool.js';
+import CalculateContrastTool from './tools/calculation/calculate-contrast-tool.js';
+import CalculateHslTokensTool from './tools/calculation/calculate-hsl-tokens-tool.js';
+
 /**
  * Create and configure the MCP server
  */
 const server = new McpServer({
   name: 'optics-mcp',
   version: '0.1.0',
+}, {
+  capabilities: {
+    tools: {},
+    prompts: {},
+    resources: {},
+  }
 });
 
 /**
@@ -141,12 +162,19 @@ tokenCategories.forEach((category) => {
  */
 
 const prompts = [
+  // Original prompts
   createThemedComponentPrompt,
   migrateToTokensPrompt,
   accessibleColorComboPrompt,
   designReviewPrompt,
   explainTokenSystemPrompt,
-  getTokenReferencePrompt
+  getTokenReferencePrompt,
+  configureIconsPrompt,
+  useRecipePrompt,
+  // New prompts (Phase 1)
+  buildComponentPrompt,
+  createBrandThemePrompt,
+  reviewCodePrompt,
 ]
 
 prompts.forEach((prompt) => {
@@ -181,6 +209,7 @@ prompts.forEach((prompt) => {
  */
 
 const tools = [
+  // Original tools
   new GetTokenTool(),
   new GetTokenUsageStatsTool(),
   new SearchTokensTool(),
@@ -194,7 +223,15 @@ const tools = [
   new CheckContrastTool(),
   new SuggestTokenMigrationTool(),
   new GenerateComponentScaffoldTool(),
-  new GenerateStickerSheetTool()
+  new GenerateStickerSheetTool(),
+  // New tools (Phase 1)
+  new ValidateColorPairingTool(),
+  new DetectRedundantCssTool(),
+  new GetComponentHtmlTool(),
+  new GetLayoutUtilityTool(),
+  new GetColorScaleTool(),
+  new CalculateContrastTool(),
+  new CalculateHslTokensTool(),
 ]
 
 tools.forEach((tool) => {
diff --git a/src/prompts/accessible-color-combo-prompt.md b/src/prompts/_templates/accessible-color-combo-prompt.md
similarity index 100%
rename from src/prompts/accessible-color-combo-prompt.md
rename to src/prompts/_templates/accessible-color-combo-prompt.md
diff --git a/src/prompts/_templates/build-component-prompt.md b/src/prompts/_templates/build-component-prompt.md
new file mode 100644
index 0000000..93497ee
--- /dev/null
+++ b/src/prompts/_templates/build-component-prompt.md
@@ -0,0 +1,48 @@
+# Build {{TYPE}} Component
+
+## Task
+Create a {{VARIANT}} {{TYPE}} component using Optics design system.
+
+## Optics Component Information
+
+### HTML Structure
+```html
+{{EXAMPLE_HTML}}
+```
+
+### CSS Class
+- **Base class**: `{{CLASS_NAME}}`
+- **Modifiers**: {{MODIFIERS}}
+
+### Documentation
+{{DOCS_URL}}
+
+## Design Token Requirements
+{{TOKENS}}
+
+## Usage Guidelines
+{{USAGE}}
+
+## Critical Rules (MUST FOLLOW)
+
+### 1. Use Existing Optics Classes
+- DO NOT write custom CSS for patterns that already exist in Optics
+- Use the `{{CLASS_NAME}}` class as shown above
+- Apply modifiers using BEM syntax: `{{CLASS_NAME}}--modifier`
+
+### 2. Color Pairing Rule
+- ALWAYS pair background and text colors correctly
+- If using `--op-color-{family}-{scale}` for background, MUST use `--op-color-{family}-on-{scale}` for text
+- Use `validate_color_pairing` tool to verify any custom color combinations
+
+### 3. Validate Before Finalizing
+- Run `detect_redundant_css` on any custom CSS to ensure you're not duplicating Optics patterns
+- Check color contrast with `calculate_contrast` for accessibility
+
+## Tools to Use
+1. `get_component_html` - Get exact HTML structure for this component
+2. `validate_color_pairing` - Verify color combinations meet requirements
+3. `detect_redundant_css` - Check for unnecessary custom CSS
+
+## Output Requirements
+Provide the complete component implementation following the Optics patterns shown above.
diff --git a/src/prompts/_templates/create-brand-theme-prompt.md b/src/prompts/_templates/create-brand-theme-prompt.md
new file mode 100644
index 0000000..4960169
--- /dev/null
+++ b/src/prompts/_templates/create-brand-theme-prompt.md
@@ -0,0 +1,49 @@
+# Create Brand Theme: {{BRAND_NAME}}
+
+## Task
+Generate a complete Optics theme customized for {{BRAND_NAME}} using the provided brand colors.
+
+## Brand Colors
+- **Primary**: {{PRIMARY_COLOR}}
+{{NEUTRAL_COLOR_SECTION}}
+
+## Theme Generation Process
+
+### Step 1: Convert Colors to HSL Tokens
+Use `calculate_hsl_tokens` to convert the hex colors to Optics HSL format:
+- Primary color → `--op-color-primary-h`, `--op-color-primary-s`, `--op-color-primary-l`
+- Neutral color → `--op-color-neutral-h`, `--op-color-neutral-s`, `--op-color-neutral-l`
+
+### Step 2: View Generated Color Scale
+Use `get_color_scale` with "primary" to see the full palette that will be generated from your primary color.
+
+### Step 3: Validate Accessibility
+Use `calculate_contrast` to verify key color combinations meet WCAG requirements:
+- Primary background with white text
+- Primary text on white background
+- Neutral variations for UI elements
+
+## Critical Rules
+
+### Color Pairing
+All background colors MUST be paired with their matching "on" text colors:
+- `--op-color-primary-plus-two` background → `--op-color-primary-on-plus-two` text
+- `--op-color-neutral-plus-five` background → `--op-color-neutral-on-plus-five` text
+
+### HSL System
+Optics uses HSL (Hue, Saturation, Lightness) for colors:
+- Only the H, S, L base values need to be customized
+- The scale system (plus-1, plus-2, minus-1, etc.) is calculated automatically
+- This ensures consistent color relationships across the palette
+
+## Tools to Use
+1. `calculate_hsl_tokens` - Convert hex to HSL and generate theme
+2. `get_color_scale` - View the full color palette
+3. `calculate_contrast` - Verify accessibility
+4. `validate_color_pairing` - Check color pair validity
+
+## Expected Output
+A complete CSS file with:
+1. HSL base token overrides for brand colors
+2. Any additional customizations needed
+3. Documentation of the color system
diff --git a/src/prompts/create-themed-component-prompt.md b/src/prompts/_templates/create-themed-component-prompt.md
similarity index 100%
rename from src/prompts/create-themed-component-prompt.md
rename to src/prompts/_templates/create-themed-component-prompt.md
diff --git a/src/prompts/design-review-prompt.md b/src/prompts/_templates/design-review-prompt.md
similarity index 100%
rename from src/prompts/design-review-prompt.md
rename to src/prompts/_templates/design-review-prompt.md
diff --git a/src/prompts/explain-token-system-prompt.md b/src/prompts/_templates/explain-token-system-prompt.md
similarity index 100%
rename from src/prompts/explain-token-system-prompt.md
rename to src/prompts/_templates/explain-token-system-prompt.md
diff --git a/src/prompts/get-token-reference-prompt.md b/src/prompts/_templates/get-token-reference-prompt.md
similarity index 100%
rename from src/prompts/get-token-reference-prompt.md
rename to src/prompts/_templates/get-token-reference-prompt.md
diff --git a/src/prompts/get_token_reference_prompt_partials/get-token-reference-border.md b/src/prompts/_templates/get_token_reference_prompt_partials/get-token-reference-border.md
similarity index 100%
rename from src/prompts/get_token_reference_prompt_partials/get-token-reference-border.md
rename to src/prompts/_templates/get_token_reference_prompt_partials/get-token-reference-border.md
diff --git a/src/prompts/get_token_reference_prompt_partials/get-token-reference-shadow.md b/src/prompts/_templates/get_token_reference_prompt_partials/get-token-reference-shadow.md
similarity index 100%
rename from src/prompts/get_token_reference_prompt_partials/get-token-reference-shadow.md
rename to src/prompts/_templates/get_token_reference_prompt_partials/get-token-reference-shadow.md
diff --git a/src/prompts/get_token_reference_prompt_partials/get-token-reference-spacing.md b/src/prompts/_templates/get_token_reference_prompt_partials/get-token-reference-spacing.md
similarity index 100%
rename from src/prompts/get_token_reference_prompt_partials/get-token-reference-spacing.md
rename to src/prompts/_templates/get_token_reference_prompt_partials/get-token-reference-spacing.md
diff --git a/src/prompts/get_token_reference_prompt_partials/get-token-reference-typography.md b/src/prompts/_templates/get_token_reference_prompt_partials/get-token-reference-typography.md
similarity index 100%
rename from src/prompts/get_token_reference_prompt_partials/get-token-reference-typography.md
rename to src/prompts/_templates/get_token_reference_prompt_partials/get-token-reference-typography.md
diff --git a/src/prompts/migrate-to-tokens-prompt.md b/src/prompts/_templates/migrate-to-tokens-prompt.md
similarity index 100%
rename from src/prompts/migrate-to-tokens-prompt.md
rename to src/prompts/_templates/migrate-to-tokens-prompt.md
diff --git a/src/prompts/_templates/review-code-prompt.md b/src/prompts/_templates/review-code-prompt.md
new file mode 100644
index 0000000..30ac57c
--- /dev/null
+++ b/src/prompts/_templates/review-code-prompt.md
@@ -0,0 +1,57 @@
+# Code Review: {{COMPONENT_TYPE}}
+
+## Code to Review
+```
+{{CODE}}
+```
+
+## Review Checklist
+
+### 1. Color Pairing Validation
+Use `validate_color_pairing` to check all background/text color combinations:
+- Every background color must have a matching "on" text color
+- Verify contrast ratios meet WCAG AA (4.5:1 for normal text)
+
+### 2. Redundant CSS Detection
+Use `detect_redundant_css` to identify:
+- Custom CSS that duplicates existing Optics components
+- Patterns that could use Optics utility classes
+- Unnecessary style overrides
+
+### 3. Component Usage Validation
+Check that Optics components are used correctly:
+- Correct class names (e.g., `btn` not `button`)
+- Proper BEM modifier syntax (e.g., `btn--primary`)
+- Required sub-elements present
+
+### 4. Token Usage
+Verify design tokens are used instead of hard-coded values:
+- Colors should use `var(--op-color-*)` not hex/rgb
+- Spacing should use `var(--op-spacing-*)` not px values
+- Typography should use `var(--op-font-*)` tokens
+
+## Tools to Use
+1. `validate_color_pairing` - Check all color combinations
+2. `detect_redundant_css` - Find unnecessary custom CSS
+3. `validate_token_usage` - Find hard-coded values
+4. `calculate_contrast` - Verify specific color pairs
+
+## Review Output Format
+
+### Issues Found
+List each issue with:
+- **Severity**: Error / Warning / Info
+- **Location**: Line number or selector
+- **Issue**: Description of the problem
+- **Fix**: How to resolve it
+
+### Recommendations
+- Optics components that could replace custom code
+- Token suggestions for hard-coded values
+- Accessibility improvements
+
+### Summary
+- Total issues: X
+- Errors: X
+- Warnings: X
+- Overall assessment: Pass / Needs Work / Fail
diff --git a/src/prompts/building/build-component.ts b/src/prompts/building/build-component.ts
new file mode 100644
index 0000000..668a886
--- /dev/null
+++ b/src/prompts/building/build-component.ts
@@ -0,0 +1,113 @@
+/**
+ * Build Component Prompt
+ * Orchestrates component creation using Optics patterns
+ * Combines: get_component_html, validate_color_pairing, detect_redundant_css
+ */
+
+import { z } from 'zod';
+import { components } from '../../optics-data.js';
+import { readPromptFile } from '../../_internal/resource-path.js';
+
+type BuildComponentPromptArgs = {
+  componentType: string;
+  variant?: string;
+};
+
+export const inputSchema = {
+  componentType: z.string().describe('Type of component to build (button, card, alert, modal, form, etc.)'),
+  variant: z.string().optional().describe('Component variant (primary, secondary, danger, filled, etc.)'),
+};
+
+export const metadata = {
+  name: 'build-component',
+  title: 'Build Component',
+  description: 'Build a component using Optics design system patterns. Enforces correct class usage and color pairing.',
+  role: 'user',
+};
+
+/**
+ * Find component by name (case-insensitive)
+ */
+const findComponent = (componentType: string) => {
+  return components.find(
+    (c) => c.name.toLowerCase() === componentType.toLowerCase()
+  );
+};
+
+/**
+ * Find similar components for suggestions
+ */
+const findSimilarComponents = (componentType: string) => {
+  const searchTerm = componentType.toLowerCase();
+  return components.filter(
+    (c) =>
+      c.name.toLowerCase().includes(searchTerm) ||
+      c.description.toLowerCase().includes(searchTerm)
+  );
+};
+
+export async function handler(args: BuildComponentPromptArgs): Promise<string> {
+  const componentType = args.componentType || 'button';
+  const variant = args.variant || 'default';
+
+  const component = findComponent(componentType);
+
+  if (!component) {
+    // Try to find similar components
+    const similar = findSimilarComponents(componentType);
+    const availableComponents = components.map((c) => c.name).join(', ');
+
+    if (similar.length > 0) {
+      return `# Component Not Found
+
+The component "${componentType}" was not found in Optics.
+
+## Did you mean?
+${similar.map((c) => `- **${c.name}**: ${c.description}`).join('\n')}
+
+## Available Components
+${availableComponents}
+
+## Tools to Use
+- Use \`list_components\` to see all available components
+- Use \`get_component_html\` with a valid component name to get the HTML structure`;
+    }
+
+    return `# Component Not Found
+
+The component "${componentType}" was not found in Optics.
+
+## Available Components
+${availableComponents}
+
+## Tools to Use
+- Use \`list_components\` to see all available components with descriptions
+- Use \`search_components\` to find components by description`;
+  }
+
+  // Load and populate the template
+  let promptTemplate = await readPromptFile('build-component-prompt.md');
+
+  // Format modifiers list
+  const modifiersText = component.modifiers.length > 0
+    ? component.modifiers.map((m) => `\`${m}\``).join(', ')
+    : 'None';
+
+  // Format tokens list
+  const tokensText = component.tokens.length > 0
+    ? component.tokens.map((t) => `- \`${t}\``).join('\n')
+    : 'No specific tokens required';
+
+  // Replace placeholders
+  promptTemplate = promptTemplate
+    .replace(/{{TYPE}}/g, component.name)
+    .replace(/{{VARIANT}}/g, variant)
+    .replace(/{{EXAMPLE_HTML}}/g, component.exampleHtml || '<div class="' + component.className + '">...</div>')
+    .replace(/{{CLASS_NAME}}/g, component.className)
+    .replace(/{{MODIFIERS}}/g, modifiersText)
+    .replace(/{{DOCS_URL}}/g, component.docsUrl || 'No documentation URL available')
+    .replace(/{{TOKENS}}/g, tokensText)
+    .replace(/{{USAGE}}/g, component.usage || component.description);
+
+  return promptTemplate;
+}
diff --git a/src/prompts/review/review-code.ts b/src/prompts/review/review-code.ts
new file mode 100644
index 0000000..b2fb28c
--- /dev/null
+++ b/src/prompts/review/review-code.ts
@@ -0,0 +1,61 @@
+/**
+ * Review Code Prompt
+ * Comprehensive code review for Optics compliance
+ * Combines: validate_color_pairing, detect_redundant_css, validate_token_usage, calculate_contrast
+ */
+
+import { z } from 'zod';
+import { readPromptFile } from '../../_internal/resource-path.js';
+
+type ReviewCodePromptArgs = {
+  code: string;
+  componentType?: string;
+};
+
+export const inputSchema = {
+  code: z.string().describe('CSS, HTML, or component code to review for Optics compliance'),
+  componentType: z.string().optional().describe('Type of component being reviewed (e.g., "button", "card", "form")'),
+};
+
+export const metadata = {
+  name: 'review-code',
+  title: 'Review Code',
+  description: 'Review code for Optics design system compliance. Checks color pairing, redundant CSS, token usage, and accessibility.',
+  role: 'user',
+};
+
+export async function handler(args: ReviewCodePromptArgs): Promise<string> {
+  const code = args.code || '';
+  const componentType = args.componentType || 'component';
+
+  if (!code.trim()) {
+    return `# Code Review Error
+
+No code provided for review.
+
+## How to Use
+Provide the CSS, HTML, or component code you want reviewed:
+
+\`\`\`
+review-code({
+  code: "your code here",
+  componentType: "button" // optional
+})
+\`\`\`
+
+## What Gets Reviewed
+- Color pairing compliance
+- Redundant CSS patterns
+- Hard-coded values that should use tokens
+- Accessibility (contrast ratios)
+- Correct Optics class usage`;
+  }
+
+  let promptTemplate = await readPromptFile('review-code-prompt.md');
+  
+  promptTemplate = promptTemplate
+    .replace(/{{COMPONENT_TYPE}}/g, componentType)
+    .replace(/{{CODE}}/g, code);
+
+  return promptTemplate;
+}
diff --git a/src/prompts/theming/create-brand-theme.ts b/src/prompts/theming/create-brand-theme.ts
new file mode 100644
index 0000000..1a4cbd5
--- /dev/null
+++ b/src/prompts/theming/create-brand-theme.ts
@@ -0,0 +1,97 @@
+/**
+ * Create Brand Theme Prompt
+ * Orchestrates theme creation with brand colors
+ * Combines: calculate_hsl_tokens, get_color_scale, calculate_contrast
+ */
+
+import { z } from 'zod';
+import { readPromptFile } from '../../_internal/resource-path.js';
+
+type CreateBrandThemePromptArgs = {
+  brandName: string;
+  primaryColor: string;
+  neutralColor?: string;
+};
+
+export const inputSchema = {
+  brandName: z.string().describe('Name of the brand (e.g., "Acme Corp", "TechStartup")'),
+  primaryColor: z.string().describe('Primary brand color in hex format (e.g., "#FF5733", "#2D6FDB")'),
+  neutralColor: z.string().optional().describe('Optional neutral/gray color in hex format'),
+};
+
+export const metadata = {
+  name: 'create-brand-theme',
+  title: 'Create Brand Theme',
+  description: 'Generate a complete Optics theme customized with brand colors. Includes HSL conversion and accessibility validation.',
+  role: 'user',
+};
+
+/**
+ * Validate hex color format
+ */
+const isValidHexColor = (color: string): boolean => {
+  return /^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$/.test(color);
+};
+
+/**
+ * Normalize hex color (add # if missing)
+ */
+const normalizeHexColor = (color: string): string => {
+  if (!color.startsWith('#')) {
+    return '#' + color;
+  }
+  return color;
+};
+
+export async function handler(args: CreateBrandThemePromptArgs): Promise<string> {
+  const brandName = args.brandName || 'My Brand';
+  let primaryColor = args.primaryColor || '#2D6FDB';
+  let neutralColor = args.neutralColor;
+
+  // Normalize colors
+  primaryColor = normalizeHexColor(primaryColor);
+  if (neutralColor) {
+    neutralColor = normalizeHexColor(neutralColor);
+  }
+
+  // Validate colors
+  if (!isValidHexColor(primaryColor)) {
+    return `# Invalid Color Format
+
+The primary color "${primaryColor}" is not a valid hex color.
+
+## Valid Formats
+- 6-digit hex: \`#FF5733\`, \`#2D6FDB\`
+- 3-digit hex: \`#F53\`, \`#26D\`
+
+Please provide a valid hex color and try again.`;
+  }
+
+  if (neutralColor && !isValidHexColor(neutralColor)) {
+    return `# Invalid Color Format
+
+The neutral color "${neutralColor}" is not a valid hex color.
+
+## Valid Formats
+- 6-digit hex: \`#757882\`, \`#808080\`
+- 3-digit hex: \`#888\`, \`#666\`
+
+Please provide a valid hex color and try again.`;
+  }
+
+  // Load and populate the template
+  let promptTemplate = await readPromptFile('create-brand-theme-prompt.md');
+
+  // Build neutral color section
+  const neutralColorSection = neutralColor
+    ? `- **Neutral**: ${neutralColor}`
+    : '- **Neutral**: Using default Optics neutral (will inherit primary hue)';
+
+  // Replace placeholders
+  promptTemplate = promptTemplate
+    .replace(/{{BRAND_NAME}}/g, brandName)
+    .replace(/{{PRIMARY_COLOR}}/g, primaryColor)
+    .replace(/{{NEUTRAL_COLOR_SECTION}}/g, neutralColorSection);
+
+  return promptTemplate;
+}
diff --git a/src/tools/check-contrast-error.md b/src/tools/_templates/check-contrast-error.md
similarity index 100%
rename from src/tools/check-contrast-error.md
rename to src/tools/_templates/check-contrast-error.md
diff --git a/src/tools/check-contrast-result.md b/src/tools/_templates/check-contrast-result.md
similarity index 100%
rename from src/tools/check-contrast-result.md
rename to src/tools/_templates/check-contrast-result.md
diff --git a/src/tools/_templates/detect-redundant-css-result.md b/src/tools/_templates/detect-redundant-css-result.md
new file mode 100644
index 0000000..e0c2c76
--- /dev/null
+++ b/src/tools/_templates/detect-redundant-css-result.md
@@ -0,0 +1,14 @@
+# Redundant CSS Detection
+
+## Summary
+- **Total patterns analyzed**: {{totalPatterns}}
+- **Redundant patterns found**: {{redundantCount}}
+- **Optics replacements available**: {{replacementCount}}
+
+## Findings
+
+{{findings}}
+
+## Recommendations
+
+{{recommendations}}
diff --git a/src/tools/generate-component-scaffold-usage.md b/src/tools/_templates/generate-component-scaffold-usage.md
similarity index 100%
rename from src/tools/generate-component-scaffold-usage.md
rename to src/tools/_templates/generate-component-scaffold-usage.md
diff --git a/src/tools/generate-sticker-sheet-instructions.md b/src/tools/_templates/generate-sticker-sheet-instructions.md
similarity index 100%
rename from src/tools/generate-sticker-sheet-instructions.md
rename to src/tools/_templates/generate-sticker-sheet-instructions.md
diff --git a/src/tools/generate-theme-instructions.md b/src/tools/_templates/generate-theme-instructions.md
similarity index 100%
rename from src/tools/generate-theme-instructions.md
rename to src/tools/_templates/generate-theme-instructions.md
diff --git a/src/tools/generate-theme-output.md b/src/tools/_templates/generate-theme-output.md
similarity index 100%
rename from src/tools/generate-theme-output.md
rename to src/tools/_templates/generate-theme-output.md
diff --git a/src/tools/_templates/get-color-scale-result.md b/src/tools/_templates/get-color-scale-result.md
new file mode 100644
index 0000000..99c647e
--- /dev/null
+++ b/src/tools/_templates/get-color-scale-result.md
@@ -0,0 +1,14 @@
+# {{colorFamily}} Color Scale
+
+## Base Color
+- **HSL**: `hsl({{hue}} {{saturation}} {{lightness}})`
+- **CSS Variable**: `--op-color-{{colorFamily}}-original`
+
+## Scale Tokens
+{{scaleTokens}}
+
+## Pairing Guidance
+{{pairingGuidance}}
+
+## Usage Examples
+{{usageExamples}}
diff --git a/src/tools/_templates/get-component-html-result.md b/src/tools/_templates/get-component-html-result.md
new file mode 100644
index 0000000..f2f75f7
--- /dev/null
+++ b/src/tools/_templates/get-component-html-result.md
@@ -0,0 +1,23 @@
+# {{componentName}} Component
+
+## HTML Structure
+
+```html
+{{exampleHtml}}
+```
+
+## CSS Class
+- **Base class**: `{{className}}`
+- **Type**: {{type}}
+
+## Modifiers
+{{modifiers}}
+
+## Elements
+{{elements}}
+
+## Documentation
+{{docsUrl}}
+
+## Usage Notes
+{{description}}
diff --git a/src/tools/_templates/get-layout-utility-result.md b/src/tools/_templates/get-layout-utility-result.md
new file mode 100644
index 0000000..ecc9f13
--- /dev/null
+++ b/src/tools/_templates/get-layout-utility-result.md
@@ -0,0 +1,22 @@
+# {{utilityName}} Layout Utility
+
+## HTML Structure
+
+```html
+{{exampleHtml}}
+```
+
+## CSS Class
+`{{className}}`
+
+## Purpose
+{{description}}
+
+## When to Use
+{{whenToUse}}
+
+## Common Patterns
+{{patterns}}
+
+## Documentation
+{{docsUrl}}
diff --git a/src/tools/suggest-token-migration-header.md b/src/tools/_templates/suggest-token-migration-header.md
similarity index 100%
rename from src/tools/suggest-token-migration-header.md
rename to src/tools/_templates/suggest-token-migration-header.md
diff --git a/src/tools/suggest-token-migration-none.md b/src/tools/_templates/suggest-token-migration-none.md
similarity index 100%
rename from src/tools/suggest-token-migration-none.md
rename to src/tools/_templates/suggest-token-migration-none.md
diff --git a/src/tools/_templates/validate-color-pairing-error.md b/src/tools/_templates/validate-color-pairing-error.md
new file mode 100644
index 0000000..4bb7e90
--- /dev/null
+++ b/src/tools/_templates/validate-color-pairing-error.md
@@ -0,0 +1,11 @@
+# Color Pairing Validation Error
+
+## Tokens
+- **Background**: `{{backgroundToken}}`
+- **Text**: `{{textToken}}`
+
+## Error
+{{reason}}
+
+## Suggestion
+{{suggestion}}
diff --git a/src/tools/_templates/validate-color-pairing-result.md b/src/tools/_templates/validate-color-pairing-result.md
new file mode 100644
index 0000000..163cdd1
--- /dev/null
+++ b/src/tools/_templates/validate-color-pairing-result.md
@@ -0,0 +1,16 @@
+# Color Pairing Validation
+
+## Pair Analysis
+- **Background**: `{{backgroundToken}}` ({{backgroundValue}})
+- **Text**: `{{textToken}}` ({{textValue}})
+
+## Contrast Check
+- **Ratio**: {{contrastRatio}}:1
+- **WCAG AA**: {{wcagAA}}
+- **WCAG AAA**: {{wcagAAA}}
+
+## Pairing Rules
+{{pairingRules}}
+
+## Result
+{{result}}
diff --git a/src/tools/validate-token-usage-header.md b/src/tools/_templates/validate-token-usage-header.md
similarity index 100%
rename from src/tools/validate-token-usage-header.md
rename to src/tools/_templates/validate-token-usage-header.md
diff --git a/src/tools/validate-token-usage-valid.md b/src/tools/_templates/validate-token-usage-valid.md
similarity index 100%
rename from src/tools/validate-token-usage-valid.md
rename to src/tools/_templates/validate-token-usage-valid.md
diff --git a/src/tools/calculation/calculate-contrast-tool.ts b/src/tools/calculation/calculate-contrast-tool.ts
new file mode 100644
index 0000000..70cb6a8
--- /dev/null
+++ b/src/tools/calculation/calculate-contrast-tool.ts
@@ -0,0 +1,149 @@
+/**
+ * Calculate Contrast Tool
+ * Validates WCAG contrast ratios for token combinations
+ * (Renamed from check_contrast for clarity)
+ */
+
+import { z } from 'zod';
+import Tool, { type ToolInputSchema } from '../tool.js';
+import { designTokens, type DesignToken } from '../../optics-data.js';
+import { checkContrast, type ContrastResult } from '../../utils/color.js';
+import { readToolFile } from '../../_internal/resource-path.js';
+
+export interface ContrastCheckResult {
+  foregroundToken: string;
+  backgroundToken: string;
+  foregroundValue: string;
+  backgroundValue: string;
+  contrast: ContrastResult | null;
+  passes: boolean;
+  recommendation?: string;
+}
+
+class CalculateContrastTool extends Tool {
+  name = 'calculate_contrast';
+  title = 'Calculate Contrast';
+  description = 'Calculate WCAG contrast ratio between two color tokens';
+
+  inputSchema = {
+    foregroundToken: z.string().describe('Foreground color token name'),
+    backgroundToken: z.string().describe('Background color token name'),
+  };
+
+  async handler(args: ToolInputSchema): Promise<string> {
+    const { foregroundToken, backgroundToken } = args;
+    const result = this.checkTokenContrast(foregroundToken, backgroundToken, designTokens);
+    const formatted = await this.formatContrastResult(result);
+
+    return formatted;
+  }
+
+  /**
+   * Check contrast between two tokens
+   */
+  private checkTokenContrast(
+    foregroundToken: string,
+    backgroundToken: string,
+    tokens: DesignToken[]
+  ): ContrastCheckResult {
+    const fgToken = tokens.find(t => t.name === foregroundToken);
+    const bgToken = tokens.find(t => t.name === backgroundToken);
+
+    if (!fgToken || !bgToken) {
+      return {
+        foregroundToken,
+        backgroundToken,
+        foregroundValue: '',
+        backgroundValue: '',
+        contrast: null,
+        passes: false,
+        recommendation: 'Token not found'
+      };
+    }
+
+    const contrast = checkContrast(fgToken.value, bgToken.value);
+
+    if (!contrast) {
+      return {
+        foregroundToken,
+        backgroundToken,
+        foregroundValue: fgToken.value,
+        backgroundValue: bgToken.value,
+        contrast: null,
+        passes: false,
+        recommendation: 'Unable to calculate contrast (non-color tokens?)'
+      };
+    }
+
+    const passes = contrast.wcagAA;
+    let recommendation = '';
+
+    if (!passes) {
+      recommendation = this.findBetterTokenCombination(fgToken, tokens, bgToken.value);
+    }
+
+    return {
+      foregroundToken,
+      backgroundToken,
+      foregroundValue: fgToken.value,
+      backgroundValue: bgToken.value,
+      contrast,
+      passes,
+      recommendation
+    };
+  }
+
+  /**
+   * Find better token combination with sufficient contrast
+   */
+  private findBetterTokenCombination(
+    currentToken: DesignToken,
+    allTokens: DesignToken[],
+    backgroundValue: string
+  ): string {
+    const colorTokens = allTokens.filter(t => t.category === 'color');
+
+    for (const token of colorTokens) {
+      const contrast = checkContrast(token.value, backgroundValue);
+      if (contrast && contrast.wcagAA) {
+        return `Try using ${token.name} (${token.value}) for better contrast`;
+      }
+    }
+
+    return 'No alternative tokens found with sufficient contrast';
+  }
+
+  /**
+   * Format contrast check result
+   */
+  private async formatContrastResult(result: ContrastCheckResult): Promise<string> {
+    if (result.contrast) {
+      const template = await readToolFile('check-contrast-result.md');
+      let output = template
+        .replace('{{foregroundToken}}', result.foregroundToken)
+        .replace('{{foregroundValue}}', result.foregroundValue)
+        .replace('{{backgroundToken}}', result.backgroundToken)
+        .replace('{{backgroundValue}}', result.backgroundValue)
+        .replace('{{contrastRatio}}', result.contrast.ratio.toString())
+        .replace('{{wcagAA}}', result.contrast.wcagAA ? '✓ Pass' : '✗ Fail')
+        .replace('{{wcagAAA}}', result.contrast.wcagAAA ? '✓ Pass' : '✗ Fail')
+        .replace('{{score}}', result.contrast.score);
+
+      if (!result.passes && result.recommendation) {
+        output += '\n\n## Recommendation\n' + result.recommendation;
+      }
+
+      return output;
+    } else {
+      const template = await readToolFile('check-contrast-error.md');
+      return template
+        .replace('{{foregroundToken}}', result.foregroundToken)
+        .replace('{{foregroundValue}}', result.foregroundValue)
+        .replace('{{backgroundToken}}', result.backgroundToken)
+        .replace('{{backgroundValue}}', result.backgroundValue)
+        .replace('{{reason}}', result.recommendation || 'Unknown error');
+    }
+  }
+}
+
+export default CalculateContrastTool;
diff --git a/src/tools/calculation/calculate-hsl-tokens-tool.ts b/src/tools/calculation/calculate-hsl-tokens-tool.ts
new file mode 100644
index 0000000..3bf5c2a
--- /dev/null
+++ b/src/tools/calculation/calculate-hsl-tokens-tool.ts
@@ -0,0 +1,266 @@
+/**
+ * Calculate HSL Tokens Tool
+ * Converts hex colors to Optics HSL format tokens
+ * (Renamed from generate_theme for clarity - focused on the calculation aspect)
+ */
+
+import { z } from 'zod';
+import Tool, { type ToolInputSchema } from '../tool.js';
+import { designTokens, type DesignToken } from '../../optics-data.js';
+import { generateFigmaVariablesJSON } from '../../utils/figma-tokens.js';
+import { readToolFile } from '../../_internal/resource-path.js';
+
+interface BrandColors {
+  primary?: string;
+  neutral?: string;
+  'alerts-warning'?: string;
+  'alerts-danger'?: string;
+  'alerts-info'?: string;
+  'alerts-notice'?: string;
+}
+
+interface GeneratedTheme {
+  cssVariables: string;
+  figmaVariables: string;
+  tokens: DesignToken[];
+  documentation: string;
+}
+
+class CalculateHslTokensTool extends Tool {
+  name = 'calculate_hsl_tokens';
+  title = 'Calculate HSL Tokens';
+  description = 'Convert hex colors to Optics HSL format and generate theme tokens';
+
+  inputSchema = {
+    brandName: z
+      .string()
+      .describe('The name of the brand/theme (e.g., "Acme Corp")'),
+    primary: z
+      .string()
+      .describe('Primary brand color (hex, e.g., "#FF5733")'),
+    neutral: z
+      .string()
+      .optional()
+      .describe('Neutral color (hex, optional)')
+  };
+
+  async handler(args: ToolInputSchema): Promise<string> {
+    const brandColors: BrandColors = {
+      primary: args.primary,
+      neutral: args.neutral
+    };
+    const theme = await this.generateTheme(args.brandName, brandColors);
+
+    let output = await readToolFile('generate-theme-output.md');
+
+    output = output
+      .replace('{{brandName}}', args.brandName)
+      .replace('{{cssVariables}}', theme.cssVariables)
+      .replace('{{figmaVariables}}', theme.figmaVariables)
+      .replace('{{totalTokens}}', String(theme.tokens.length))
+      .replace('{{colorTokens}}', String(theme.tokens.filter(t => t.category === 'color').length))
+      .replace('{{typographyTokens}}', String(theme.tokens.filter(t => t.category === 'typography').length))
+      .replace('{{spacingTokens}}', String(theme.tokens.filter(t => t.category === 'spacing').length))
+      .replace('{{documentation}}', theme.documentation);
+
+    return output;
+  }
+
+  /**
+   * Generate Optics HSL color tokens from brand colors
+   */
+  private generateColorTokens(brandColors: BrandColors): DesignToken[] {
+    const tokens: DesignToken[] = [];
+
+    const defaults: BrandColors = {
+      primary: '#2D6FDB',
+      neutral: '#757882',
+      'alerts-warning': '#FFD93D',
+      'alerts-danger': '#FF6B94',
+      'alerts-info': '#2D6FDB',
+      'alerts-notice': '#6ACF71'
+    };
+
+    const colors = { ...defaults, ...brandColors };
+
+    for (const [family, hex] of Object.entries(colors)) {
+      if (!hex) continue;
+
+      const hsl = this.hexToHSL(hex);
+
+      tokens.push({
+        name: `op-color-${family}-h`,
+        cssVar: `--op-color-${family}-h`,
+        value: String(hsl.h),
+        category: 'color',
+        description: `${family} color hue (HSL) - drives all ${family} scale tokens`
+      });
+
+      tokens.push({
+        name: `op-color-${family}-s`,
+        cssVar: `--op-color-${family}-s`,
+        value: `${hsl.s}%`,
+        category: 'color',
+        description: `${family} color saturation (HSL)`
+      });
+
+      tokens.push({
+        name: `op-color-${family}-l`,
+        cssVar: `--op-color-${family}-l`,
+        value: `${hsl.l}%`,
+        category: 'color',
+        description: `${family} color lightness (HSL)`
+      });
+    }
+
+    return tokens;
+  }
+
+  /**
+   * Convert hex to HSL
+   */
+  private hexToHSL(hex: string): { h: number; s: number; l: number } {
+    hex = hex.replace('#', '');
+
+    const r = parseInt(hex.substring(0, 2), 16) / 255;
+    const g = parseInt(hex.substring(2, 4), 16) / 255;
+    const b = parseInt(hex.substring(4, 6), 16) / 255;
+
+    const max = Math.max(r, g, b);
+    const min = Math.min(r, g, b);
+    let h = 0;
+    let s = 0;
+    const l = (max + min) / 2;
+
+    if (max !== min) {
+      const d = max - min;
+      s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+
+      switch (max) {
+        case r: h = ((g - b) / d + (g < b ? 6 : 0)) / 6; break;
+        case g: h = ((b - r) / d + 2) / 6; break;
+        case b: h = ((r - g) / d + 4) / 6; break;
+      }
+    }
+
+    return {
+      h: Math.round(h * 360),
+      s: Math.round(s * 100),
+      l: Math.round(l * 100)
+    };
+  }
+
+  /**
+   * Generate CSS variables from tokens
+   */
+  private generateCSSVariables(tokens: DesignToken[], themeName: string = 'default'): string {
+    const lines: string[] = [
+      `/* ${themeName} Theme - Generated by Optics MCP */`,
+      `/* HSL tokens for easy theming */`,
+      `:root {`
+    ];
+
+    const grouped: Record<string, DesignToken[]> = {};
+    tokens.forEach(token => {
+      if (!grouped[token.category]) grouped[token.category] = [];
+      grouped[token.category].push(token);
+    });
+
+    if (grouped['color']) {
+      lines.push(`  /* Colors (HSL) */`);
+      for (const token of grouped['color']) {
+        lines.push(`  --${token.name}: ${token.value};`);
+      }
+      lines.push('');
+    }
+
+    for (const [category, categoryTokens] of Object.entries(grouped)) {
+      if (category === 'color') continue;
+
+      lines.push(`  /* ${category.charAt(0).toUpperCase() + category.slice(1)} */`);
+      for (const token of categoryTokens) {
+        lines.push(`  --${token.name}: ${token.value};`);
+      }
+      lines.push('');
+    }
+
+    lines.push('}');
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Generate theme documentation
+   */
+  private async generateDocumentation(themeName: string, tokens: DesignToken[]): Promise<string> {
+    let documentation = await readToolFile('generate-theme-instructions.md');
+
+    const stats = tokens.reduce((acc, token) => {
+      acc[token.category] = (acc[token.category] || 0) + 1;
+      return acc;
+    }, {} as Record<string, number>);
+
+    const tokenSummary = Object.entries(stats)
+      .map(([category, count]) => `- **${category}**: ${count} tokens`)
+      .join('\n');
+
+    const grouped: Record<string, DesignToken[]> = {};
+    tokens.forEach(token => {
+      if (!grouped[token.category]) grouped[token.category] = [];
+      grouped[token.category].push(token);
+    });
+
+    const tokenCategories = Object.entries(grouped)
+      .map(([category, categoryTokens]) => {
+        const lines = [
+          `### ${category.charAt(0).toUpperCase() + category.slice(1)}`,
+          '',
+          '| Token Name | Value | Description |',
+          '|------------|-------|-------------|'
+        ];
+
+        for (const token of categoryTokens) {
+          lines.push(`| \`${token.name}\` | \`${token.value}\` | ${token.description || ''} |`);
+        }
+
+        return lines.join('\n');
+      })
+      .join('\n\n');
+
+    documentation = documentation
+      .replace('{{themeName}}', themeName)
+      .replace('{{tokenSummary}}', tokenSummary)
+      .replace('{{tokenCategories}}', tokenCategories);
+
+    return documentation;
+  }
+
+  /**
+   * Main theme generation function
+   */
+  private async generateTheme(brandName: string, brandColors: BrandColors): Promise<GeneratedTheme> {
+    let tokens: DesignToken[] = [...designTokens];
+
+    if (Object.keys(brandColors).length > 0) {
+      const customColorTokens = this.generateColorTokens(brandColors);
+
+      tokens = tokens.map(token => {
+        const customToken = customColorTokens.find(ct => ct.name === token.name);
+        return customToken || token;
+      });
+    }
+
+    const cssVariables = this.generateCSSVariables(tokens, brandName);
+    const figmaVariables = generateFigmaVariablesJSON(tokens, { collectionName: `${brandName} Design System` });
+    const documentation = await this.generateDocumentation(brandName, tokens);
+
+    return {
+      cssVariables,
+      figmaVariables,
+      tokens,
+      documentation
+    };
+  }
+}
+
+export default CalculateHslTokensTool;
diff --git a/src/tools/data-retrieval/get-color-scale-tool.ts b/src/tools/data-retrieval/get-color-scale-tool.ts
new file mode 100644
index 0000000..b125a36
--- /dev/null
+++ b/src/tools/data-retrieval/get-color-scale-tool.ts
@@ -0,0 +1,241 @@
+/**
+ * Get Color Scale Tool
+ * Returns all tokens in a color family with pairing guidance
+ */
+
+import { z } from 'zod';
+import Tool, { type ToolInputSchema } from '../tool.js';
+import { designTokens, type DesignToken } from '../../optics-data.js';
+import { readToolFile } from '../../_internal/resource-path.js';
+
+/**
+ * Color pairing rules for each color family
+ */
+const COLOR_PAIRING_GUIDANCE: Record<string, {
+  backgrounds: string[];
+  textColors: string[];
+  notes: string;
+}> = {
+  primary: {
+    backgrounds: ['color-primary-original', 'color-primary-plus-*', 'color-primary-minus-*'],
+    textColors: ['color-primary-on-*', 'color-white', 'color-black'],
+    notes: 'Primary colors should use matching "on" tokens for text. For example, if using --op-color-primary-plus-two as background, use --op-color-primary-on-plus-two for text.'
+  },
+  neutral: {
+    backgrounds: ['color-neutral-plus-*', 'color-neutral-minus-*', 'color-background'],
+    textColors: ['color-neutral-on-*', 'color-on-background'],
+    notes: 'Neutral colors form the foundation of your UI. Always pair neutral backgrounds with their matching "on" tokens.'
+  },
+  'alerts-danger': {
+    backgrounds: ['color-alerts-danger-original'],
+    textColors: ['color-white', 'color-alerts-danger-on-*'],
+    notes: 'Danger/error colors should be used sparingly. Ensure high contrast for accessibility.'
+  },
+  'alerts-warning': {
+    backgrounds: ['color-alerts-warning-original'],
+    textColors: ['color-black', 'color-neutral-900'],
+    notes: 'Warning colors often need dark text due to their lighter nature.'
+  },
+  'alerts-info': {
+    backgrounds: ['color-alerts-info-original'],
+    textColors: ['color-white', 'color-alerts-info-on-*'],
+    notes: 'Info colors are used for informational messages and highlights.'
+  },
+  'alerts-notice': {
+    backgrounds: ['color-alerts-notice-original'],
+    textColors: ['color-black', 'color-neutral-900'],
+    notes: 'Notice/success colors indicate positive outcomes or confirmations.'
+  }
+};
+
+class GetColorScaleTool extends Tool {
+  name = 'get_color_scale';
+  title = 'Get Color Scale';
+  description = 'Get all tokens in a color family with pairing guidance';
+
+  inputSchema = {
+    colorFamily: z.string().describe('Color family name: "primary", "neutral", "alerts-danger", "alerts-warning", "alerts-info", "alerts-notice"'),
+  };
+
+  async handler(args: ToolInputSchema): Promise<string> {
+    const { colorFamily } = args;
+    const result = await this.getColorScale(colorFamily.toLowerCase());
+
+    return result;
+  }
+
+  /**
+   * Get all tokens for a color family
+   */
+  private async getColorScale(colorFamily: string): Promise<string> {
+    // Find all tokens that belong to this color family
+    const familyTokens = designTokens.filter(
+      t => t.category === 'color' && t.name.startsWith(`color-${colorFamily}`)
+    );
+
+    if (familyTokens.length === 0) {
+      const availableFamilies = this.getAvailableColorFamilies();
+      return `# Color Family Not Found\n\nColor family "${colorFamily}" not found.\n\nAvailable color families:\n${availableFamilies.map(f => `- ${f}`).join('\n')}\n\nUse one of these family names to get the full color scale.`;
+    }
+
+    const template = await readToolFile('get-color-scale-result.md');
+
+    // Extract HSL components
+    const hueToken = familyTokens.find(t => t.name.endsWith('-h'));
+    const satToken = familyTokens.find(t => t.name.endsWith('-s'));
+    const lightToken = familyTokens.find(t => t.name.endsWith('-l'));
+
+    // Build scale tokens list
+    const scaleTokensText = this.formatScaleTokens(familyTokens);
+
+    // Get pairing guidance
+    const guidance = COLOR_PAIRING_GUIDANCE[colorFamily];
+    const pairingText = guidance
+      ? this.formatPairingGuidance(guidance)
+      : 'No specific pairing guidance available. Follow the general rule: always pair background colors with their matching "on" text colors.';
+
+    // Build usage examples
+    const usageExamples = this.getUsageExamples(colorFamily, familyTokens);
+
+    return template
+      .replace('{{colorFamily}}', this.capitalize(colorFamily))
+      .replace('{{hue}}', hueToken?.value || 'N/A')
+      .replace('{{saturation}}', satToken?.value || 'N/A')
+      .replace('{{lightness}}', lightToken?.value || 'N/A')
+      .replace('{{scaleTokens}}', scaleTokensText)
+      .replace('{{pairingGuidance}}', pairingText)
+      .replace('{{usageExamples}}', usageExamples);
+  }
+
+  /**
+   * Get available color families from tokens
+   */
+  private getAvailableColorFamilies(): string[] {
+    const families = new Set<string>();
+    
+    for (const token of designTokens) {
+      if (token.category === 'color' && token.name.startsWith('color-')) {
+        // Extract family name (e.g., "primary" from "color-primary-h")
+        const parts = token.name.replace('color-', '').split('-');
+        if (parts.length >= 1) {
+          // Handle compound names like "alerts-danger"
+          if (parts[0] === 'alerts' && parts.length >= 2) {
+            families.add(`alerts-${parts[1]}`);
+          } else if (!['h', 's', 'l', 'original', 'on', 'plus', 'minus'].includes(parts[0])) {
+            families.add(parts[0]);
+          }
+        }
+      }
+    }
+
+    return Array.from(families).sort();
+  }
+
+  /**
+   * Format scale tokens as a list
+   */
+  private formatScaleTokens(tokens: DesignToken[]): string {
+    // Group tokens by type
+    const hslTokens = tokens.filter(t => t.name.match(/-[hsl]$/));
+    const scaleTokens = tokens.filter(t => t.name.match(/-(plus|minus)-\d+$/));
+    const onTokens = tokens.filter(t => t.name.includes('-on-'));
+    const otherTokens = tokens.filter(t => 
+      !hslTokens.includes(t) && 
+      !scaleTokens.includes(t) && 
+      !onTokens.includes(t)
+    );
+
+    const lines: string[] = [];
+
+    if (hslTokens.length > 0) {
+      lines.push('### HSL Components');
+      for (const token of hslTokens) {
+        lines.push(`- \`${token.cssVar}\`: ${token.value}`);
+      }
+      lines.push('');
+    }
+
+    if (scaleTokens.length > 0) {
+      lines.push('### Scale Variations');
+      for (const token of scaleTokens.sort((a, b) => a.name.localeCompare(b.name))) {
+        lines.push(`- \`${token.cssVar}\`: ${token.value}`);
+      }
+      lines.push('');
+    }
+
+    if (onTokens.length > 0) {
+      lines.push('### Text Colors (for pairing)');
+      for (const token of onTokens.sort((a, b) => a.name.localeCompare(b.name))) {
+        lines.push(`- \`${token.cssVar}\`: ${token.value}`);
+      }
+      lines.push('');
+    }
+
+    if (otherTokens.length > 0) {
+      lines.push('### Other Tokens');
+      for (const token of otherTokens) {
+        lines.push(`- \`${token.cssVar}\`: ${token.value}`);
+      }
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Format pairing guidance
+   */
+  private formatPairingGuidance(guidance: { backgrounds: string[]; textColors: string[]; notes: string }): string {
+    const lines: string[] = [
+      '### Background Colors',
+      ...guidance.backgrounds.map(b => `- \`--op-${b}\``),
+      '',
+      '### Recommended Text Colors',
+      ...guidance.textColors.map(t => `- \`--op-${t}\``),
+      '',
+      '### Important Notes',
+      guidance.notes
+    ];
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Get usage examples for the color family
+   */
+  private getUsageExamples(colorFamily: string, tokens: DesignToken[]): string {
+    const examples: string[] = [];
+
+    // Find a background and matching text token
+    const bgToken = tokens.find(t => t.name.includes('original') || t.name.includes('plus'));
+    const onToken = tokens.find(t => t.name.includes('-on-'));
+
+    if (bgToken && onToken) {
+      examples.push('```css');
+      examples.push('.my-element {');
+      examples.push(`  background-color: var(${bgToken.cssVar});`);
+      examples.push(`  color: var(${onToken.cssVar});`);
+      examples.push('}');
+      examples.push('```');
+    } else if (bgToken) {
+      examples.push('```css');
+      examples.push('.my-element {');
+      examples.push(`  background-color: var(${bgToken.cssVar});`);
+      examples.push(`  /* Always pair with matching "on" token for text */`);
+      examples.push('}');
+      examples.push('```');
+    }
+
+    return examples.length > 0 
+      ? examples.join('\n')
+      : 'No specific examples available.';
+  }
+
+  /**
+   * Capitalize first letter
+   */
+  private capitalize(str: string): string {
+    return str.charAt(0).toUpperCase() + str.slice(1);
+  }
+}
+
+export default GetColorScaleTool;
diff --git a/src/tools/data-retrieval/get-component-html-tool.ts b/src/tools/data-retrieval/get-component-html-tool.ts
new file mode 100644
index 0000000..0293a1e
--- /dev/null
+++ b/src/tools/data-retrieval/get-component-html-tool.ts
@@ -0,0 +1,150 @@
+/**
+ * Get Component HTML Tool
+ * Returns exact HTML/classes for an Optics component
+ */
+
+import { z } from 'zod';
+import Tool, { type ToolInputSchema } from '../tool.js';
+import { components, type Component } from '../../optics-data.js';
+import { readToolFile } from '../../_internal/resource-path.js';
+
+export interface ComponentHTMLResult {
+  found: boolean;
+  component?: Component;
+  variant?: string;
+  variantHtml?: string;
+  error?: string;
+}
+
+class GetComponentHtmlTool extends Tool {
+  name = 'get_component_html';
+  title = 'Get Component HTML';
+  description = 'Get the exact HTML structure and CSS classes for an Optics component';
+
+  inputSchema = {
+    componentName: z.string().describe('Name of the component (e.g., "Button", "Card", "Alert")'),
+    variant: z.string().optional().describe('Optional variant/modifier (e.g., "primary", "danger", "filled")'),
+  };
+
+  async handler(args: ToolInputSchema): Promise<string> {
+    const { componentName, variant } = args;
+    const result = this.getComponentHtml(componentName, variant);
+    const formatted = await this.formatResult(result);
+
+    return formatted;
+  }
+
+  /**
+   * Get component HTML and details
+   */
+  private getComponentHtml(componentName: string, variant?: string): ComponentHTMLResult {
+    const component = components.find(
+      c => c.name.toLowerCase() === componentName.toLowerCase()
+    );
+
+    if (!component) {
+      // Try to find partial matches
+      const partialMatches = components.filter(
+        c => c.name.toLowerCase().includes(componentName.toLowerCase()) ||
+             componentName.toLowerCase().includes(c.name.toLowerCase())
+      );
+
+      if (partialMatches.length > 0) {
+        return {
+          found: false,
+          error: `Component "${componentName}" not found. Did you mean: ${partialMatches.map(c => c.name).join(', ')}?`
+        };
+      }
+
+      return {
+        found: false,
+        error: `Component "${componentName}" not found. Use list_components to see available components.`
+      };
+    }
+
+    // If variant specified, generate variant-specific HTML
+    let variantHtml: string | undefined;
+    if (variant) {
+      const matchingModifier = component.modifiers.find(
+        m => m.toLowerCase().includes(variant.toLowerCase())
+      );
+
+      if (matchingModifier) {
+        // Generate HTML with the variant class applied
+        variantHtml = this.applyVariantToHtml(component.exampleHtml, component.className, matchingModifier);
+      }
+    }
+
+    return {
+      found: true,
+      component,
+      variant,
+      variantHtml
+    };
+  }
+
+  /**
+   * Apply a variant modifier to the example HTML
+   */
+  private applyVariantToHtml(html: string, baseClass: string, modifier: string): string {
+    // Replace the base class with base class + modifier
+    const classPattern = new RegExp(`class="([^"]*\\b${baseClass}\\b[^"]*)"`, 'g');
+    return html.replace(classPattern, (match, classes) => {
+      // Check if modifier already exists
+      if (classes.includes(modifier)) {
+        return match;
+      }
+      return `class="${classes} ${modifier}"`;
+    });
+  }
+
+  /**
+   * Format the result
+   */
+  private async formatResult(result: ComponentHTMLResult): Promise<string> {
+    if (!result.found || !result.component) {
+      return `# Component Not Found\n\n${result.error}`;
+    }
+
+    const component = result.component;
+    const template = await readToolFile('get-component-html-result.md');
+
+    // Format modifiers list
+    const modifiersText = component.modifiers.length > 0
+      ? component.modifiers.map(m => `- \`${m}\``).join('\n')
+      : 'No modifiers available';
+
+    // Format elements list
+    const elementsText = component.elements.length > 0
+      ? component.elements.map(e => `- \`${e}\``).join('\n')
+      : 'No sub-elements defined';
+
+    // Use variant HTML if available, otherwise use base example
+    const htmlToShow = result.variantHtml || component.exampleHtml;
+
+    let output = template
+      .replace('{{componentName}}', component.name)
+      .replace('{{exampleHtml}}', htmlToShow)
+      .replace('{{className}}', component.className)
+      .replace('{{type}}', component.type)
+      .replace('{{modifiers}}', modifiersText)
+      .replace('{{elements}}', elementsText)
+      .replace('{{docsUrl}}', component.docsUrl || 'No documentation URL available')
+      .replace('{{description}}', component.description);
+
+    // Add variant info if specified
+    if (result.variant && result.variantHtml) {
+      output += `\n\n## Applied Variant\n- **Variant**: \`${result.variant}\`\n- The HTML above includes the variant modifier class.`;
+    } else if (result.variant && !result.variantHtml) {
+      const availableVariants = component.modifiers
+        .filter(m => m.includes('--'))
+        .map(m => m.split('--')[1])
+        .join(', ');
+      output += `\n\n## Variant Note\nVariant "${result.variant}" not found. Available variants: ${availableVariants || 'none'}`;
+    }
+
+    return output;
+  }
+}
+
+export default GetComponentHtmlTool;
diff --git a/src/tools/data-retrieval/get-layout-utility-tool.ts b/src/tools/data-retrieval/get-layout-utility-tool.ts
new file mode 100644
index 0000000..aaa71b8
--- /dev/null
+++ b/src/tools/data-retrieval/get-layout-utility-tool.ts
@@ -0,0 +1,202 @@
+/**
+ * Get Layout Utility Tool
+ * Returns HTML patterns and guidance for Optics layout utilities
+ */
+
+import { z } from 'zod';
+import Tool, { type ToolInputSchema } from '../tool.js';
+import { components, type Component } from '../../optics-data.js';
+import { readToolFile } from '../../_internal/resource-path.js';
+
+/**
+ * Extended layout utility information
+ */
+const LAYOUT_UTILITY_DETAILS: Record<string, {
+  whenToUse: string;
+  patterns: string[];
+  responsiveModifiers?: string[];
+}> = {
+  stack: {
+    whenToUse: 'Use Stack for vertical layouts with consistent spacing between items. Perfect for forms, card content, navigation lists, and any vertical flow of content.',
+    patterns: [
+      '**Form layout**: Wrap form fields in a stack for consistent vertical spacing',
+      '**Card content**: Use inside cards to space out title, description, and actions',
+      '**Navigation**: Vertical nav items with consistent gaps',
+      '**Article content**: Space out paragraphs and sections'
+    ],
+    responsiveModifiers: ['op-stack--small', 'op-stack--large']
+  },
+  cluster: {
+    whenToUse: 'Use Cluster for horizontal layouts that wrap naturally. Ideal for tags, buttons, badges, and any group of items that should flow and wrap.',
+    patterns: [
+      '**Tag groups**: Display multiple tags that wrap to new lines',
+      '**Button groups**: Group related actions horizontally',
+      '**Badge collections**: Show multiple badges inline',
+      '**Filter chips**: Wrap filter options naturally'
+    ],
+    responsiveModifiers: ['op-cluster--small', 'op-cluster--large']
+  },
+  split: {
+    whenToUse: 'Use Split for two-column layouts where content is pushed to opposite ends. Perfect for headers, footers, and any "left vs right" arrangement.',
+    patterns: [
+      '**Header layout**: Logo on left, navigation on right',
+      '**Card footer**: Metadata on left, actions on right',
+      '**List items**: Label on left, value on right',
+      '**Toolbar**: Title on left, buttons on right'
+    ],
+    responsiveModifiers: []
+  },
+  sidebar: {
+    whenToUse: 'Use Sidebar for layouts with a fixed-width sidebar and flexible main content area.',
+    patterns: [
+      '**Dashboard layout**: Navigation sidebar with main content',
+      '**Settings page**: Menu sidebar with settings panels',
+      '**Documentation**: Table of contents with content area'
+    ],
+    responsiveModifiers: ['op-sidebar--right']
+  },
+  grid: {
+    whenToUse: 'Use Grid for multi-column layouts with equal-width columns. Great for card grids, galleries, and dashboard widgets.',
+    patterns: [
+      '**Card grid**: Display cards in responsive columns',
+      '**Image gallery**: Equal-sized image thumbnails',
+      '**Dashboard widgets**: Arrange dashboard panels',
+      '**Product listing**: E-commerce product grid'
+    ],
+    responsiveModifiers: ['op-grid--2', 'op-grid--3', 'op-grid--4']
+  }
+};
+
+class GetLayoutUtilityTool extends Tool {
+  name = 'get_layout_utility';
+  title = 'Get Layout Utility';
+  description = 'Get HTML patterns and usage guidance for Optics layout utilities (Stack, Cluster, Split, Sidebar, Grid)';
+
+  inputSchema = {
+    utilityType: z.string().describe('Type of layout utility: "stack", "cluster", "split", "sidebar", or "grid"'),
+  };
+
+  async handler(args: ToolInputSchema): Promise<string> {
+    const { utilityType } = args;
+    const result = await this.getLayoutUtility(utilityType.toLowerCase());
+
+    return result;
+  }
+
+  /**
+   * Get layout utility details
+   */
+  private async getLayoutUtility(utilityType: string): Promise<string> {
+    // Find the layout component in optics-data
+    const layoutComponent = components.find(
+      c => c.type === 'layout' && c.name.toLowerCase() === utilityType.toLowerCase()
+    );
+
+    // Get extended details
+    const details = LAYOUT_UTILITY_DETAILS[utilityType];
+
+    if (!layoutComponent && !details) {
+      const availableLayouts = Object.keys(LAYOUT_UTILITY_DETAILS).join(', ');
+      return `# Layout Utility Not Found\n\nUtility "${utilityType}" not found.\n\nAvailable layout utilities: ${availableLayouts}\n\nUse one of these utility types to get detailed information.`;
+    }
+
+    const template = await readToolFile('get-layout-utility-result.md');
+
+    // Build patterns text
+    const patternsText = details?.patterns
+      ? details.patterns.map(p => `- ${p}`).join('\n')
+      : 'No specific patterns documented.';
+
+    // Build example HTML with more detail
+    let exampleHtml = layoutComponent?.exampleHtml || `<div class="op-${utilityType}">...</div>`;
+    
+    // Enhance example HTML based on utility type
+    exampleHtml = this.getEnhancedExample(utilityType, exampleHtml);
+
+    return template
+      .replace('{{utilityName}}', this.capitalize(utilityType))
+      .replace('{{exampleHtml}}', exampleHtml)
+      .replace('{{className}}', layoutComponent?.className || `op-${utilityType}`)
+      .replace('{{description}}', layoutComponent?.description || `Layout utility: op-${utilityType}`)
+      .replace('{{whenToUse}}', details?.whenToUse || 'Use for layout purposes.')
+      .replace('{{patterns}}', patternsText)
+      .replace('{{docsUrl}}', layoutComponent?.docsUrl || `https://docs.optics.rolemodel.design/?path=/docs/layout-${utilityType}--docs`);
+  }
+
+  /**
+   * Get enhanced example HTML for each utility type
+   */
+  private getEnhancedExample(utilityType: string, baseExample: string): string {
+    const examples: Record<string, string> = {
+      stack: `<!-- Vertical stack with consistent spacing -->
+<div class="op-stack">
+  <div>First item</div>
+  <div>Second item</div>
+  <div>Third item</div>
+</div>
+
+<!-- Stack with custom gap using CSS variable -->
+<div class="op-stack" style="--op-stack-gap: var(--op-spacing-lg)">
+  <h2>Title</h2>
+  <p>Description text</p>
+  <button class="btn">Action</button>
+</div>`,
+
+      cluster: `<!-- Horizontal cluster that wraps -->
+<div class="op-cluster">
+  <span class="badge">Tag 1</span>
+  <span class="badge">Tag 2</span>
+  <span class="badge">Tag 3</span>
+</div>
+
+<!-- Button cluster -->
+<div class="op-cluster">
+  <button class="btn btn--primary">Save</button>
+  <button class="btn btn--ghost">Cancel</button>
+</div>`,
+
+      split: `<!-- Split layout: content on opposite ends -->
+<div class="op-split">
+  <div>Left content (logo, title)</div>
+  <div>Right content (actions, nav)</div>
+</div>
+
+<!-- Card footer with split -->
+<footer class="op-split">
+  <span class="text-muted">Last updated: Today</span>
+  <button class="btn btn--small">Edit</button>
+</footer>`,
+
+      sidebar: `<!-- Sidebar layout -->
+<div class="op-sidebar">
+  <aside>
+    <!-- Sidebar content (nav, filters) -->
+    <nav>...</nav>
+  </aside>
+  <main>
+    <!-- Main content area -->
+    <article>...</article>
+  </main>
+</div>`,
+
+      grid: `<!-- Responsive grid -->
+<div class="op-grid">
+  <div class="card">Card 1</div>
+  <div class="card">Card 2</div>
+  <div class="card">Card 3</div>
+  <div class="card">Card 4</div>
+</div>`
+    };
+
+    return examples[utilityType] || baseExample;
+  }
+
+  /**
+   * Capitalize first letter
+   */
+  private capitalize(str: string): string {
+    return str.charAt(0).toUpperCase() + str.slice(1);
+  }
+}
+
+export default GetLayoutUtilityTool;
diff --git a/src/tools/validation/detect-redundant-css-tool.ts b/src/tools/validation/detect-redundant-css-tool.ts
new file mode 100644
index 0000000..29b71ac
--- /dev/null
+++ b/src/tools/validation/detect-redundant-css-tool.ts
@@ -0,0 +1,332 @@
+/**
+ * Detect Redundant CSS Tool
+ * Finds CSS patterns that duplicate existing Optics components
+ */
+
+import { z } from 'zod';
+import Tool, { type ToolInputSchema } from '../tool.js';
+import { components, type Component } from '../../optics-data.js';
+import { readToolFile } from '../../_internal/resource-path.js';
+
+export interface RedundantPattern {
+  cssPattern: string;
+  line?: number;
+  opticsComponent: string;
+  opticsClass: string;
+  confidence: 'high' | 'medium' | 'low';
+  suggestion: string;
+}
+
+export interface DetectionResult {
+  totalPatterns: number;
+  redundantPatterns: RedundantPattern[];
+  recommendations: string[];
+}
+
+/**
+ * CSS patterns that map to Optics components
+ */
+const CSS_PATTERN_MAPPINGS: Array<{
+  pattern: RegExp;
+  component: string;
+  className: string;
+  confidence: 'high' | 'medium' | 'low';
+  description: string;
+}> = [
+  // Button patterns
+  {
+    pattern: /display:\s*inline-flex.*align-items:\s*center.*justify-content:\s*center/s,
+    component: 'Button',
+    className: 'op-button',
+    confidence: 'medium',
+    description: 'Inline-flex centering pattern matches Button component'
+  },
+  {
+    pattern: /padding:\s*[\d.]+(?:px|rem|em)\s+[\d.]+(?:px|rem|em).*border-radius.*cursor:\s*pointer/s,
+    component: 'Button',
+    className: 'op-button',
+    confidence: 'medium',
+    description: 'Button-like padding, border-radius, and cursor'
+  },
+  // Card patterns
+  {
+    pattern: /border-radius.*box-shadow.*padding.*background/s,
+    component: 'Card',
+    className: 'op-card',
+    confidence: 'medium',
+    description: 'Card-like container with shadow and padding'
+  },
+  {
+    pattern: /\.card\s*\{/i,
+    component: 'Card',
+    className: 'op-card',
+    confidence: 'high',
+    description: 'Class named "card" - use Optics Card component'
+  },
+  // Alert/notification patterns
+  {
+    pattern: /\.alert\s*\{/i,
+    component: 'Alert',
+    className: 'op-alert',
+    confidence: 'high',
+    description: 'Class named "alert" - use Optics Alert component'
+  },
+  {
+    pattern: /border-left:\s*[\d.]+(?:px|rem|em)\s+solid.*padding.*background/s,
+    component: 'Alert',
+    className: 'op-alert',
+    confidence: 'medium',
+    description: 'Alert-like left border accent pattern'
+  },
+  // Badge patterns
+  {
+    pattern: /\.badge\s*\{/i,
+    component: 'Badge',
+    className: 'op-badge',
+    confidence: 'high',
+    description: 'Class named "badge" - use Optics Badge component'
+  },
+  {
+    pattern: /display:\s*inline.*padding:\s*[\d.]+(?:px|rem|em).*border-radius:\s*(?:9999px|50%|100px)/s,
+    component: 'Badge',
+    className: 'op-badge',
+    confidence: 'medium',
+    description: 'Pill-shaped inline element matches Badge'
+  },
+  // Modal patterns
+  {
+    pattern: /\.modal\s*\{/i,
+    component: 'Modal',
+    className: 'op-modal',
+    confidence: 'high',
+    description: 'Class named "modal" - use Optics Modal component'
+  },
+  {
+    pattern: /position:\s*fixed.*inset:\s*0.*background.*rgba?\([^)]*0\.[0-9]/s,
+    component: 'Modal',
+    className: 'op-modal',
+    confidence: 'medium',
+    description: 'Fixed overlay pattern matches Modal backdrop'
+  },
+  // Form input patterns
+  {
+    pattern: /\.input\s*\{/i,
+    component: 'Form',
+    className: 'op-input',
+    confidence: 'high',
+    description: 'Class named "input" - use Optics Form input'
+  },
+  {
+    pattern: /border:\s*1px\s+solid.*padding.*border-radius.*:focus/s,
+    component: 'Form',
+    className: 'op-input',
+    confidence: 'medium',
+    description: 'Input-like border and focus styles'
+  },
+  // Layout patterns - Stack
+  {
+    pattern: /display:\s*flex.*flex-direction:\s*column.*gap/s,
+    component: 'Stack',
+    className: 'op-stack',
+    confidence: 'medium',
+    description: 'Vertical flex with gap - use Stack layout'
+  },
+  // Layout patterns - Cluster
+  {
+    pattern: /display:\s*flex.*flex-wrap:\s*wrap.*gap/s,
+    component: 'Cluster',
+    className: 'op-cluster',
+    confidence: 'medium',
+    description: 'Wrapping flex with gap - use Cluster layout'
+  },
+  // Layout patterns - Split
+  {
+    pattern: /display:\s*flex.*justify-content:\s*space-between/s,
+    component: 'Split',
+    className: 'op-split',
+    confidence: 'medium',
+    description: 'Space-between flex - use Split layout'
+  },
+  // Spinner/loading patterns
+  {
+    pattern: /\.spinner\s*\{/i,
+    component: 'Spinner',
+    className: 'op-spinner',
+    confidence: 'high',
+    description: 'Class named "spinner" - use Optics Spinner'
+  },
+  {
+    pattern: /@keyframes\s+spin|animation:.*rotate|animation:.*spin/i,
+    component: 'Spinner',
+    className: 'op-spinner',
+    confidence: 'medium',
+    description: 'Rotation animation - consider Optics Spinner'
+  },
+  // Table patterns
+  {
+    pattern: /\.table\s*\{/i,
+    component: 'Table',
+    className: 'op-table',
+    confidence: 'high',
+    description: 'Class named "table" - use Optics Table'
+  },
+  // Tab patterns
+  {
+    pattern: /\.tabs?\s*\{/i,
+    component: 'Tab',
+    className: 'op-tabs',
+    confidence: 'high',
+    description: 'Class named "tab(s)" - use Optics Tab component'
+  },
+  // Tooltip patterns
+  {
+    pattern: /\.tooltip\s*\{/i,
+    component: 'Tooltip',
+    className: 'op-tooltip',
+    confidence: 'high',
+    description: 'Class named "tooltip" - use Optics Tooltip'
+  },
+  {
+    pattern: /position:\s*absolute.*::(?:before|after).*content:/s,
+    component: 'Tooltip',
+    className: 'op-tooltip',
+    confidence: 'low',
+    description: 'Pseudo-element positioning may be tooltip-like'
+  },
+];
+
+class DetectRedundantCssTool extends Tool {
+  name = 'detect_redundant_css';
+  title = 'Detect Redundant CSS';
+  description = 'Find CSS patterns that duplicate existing Optics components and suggest replacements';
+
+  inputSchema = {
+    css: z.string().describe('CSS code to analyze for redundant patterns'),
+  };
+
+  async handler(args: ToolInputSchema): Promise<string> {
+    const { css } = args;
+    const result = this.detectRedundantPatterns(css);
+    const formatted = await this.formatResult(result);
+
+    return formatted;
+  }
+
+  /**
+   * Detect redundant CSS patterns
+   */
+  private detectRedundantPatterns(css: string): DetectionResult {
+    const redundantPatterns: RedundantPattern[] = [];
+    const lines = css.split('\n');
+
+    for (const mapping of CSS_PATTERN_MAPPINGS) {
+      const match = css.match(mapping.pattern);
+      if (match) {
+        // Find approximate line number
+        let lineNumber: number | undefined;
+        const matchIndex = match.index || 0;
+        const beforeMatch = css.substring(0, matchIndex);
+        lineNumber = beforeMatch.split('\n').length;
+
+        // Check if component exists in Optics
+        const opticsComponent = components.find(
+          c => c.name.toLowerCase() === mapping.component.toLowerCase()
+        );
+
+        redundantPatterns.push({
+          cssPattern: match[0].substring(0, 100) + (match[0].length > 100 ? '...' : ''),
+          line: lineNumber,
+          opticsComponent: mapping.component,
+          opticsClass: opticsComponent?.className || mapping.className,
+          confidence: mapping.confidence,
+          suggestion: mapping.description
+        });
+      }
+    }
+
+    // Generate recommendations
+    const recommendations = this.generateRecommendations(redundantPatterns);
+
+    return {
+      totalPatterns: CSS_PATTERN_MAPPINGS.length,
+      redundantPatterns,
+      recommendations
+    };
+  }
+
+  /**
+   * Generate recommendations based on findings
+   */
+  private generateRecommendations(patterns: RedundantPattern[]): string[] {
+    const recommendations: string[] = [];
+
+    if (patterns.length === 0) {
+      recommendations.push('No obvious redundant patterns detected. Your CSS appears to be using custom styles appropriately.');
+      recommendations.push('Consider using `list_components` to see all available Optics components.');
+      return recommendations;
+    }
+
+    // Group by component
+    const byComponent = new Map<string, RedundantPattern[]>();
+    for (const pattern of patterns) {
+      const existing = byComponent.get(pattern.opticsComponent) || [];
+      existing.push(pattern);
+      byComponent.set(pattern.opticsComponent, existing);
+    }
+
+    for (const [component, componentPatterns] of byComponent) {
+      const highConfidence = componentPatterns.filter(p => p.confidence === 'high');
+      const opticsComp = components.find(c => c.name.toLowerCase() === component.toLowerCase());
+
+      if (highConfidence.length > 0) {
+        recommendations.push(
+          `**${component}**: Found ${highConfidence.length} pattern(s) that should use \`${opticsComp?.className || `op-${component.toLowerCase()}`}\` class.`
+        );
+      } else {
+        recommendations.push(
+          `**${component}**: Found ${componentPatterns.length} pattern(s) that may be replaceable with the Optics ${component} component.`
+        );
+      }
+
+      if (opticsComp) {
+        recommendations.push(`  - Use \`get_component_info\` with "${component}" for usage details.`);
+      }
+    }
+
+    recommendations.push('');
+    recommendations.push('Run `list_components` to see all available Optics components and their classes.');
+
+    return recommendations;
+  }
+
+  /**
+   * Format the detection result
+   */
+  private async formatResult(result: DetectionResult): Promise<string> {
+    const template = await readToolFile('detect-redundant-css-result.md');
+
+    let findingsText = '';
+    if (result.redundantPatterns.length === 0) {
+      findingsText = 'No redundant patterns detected.';
+    } else {
+      for (const pattern of result.redundantPatterns) {
+        findingsText += `### ${pattern.opticsComponent} (${pattern.confidence} confidence)\n`;
+        if (pattern.line) {
+          findingsText += `- **Line**: ~${pattern.line}\n`;
+        }
+        findingsText += `- **Pattern**: \`${pattern.cssPattern.replace(/\n/g, ' ').trim()}\`\n`;
+        findingsText += `- **Optics class**: \`${pattern.opticsClass}\`\n`;
+        findingsText += `- **Suggestion**: ${pattern.suggestion}\n\n`;
+      }
+    }
+
+    return template
+      .replace('{{totalPatterns}}', result.totalPatterns.toString())
+      .replace('{{redundantCount}}', result.redundantPatterns.length.toString())
+      .replace('{{replacementCount}}', result.redundantPatterns.filter(p => p.confidence === 'high').length.toString())
+      .replace('{{findings}}', findingsText)
+      .replace('{{recommendations}}', result.recommendations.join('\n'));
+  }
+}
+
+export default DetectRedundantCssTool;
diff --git a/src/tools/validation/validate-color-pairing-tool.ts b/src/tools/validation/validate-color-pairing-tool.ts
new file mode 100644
index 0000000..b0b918a
--- /dev/null
+++ b/src/tools/validation/validate-color-pairing-tool.ts
@@ -0,0 +1,240 @@
+/**
+ * Validate Color Pairing Tool
+ * Checks if background/text color pairs follow Optics design system rules
+ */
+
+import { z } from 'zod';
+import Tool, { type ToolInputSchema } from '../tool.js';
+import { designTokens, type DesignToken } from '../../optics-data.js';
+import { checkContrast, type ContrastResult } from '../../utils/color.js';
+import { readToolFile } from '../../_internal/resource-path.js';
+
+export interface ColorPairingResult {
+  backgroundToken: string;
+  textToken: string;
+  backgroundValue: string;
+  textValue: string;
+  contrast: ContrastResult | null;
+  isValidPairing: boolean;
+  pairingRules: string[];
+  recommendation?: string;
+}
+
+/**
+ * Optics color pairing rules:
+ * - Primary backgrounds should use white or light text
+ * - Neutral backgrounds should use appropriate contrast text
+ * - Danger/warning colors have specific pairing requirements
+ * - Surface colors pair with content colors
+ */
+const COLOR_PAIRING_RULES: Record<string, string[]> = {
+  'color-primary': ['color-white', 'color-neutral-100', 'color-neutral-200'],
+  'color-danger': ['color-white', 'color-neutral-100'],
+  'color-warning': ['color-neutral-900', 'color-neutral-800', 'color-black'],
+  'color-success': ['color-white', 'color-neutral-100'],
+  'color-info': ['color-white', 'color-neutral-100'],
+  'color-neutral-900': ['color-white', 'color-neutral-100', 'color-neutral-200'],
+  'color-neutral-800': ['color-white', 'color-neutral-100', 'color-neutral-200'],
+  'color-neutral-100': ['color-neutral-900', 'color-neutral-800', 'color-black'],
+  'color-neutral-200': ['color-neutral-900', 'color-neutral-800', 'color-black'],
+  'color-white': ['color-neutral-900', 'color-neutral-800', 'color-neutral-700', 'color-black', 'color-primary'],
+};
+
+class ValidateColorPairingTool extends Tool {
+  name = 'validate_color_pairing';
+  title = 'Validate Color Pairing';
+  description = 'Check if background/text color pairs follow Optics design system rules and meet WCAG contrast requirements';
+
+  inputSchema = {
+    backgroundToken: z.string().describe('Background color token name (e.g., "color-primary", "color-neutral-100")'),
+    textToken: z.string().describe('Text/foreground color token name (e.g., "color-white", "color-neutral-900")'),
+  };
+
+  async handler(args: ToolInputSchema): Promise<string> {
+    const { backgroundToken, textToken } = args;
+    const result = this.validateColorPairing(backgroundToken, textToken, designTokens);
+    const formatted = await this.formatResult(result);
+
+    return formatted;
+  }
+
+  /**
+   * Validate a color pairing
+   */
+  private validateColorPairing(
+    backgroundToken: string,
+    textToken: string,
+    tokens: DesignToken[]
+  ): ColorPairingResult {
+    const bgToken = tokens.find(t => t.name === backgroundToken);
+    const txtToken = tokens.find(t => t.name === textToken);
+
+    if (!bgToken || !txtToken) {
+      const missing = !bgToken ? backgroundToken : textToken;
+      return {
+        backgroundToken,
+        textToken,
+        backgroundValue: bgToken?.value || '',
+        textValue: txtToken?.value || '',
+        contrast: null,
+        isValidPairing: false,
+        pairingRules: [],
+        recommendation: `Token "${missing}" not found. Use search_tokens to find available color tokens.`
+      };
+    }
+
+    // Check contrast
+    const contrast = checkContrast(txtToken.value, bgToken.value);
+
+    // Check pairing rules
+    const pairingRules = this.getPairingRules(backgroundToken, textToken);
+    const followsRules = pairingRules.length > 0;
+
+    // A valid pairing must have sufficient contrast AND follow design rules (if rules exist)
+    const hasContrast = contrast ? contrast.wcagAA : false;
+    const isValidPairing = hasContrast && (followsRules || !this.hasDefinedRules(backgroundToken));
+
+    let recommendation: string | undefined;
+    if (!isValidPairing) {
+      recommendation = this.getRecommendation(backgroundToken, textToken, hasContrast, followsRules, tokens);
+    }
+
+    return {
+      backgroundToken,
+      textToken,
+      backgroundValue: bgToken.value,
+      textValue: txtToken.value,
+      contrast,
+      isValidPairing,
+      pairingRules,
+      recommendation
+    };
+  }
+
+  /**
+   * Get applicable pairing rules for a background color
+   */
+  private getPairingRules(backgroundToken: string, textToken: string): string[] {
+    const rules: string[] = [];
+
+    // Check direct rules
+    for (const [bgPattern, allowedText] of Object.entries(COLOR_PAIRING_RULES)) {
+      if (backgroundToken.includes(bgPattern) || backgroundToken === bgPattern) {
+        if (allowedText.some(t => textToken.includes(t) || textToken === t)) {
+          rules.push(`✓ "${textToken}" is a recommended pairing for "${bgPattern}" backgrounds`);
+        }
+      }
+    }
+
+    return rules;
+  }
+
+  /**
+   * Check if background has defined pairing rules
+   */
+  private hasDefinedRules(backgroundToken: string): boolean {
+    return Object.keys(COLOR_PAIRING_RULES).some(
+      pattern => backgroundToken.includes(pattern) || backgroundToken === pattern
+    );
+  }
+
+  /**
+   * Get recommendation for invalid pairing
+   */
+  private getRecommendation(
+    backgroundToken: string,
+    textToken: string,
+    hasContrast: boolean,
+    followsRules: boolean,
+    tokens: DesignToken[]
+  ): string {
+    const recommendations: string[] = [];
+
+    if (!hasContrast) {
+      recommendations.push('Contrast ratio is below WCAG AA requirements (4.5:1 for normal text).');
+    }
+
+    if (!followsRules && this.hasDefinedRules(backgroundToken)) {
+      // Find recommended pairings
+      for (const [bgPattern, allowedText] of Object.entries(COLOR_PAIRING_RULES)) {
+        if (backgroundToken.includes(bgPattern) || backgroundToken === bgPattern) {
+          recommendations.push(`Recommended text colors for this background: ${allowedText.join(', ')}`);
+          break;
+        }
+      }
+    }
+
+    // Suggest alternatives with good contrast
+    if (!hasContrast) {
+      const alternatives = this.findContrastingTokens(backgroundToken, tokens);
+      if (alternatives.length > 0) {
+        recommendations.push(`Alternative tokens with sufficient contrast: ${alternatives.slice(0, 3).join(', ')}`);
+      }
+    }
+
+    return recommendations.join('\n');
+  }
+
+  /**
+   * Find tokens that have sufficient contrast with the background
+   */
+  private findContrastingTokens(backgroundToken: string, tokens: DesignToken[]): string[] {
+    const bgToken = tokens.find(t => t.name === backgroundToken);
+    if (!bgToken) return [];
+
+    const contrasting: string[] = [];
+    const colorTokens = tokens.filter(t => 
+      t.category === 'color' && 
+      !t.name.includes('-h') && 
+      !t.name.includes('-s') && 
+      !t.name.includes('-l') &&
+      !t.name.includes('-original')
+    );
+
+    for (const token of colorTokens) {
+      const contrast = checkContrast(token.value, bgToken.value);
+      if (contrast && contrast.wcagAA) {
+        contrasting.push(token.name);
+      }
+    }
+
+    return contrasting;
+  }
+
+  /**
+   * Format the validation result
+   */
+  private async formatResult(result: ColorPairingResult): Promise<string> {
+    if (!result.contrast && result.recommendation) {
+      const template = await readToolFile('validate-color-pairing-error.md');
+      return template
+        .replace('{{backgroundToken}}', result.backgroundToken)
+        .replace('{{textToken}}', result.textToken)
+        .replace('{{reason}}', 'Unable to calculate contrast. Tokens may not be valid color values.')
+        .replace('{{suggestion}}', result.recommendation);
+    }
+
+    const template = await readToolFile('validate-color-pairing-result.md');
+    
+    const pairingRulesText = result.pairingRules.length > 0 
+      ? result.pairingRules.join('\n') 
+      : 'No specific pairing rules defined for this background color.';
+
+    const resultText = result.isValidPairing
+      ? '✓ **Valid Pairing** - This color combination meets contrast requirements and follows design guidelines.'
+      : `✗ **Invalid Pairing** - ${result.recommendation || 'This combination does not meet requirements.'}`;
+
+    return template
+      .replace('{{backgroundToken}}', result.backgroundToken)
+      .replace('{{backgroundValue}}', result.backgroundValue)
+      .replace('{{textToken}}', result.textToken)
+      .replace('{{textValue}}', result.textValue)
+      .replace('{{contrastRatio}}', result.contrast?.ratio.toString() || 'N/A')
+      .replace('{{wcagAA}}', result.contrast?.wcagAA ? '✓ Pass' : '✗ Fail')
+      .replace('{{wcagAAA}}', result.contrast?.wcagAAA ? '✓ Pass' : '✗ Fail')
+      .replace('{{pairingRules}}', pairingRulesText)
+      .replace('{{result}}', resultText);
+  }
+}
+
+export default ValidateColorPairingTool;

From 6a7df988ada27d2aaa7df85bcc386c992cec5853 Mon Sep 17 00:00:00 2001
From: Dallas Peters <dallaspeters@gmail.com>
Date: Mon, 9 Feb 2026 13:58:34 -0600
Subject: [PATCH 21/28] Resolve merge conflict in src/index.ts by consolidating
 tool imports and array registration

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 src/index.ts | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/index.ts b/src/index.ts
index e127eb6..634fbfb 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -59,6 +59,8 @@ import GetColorScaleTool from './tools/data-retrieval/get-color-scale-tool.js';
 import CalculateContrastTool from './tools/calculation/calculate-contrast-tool.js';
 import CalculateHslTokensTool from './tools/calculation/calculate-hsl-tokens-tool.js';
 
+// Tools
+
 /**
  * Create and configure the MCP server
  */

From 1f002082153d31e2e4f7ec42587ea0f25bc4afa8 Mon Sep 17 00:00:00 2001
From: Dallas Peters <dallaspeters@gmail.com>
Date: Mon, 9 Feb 2026 14:00:32 -0600
Subject: [PATCH 22/28] Rebase: keep our versions of index.ts and
 replace-hard-coded-values-tool.ts

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 src/index.ts | 210 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 210 insertions(+)

diff --git a/src/index.ts b/src/index.ts
index 634fbfb..2f71b4c 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -12,6 +12,17 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import type { ListPromptsRequestSchema, GetPromptRequestSchema } from "@modelcontextprotocol/sdk/types"
 import { z } from 'zod';
 import { designTokens } from './optics-data.js';
+<<<<<<< HEAD
+=======
+import { generateTheme } from './tools/theme-generator.js';
+import { validateTokenUsage, formatValidationReport } from './tools/validate.js';
+
+import { checkTokenContrast, formatContrastResult } from './tools/accessibility.js';
+import { suggestTokenMigration, formatMigrationSuggestions } from './tools/migration.js';
+import { generateComponentScaffold, formatScaffoldOutput } from './tools/scaffold.js';
+import { generateStickerSheet, formatStickerSheet } from './tools/sticker-sheet.js';
+
+>>>>>>> a8fdcbb (Extract the replace hard coded values tool (#26))
 // Resources
 import * as systemOverview from './resources/system-overview.js';
 import * as documentationSection from './resources/documentation/section.js';
@@ -42,6 +53,7 @@ import ListComponentsTool from './tools/list-components-tool.js';
 import GetComponentInfoTool from './tools/get-component-info-tool.js';
 import GetComponentTokensTool from './tools/get-component-tokens-tool.js';
 import SearchDocumentationTool from './tools/search-documentation-tool.js';
+<<<<<<< HEAD
 import GenerateThemeTool from './tools/generate-theme-tool.js';
 import ValidateTokenUsageTool from './tools/validate-token-usage-tool.js';
 import ReplaceHardCodedValuesTool from './tools/replace-hard-coded-values-tool.js';
@@ -60,6 +72,9 @@ import CalculateContrastTool from './tools/calculation/calculate-contrast-tool.j
 import CalculateHslTokensTool from './tools/calculation/calculate-hsl-tokens-tool.js';
 
 // Tools
+=======
+import ReplaceHardCodedValuesTool from './tools/replace-hard-coded-values-tool.js';
+>>>>>>> a8fdcbb (Extract the replace hard coded values tool (#26))
 
 /**
  * Create and configure the MCP server
@@ -219,6 +234,7 @@ const tools = [
   new GetComponentInfoTool(),
   new GetComponentTokensTool(),
   new SearchDocumentationTool(),
+<<<<<<< HEAD
   new GenerateThemeTool(),
   new ValidateTokenUsageTool(),
   new ReplaceHardCodedValuesTool(),
@@ -234,6 +250,9 @@ const tools = [
   new GetColorScaleTool(),
   new CalculateContrastTool(),
   new CalculateHslTokensTool(),
+=======
+  new ReplaceHardCodedValuesTool()
+>>>>>>> a8fdcbb (Extract the replace hard coded values tool (#26))
 ]
 
 tools.forEach((tool) => {
@@ -260,6 +279,197 @@ tools.forEach((tool) => {
 })
 
 /**
+<<<<<<< HEAD
+=======
+ * Tool: Generate Theme
+ */
+server.registerTool(
+  'generate_theme',
+  {
+    title: 'Generate Theme',
+    description: 'Generate a custom Optics theme with CSS variable overrides',
+    inputSchema: {
+      brandName: z.string().describe('Name of the brand/theme (e.g., "Acme Corp")'),
+      primary: z.string().describe('Primary brand color (hex, e.g., "#0066CC")'),
+      secondary: z.string().optional().describe('Secondary color (hex, optional)'),
+    },
+  },
+  async ({ brandName, primary, secondary }) => {
+    const brandColors = {
+      primary,
+      secondary,
+    };
+
+    const theme = generateTheme(brandName, brandColors);
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `# ${brandName} Theme Generated\n\n## CSS Variables\n\n\`\`\`css\n${theme.cssVariables}\n\`\`\`\n\n## Figma Variables\n\nSave this as \`figma-variables.json\`:\n\n\`\`\`json\n${theme.figmaVariables}\n\`\`\`\n\n## Summary\n\n- **Total tokens**: ${theme.tokens.length}\n- **Colors**: ${theme.tokens.filter(t => t.category === 'color').length}\n- **Typography**: ${theme.tokens.filter(t => t.category === 'typography').length}\n- **Spacing**: ${theme.tokens.filter(t => t.category === 'spacing').length}\n\n${theme.documentation}`,
+        },
+      ],
+    };
+  }
+);
+
+/**
+ * Tool: Validate Token Usage
+ */
+server.registerTool(
+  'validate_token_usage',
+  {
+    title: 'Validate Token Usage',
+    description: 'Validate code for hard-coded values that should use design tokens',
+    inputSchema: {
+      code: z.string().describe('CSS or component code to validate'),
+    },
+  },
+  async ({ code }) => {
+    const report = validateTokenUsage(code, designTokens);
+    const formatted = formatValidationReport(report);
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: formatted,
+        },
+      ],
+    };
+  }
+);
+
+
+
+/**
+ * Tool: Check Contrast
+ */
+server.registerTool(
+  'check_contrast',
+  {
+    title: 'Check Contrast',
+    description: 'Check WCAG contrast ratio between two color tokens',
+    inputSchema: {
+      foregroundToken: z.string().describe('Foreground color token name'),
+      backgroundToken: z.string().describe('Background color token name'),
+    },
+  },
+  async ({ foregroundToken, backgroundToken }) => {
+    const result = checkTokenContrast(foregroundToken, backgroundToken, designTokens);
+    const formatted = formatContrastResult(result);
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: formatted,
+        },
+      ],
+    };
+  }
+);
+
+/**
+ * Tool: Suggest Token Migration
+ */
+server.registerTool(
+  'suggest_token_migration',
+  {
+    title: 'Suggest Token Migration',
+    description: 'Suggest design tokens for a hard-coded value',
+    inputSchema: {
+      value: z.string().describe('Hard-coded value to find tokens for (e.g., "#0066CC", "16px")'),
+      category: z.string().optional().describe('Optional category filter (color, spacing, typography)'),
+    },
+  },
+  async ({ value, category }) => {
+    const suggestion = suggestTokenMigration(value, designTokens, category);
+    const formatted = formatMigrationSuggestions(suggestion);
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: formatted,
+        },
+      ],
+    };
+  }
+);
+
+/**
+ * Tool: Generate Component Scaffold
+ */
+server.registerTool(
+  'generate_component_scaffold',
+  {
+    title: 'Generate Component Scaffold',
+    description: 'Generate a React component scaffold with proper token usage',
+    inputSchema: {
+      componentName: z.string().describe('Name of the component (e.g., "Alert", "Card")'),
+      description: z.string().describe('Brief description of the component'),
+      tokens: z.array(z.string()).describe('List of token names the component should use'),
+    },
+  },
+  async ({ componentName, description, tokens }) => {
+    const scaffold = generateComponentScaffold(
+      componentName,
+      description,
+      tokens,
+      designTokens
+    );
+    const formatted = formatScaffoldOutput(scaffold);
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: formatted,
+        },
+      ],
+    };
+  }
+);
+
+/**
+ * Tool: Generate Sticker Sheet
+ */
+server.registerTool(
+  'generate_sticker_sheet',
+  {
+    title: 'Generate Sticker Sheet',
+    description: 'Generate a visual style guide with color swatches and component examples',
+    inputSchema: {
+      framework: z.enum(['react', 'vue', 'svelte', 'html']).optional().describe('Target framework (default: react)'),
+      includeColors: z.boolean().optional().describe('Include color swatches (default: true)'),
+      includeTypography: z.boolean().optional().describe('Include typography specimens (default: true)'),
+      includeComponents: z.boolean().optional().describe('Include component examples (default: true)'),
+    },
+  },
+  async ({ framework, includeColors, includeTypography, includeComponents }) => {
+    const options = {
+      framework: framework ?? 'react',
+      includeColors: includeColors ?? true,
+      includeTypography: includeTypography ?? true,
+      includeComponents: includeComponents ?? true,
+    };
+    const sheet = generateStickerSheet(designTokens, components, options);
+    const formatted = formatStickerSheet(sheet);
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: formatted,
+        },
+      ],
+    };
+  }
+);
+
+/**
+>>>>>>> a8fdcbb (Extract the replace hard coded values tool (#26))
  * Start the server
  */
 async function main() {

From 261ef2fc0233b9fb04fd8ccdee16291d943e2a98 Mon Sep 17 00:00:00 2001
From: Dallas Peters <dallaspeters@gmail.com>
Date: Mon, 9 Feb 2026 14:00:43 -0600
Subject: [PATCH 23/28] Rebase: keep our versions of resource-path, index.ts,
 generate-theme-tool

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 src/tools/check-contrast-error.md             |  7 +++
 src/tools/check-contrast-result.md            |  9 +++
 .../generate-component-scaffold-usage.md      | 23 +++++++
 .../generate-sticker-sheet-instructions.md    | 22 +++++++
 src/tools/generate-theme-instructions.md      | 63 +++++++++++++++++++
 src/tools/generate-theme-output.md            | 24 +++++++
 src/tools/suggest-token-migration-header.md   |  5 ++
 src/tools/suggest-token-migration-none.md     |  6 ++
 src/tools/validate-token-usage-header.md      |  7 +++
 src/tools/validate-token-usage-valid.md       |  7 +++
 10 files changed, 173 insertions(+)
 create mode 100644 src/tools/check-contrast-error.md
 create mode 100644 src/tools/check-contrast-result.md
 create mode 100644 src/tools/generate-component-scaffold-usage.md
 create mode 100644 src/tools/generate-sticker-sheet-instructions.md
 create mode 100644 src/tools/generate-theme-instructions.md
 create mode 100644 src/tools/generate-theme-output.md
 create mode 100644 src/tools/suggest-token-migration-header.md
 create mode 100644 src/tools/suggest-token-migration-none.md
 create mode 100644 src/tools/validate-token-usage-header.md
 create mode 100644 src/tools/validate-token-usage-valid.md

diff --git a/src/tools/check-contrast-error.md b/src/tools/check-contrast-error.md
new file mode 100644
index 0000000..fbaecf2
--- /dev/null
+++ b/src/tools/check-contrast-error.md
@@ -0,0 +1,7 @@
+# Contrast Check Result
+
+**Foreground**: {{foregroundToken}} (`{{foregroundValue}}`)
+**Background**: {{backgroundToken}} (`{{backgroundValue}}`)
+
+✗ Unable to calculate contrast
+**Reason**: {{reason}}
diff --git a/src/tools/check-contrast-result.md b/src/tools/check-contrast-result.md
new file mode 100644
index 0000000..06f3fab
--- /dev/null
+++ b/src/tools/check-contrast-result.md
@@ -0,0 +1,9 @@
+# Contrast Check Result
+
+**Foreground**: {{foregroundToken}} (`{{foregroundValue}}`)
+**Background**: {{backgroundToken}} (`{{backgroundValue}}`)
+
+**Contrast Ratio**: {{contrastRatio}}:1
+**WCAG AA**: {{wcagAA}}
+**WCAG AAA**: {{wcagAAA}}
+**Score**: {{score}}
diff --git a/src/tools/generate-component-scaffold-usage.md b/src/tools/generate-component-scaffold-usage.md
new file mode 100644
index 0000000..8c8abec
--- /dev/null
+++ b/src/tools/generate-component-scaffold-usage.md
@@ -0,0 +1,23 @@
+# {{componentName}} Usage
+
+## Import
+
+```typescript
+import { {{componentName}} } from './components/{{componentName}}';
+```
+
+## Basic Usage
+
+```tsx
+<{{componentName}}>
+  Your content here
+</{{componentName}}>
+```
+
+## With Custom ClassName
+
+```tsx
+<{{componentName}} className="custom-class">
+  Your content here
+</{{componentName}}>
+```
diff --git a/src/tools/generate-sticker-sheet-instructions.md b/src/tools/generate-sticker-sheet-instructions.md
new file mode 100644
index 0000000..f3dfd40
--- /dev/null
+++ b/src/tools/generate-sticker-sheet-instructions.md
@@ -0,0 +1,22 @@
+# Optics Sticker Sheet - {{framework}}
+
+This sticker sheet provides a visual reference for all Optics design tokens and components.
+
+## Usage
+
+1. Copy the component code below into your {{framework}} project
+2. Copy the CSS styles into your stylesheet
+3. Import and use the components in your app
+4. Replace placeholders with actual component implementations
+
+## Files Generated
+
+- **Component Code**: Ready-to-use {{framework}} components
+- **Styles**: CSS using Optics design tokens
+- **Examples**: Visual specimens of colors, typography, and components
+
+## Next Steps
+
+- Customize the examples to match your specific components
+- Add interactive states (hover, focus, disabled)
+- Include additional token categories as needed
diff --git a/src/tools/generate-theme-instructions.md b/src/tools/generate-theme-instructions.md
new file mode 100644
index 0000000..ff891d2
--- /dev/null
+++ b/src/tools/generate-theme-instructions.md
@@ -0,0 +1,63 @@
+# {{themeName}} Theme
+
+## Overview
+This theme was generated by Optics MCP and uses the Optics Design System tokens.
+
+## Step 1: Install Optics Design System
+
+### Option A: Via npm (Recommended)
+```bash
+npm install @rolemodel/optics
+```
+
+Then import in your CSS:
+```css
+@import "@rolemodel/optics/dist/optics.css";
+```
+
+### Option B: Via CDN (jsDelivr)
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@rolemodel/optics@latest/dist/optics.css">
+```
+
+### Option C: Via unpkg
+```html
+<link rel="stylesheet" href="https://unpkg.com/@rolemodel/optics@latest/dist/optics.css">
+```
+
+## Step 2: Add Your Custom Theme Overrides
+
+Create a `theme.css` file with the custom HSL color values below and load it AFTER Optics:
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@rolemodel/optics@latest/dist/optics.css">
+<link rel="stylesheet" href="./theme.css">
+```
+
+## Token Summary
+
+{{tokenSummary}}
+
+## Step 3: Using Optics Components
+
+**IMPORTANT:** Optics has pre-built components with specific HTML structure and CSS classes.
+
+Do NOT make up CSS classes. Use the actual Optics components and their documentation:
+
+**Component Documentation:** https://docs.optics.rolemodel.design
+
+Your custom theme will automatically apply to all Optics components through the HSL base values.
+
+### Example: Using an Optics Button
+Refer to the Optics documentation for the actual button HTML structure and CSS classes.
+Your theme colors will apply automatically through the `--op-color-primary-*` variables.
+
+### Figma Variables
+Import the `figma-variables.json` file into Figma:
+1. Open your Figma file
+2. Go to Variables panel
+3. Import → Select `figma-variables.json`
+
+## Token Categories
+
+{{tokenCategories}}
diff --git a/src/tools/generate-theme-output.md b/src/tools/generate-theme-output.md
new file mode 100644
index 0000000..a34d95a
--- /dev/null
+++ b/src/tools/generate-theme-output.md
@@ -0,0 +1,24 @@
+# {{brandName}} Theme Generated
+
+## CSS Variables
+
+```css
+{{cssVariables}}
+```
+
+## Figma Variables
+
+Save this as `figma-variables.json`:
+
+```json
+{{figmaVariables}}
+```
+
+## Summary
+
+- **Total tokens**: {{totalTokens}}
+- **Colors**: {{colorTokens}}
+- **Typography**: {{typographyTokens}}
+- **Spacing**: {{spacingTokens}}
+
+{{documentation}}
diff --git a/src/tools/suggest-token-migration-header.md b/src/tools/suggest-token-migration-header.md
new file mode 100644
index 0000000..20db436
--- /dev/null
+++ b/src/tools/suggest-token-migration-header.md
@@ -0,0 +1,5 @@
+# Token Migration Suggestions
+
+**Input Value**: `{{inputValue}}`
+
+## Suggested Tokens
diff --git a/src/tools/suggest-token-migration-none.md b/src/tools/suggest-token-migration-none.md
new file mode 100644
index 0000000..c0a5d3c
--- /dev/null
+++ b/src/tools/suggest-token-migration-none.md
@@ -0,0 +1,6 @@
+# Token Migration Suggestions
+
+**Input Value**: `{{inputValue}}`
+
+No suitable tokens found for this value.
+Consider adding a new token to your design system.
diff --git a/src/tools/validate-token-usage-header.md b/src/tools/validate-token-usage-header.md
new file mode 100644
index 0000000..6ccc5b4
--- /dev/null
+++ b/src/tools/validate-token-usage-header.md
@@ -0,0 +1,7 @@
+# Token Validation Report
+
+**Status**: {{status}}
+**Issues**: {{issueCount}}
+**Values Checked**: {{totalChecked}}
+
+## Issues
diff --git a/src/tools/validate-token-usage-valid.md b/src/tools/validate-token-usage-valid.md
new file mode 100644
index 0000000..eaa5b43
--- /dev/null
+++ b/src/tools/validate-token-usage-valid.md
@@ -0,0 +1,7 @@
+# Token Validation Report
+
+**Status**: ✓ Valid
+**Issues**: 0
+**Values Checked**: {{totalChecked}}
+
+✓ No issues found! All values use design tokens.

From 06405c252d807a98184cdf903a77ac6f5c380dcc Mon Sep 17 00:00:00 2001
From: Jeremy Walton <jeremy.patrick.walton@gmail.com>
Date: Fri, 6 Feb 2026 11:25:50 -0500
Subject: [PATCH 24/28] Update README and package details to prep for
 publishing

---
 .github/workflows/publish.yml | 20 ++++-------
 README.md                     | 64 ++++++++++++++++++++---------------
 package-lock.json             |  8 ++---
 package.json                  |  8 ++---
 4 files changed, 52 insertions(+), 48 deletions(-)

diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index ae7bbe3..0d3ef2c 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -1,9 +1,8 @@
-name: Publish to GitHub Packages
+name: Publish to NPM
 
 on:
   release:
-    types: [created]
-  workflow_dispatch:
+    types: [published]
 
 jobs:
   publish:
@@ -12,20 +11,15 @@ jobs:
       contents: read
       packages: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           node-version: '24.x'
           registry-url: 'https://registry.npmjs.org'
 
       - run: npm ci
-
-      - run: npm test
-
-      - name: Configure npm for GitHub Packages
-        run: |
-          echo "//npm.pkg.github.com/:_authToken=${{ secrets.GH_PAT }}" > ~/.npmrc
-          echo "@dallasbpeters:registry=https://npm.pkg.github.com" >> ~/.npmrc
-
+      - run: npm run build
       - run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
diff --git a/README.md b/README.md
index 1ed408e..45e65d2 100644
--- a/README.md
+++ b/README.md
@@ -35,7 +35,7 @@ graph TB
 
     subgraph "Optics MCP Server"
         SERVER[MCP Server<br/>stdio transport]
-        
+
         subgraph "Resources (13)"
             SYSTEM[optics://system-overview]
             DOC_INTRO[optics://documentation/introduction]
@@ -52,7 +52,7 @@ graph TB
             TOK_TYPO[optics://tokens/typography]
             COMP_ALL[optics://components/all]
         end
-        
+
         subgraph "Core Tools (7)"
             T1[get_token]
             T2[search_tokens]
@@ -62,7 +62,7 @@ graph TB
             T6[get_component_tokens]
             T7[search_documentation]
         end
-        
+
         subgraph "Advanced Tools (7)"
             T8[generate_theme]
             T9[validate_token_usage]
@@ -72,7 +72,7 @@ graph TB
             T13[generate_component_scaffold]
             T14[generate_sticker_sheet]
         end
-        
+
         subgraph "Prompts (5)"
             P1[start-here]
             P2[get-token-reference]
@@ -80,14 +80,14 @@ graph TB
             P4[theme-customization]
             P5[migration-guide]
         end
-        
+
         subgraph "Data Layer"
             TOKENS[83 Design Tokens<br/>HSL colors, spacing,<br/>typography, borders, shadows]
             COMPONENTS[24 Components<br/>with token dependencies]
             DOCS[Documentation<br/>Guidelines & best practices]
         end
     end
-    
+
     CLIENT -->|JSON-RPC| SERVER
     SERVER --> SYSTEM
     SERVER --> DOC_INTRO
@@ -152,16 +152,20 @@ graph TB
 
 1. Command Palette → **MCP: Open User Configuration**
 2. Add this configuration:
-   ```json
-   {
-     "servers": {
-       "optics": {
-         "command": "npx",
-         "args": ["-y", "optics-mcp"]
-       }
-     }
-   }
-   ```
+
+```json
+{
+  "servers": {
+    "optics": {
+      "command": "npx",
+      "args": [
+        "@rolemodel/optics-mcp@latest"
+      ]
+    }
+  }
+}
+```
+
 3. Open GitHub Copilot in **Agent Mode**
 4. Click the tools icon to see Optics tools available
 
@@ -180,16 +184,20 @@ cursor://anysphere.cursor-deeplink/mcp/install?name=optics&config=eyJvcHRpY3MiOn
 
 1. Open Cursor Settings → **MCP**
 2. Add this configuration:
-   ```json
-   {
-     "servers": {
-       "optics": {
-         "command": "npx",
-         "args": ["-y", "optics-mcp"]
-       }
-     }
-   }
-   ```
+
+```json
+{
+  "servers": {
+    "optics": {
+      "command": "npx",
+      "args": [
+        "@rolemodel/optics-mcp@latest"
+      ]
+    }
+  }
+}
+```
+
 3. Chat with Cursor AI to access Optics tools
 
 ### Quick Start (Zero-Install) ⚡
@@ -205,7 +213,9 @@ Add to your MCP configuration:
   "mcpServers": {
     "optics": {
       "command": "npx",
-      "args": ["-y", "optics-mcp"]
+      "args": [
+        "@rolemodel/optics-mcp@latest"
+      ]
     }
   }
 }
diff --git a/package-lock.json b/package-lock.json
index ddbdd5e..4785716 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
-  "name": "optics-mcp",
-  "version": "0.2.6",
+  "name": "@rolemodel/optics-mcp",
+  "version": "0.2.7",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
-      "name": "optics-mcp",
-      "version": "0.2.6",
+      "name": "@rolemodel/optics-mcp",
+      "version": "0.2.7",
       "license": "MIT",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.24.0",
diff --git a/package.json b/package.json
index f5167b4..3b1928b 100644
--- a/package.json
+++ b/package.json
@@ -1,12 +1,12 @@
 {
-  "name": "optics-mcp",
-  "version": "0.2.6",
-  "mcpName": "io.github.RoleModel/optics-mcp",
+  "name": "@rolemodel/optics-mcp",
+  "version": "0.2.7",
   "description": "MCP Server for Optics Design System documentation and token usage with AI-optimized comprehension guide",
+  "mcpName": "io.github.rolemodel/optics-mcp",
   "main": "dist/index.js",
   "type": "module",
   "bin": {
-    "optics-mcp": "dist/index.js"
+    "@rolemodel/optics-mcp": "dist/index.js"
   },
   "scripts": {
     "build": "npx tsc && npm run copy:md",

From f36fdbb4156efb8dfe03c0ec76a069d8486112bb Mon Sep 17 00:00:00 2001
From: Jeremy Walton <jeremy.walton@rolemodelsoftware.com>
Date: Fri, 6 Feb 2026 11:41:00 -0500
Subject: [PATCH 25/28] Update workflow permissions (#29)

---
 .github/workflows/publish.yml | 6 ++----
 package.json                  | 2 +-
 2 files changed, 3 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 0d3ef2c..949e4f5 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -3,13 +3,11 @@ name: Publish to NPM
 on:
   release:
     types: [published]
-
+permissions:
+  contents: write
 jobs:
   publish:
     runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      packages: write
     steps:
       - uses: actions/checkout@v6
 
diff --git a/package.json b/package.json
index 3b1928b..20f25cd 100644
--- a/package.json
+++ b/package.json
@@ -6,7 +6,7 @@
   "main": "dist/index.js",
   "type": "module",
   "bin": {
-    "@rolemodel/optics-mcp": "dist/index.js"
+    "optics-mcp": "dist/index.js"
   },
   "scripts": {
     "build": "npx tsc && npm run copy:md",

From 55a09fdf0a6c31b59c1c16cd4547c371210427bd Mon Sep 17 00:00:00 2001
From: Dallas Peters <dallaspeters@gmail.com>
Date: Mon, 9 Feb 2026 14:02:13 -0600
Subject: [PATCH 26/28] Rebase: keep our consolidated index.ts (Validate Pairs
 Tool conflict)

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .github/workflows/ci.yml                      |    3 +
 .gitignore                                    |    5 +-
 package-lock.json                             | 1188 ++++++++++++++++-
 package.json                                  |    8 +-
 spec/javascript/example.spec.js               |   12 +
 spec/javascript/test-setup.js                 |    0
 .../tools/validate-color-pair-tool.spec.js    |   78 ++
 src/tools/index.ts                            |   15 +
 src/tools/validate-color-pair-tool.ts         |   68 +
 vitest.config.js                              |   23 +
 10 files changed, 1396 insertions(+), 4 deletions(-)
 create mode 100644 spec/javascript/example.spec.js
 create mode 100644 spec/javascript/test-setup.js
 create mode 100644 spec/javascript/tools/validate-color-pair-tool.spec.js
 create mode 100644 src/tools/index.ts
 create mode 100644 src/tools/validate-color-pair-tool.ts
 create mode 100644 vitest.config.js

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 6587fc4..101c237 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -29,6 +29,9 @@ jobs:
       - name: Build
         run: npm run build
 
+      - name: Install playwright
+        run: npx playwright install
+
       - name: Run tests
         run: npm test
 
diff --git a/.gitignore b/.gitignore
index d83ee98..714dc93 100644
--- a/.gitignore
+++ b/.gitignore
@@ -39,4 +39,7 @@ logs/
 .cursor/rules/byterover-rules.mdc
 .kiro/steering/byterover-rules.md
 .qoder/rules/byterover-rules.md
-.augment/rules/byterover-rules.md
\ No newline at end of file
+.augment/rules/byterover-rules.md
+
+# Vitest
+spec/**/__screenshots__/*
diff --git a/package-lock.json b/package-lock.json
index 4785716..5d03f24 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -18,9 +18,13 @@
       "devDependencies": {
         "@rolemodel/optics": "^2.3.0",
         "@types/node": "^20.10.0",
+        "@vitest/browser-playwright": "^4.0.18",
+        "@vitest/ui": "^4.0.18",
         "esbuild": "^0.27.2",
+        "playwright": "^1.58.1",
         "ts-node": "^10.9.2",
-        "typescript": "^5.9.3"
+        "typescript": "^5.9.3",
+        "vitest": "^4.0.18"
       },
       "engines": {
         "node": ">=24.13.0"
@@ -560,6 +564,13 @@
         }
       }
     },
+    "node_modules/@polka/url": {
+      "version": "1.0.0-next.29",
+      "resolved": "https://registry.npmjs.org/@polka/url/-/url-1.0.0-next.29.tgz",
+      "integrity": "sha512-wwQAWhWSuHaag8c4q/KN/vCoeOJYshAIvMQwD4GpSb3OiZklFfvAgmj0VCBBImRpuF/aFgIRzllXlVX93Jevww==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@rolemodel/optics": {
       "version": "2.3.0",
       "resolved": "https://registry.npmjs.org/@rolemodel/optics/-/optics-2.3.0.tgz",
@@ -578,6 +589,363 @@
         }
       }
     },
+    "node_modules/@rollup/rollup-android-arm-eabi": {
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.57.1.tgz",
+      "integrity": "sha512-A6ehUVSiSaaliTxai040ZpZ2zTevHYbvu/lDoeAteHI8QnaosIzm4qwtezfRg1jOYaUmnzLX1AOD6Z+UJjtifg==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ]
+    },
+    "node_modules/@rollup/rollup-android-arm64": {
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.57.1.tgz",
+      "integrity": "sha512-dQaAddCY9YgkFHZcFNS/606Exo8vcLHwArFZ7vxXq4rigo2bb494/xKMMwRRQW6ug7Js6yXmBZhSBRuBvCCQ3w==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ]
+    },
+    "node_modules/@rollup/rollup-darwin-arm64": {
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.57.1.tgz",
+      "integrity": "sha512-crNPrwJOrRxagUYeMn/DZwqN88SDmwaJ8Cvi/TN1HnWBU7GwknckyosC2gd0IqYRsHDEnXf328o9/HC6OkPgOg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@rollup/rollup-darwin-x64": {
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.57.1.tgz",
+      "integrity": "sha512-Ji8g8ChVbKrhFtig5QBV7iMaJrGtpHelkB3lsaKzadFBe58gmjfGXAOfI5FV0lYMH8wiqsxKQ1C9B0YTRXVy4w==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@rollup/rollup-freebsd-arm64": {
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.57.1.tgz",
+      "integrity": "sha512-R+/WwhsjmwodAcz65guCGFRkMb4gKWTcIeLy60JJQbXrJ97BOXHxnkPFrP+YwFlaS0m+uWJTstrUA9o+UchFug==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ]
+    },
+    "node_modules/@rollup/rollup-freebsd-x64": {
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.57.1.tgz",
+      "integrity": "sha512-IEQTCHeiTOnAUC3IDQdzRAGj3jOAYNr9kBguI7MQAAZK3caezRrg0GxAb6Hchg4lxdZEI5Oq3iov/w/hnFWY9Q==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm-gnueabihf": {
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.57.1.tgz",
+      "integrity": "sha512-F8sWbhZ7tyuEfsmOxwc2giKDQzN3+kuBLPwwZGyVkLlKGdV1nvnNwYD0fKQ8+XS6hp9nY7B+ZeK01EBUE7aHaw==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm-musleabihf": {
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.57.1.tgz",
+      "integrity": "sha512-rGfNUfn0GIeXtBP1wL5MnzSj98+PZe/AXaGBCRmT0ts80lU5CATYGxXukeTX39XBKsxzFpEeK+Mrp9faXOlmrw==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm64-gnu": {
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.57.1.tgz",
+      "integrity": "sha512-MMtej3YHWeg/0klK2Qodf3yrNzz6CGjo2UntLvk2RSPlhzgLvYEB3frRvbEF2wRKh1Z2fDIg9KRPe1fawv7C+g==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm64-musl": {
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.57.1.tgz",
+      "integrity": "sha512-1a/qhaaOXhqXGpMFMET9VqwZakkljWHLmZOX48R0I/YLbhdxr1m4gtG1Hq7++VhVUmf+L3sTAf9op4JlhQ5u1Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-loong64-gnu": {
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.57.1.tgz",
+      "integrity": "sha512-QWO6RQTZ/cqYtJMtxhkRkidoNGXc7ERPbZN7dVW5SdURuLeVU7lwKMpo18XdcmpWYd0qsP1bwKPf7DNSUinhvA==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-loong64-musl": {
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-musl/-/rollup-linux-loong64-musl-4.57.1.tgz",
+      "integrity": "sha512-xpObYIf+8gprgWaPP32xiN5RVTi/s5FCR+XMXSKmhfoJjrpRAjCuuqQXyxUa/eJTdAE6eJ+KDKaoEqjZQxh3Gw==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-ppc64-gnu": {
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.57.1.tgz",
+      "integrity": "sha512-4BrCgrpZo4hvzMDKRqEaW1zeecScDCR+2nZ86ATLhAoJ5FQ+lbHVD3ttKe74/c7tNT9c6F2viwB3ufwp01Oh2w==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-ppc64-musl": {
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-musl/-/rollup-linux-ppc64-musl-4.57.1.tgz",
+      "integrity": "sha512-NOlUuzesGauESAyEYFSe3QTUguL+lvrN1HtwEEsU2rOwdUDeTMJdO5dUYl/2hKf9jWydJrO9OL/XSSf65R5+Xw==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-riscv64-gnu": {
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.57.1.tgz",
+      "integrity": "sha512-ptA88htVp0AwUUqhVghwDIKlvJMD/fmL/wrQj99PRHFRAG6Z5nbWoWG4o81Nt9FT+IuqUQi+L31ZKAFeJ5Is+A==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-riscv64-musl": {
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.57.1.tgz",
+      "integrity": "sha512-S51t7aMMTNdmAMPpBg7OOsTdn4tySRQvklmL3RpDRyknk87+Sp3xaumlatU+ppQ+5raY7sSTcC2beGgvhENfuw==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-s390x-gnu": {
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.57.1.tgz",
+      "integrity": "sha512-Bl00OFnVFkL82FHbEqy3k5CUCKH6OEJL54KCyx2oqsmZnFTR8IoNqBF+mjQVcRCT5sB6yOvK8A37LNm/kPJiZg==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-x64-gnu": {
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.57.1.tgz",
+      "integrity": "sha512-ABca4ceT4N+Tv/GtotnWAeXZUZuM/9AQyCyKYyKnpk4yoA7QIAuBt6Hkgpw8kActYlew2mvckXkvx0FfoInnLg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-x64-musl": {
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.57.1.tgz",
+      "integrity": "sha512-HFps0JeGtuOR2convgRRkHCekD7j+gdAuXM+/i6kGzQtFhlCtQkpwtNzkNj6QhCDp7DRJ7+qC/1Vg2jt5iSOFw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-openbsd-x64": {
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-openbsd-x64/-/rollup-openbsd-x64-4.57.1.tgz",
+      "integrity": "sha512-H+hXEv9gdVQuDTgnqD+SQffoWoc0Of59AStSzTEj/feWTBAnSfSD3+Dql1ZruJQxmykT/JVY0dE8Ka7z0DH1hw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ]
+    },
+    "node_modules/@rollup/rollup-openharmony-arm64": {
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.57.1.tgz",
+      "integrity": "sha512-4wYoDpNg6o/oPximyc/NG+mYUejZrCU2q+2w6YZqrAs2UcNUChIZXjtafAiiZSUc7On8v5NyNj34Kzj/Ltk6dQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-arm64-msvc": {
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.57.1.tgz",
+      "integrity": "sha512-O54mtsV/6LW3P8qdTcamQmuC990HDfR71lo44oZMZlXU4tzLrbvTii87Ni9opq60ds0YzuAlEr/GNwuNluZyMQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-ia32-msvc": {
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.57.1.tgz",
+      "integrity": "sha512-P3dLS+IerxCT/7D2q2FYcRdWRl22dNbrbBEtxdWhXrfIMPP9lQhb5h4Du04mdl5Woq05jVCDPCMF7Ub0NAjIew==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-x64-gnu": {
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.57.1.tgz",
+      "integrity": "sha512-VMBH2eOOaKGtIJYleXsi2B8CPVADrh+TyNxJ4mWPnKfLB/DBUmzW+5m1xUrcwWoMfSLagIRpjUFeW5CO5hyciQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-x64-msvc": {
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.57.1.tgz",
+      "integrity": "sha512-mxRFDdHIWRxg3UfIIAwCm6NzvxG0jDX/wBN6KsQFTvKFqqg9vTrWUE68qEjHt19A5wwx5X5aUi2zuZT7YR0jrA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@standard-schema/spec": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/@standard-schema/spec/-/spec-1.1.0.tgz",
+      "integrity": "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@tsconfig/node10": {
       "version": "1.0.12",
       "resolved": "https://registry.npmjs.org/@tsconfig/node10/-/node10-1.0.12.tgz",
@@ -606,6 +974,31 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@types/chai": {
+      "version": "5.2.3",
+      "resolved": "https://registry.npmjs.org/@types/chai/-/chai-5.2.3.tgz",
+      "integrity": "sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/deep-eql": "*",
+        "assertion-error": "^2.0.1"
+      }
+    },
+    "node_modules/@types/deep-eql": {
+      "version": "4.0.2",
+      "resolved": "https://registry.npmjs.org/@types/deep-eql/-/deep-eql-4.0.2.tgz",
+      "integrity": "sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@types/estree": {
+      "version": "1.0.8",
+      "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.8.tgz",
+      "integrity": "sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/node": {
       "version": "20.19.31",
       "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.31.tgz",
@@ -617,6 +1010,188 @@
         "undici-types": "~6.21.0"
       }
     },
+    "node_modules/@vitest/browser": {
+      "version": "4.0.18",
+      "resolved": "https://registry.npmjs.org/@vitest/browser/-/browser-4.0.18.tgz",
+      "integrity": "sha512-gVQqh7paBz3gC+ZdcCmNSWJMk70IUjDeVqi+5m5vYpEHsIwRgw3Y545jljtajhkekIpIp5Gg8oK7bctgY0E2Ng==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/mocker": "4.0.18",
+        "@vitest/utils": "4.0.18",
+        "magic-string": "^0.30.21",
+        "pixelmatch": "7.1.0",
+        "pngjs": "^7.0.0",
+        "sirv": "^3.0.2",
+        "tinyrainbow": "^3.0.3",
+        "ws": "^8.18.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "vitest": "4.0.18"
+      }
+    },
+    "node_modules/@vitest/browser-playwright": {
+      "version": "4.0.18",
+      "resolved": "https://registry.npmjs.org/@vitest/browser-playwright/-/browser-playwright-4.0.18.tgz",
+      "integrity": "sha512-gfajTHVCiwpxRj1qh0Sh/5bbGLG4F/ZH/V9xvFVoFddpITfMta9YGow0W6ZpTTORv2vdJuz9TnrNSmjKvpOf4g==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "@vitest/browser": "4.0.18",
+        "@vitest/mocker": "4.0.18",
+        "tinyrainbow": "^3.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "playwright": "*",
+        "vitest": "4.0.18"
+      },
+      "peerDependenciesMeta": {
+        "playwright": {
+          "optional": false
+        }
+      }
+    },
+    "node_modules/@vitest/expect": {
+      "version": "4.0.18",
+      "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-4.0.18.tgz",
+      "integrity": "sha512-8sCWUyckXXYvx4opfzVY03EOiYVxyNrHS5QxX3DAIi5dpJAAkyJezHCP77VMX4HKA2LDT/Jpfo8i2r5BE3GnQQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@standard-schema/spec": "^1.0.0",
+        "@types/chai": "^5.2.2",
+        "@vitest/spy": "4.0.18",
+        "@vitest/utils": "4.0.18",
+        "chai": "^6.2.1",
+        "tinyrainbow": "^3.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/mocker": {
+      "version": "4.0.18",
+      "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-4.0.18.tgz",
+      "integrity": "sha512-HhVd0MDnzzsgevnOWCBj5Otnzobjy5wLBe4EdeeFGv8luMsGcYqDuFRMcttKWZA5vVO8RFjexVovXvAM4JoJDQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/spy": "4.0.18",
+        "estree-walker": "^3.0.3",
+        "magic-string": "^0.30.21"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "msw": "^2.4.9",
+        "vite": "^6.0.0 || ^7.0.0-0"
+      },
+      "peerDependenciesMeta": {
+        "msw": {
+          "optional": true
+        },
+        "vite": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@vitest/pretty-format": {
+      "version": "4.0.18",
+      "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-4.0.18.tgz",
+      "integrity": "sha512-P24GK3GulZWC5tz87ux0m8OADrQIUVDPIjjj65vBXYG17ZeU3qD7r+MNZ1RNv4l8CGU2vtTRqixrOi9fYk/yKw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "tinyrainbow": "^3.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/runner": {
+      "version": "4.0.18",
+      "resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-4.0.18.tgz",
+      "integrity": "sha512-rpk9y12PGa22Jg6g5M3UVVnTS7+zycIGk9ZNGN+m6tZHKQb7jrP7/77WfZy13Y/EUDd52NDsLRQhYKtv7XfPQw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/utils": "4.0.18",
+        "pathe": "^2.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/snapshot": {
+      "version": "4.0.18",
+      "resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-4.0.18.tgz",
+      "integrity": "sha512-PCiV0rcl7jKQjbgYqjtakly6T1uwv/5BQ9SwBLekVg/EaYeQFPiXcgrC2Y7vDMA8dM1SUEAEV82kgSQIlXNMvA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/pretty-format": "4.0.18",
+        "magic-string": "^0.30.21",
+        "pathe": "^2.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/spy": {
+      "version": "4.0.18",
+      "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-4.0.18.tgz",
+      "integrity": "sha512-cbQt3PTSD7P2OARdVW3qWER5EGq7PHlvE+QfzSC0lbwO+xnt7+XH06ZzFjFRgzUX//JmpxrCu92VdwvEPlWSNw==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/ui": {
+      "version": "4.0.18",
+      "resolved": "https://registry.npmjs.org/@vitest/ui/-/ui-4.0.18.tgz",
+      "integrity": "sha512-CGJ25bc8fRi8Lod/3GHSvXRKi7nBo3kxh0ApW4yCjmrWmRmlT53B5E08XRSZRliygG0aVNxLrBEqPYdz/KcCtQ==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "@vitest/utils": "4.0.18",
+        "fflate": "^0.8.2",
+        "flatted": "^3.3.3",
+        "pathe": "^2.0.3",
+        "sirv": "^3.0.2",
+        "tinyglobby": "^0.2.15",
+        "tinyrainbow": "^3.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "vitest": "4.0.18"
+      }
+    },
+    "node_modules/@vitest/utils": {
+      "version": "4.0.18",
+      "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-4.0.18.tgz",
+      "integrity": "sha512-msMRKLMVLWygpK3u2Hybgi4MNjcYJvwTb0Ru09+fOyCXIgT5raYP041DRRdiJiI3k/2U6SEbAETB3YtBrUkCFA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/pretty-format": "4.0.18",
+        "tinyrainbow": "^3.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
     "node_modules/accepts": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/accepts/-/accepts-2.0.0.tgz",
@@ -695,6 +1270,16 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/assertion-error": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/assertion-error/-/assertion-error-2.0.1.tgz",
+      "integrity": "sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      }
+    },
     "node_modules/body-parser": {
       "version": "2.2.2",
       "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-2.2.2.tgz",
@@ -753,6 +1338,16 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/chai": {
+      "version": "6.2.2",
+      "resolved": "https://registry.npmjs.org/chai/-/chai-6.2.2.tgz",
+      "integrity": "sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/content-disposition": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/content-disposition/-/content-disposition-1.0.1.tgz",
@@ -903,6 +1498,13 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/es-module-lexer": {
+      "version": "1.7.0",
+      "resolved": "https://registry.npmjs.org/es-module-lexer/-/es-module-lexer-1.7.0.tgz",
+      "integrity": "sha512-jEQoCwk8hyb2AZziIOLhDqpm5+2ww5uIE6lkO/6jcOCusfk6LhMHpXXfBLXTZ7Ydyt0j4VoUQv6uGNYbdW+kBA==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/es-object-atoms": {
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/es-object-atoms/-/es-object-atoms-1.1.1.tgz",
@@ -961,6 +1563,16 @@
       "resolved": "https://registry.npmjs.org/escape-html/-/escape-html-1.0.3.tgz",
       "integrity": "sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow=="
     },
+    "node_modules/estree-walker": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-3.0.3.tgz",
+      "integrity": "sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "^1.0.0"
+      }
+    },
     "node_modules/etag": {
       "version": "1.8.1",
       "resolved": "https://registry.npmjs.org/etag/-/etag-1.8.1.tgz",
@@ -990,6 +1602,16 @@
         "node": ">=18.0.0"
       }
     },
+    "node_modules/expect-type": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/expect-type/-/expect-type-1.3.0.tgz",
+      "integrity": "sha512-knvyeauYhqjOYvQ66MznSMs83wmHrCycNEN6Ao+2AeYEfxUIkuiVxdEa1qlGEPK+We3n0THiDciYSsCcgW/DoA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=12.0.0"
+      }
+    },
     "node_modules/express": {
       "version": "5.2.1",
       "resolved": "https://registry.npmjs.org/express/-/express-5.2.1.tgz",
@@ -1072,6 +1694,31 @@
       ],
       "license": "BSD-3-Clause"
     },
+    "node_modules/fdir": {
+      "version": "6.5.0",
+      "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz",
+      "integrity": "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12.0.0"
+      },
+      "peerDependencies": {
+        "picomatch": "^3 || ^4"
+      },
+      "peerDependenciesMeta": {
+        "picomatch": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/fflate": {
+      "version": "0.8.2",
+      "resolved": "https://registry.npmjs.org/fflate/-/fflate-0.8.2.tgz",
+      "integrity": "sha512-cPJU47OaAoCbg0pBvzsgpTPhmhqI5eJjh/JIu8tPj5q+T7iLvW/JAYUqmE7KOB4R1ZyEhzBaIQpQpardBF5z8A==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/finalhandler": {
       "version": "2.1.1",
       "resolved": "https://registry.npmjs.org/finalhandler/-/finalhandler-2.1.1.tgz",
@@ -1092,6 +1739,13 @@
         "url": "https://opencollective.com/express"
       }
     },
+    "node_modules/flatted": {
+      "version": "3.3.3",
+      "resolved": "https://registry.npmjs.org/flatted/-/flatted-3.3.3.tgz",
+      "integrity": "sha512-GX+ysw4PBCz0PzosHDepZGANEuFCMLrnRTiEy9McGjmkCQYwRq4A/X786G/fjM/+OjsWSU1ZrY5qyARZmO/uwg==",
+      "dev": true,
+      "license": "ISC"
+    },
     "node_modules/forwarded": {
       "version": "0.2.0",
       "resolved": "https://registry.npmjs.org/forwarded/-/forwarded-0.2.0.tgz",
@@ -1108,6 +1762,21 @@
         "node": ">= 0.8"
       }
     },
+    "node_modules/fsevents": {
+      "version": "2.3.2",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz",
+      "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
     "node_modules/function-bind": {
       "version": "1.1.2",
       "resolved": "https://registry.npmjs.org/function-bind/-/function-bind-1.1.2.tgz",
@@ -1281,6 +1950,16 @@
       "integrity": "sha512-fQhoXdcvc3V28x7C7BMs4P5+kNlgUURe2jmUT1T//oBRMDrqy1QPelJimwZGo7Hg9VPV3EQV5Bnq4hbFy2vetA==",
       "license": "BSD-2-Clause"
     },
+    "node_modules/magic-string": {
+      "version": "0.30.21",
+      "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.21.tgz",
+      "integrity": "sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/sourcemap-codec": "^1.5.5"
+      }
+    },
     "node_modules/make-error": {
       "version": "1.3.6",
       "resolved": "https://registry.npmjs.org/make-error/-/make-error-1.3.6.tgz",
@@ -1345,11 +2024,40 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/mrmime": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/mrmime/-/mrmime-2.0.1.tgz",
+      "integrity": "sha512-Y3wQdFg2Va6etvQ5I82yUhGdsKrcYox6p7FfL1LbK2J4V01F9TGlepTIhnK24t7koZibmg82KGglhA1XK5IsLQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=10"
+      }
+    },
     "node_modules/ms": {
       "version": "2.1.3",
       "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
       "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA=="
     },
+    "node_modules/nanoid": {
+      "version": "3.3.11",
+      "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.11.tgz",
+      "integrity": "sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "bin": {
+        "nanoid": "bin/nanoid.cjs"
+      },
+      "engines": {
+        "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1"
+      }
+    },
     "node_modules/negotiator": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/negotiator/-/negotiator-1.0.0.tgz",
@@ -1378,6 +2086,17 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/obug": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/obug/-/obug-2.1.1.tgz",
+      "integrity": "sha512-uTqF9MuPraAQ+IsnPf366RG4cP9RtUi7MLO1N3KEc+wb0a6yKpeL0lmk2IB1jY5KHPAlTc6T/JRdC/YqxHNwkQ==",
+      "dev": true,
+      "funding": [
+        "https://github.com/sponsors/sxzz",
+        "https://opencollective.com/debug"
+      ],
+      "license": "MIT"
+    },
     "node_modules/on-finished": {
       "version": "2.4.1",
       "resolved": "https://registry.npmjs.org/on-finished/-/on-finished-2.4.1.tgz",
@@ -1423,6 +2142,47 @@
         "url": "https://opencollective.com/express"
       }
     },
+    "node_modules/pathe": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/pathe/-/pathe-2.0.3.tgz",
+      "integrity": "sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/picocolors": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
+      "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==",
+      "dev": true,
+      "license": "ISC"
+    },
+    "node_modules/picomatch": {
+      "version": "4.0.3",
+      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.3.tgz",
+      "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/jonschlinkert"
+      }
+    },
+    "node_modules/pixelmatch": {
+      "version": "7.1.0",
+      "resolved": "https://registry.npmjs.org/pixelmatch/-/pixelmatch-7.1.0.tgz",
+      "integrity": "sha512-1wrVzJ2STrpmONHKBy228LM1b84msXDUoAzVEl0R8Mz4Ce6EPr+IVtxm8+yvrqLYMHswREkjYFaMxnyGnaY3Ng==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "pngjs": "^7.0.0"
+      },
+      "bin": {
+        "pixelmatch": "bin/pixelmatch"
+      }
+    },
     "node_modules/pkce-challenge": {
       "version": "5.0.1",
       "resolved": "https://registry.npmjs.org/pkce-challenge/-/pkce-challenge-5.0.1.tgz",
@@ -1432,6 +2192,78 @@
         "node": ">=16.20.0"
       }
     },
+    "node_modules/playwright": {
+      "version": "1.58.1",
+      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.58.1.tgz",
+      "integrity": "sha512-+2uTZHxSCcxjvGc5C891LrS1/NlxglGxzrC4seZiVjcYVQfUa87wBL6rTDqzGjuoWNjnBzRqKmF6zRYGMvQUaQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "peer": true,
+      "dependencies": {
+        "playwright-core": "1.58.1"
+      },
+      "bin": {
+        "playwright": "cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "fsevents": "2.3.2"
+      }
+    },
+    "node_modules/playwright-core": {
+      "version": "1.58.1",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.58.1.tgz",
+      "integrity": "sha512-bcWzOaTxcW+VOOGBCQgnaKToLJ65d6AqfLVKEWvexyS3AS6rbXl+xdpYRMGSRBClPvyj44njOWoxjNdL/H9UNg==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "playwright-core": "cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/pngjs": {
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/pngjs/-/pngjs-7.0.0.tgz",
+      "integrity": "sha512-LKWqWJRhstyYo9pGvgor/ivk2w94eSjE3RGVuzLGlr3NmD8bf7RcYGze1mNdEHRP6TRP6rMuDHk5t44hnTRyow==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.19.0"
+      }
+    },
+    "node_modules/postcss": {
+      "version": "8.5.6",
+      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.6.tgz",
+      "integrity": "sha512-3Ybi1tAuwAP9s0r1UQ2J4n5Y0G05bJkpUIO0/bI9MhwmD70S5aTWbXGBwxHrelT+XM1k6dM0pk+SwNkpTRN7Pg==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/postcss/"
+        },
+        {
+          "type": "tidelift",
+          "url": "https://tidelift.com/funding/github/npm/postcss"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "nanoid": "^3.3.11",
+        "picocolors": "^1.1.1",
+        "source-map-js": "^1.2.1"
+      },
+      "engines": {
+        "node": "^10 || ^12 || >=14"
+      }
+    },
     "node_modules/proxy-addr": {
       "version": "2.0.7",
       "resolved": "https://registry.npmjs.org/proxy-addr/-/proxy-addr-2.0.7.tgz",
@@ -1489,6 +2321,51 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/rollup": {
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.57.1.tgz",
+      "integrity": "sha512-oQL6lgK3e2QZeQ7gcgIkS2YZPg5slw37hYufJ3edKlfQSGGm8ICoxswK15ntSzF/a8+h7ekRy7k7oWc3BQ7y8A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "1.0.8"
+      },
+      "bin": {
+        "rollup": "dist/bin/rollup"
+      },
+      "engines": {
+        "node": ">=18.0.0",
+        "npm": ">=8.0.0"
+      },
+      "optionalDependencies": {
+        "@rollup/rollup-android-arm-eabi": "4.57.1",
+        "@rollup/rollup-android-arm64": "4.57.1",
+        "@rollup/rollup-darwin-arm64": "4.57.1",
+        "@rollup/rollup-darwin-x64": "4.57.1",
+        "@rollup/rollup-freebsd-arm64": "4.57.1",
+        "@rollup/rollup-freebsd-x64": "4.57.1",
+        "@rollup/rollup-linux-arm-gnueabihf": "4.57.1",
+        "@rollup/rollup-linux-arm-musleabihf": "4.57.1",
+        "@rollup/rollup-linux-arm64-gnu": "4.57.1",
+        "@rollup/rollup-linux-arm64-musl": "4.57.1",
+        "@rollup/rollup-linux-loong64-gnu": "4.57.1",
+        "@rollup/rollup-linux-loong64-musl": "4.57.1",
+        "@rollup/rollup-linux-ppc64-gnu": "4.57.1",
+        "@rollup/rollup-linux-ppc64-musl": "4.57.1",
+        "@rollup/rollup-linux-riscv64-gnu": "4.57.1",
+        "@rollup/rollup-linux-riscv64-musl": "4.57.1",
+        "@rollup/rollup-linux-s390x-gnu": "4.57.1",
+        "@rollup/rollup-linux-x64-gnu": "4.57.1",
+        "@rollup/rollup-linux-x64-musl": "4.57.1",
+        "@rollup/rollup-openbsd-x64": "4.57.1",
+        "@rollup/rollup-openharmony-arm64": "4.57.1",
+        "@rollup/rollup-win32-arm64-msvc": "4.57.1",
+        "@rollup/rollup-win32-ia32-msvc": "4.57.1",
+        "@rollup/rollup-win32-x64-gnu": "4.57.1",
+        "@rollup/rollup-win32-x64-msvc": "4.57.1",
+        "fsevents": "~2.3.2"
+      }
+    },
     "node_modules/router": {
       "version": "2.2.0",
       "resolved": "https://registry.npmjs.org/router/-/router-2.2.0.tgz",
@@ -1646,6 +2523,45 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/siginfo": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/siginfo/-/siginfo-2.0.0.tgz",
+      "integrity": "sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==",
+      "dev": true,
+      "license": "ISC"
+    },
+    "node_modules/sirv": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/sirv/-/sirv-3.0.2.tgz",
+      "integrity": "sha512-2wcC/oGxHis/BoHkkPwldgiPSYcpZK3JU28WoMVv55yHJgcZ8rlXvuG9iZggz+sU1d4bRgIGASwyWqjxu3FM0g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@polka/url": "^1.0.0-next.24",
+        "mrmime": "^2.0.0",
+        "totalist": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/source-map-js": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
+      "integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/stackback": {
+      "version": "0.0.2",
+      "resolved": "https://registry.npmjs.org/stackback/-/stackback-0.0.2.tgz",
+      "integrity": "sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/statuses": {
       "version": "2.0.2",
       "resolved": "https://registry.npmjs.org/statuses/-/statuses-2.0.2.tgz",
@@ -1654,6 +2570,57 @@
         "node": ">= 0.8"
       }
     },
+    "node_modules/std-env": {
+      "version": "3.10.0",
+      "resolved": "https://registry.npmjs.org/std-env/-/std-env-3.10.0.tgz",
+      "integrity": "sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/tinybench": {
+      "version": "2.9.0",
+      "resolved": "https://registry.npmjs.org/tinybench/-/tinybench-2.9.0.tgz",
+      "integrity": "sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/tinyexec": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-1.0.2.tgz",
+      "integrity": "sha512-W/KYk+NFhkmsYpuHq5JykngiOCnxeVL8v8dFnqxSD8qEEdRfXk1SDM6JzNqcERbcGYj9tMrDQBYV9cjgnunFIg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tinyglobby": {
+      "version": "0.2.15",
+      "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.15.tgz",
+      "integrity": "sha512-j2Zq4NyQYG5XMST4cbs02Ak8iJUdxRM0XI5QyxXuZOzKOINmWurp3smXu3y5wDcJrptwpSjgXHzIQxR0omXljQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "fdir": "^6.5.0",
+        "picomatch": "^4.0.3"
+      },
+      "engines": {
+        "node": ">=12.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/SuperchupuDev"
+      }
+    },
+    "node_modules/tinyrainbow": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/tinyrainbow/-/tinyrainbow-3.0.3.tgz",
+      "integrity": "sha512-PSkbLUoxOFRzJYjjxHJt9xro7D+iilgMX/C9lawzVuYiIdcihh9DXmVibBe8lmcFrRi/VzlPjBxbN7rH24q8/Q==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.0.0"
+      }
+    },
     "node_modules/toidentifier": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/toidentifier/-/toidentifier-1.0.1.tgz",
@@ -1662,6 +2629,16 @@
         "node": ">=0.6"
       }
     },
+    "node_modules/totalist": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/totalist/-/totalist-3.0.1.tgz",
+      "integrity": "sha512-sf4i37nQ2LBx4m3wB74y+ubopq6W/dIzXg0FDGjsYnZHVa1Da8FH853wlL2gtUhg+xJXjfk3kUZS3BRoQeoQBQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/ts-node": {
       "version": "10.9.2",
       "resolved": "https://registry.npmjs.org/ts-node/-/ts-node-10.9.2.tgz",
@@ -1765,6 +2742,176 @@
         "node": ">= 0.8"
       }
     },
+    "node_modules/vite": {
+      "version": "7.3.1",
+      "resolved": "https://registry.npmjs.org/vite/-/vite-7.3.1.tgz",
+      "integrity": "sha512-w+N7Hifpc3gRjZ63vYBXA56dvvRlNWRczTdmCBBa+CotUzAPf5b7YMdMR/8CQoeYE5LX3W4wj6RYTgonm1b9DA==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "esbuild": "^0.27.0",
+        "fdir": "^6.5.0",
+        "picomatch": "^4.0.3",
+        "postcss": "^8.5.6",
+        "rollup": "^4.43.0",
+        "tinyglobby": "^0.2.15"
+      },
+      "bin": {
+        "vite": "bin/vite.js"
+      },
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      },
+      "funding": {
+        "url": "https://github.com/vitejs/vite?sponsor=1"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.3"
+      },
+      "peerDependencies": {
+        "@types/node": "^20.19.0 || >=22.12.0",
+        "jiti": ">=1.21.0",
+        "less": "^4.0.0",
+        "lightningcss": "^1.21.0",
+        "sass": "^1.70.0",
+        "sass-embedded": "^1.70.0",
+        "stylus": ">=0.54.8",
+        "sugarss": "^5.0.0",
+        "terser": "^5.16.0",
+        "tsx": "^4.8.1",
+        "yaml": "^2.4.2"
+      },
+      "peerDependenciesMeta": {
+        "@types/node": {
+          "optional": true
+        },
+        "jiti": {
+          "optional": true
+        },
+        "less": {
+          "optional": true
+        },
+        "lightningcss": {
+          "optional": true
+        },
+        "sass": {
+          "optional": true
+        },
+        "sass-embedded": {
+          "optional": true
+        },
+        "stylus": {
+          "optional": true
+        },
+        "sugarss": {
+          "optional": true
+        },
+        "terser": {
+          "optional": true
+        },
+        "tsx": {
+          "optional": true
+        },
+        "yaml": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/vite/node_modules/fsevents": {
+      "version": "2.3.3",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
+      "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
+    "node_modules/vitest": {
+      "version": "4.0.18",
+      "resolved": "https://registry.npmjs.org/vitest/-/vitest-4.0.18.tgz",
+      "integrity": "sha512-hOQuK7h0FGKgBAas7v0mSAsnvrIgAvWmRFjmzpJ7SwFHH3g1k2u37JtYwOwmEKhK6ZO3v9ggDBBm0La1LCK4uQ==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "@vitest/expect": "4.0.18",
+        "@vitest/mocker": "4.0.18",
+        "@vitest/pretty-format": "4.0.18",
+        "@vitest/runner": "4.0.18",
+        "@vitest/snapshot": "4.0.18",
+        "@vitest/spy": "4.0.18",
+        "@vitest/utils": "4.0.18",
+        "es-module-lexer": "^1.7.0",
+        "expect-type": "^1.2.2",
+        "magic-string": "^0.30.21",
+        "obug": "^2.1.1",
+        "pathe": "^2.0.3",
+        "picomatch": "^4.0.3",
+        "std-env": "^3.10.0",
+        "tinybench": "^2.9.0",
+        "tinyexec": "^1.0.2",
+        "tinyglobby": "^0.2.15",
+        "tinyrainbow": "^3.0.3",
+        "vite": "^6.0.0 || ^7.0.0",
+        "why-is-node-running": "^2.3.0"
+      },
+      "bin": {
+        "vitest": "vitest.mjs"
+      },
+      "engines": {
+        "node": "^20.0.0 || ^22.0.0 || >=24.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "@edge-runtime/vm": "*",
+        "@opentelemetry/api": "^1.9.0",
+        "@types/node": "^20.0.0 || ^22.0.0 || >=24.0.0",
+        "@vitest/browser-playwright": "4.0.18",
+        "@vitest/browser-preview": "4.0.18",
+        "@vitest/browser-webdriverio": "4.0.18",
+        "@vitest/ui": "4.0.18",
+        "happy-dom": "*",
+        "jsdom": "*"
+      },
+      "peerDependenciesMeta": {
+        "@edge-runtime/vm": {
+          "optional": true
+        },
+        "@opentelemetry/api": {
+          "optional": true
+        },
+        "@types/node": {
+          "optional": true
+        },
+        "@vitest/browser-playwright": {
+          "optional": true
+        },
+        "@vitest/browser-preview": {
+          "optional": true
+        },
+        "@vitest/browser-webdriverio": {
+          "optional": true
+        },
+        "@vitest/ui": {
+          "optional": true
+        },
+        "happy-dom": {
+          "optional": true
+        },
+        "jsdom": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/which": {
       "version": "2.0.2",
       "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",
@@ -1780,11 +2927,50 @@
         "node": ">= 8"
       }
     },
+    "node_modules/why-is-node-running": {
+      "version": "2.3.0",
+      "resolved": "https://registry.npmjs.org/why-is-node-running/-/why-is-node-running-2.3.0.tgz",
+      "integrity": "sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "siginfo": "^2.0.0",
+        "stackback": "0.0.2"
+      },
+      "bin": {
+        "why-is-node-running": "cli.js"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/wrappy": {
       "version": "1.0.2",
       "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz",
       "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ=="
     },
+    "node_modules/ws": {
+      "version": "8.19.0",
+      "resolved": "https://registry.npmjs.org/ws/-/ws-8.19.0.tgz",
+      "integrity": "sha512-blAT2mjOEIi0ZzruJfIhb3nps74PRWTCz1IjglWEEpQl5XS/UNama6u2/rjFkDDouqr4L67ry+1aGIALViWjDg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=10.0.0"
+      },
+      "peerDependencies": {
+        "bufferutil": "^4.0.1",
+        "utf-8-validate": ">=5.0.2"
+      },
+      "peerDependenciesMeta": {
+        "bufferutil": {
+          "optional": true
+        },
+        "utf-8-validate": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/yn": {
       "version": "3.1.1",
       "resolved": "https://registry.npmjs.org/yn/-/yn-3.1.1.tgz",
diff --git a/package.json b/package.json
index 20f25cd..4eb80c7 100644
--- a/package.json
+++ b/package.json
@@ -14,7 +14,7 @@
     "prepare": "npm run build",
     "watch": "npx tsc --watch",
     "start": "node dist/index.js",
-    "test": "node dist/test.js",
+    "test": "NODE_ENV=test vitest",
     "test:interactive": "npm run build && node dist/interactive-client.js",
     "sync-data": "npx ts-node scripts/sync-optics-data.ts"
   },
@@ -45,9 +45,13 @@
   "devDependencies": {
     "@rolemodel/optics": "^2.3.0",
     "@types/node": "^20.10.0",
+    "@vitest/browser-playwright": "^4.0.18",
+    "@vitest/ui": "^4.0.18",
     "esbuild": "^0.27.2",
+    "playwright": "^1.58.1",
     "ts-node": "^10.9.2",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
   },
   "engines": {
     "node": ">=24.13.0"
diff --git a/spec/javascript/example.spec.js b/spec/javascript/example.spec.js
new file mode 100644
index 0000000..8d6192d
--- /dev/null
+++ b/spec/javascript/example.spec.js
@@ -0,0 +1,12 @@
+import { describe, it, expect } from 'vitest'
+
+describe('Invisible Class', () => {
+  it('shows the element', async () => {
+    document.body.innerHTML = `
+      <button>My Button</button>
+    `
+
+    const button = document.querySelector('button')
+    await expect.element(button).toBeVisible()
+  })
+})
diff --git a/spec/javascript/test-setup.js b/spec/javascript/test-setup.js
new file mode 100644
index 0000000..e69de29
diff --git a/spec/javascript/tools/validate-color-pair-tool.spec.js b/spec/javascript/tools/validate-color-pair-tool.spec.js
new file mode 100644
index 0000000..3dcc6e0
--- /dev/null
+++ b/spec/javascript/tools/validate-color-pair-tool.spec.js
@@ -0,0 +1,78 @@
+import { describe, it, expect } from 'vitest'
+
+import ValidateColorPairTool from '../../../src/tools/validate-color-pair-tool.js'
+
+describe('ValidateColorPairTool', () => {
+  describe('getValidForegroundTokens', () => {
+    it('returns valid foreground tokens for a given background token', async () => {
+      const tool = new ValidateColorPairTool()
+
+      const response = tool.getValidForegroundTokens('op-color-primary-plus-three')
+
+      expect(response).toEqual([
+        'op-color-primary-on-plus-three',
+        'op-color-primary-on-plus-three-alt',
+      ])
+    })
+
+    it('returns valid foreground tokens for more complex colors of a given background token', async () => {
+      const tool = new ValidateColorPairTool()
+
+      const response = tool.getValidForegroundTokens('op-color-alerts-neutral-plus-one')
+
+      expect(response).toEqual([
+        'op-color-alerts-neutral-on-plus-one',
+        'op-color-alerts-neutral-on-plus-one-alt',
+      ])
+    })
+
+    it('returns an empty array when no valid foreground tokens exist for the given argument', () => {
+      const tool = new ValidateColorPairTool()
+
+      const response = tool.getValidForegroundTokens('op-color-nonexistent')
+
+      expect(response).toEqual([])
+    })
+  })
+
+  describe('getResponse', () => {
+    it('returns a valid response with valid foreground tokens for a given background token', async () => {
+      const tool = new ValidateColorPairTool()
+
+      const response = tool.getResponse('op-color-primary-plus-three', 'op-color-primary-on-plus-three')
+
+      expect(response).toEqual({
+        valid: true,
+        validForegroundTokens: [
+          'op-color-primary-on-plus-three',
+          'op-color-primary-on-plus-three-alt',
+        ]
+      })
+    })
+
+    it('returns an invalid response with valid foreground tokens for a given background token', async () => {
+      const tool = new ValidateColorPairTool()
+
+      const response = tool.getResponse('op-color-primary-plus-three', 'op-color-primary-on-plus-six')
+
+      expect(response).toEqual({
+        valid: false,
+        validForegroundTokens: [
+          'op-color-primary-on-plus-three',
+          'op-color-primary-on-plus-three-alt',
+        ]
+      })
+    })
+
+    it('returns an invalid response with an error when no tokens exist for the given background token', () => {
+      const tool = new ValidateColorPairTool()
+
+      const response = tool.getResponse('op-color-nonexistent', 'op-color-primary-on-plus-three')
+
+      expect(response).toEqual({
+        valid: false,
+        errorMessage: 'The given background token is not valid.'
+      })
+    })
+  })
+})
diff --git a/src/tools/index.ts b/src/tools/index.ts
new file mode 100644
index 0000000..71d900a
--- /dev/null
+++ b/src/tools/index.ts
@@ -0,0 +1,15 @@
+export { default as GetTokenTool } from './get-token-tool.js';
+export { default as GetTokenUsageStatsTool } from './get-token-usage-stats-tool.js';
+export { default as SearchTokensTool } from './search-tokens-tool.js';
+export { default as ListComponentsTool } from './list-components-tool.js';
+export { default as GetComponentInfoTool } from './get-component-info-tool.js';
+export { default as GetComponentTokensTool } from './get-component-tokens-tool.js';
+export { default as SearchDocumentationTool } from './search-documentation-tool.js';
+export { default as GenerateThemeTool } from './generate-theme-tool.js';
+export { default as ValidateTokenUsageTool } from './validate-token-usage-tool.js';
+export { default as ReplaceHardCodedValuesTool } from './replace-hard-coded-values-tool.js';
+export { default as CheckContrastTool } from './check-contrast-tool.js';
+export { default as SuggestTokenMigrationTool } from './suggest-token-migration-tool.js';
+export { default as GenerateComponentScaffoldTool } from './generate-component-scaffold-tool.js';
+export { default as GenerateStickerSheetTool } from './generate-sticker-sheet-tool.js';
+export { default as ValidateColorPairTool } from './validate-color-pair-tool.js';
diff --git a/src/tools/validate-color-pair-tool.ts b/src/tools/validate-color-pair-tool.ts
new file mode 100644
index 0000000..231a34d
--- /dev/null
+++ b/src/tools/validate-color-pair-tool.ts
@@ -0,0 +1,68 @@
+/**
+ * Validate Color Pair Tool
+ * Validates if a given background and foreground color token pair is valid based on the design system's naming conventions.
+ */
+
+import { z } from 'zod'
+import Tool, { type ToolInputSchema } from './tool.js'
+
+interface ToolResponse {
+  valid: boolean
+  validForegroundTokens: string[]
+}
+
+interface ToolErrorResponse {
+  valid: boolean
+  errorMessage: string
+}
+
+class ValidateColorPairTool extends Tool {
+  name = 'validate_color_pair'
+  title = 'Validate Color Pair'
+  description = 'Check if the pair is meant to be used together'
+
+  inputSchema = {
+    backgroundToken: z.string().describe('Background color token name'),
+    foregroundToken: z.string().describe('Foreground color token name'),
+  }
+
+  async handler(args: ToolInputSchema): Promise<string> {
+    const { backgroundToken, foregroundToken } = args
+
+    const response = this.getResponse(backgroundToken, foregroundToken)
+
+    return JSON.stringify(response, null, 2)
+  }
+
+  getResponse(backgroundToken: string, foregroundToken: string): ToolResponse | ToolErrorResponse {
+    const validForegroundTokens = this.getValidForegroundTokens(backgroundToken)
+    const valid = validForegroundTokens.includes(foregroundToken)
+
+    if (validForegroundTokens.length === 0) {
+      return {
+        valid: false,
+        errorMessage: 'The given background token is not valid.'
+      }
+    }
+
+    return { valid, validForegroundTokens }
+  }
+
+  getValidForegroundTokens(backgroundToken: string): string[] {
+    // Insert '-on-' after the segment before the last two (e.g. op-color-alerts-neutral-plus-one -> op-color-alerts-neutral-on-plus-one)
+    const backgroundParts = backgroundToken.split('-');
+    if (backgroundParts.length < 4) return [];
+
+    // For tokens with 4 segments, insert after 3rd; for more, insert after (length - 2)th
+    const insertAt = backgroundParts.length > 4 ? backgroundParts.length - 2 : 3
+    const onParts = [...backgroundParts]
+    onParts.splice(insertAt, 0, 'on')
+
+    const onToken = onParts.join('-')
+    const onAltToken = `${onToken}-alt`
+
+    return [onToken, onAltToken]
+  }
+}
+
+export default ValidateColorPairTool
diff --git a/vitest.config.js b/vitest.config.js
new file mode 100644
index 0000000..47f8b71
--- /dev/null
+++ b/vitest.config.js
@@ -0,0 +1,23 @@
+import { playwright } from '@vitest/browser-playwright'
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    globals: true,
+    reporters: process.env.CI ? ['dot', 'github-actions'] : ['dot'],
+    name: 'browser',
+    include: ['spec/javascript/**/*.{test,spec}.js'],
+    setupFiles: ['./spec/javascript/test-setup.js'],
+    testTimeout: process.env.CI ? 15_000 : 5_000,
+    browser: {
+      enabled: true,
+      headless: true,
+      provider: playwright(),
+      instances: [
+        {
+          browser: 'chromium',
+        },
+      ]
+    }
+  }
+})

From 0b848620a2c3c00da715105c2c0aecdfa88a5d29 Mon Sep 17 00:00:00 2001
From: Dallas Peters <dallaspeters@gmail.com>
Date: Mon, 9 Feb 2026 13:55:26 -0600
Subject: [PATCH 27/28] Move tool markdown to src/tools/_templates and clean
 duplicates; readToolFile now targets _templates

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 src/tools/check-contrast-error.md             |  7 ---
 src/tools/check-contrast-result.md            |  9 ---
 .../generate-component-scaffold-usage.md      | 23 -------
 .../generate-sticker-sheet-instructions.md    | 22 -------
 src/tools/generate-theme-instructions.md      | 63 -------------------
 src/tools/generate-theme-output.md            | 24 -------
 src/tools/suggest-token-migration-header.md   |  5 --
 src/tools/suggest-token-migration-none.md     |  6 --
 src/tools/validate-token-usage-header.md      |  7 ---
 src/tools/validate-token-usage-valid.md       |  7 ---
 10 files changed, 173 deletions(-)
 delete mode 100644 src/tools/check-contrast-error.md
 delete mode 100644 src/tools/check-contrast-result.md
 delete mode 100644 src/tools/generate-component-scaffold-usage.md
 delete mode 100644 src/tools/generate-sticker-sheet-instructions.md
 delete mode 100644 src/tools/generate-theme-instructions.md
 delete mode 100644 src/tools/generate-theme-output.md
 delete mode 100644 src/tools/suggest-token-migration-header.md
 delete mode 100644 src/tools/suggest-token-migration-none.md
 delete mode 100644 src/tools/validate-token-usage-header.md
 delete mode 100644 src/tools/validate-token-usage-valid.md

diff --git a/src/tools/check-contrast-error.md b/src/tools/check-contrast-error.md
deleted file mode 100644
index fbaecf2..0000000
--- a/src/tools/check-contrast-error.md
+++ /dev/null
@@ -1,7 +0,0 @@
-# Contrast Check Result
-
-**Foreground**: {{foregroundToken}} (`{{foregroundValue}}`)
-**Background**: {{backgroundToken}} (`{{backgroundValue}}`)
-
-✗ Unable to calculate contrast
-**Reason**: {{reason}}
diff --git a/src/tools/check-contrast-result.md b/src/tools/check-contrast-result.md
deleted file mode 100644
index 06f3fab..0000000
--- a/src/tools/check-contrast-result.md
+++ /dev/null
@@ -1,9 +0,0 @@
-# Contrast Check Result
-
-**Foreground**: {{foregroundToken}} (`{{foregroundValue}}`)
-**Background**: {{backgroundToken}} (`{{backgroundValue}}`)
-
-**Contrast Ratio**: {{contrastRatio}}:1
-**WCAG AA**: {{wcagAA}}
-**WCAG AAA**: {{wcagAAA}}
-**Score**: {{score}}
diff --git a/src/tools/generate-component-scaffold-usage.md b/src/tools/generate-component-scaffold-usage.md
deleted file mode 100644
index 8c8abec..0000000
--- a/src/tools/generate-component-scaffold-usage.md
+++ /dev/null
@@ -1,23 +0,0 @@
-# {{componentName}} Usage
-
-## Import
-
-```typescript
-import { {{componentName}} } from './components/{{componentName}}';
-```
-
-## Basic Usage
-
-```tsx
-<{{componentName}}>
-  Your content here
-</{{componentName}}>
-```
-
-## With Custom ClassName
-
-```tsx
-<{{componentName}} className="custom-class">
-  Your content here
-</{{componentName}}>
-```
diff --git a/src/tools/generate-sticker-sheet-instructions.md b/src/tools/generate-sticker-sheet-instructions.md
deleted file mode 100644
index f3dfd40..0000000
--- a/src/tools/generate-sticker-sheet-instructions.md
+++ /dev/null
@@ -1,22 +0,0 @@
-# Optics Sticker Sheet - {{framework}}
-
-This sticker sheet provides a visual reference for all Optics design tokens and components.
-
-## Usage
-
-1. Copy the component code below into your {{framework}} project
-2. Copy the CSS styles into your stylesheet
-3. Import and use the components in your app
-4. Replace placeholders with actual component implementations
-
-## Files Generated
-
-- **Component Code**: Ready-to-use {{framework}} components
-- **Styles**: CSS using Optics design tokens
-- **Examples**: Visual specimens of colors, typography, and components
-
-## Next Steps
-
-- Customize the examples to match your specific components
-- Add interactive states (hover, focus, disabled)
-- Include additional token categories as needed
diff --git a/src/tools/generate-theme-instructions.md b/src/tools/generate-theme-instructions.md
deleted file mode 100644
index ff891d2..0000000
--- a/src/tools/generate-theme-instructions.md
+++ /dev/null
@@ -1,63 +0,0 @@
-# {{themeName}} Theme
-
-## Overview
-This theme was generated by Optics MCP and uses the Optics Design System tokens.
-
-## Step 1: Install Optics Design System
-
-### Option A: Via npm (Recommended)
-```bash
-npm install @rolemodel/optics
-```
-
-Then import in your CSS:
-```css
-@import "@rolemodel/optics/dist/optics.css";
-```
-
-### Option B: Via CDN (jsDelivr)
-```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@rolemodel/optics@latest/dist/optics.css">
-```
-
-### Option C: Via unpkg
-```html
-<link rel="stylesheet" href="https://unpkg.com/@rolemodel/optics@latest/dist/optics.css">
-```
-
-## Step 2: Add Your Custom Theme Overrides
-
-Create a `theme.css` file with the custom HSL color values below and load it AFTER Optics:
-
-```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@rolemodel/optics@latest/dist/optics.css">
-<link rel="stylesheet" href="./theme.css">
-```
-
-## Token Summary
-
-{{tokenSummary}}
-
-## Step 3: Using Optics Components
-
-**IMPORTANT:** Optics has pre-built components with specific HTML structure and CSS classes.
-
-Do NOT make up CSS classes. Use the actual Optics components and their documentation:
-
-**Component Documentation:** https://docs.optics.rolemodel.design
-
-Your custom theme will automatically apply to all Optics components through the HSL base values.
-
-### Example: Using an Optics Button
-Refer to the Optics documentation for the actual button HTML structure and CSS classes.
-Your theme colors will apply automatically through the `--op-color-primary-*` variables.
-
-### Figma Variables
-Import the `figma-variables.json` file into Figma:
-1. Open your Figma file
-2. Go to Variables panel
-3. Import → Select `figma-variables.json`
-
-## Token Categories
-
-{{tokenCategories}}
diff --git a/src/tools/generate-theme-output.md b/src/tools/generate-theme-output.md
deleted file mode 100644
index a34d95a..0000000
--- a/src/tools/generate-theme-output.md
+++ /dev/null
@@ -1,24 +0,0 @@
-# {{brandName}} Theme Generated
-
-## CSS Variables
-
-```css
-{{cssVariables}}
-```
-
-## Figma Variables
-
-Save this as `figma-variables.json`:
-
-```json
-{{figmaVariables}}
-```
-
-## Summary
-
-- **Total tokens**: {{totalTokens}}
-- **Colors**: {{colorTokens}}
-- **Typography**: {{typographyTokens}}
-- **Spacing**: {{spacingTokens}}
-
-{{documentation}}
diff --git a/src/tools/suggest-token-migration-header.md b/src/tools/suggest-token-migration-header.md
deleted file mode 100644
index 20db436..0000000
--- a/src/tools/suggest-token-migration-header.md
+++ /dev/null
@@ -1,5 +0,0 @@
-# Token Migration Suggestions
-
-**Input Value**: `{{inputValue}}`
-
-## Suggested Tokens
diff --git a/src/tools/suggest-token-migration-none.md b/src/tools/suggest-token-migration-none.md
deleted file mode 100644
index c0a5d3c..0000000
--- a/src/tools/suggest-token-migration-none.md
+++ /dev/null
@@ -1,6 +0,0 @@
-# Token Migration Suggestions
-
-**Input Value**: `{{inputValue}}`
-
-No suitable tokens found for this value.
-Consider adding a new token to your design system.
diff --git a/src/tools/validate-token-usage-header.md b/src/tools/validate-token-usage-header.md
deleted file mode 100644
index 6ccc5b4..0000000
--- a/src/tools/validate-token-usage-header.md
+++ /dev/null
@@ -1,7 +0,0 @@
-# Token Validation Report
-
-**Status**: {{status}}
-**Issues**: {{issueCount}}
-**Values Checked**: {{totalChecked}}
-
-## Issues
diff --git a/src/tools/validate-token-usage-valid.md b/src/tools/validate-token-usage-valid.md
deleted file mode 100644
index eaa5b43..0000000
--- a/src/tools/validate-token-usage-valid.md
+++ /dev/null
@@ -1,7 +0,0 @@
-# Token Validation Report
-
-**Status**: ✓ Valid
-**Issues**: 0
-**Values Checked**: {{totalChecked}}
-
-✓ No issues found! All values use design tokens.

From 5223ac552cf65b102293d69832f3500cb3d71576 Mon Sep 17 00:00:00 2001
From: Dallas Peters <dallaspeters@gmail.com>
Date: Mon, 9 Feb 2026 14:46:29 -0600
Subject: [PATCH 28/28] Refactor index.ts to remove unused tool imports and
 consolidate tool registration.

---
 src/index.ts | 21 +--------------------
 1 file changed, 1 insertion(+), 20 deletions(-)

diff --git a/src/index.ts b/src/index.ts
index 2f71b4c..6178fd0 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -12,17 +12,6 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import type { ListPromptsRequestSchema, GetPromptRequestSchema } from "@modelcontextprotocol/sdk/types"
 import { z } from 'zod';
 import { designTokens } from './optics-data.js';
-<<<<<<< HEAD
-=======
-import { generateTheme } from './tools/theme-generator.js';
-import { validateTokenUsage, formatValidationReport } from './tools/validate.js';
-
-import { checkTokenContrast, formatContrastResult } from './tools/accessibility.js';
-import { suggestTokenMigration, formatMigrationSuggestions } from './tools/migration.js';
-import { generateComponentScaffold, formatScaffoldOutput } from './tools/scaffold.js';
-import { generateStickerSheet, formatStickerSheet } from './tools/sticker-sheet.js';
-
->>>>>>> a8fdcbb (Extract the replace hard coded values tool (#26))
 // Resources
 import * as systemOverview from './resources/system-overview.js';
 import * as documentationSection from './resources/documentation/section.js';
@@ -53,7 +42,6 @@ import ListComponentsTool from './tools/list-components-tool.js';
 import GetComponentInfoTool from './tools/get-component-info-tool.js';
 import GetComponentTokensTool from './tools/get-component-tokens-tool.js';
 import SearchDocumentationTool from './tools/search-documentation-tool.js';
-<<<<<<< HEAD
 import GenerateThemeTool from './tools/generate-theme-tool.js';
 import ValidateTokenUsageTool from './tools/validate-token-usage-tool.js';
 import ReplaceHardCodedValuesTool from './tools/replace-hard-coded-values-tool.js';
@@ -72,9 +60,8 @@ import CalculateContrastTool from './tools/calculation/calculate-contrast-tool.j
 import CalculateHslTokensTool from './tools/calculation/calculate-hsl-tokens-tool.js';
 
 // Tools
-=======
 import ReplaceHardCodedValuesTool from './tools/replace-hard-coded-values-tool.js';
->>>>>>> a8fdcbb (Extract the replace hard coded values tool (#26))
+
 
 /**
  * Create and configure the MCP server
@@ -234,7 +221,6 @@ const tools = [
   new GetComponentInfoTool(),
   new GetComponentTokensTool(),
   new SearchDocumentationTool(),
-<<<<<<< HEAD
   new GenerateThemeTool(),
   new ValidateTokenUsageTool(),
   new ReplaceHardCodedValuesTool(),
@@ -250,9 +236,6 @@ const tools = [
   new GetColorScaleTool(),
   new CalculateContrastTool(),
   new CalculateHslTokensTool(),
-=======
-  new ReplaceHardCodedValuesTool()
->>>>>>> a8fdcbb (Extract the replace hard coded values tool (#26))
 ]
 
 tools.forEach((tool) => {
@@ -279,7 +262,6 @@ tools.forEach((tool) => {
 })
 
 /**
-<<<<<<< HEAD
 =======
  * Tool: Generate Theme
  */
@@ -469,7 +451,6 @@ server.registerTool(
 );
 
 /**
->>>>>>> a8fdcbb (Extract the replace hard coded values tool (#26))
  * Start the server
  */
 async function main() {