Fix theme generator to include Optics installation and stop inventing classes

- Added Optics installation instructions (npm, jsDelivr CDN, unpkg)
- Removed made-up CSS examples (button-primary, card, etc)
- Direct users to actual Optics documentation for components
- Added Mistake 5: Don't invent component classes like .op-button
- Emphasize that Optics has specific HTML structure to follow
- Version bump to 0.2.4

Author: dallasbpeters

SYSTEM_OVERVIEW.md

@@ -287,6 +287,11 @@ When you call `get_component_info` for "Button", you'll see tokens like:
 ❌ Using arbitrary text colors on colored backgrounds  
 ✅ Using the matching `-on-` token: `--op-color-primary-on-base` on `--op-color-primary-base`
 
+### Mistake 5: Inventing Component Classes
+❌ Making up classes like `.button-primary`, `.op-button`, `.card-primary`  
+✅ Use ONLY the actual Optics component HTML/CSS from https://docs.optics.rolemodel.design  
+✅ Optics components have specific HTML structure - don't invent your own
+
 ## 📚 Token Discovery Workflow
 
 **Step 1: Identify what you need**

package.json

@@ -1,6 +1,6 @@
 {
   "name": "optics-mcp",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "MCP Server for Optics Design System documentation and token usage with AI-optimized comprehension guide",
   "main": "dist/index.js",
   "type": "module",

src/index.ts

@@ -289,10 +289,15 @@ border-color: var(--op-color-neutral-plus-four);    /* Light border */
 ❌ \`var(--color-primary)\`  
 ✅ \`var(--op-color-primary-base)\`
 
-### Mistake 4: Not Using "On" Tokens for Text
+### Mistake 4: Not Using \"On\" Tokens for Text
 ❌ Using arbitrary text colors on colored backgrounds  
 ✅ Using the matching \`-on-\` token: \`--op-color-primary-on-base\` on \`--op-color-primary-base\`
 
+### Mistake 5: Inventing Component Classes
+❌ Making up classes like \`.button-primary\`, \`.op-button\`, \`.card-primary\`  
+✅ Use ONLY the actual Optics component HTML/CSS from https://docs.optics.rolemodel.design  
+✅ Optics components have specific HTML structure - don't invent your own
+
 ## 🎯 Quick Reference
 
 ### Most Common Tokens
@@ -812,7 +817,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'generate_theme',
-        description: 'Generate a custom theme with CSS variables and Figma Variables JSON',
+        description: 'Generate a custom Optics theme with CSS variable overrides. Includes installation instructions for @rolemodel/optics via npm or CDN (jsDelivr/unpkg). Output includes complete setup guide with actual Optics token names.',
         inputSchema: {
           type: 'object',
           properties: {

src/tools/theme-generator.ts

@@ -263,7 +263,38 @@ function generateDocumentation(themeName: string, tokens: DesignToken[]): string
     `# ${themeName} Theme`,
     '',
     '## Overview',
-    'This theme was generated by Optics MCP and includes a complete set of design tokens.',
+    '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',
     ''
@@ -274,17 +305,19 @@ function generateDocumentation(themeName: string, tokens: DesignToken[]): string
   }
 
   lines.push('');
-  lines.push('## Usage');
+  lines.push('## Step 3: Using Optics Components');
   lines.push('');
-  lines.push('### CSS Variables');
-  lines.push('```css');
-  lines.push('/* Use tokens with var() */');
-  lines.push('.button {');
-  lines.push('  background-color: var(--color-primary);');
-  lines.push('  padding: var(--spacing-md);');
-  lines.push('  border-radius: var(--border-radius-md);');
-  lines.push('}');
-  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:');