stitch-kit 1.5.0

package/bin/stitch-kit.mjs

@@ -0,0 +1,430 @@
+#!/usr/bin/env node
+
+/**
+ * stitch-kit CLI installer
+ *
+ * Installs stitch-kit skills and agent definition for Claude Code and/or Codex CLI.
+ * Detects which platforms are available and installs to the right locations.
+ *
+ * Usage:
+ *   npx stitch-kit              — install (default)
+ *   npx stitch-kit install      — install or update
+ *   npx stitch-kit update       — same as install (npx always fetches latest)
+ *   npx stitch-kit uninstall    — remove stitch-kit from all platforms
+ *   npx stitch-kit status       — show what's installed where
+ *
+ * Platforms:
+ *   Claude Code — agent → ~/.claude/agents/, MCP config, plugin recommendation
+ *   Codex CLI   — agent → ~/.codex/agents/, skills → ~/.codex/skills/
+ */
+
+import { existsSync, mkdirSync, cpSync, rmSync, readFileSync, readdirSync, lstatSync, symlinkSync, unlinkSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+// ── Constants ──────────────────────────────────────────────────────────────────
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PACKAGE_ROOT = resolve(__dirname, '..');
+
+const HOME = homedir();
+const CLAUDE_DIR = join(HOME, '.claude');
+const CLAUDE_AGENTS_DIR = join(CLAUDE_DIR, 'agents');
+const CLAUDE_PLUGINS_FILE = join(CLAUDE_DIR, 'plugins', 'installed_plugins.json');
+
+const CODEX_DIR = join(HOME, '.codex');
+const CODEX_AGENTS_DIR = join(CODEX_DIR, 'agents');
+const CODEX_SKILLS_DIR = join(CODEX_DIR, 'skills');
+
+const SKILLS_SRC = join(PACKAGE_ROOT, 'skills');
+const AGENTS_SRC = join(PACKAGE_ROOT, 'agents');
+
+const VERSION = JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8')).version;
+
+// ── Helpers ────────────────────────────────────────────────────────────────────
+
+/** Prints styled output — keeps it readable without dependencies */
+function log(msg) { console.log(msg); }
+function logOk(msg) { console.log(`  ✓ ${msg}`); }
+function logSkip(msg) { console.log(`  → ${msg}`); }
+function logWarn(msg) { console.log(`  ⚠ ${msg}`); }
+function logErr(msg) { console.error(`  ✗ ${msg}`); }
+
+/** Check if Claude Code is installed (has ~/.claude/) */
+function hasClaudeCode() {
+  return existsSync(CLAUDE_DIR);
+}
+
+/** Check if Codex CLI is installed (has ~/.codex/) */
+function hasCodex() {
+  return existsSync(CODEX_DIR);
+}
+
+/** Check if stitch-kit is already installed as a Claude Code plugin */
+function isPluginInstalled() {
+  if (!existsSync(CLAUDE_PLUGINS_FILE)) return false;
+  try {
+    const plugins = JSON.parse(readFileSync(CLAUDE_PLUGINS_FILE, 'utf8'));
+    // installed_plugins.json is an array of plugin objects
+    if (Array.isArray(plugins)) {
+      return plugins.some(p =>
+        (p.name && p.name.includes('stitch-kit')) ||
+        (p.source && p.source.includes('stitch-kit'))
+      );
+    }
+    // Or it could be an object with plugin entries
+    return JSON.stringify(plugins).includes('stitch-kit');
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Copy a file, creating parent directories as needed.
+ * Returns true if the file was written, false if skipped.
+ */
+function copyFile(src, dest, overwrite = true) {
+  if (!existsSync(src)) {
+    logErr(`Source not found: ${src}`);
+    return false;
+  }
+  if (existsSync(dest) && !overwrite) {
+    logSkip(`Already exists: ${dest}`);
+    return false;
+  }
+  mkdirSync(dirname(dest), { recursive: true });
+  cpSync(src, dest, { force: true });
+  return true;
+}
+
+/**
+ * Copy an entire directory recursively.
+ * @param {string} src - Source directory
+ * @param {string} dest - Destination directory
+ */
+function copyDir(src, dest) {
+  mkdirSync(dest, { recursive: true });
+  cpSync(src, dest, { recursive: true, force: true });
+}
+
+/**
+ * List skill directory names from the source.
+ * @returns {string[]} Array of skill directory names
+ */
+function listSkills() {
+  if (!existsSync(SKILLS_SRC)) return [];
+  return readdirSync(SKILLS_SRC).filter(name => {
+    const full = join(SKILLS_SRC, name);
+    return lstatSync(full).isDirectory();
+  });
+}
+
+// ── Install ────────────────────────────────────────────────────────────────────
+
+function installClaudeCode() {
+  log('');
+  log('Claude Code');
+  log('───────────');
+
+  const pluginInstalled = isPluginInstalled();
+
+  // Always install/update the agent definition
+  const agentSrc = join(AGENTS_SRC, 'stitch-kit.md');
+  const agentDest = join(CLAUDE_AGENTS_DIR, 'stitch-kit.md');
+
+  if (copyFile(agentSrc, agentDest)) {
+    logOk(`Agent installed → ${agentDest}`);
+  }
+
+  // Check if Stitch MCP is configured by reading the settings file directly
+  let mcpConfigured = false;
+  const claudeSettingsFile = join(CLAUDE_DIR, 'settings.json');
+  if (existsSync(claudeSettingsFile)) {
+    try {
+      const settings = JSON.parse(readFileSync(claudeSettingsFile, 'utf8'));
+      mcpConfigured = settings.mcpServers && 'stitch' in settings.mcpServers;
+    } catch { /* ignore parse errors */ }
+  }
+  // Also check project-level .mcp.json in common locations
+  if (!mcpConfigured) {
+    const mcpJson = join(process.cwd(), '.mcp.json');
+    if (existsSync(mcpJson)) {
+      try {
+        const mcp = JSON.parse(readFileSync(mcpJson, 'utf8'));
+        mcpConfigured = mcp.mcpServers && 'stitch' in mcp.mcpServers;
+      } catch { /* ignore */ }
+    }
+  }
+
+  if (!mcpConfigured) {
+    log('');
+    log('  Stitch MCP not detected. To add it, run in your terminal:');
+    log('');
+    log('    claude mcp add stitch -- npx -y @google/stitch-mcp');
+    log('');
+  } else {
+    logOk('Stitch MCP already configured');
+  }
+
+  // Skills: plugin system is the right path for Claude Code
+  if (pluginInstalled) {
+    logOk('Plugin already installed — skills delivered via plugin system');
+    log('');
+    log('  To update the plugin to the latest version:');
+    log('    /plugin install stitch-kit@stitch-kit');
+  } else {
+    log('');
+    log('  For full skill support in Claude Code, install the plugin:');
+    log('');
+    log('    /plugin marketplace add https://github.com/gabelul/stitch-kit.git');
+    log('    /plugin install stitch-kit@stitch-kit');
+    log('');
+    log('  The agent works standalone with MCP tools, but skills add');
+    log('  prompt engineering, design tokens, and framework conversion.');
+  }
+}
+
+function installCodex() {
+  log('');
+  log('Codex CLI');
+  log('─────────');
+
+  // Install agent
+  const agentSrc = join(AGENTS_SRC, 'stitch-kit.md');
+  const agentDest = join(CODEX_AGENTS_DIR, 'stitch-kit.md');
+  mkdirSync(CODEX_AGENTS_DIR, { recursive: true });
+
+  if (copyFile(agentSrc, agentDest)) {
+    logOk(`Agent installed → ${agentDest}`);
+  }
+
+  // Install skills — copy each skill directory
+  mkdirSync(CODEX_SKILLS_DIR, { recursive: true });
+  const skills = listSkills();
+  let installed = 0;
+  let updated = 0;
+
+  for (const skillName of skills) {
+    const src = join(SKILLS_SRC, skillName);
+    const dest = join(CODEX_SKILLS_DIR, skillName);
+
+    const existed = existsSync(dest);
+
+    // Remove old symlinks or dirs before copying fresh
+    if (existed) {
+      if (lstatSync(dest).isSymbolicLink()) {
+        unlinkSync(dest);
+      } else {
+        rmSync(dest, { recursive: true, force: true });
+      }
+      updated++;
+    } else {
+      installed++;
+    }
+
+    copyDir(src, dest);
+  }
+
+  logOk(`${installed} skills installed, ${updated} updated (${skills.length} total)`);
+
+  // Check Stitch MCP in codex config
+  const codexConfig = join(CODEX_DIR, 'config.toml');
+  let mcpConfigured = false;
+  if (existsSync(codexConfig)) {
+    try {
+      const content = readFileSync(codexConfig, 'utf8');
+      mcpConfigured = content.includes('stitch');
+    } catch { /* ignore */ }
+  }
+
+  if (!mcpConfigured) {
+    log('');
+    log('  Add Stitch MCP to ~/.codex/config.toml:');
+    log('');
+    log('    [mcp_servers.stitch]');
+    log('    command = "npx"');
+    log('    args = ["-y", "@google/stitch-mcp"]');
+  } else {
+    logOk('Stitch MCP already in config.toml');
+  }
+
+  log('');
+  log('  Use $stitch-kit to invoke the agent');
+  log('  Use $stitch-orchestrator for the full pipeline');
+}
+
+function install() {
+  log(`stitch-kit v${VERSION} — installer`);
+  log('════════════════════════════════');
+
+  const claude = hasClaudeCode();
+  const codex = hasCodex();
+
+  if (!claude && !codex) {
+    log('');
+    logErr('Neither Claude Code (~/.claude/) nor Codex CLI (~/.codex/) found.');
+    log('');
+    log('  Install Claude Code: https://claude.ai/code');
+    log('  Install Codex CLI:   https://github.com/openai/codex');
+    log('');
+    process.exit(1);
+  }
+
+  if (claude) installClaudeCode();
+  if (codex) installCodex();
+
+  log('');
+  log('════════════════════════════════');
+  log('Done.');
+  if (claude && codex) {
+    log('Installed for both Claude Code and Codex CLI.');
+  } else if (claude) {
+    log('Installed for Claude Code.');
+  } else {
+    log('Installed for Codex CLI.');
+  }
+  log('');
+}
+
+// ── Uninstall ──────────────────────────────────────────────────────────────────
+
+function uninstall() {
+  log(`stitch-kit v${VERSION} — uninstaller`);
+  log('══════════════════════════════════');
+
+  // Claude Code — remove agent only (plugin managed separately)
+  const claudeAgent = join(CLAUDE_AGENTS_DIR, 'stitch-kit.md');
+  if (existsSync(claudeAgent)) {
+    rmSync(claudeAgent);
+    logOk('Removed Claude Code agent');
+  }
+
+  if (isPluginInstalled()) {
+    logWarn('stitch-kit plugin is still installed in Claude Code.');
+    log('  To remove it, run inside Claude Code: /plugin uninstall stitch-kit');
+  }
+
+  // Codex — remove agent + all stitch skills
+  const codexAgent = join(CODEX_AGENTS_DIR, 'stitch-kit.md');
+  if (existsSync(codexAgent)) {
+    rmSync(codexAgent);
+    logOk('Removed Codex agent');
+  }
+
+  const skills = listSkills();
+  let removed = 0;
+  for (const skillName of skills) {
+    const dest = join(CODEX_SKILLS_DIR, skillName);
+    if (existsSync(dest)) {
+      if (lstatSync(dest).isSymbolicLink()) {
+        unlinkSync(dest);
+      } else {
+        rmSync(dest, { recursive: true, force: true });
+      }
+      removed++;
+    }
+  }
+
+  if (removed > 0) {
+    logOk(`Removed ${removed} Codex skills`);
+  }
+
+  log('');
+  log('Done. Stitch MCP server config was left in place — remove manually if needed.');
+  log('');
+}
+
+// ── Status ─────────────────────────────────────────────────────────────────────
+
+function status() {
+  log(`stitch-kit v${VERSION} — status`);
+  log('══════════════════════════════');
+
+  log('');
+  log('Claude Code');
+  log('───────────');
+  if (!hasClaudeCode()) {
+    logWarn('Not installed (~/.claude/ not found)');
+  } else {
+    const agentExists = existsSync(join(CLAUDE_AGENTS_DIR, 'stitch-kit.md'));
+    const pluginExists = isPluginInstalled();
+
+    if (agentExists) logOk('Agent: installed');
+    else logWarn('Agent: not installed');
+
+    if (pluginExists) logOk('Plugin: installed (skills delivered via plugin)');
+    else logWarn('Plugin: not installed (skills not available — run /plugin install)');
+  }
+
+  log('');
+  log('Codex CLI');
+  log('─────────');
+  if (!hasCodex()) {
+    logWarn('Not installed (~/.codex/ not found)');
+  } else {
+    const agentExists = existsSync(join(CODEX_AGENTS_DIR, 'stitch-kit.md'));
+    if (agentExists) logOk('Agent: installed');
+    else logWarn('Agent: not installed');
+
+    // Count installed skills
+    const skills = listSkills();
+    let installedCount = 0;
+    for (const s of skills) {
+      if (existsSync(join(CODEX_SKILLS_DIR, s))) installedCount++;
+    }
+    if (installedCount === skills.length) {
+      logOk(`Skills: ${installedCount}/${skills.length} installed`);
+    } else if (installedCount > 0) {
+      logWarn(`Skills: ${installedCount}/${skills.length} installed (outdated — run npx stitch-kit update)`);
+    } else {
+      logWarn('Skills: none installed');
+    }
+  }
+
+  log('');
+}
+
+// ── CLI entry point ────────────────────────────────────────────────────────────
+
+const command = process.argv[2] || 'install';
+
+switch (command) {
+  case 'install':
+  case 'update':
+    install();
+    break;
+  case 'uninstall':
+  case 'remove':
+    uninstall();
+    break;
+  case 'status':
+    status();
+    break;
+  case '--version':
+  case '-v':
+    log(VERSION);
+    break;
+  case '--help':
+  case '-h':
+    log(`stitch-kit v${VERSION}`);
+    log('');
+    log('Usage: npx stitch-kit [command]');
+    log('');
+    log('Commands:');
+    log('  install   Install or update stitch-kit (default)');
+    log('  update    Same as install — npx always fetches latest');
+    log('  uninstall Remove stitch-kit from all platforms');
+    log('  status    Show what is installed where');
+    log('');
+    log('Platforms detected automatically:');
+    log('  Claude Code  ~/.claude/agents/ + plugin system');
+    log('  Codex CLI    ~/.codex/agents/ + ~/.codex/skills/');
+    log('');
+    break;
+  default:
+    logErr(`Unknown command: ${command}`);
+    log('Run: npx stitch-kit --help');
+    process.exit(1);
+}

package/docs/architecture.md

@@ -0,0 +1,118 @@
+# stitch-kit Architecture
+
+How the skills are organized and why. The short version: there are 4 layers, each with a specific job, and the MCP wrappers exist because the Stitch API has inconsistent ID format requirements that break agent runs.
+
+---
+
+## The four layers
+
+```
+stitch-kit
+├── Brain    (stitch-ui-*)      — design logic, no API calls
+├── Hands    (stitch-mcp-*)     — MCP execution, one skill per tool
+├── Quality  (stitch-design-*, stitch-animate, stitch-a11y)
+└── Loop     (stitch-loop, stitch-design-md)
+```
+
+---
+
+### Brain (`stitch-ui-*`)
+
+Pure design intelligence. These skills handle spec generation and prompt engineering without making any Stitch API calls — so they're free to run and fast to iterate on.
+
+| Skill | What it does |
+|-------|-------------|
+| `stitch-ui-design-spec-generator` | Turns a vague request or PRD into a structured Design Spec JSON (theme, color, font, device, density). This spec is the contract that feeds the prompt architect. |
+| `stitch-ui-prompt-architect` | **Two modes:** (A) vague idea → enhanced Stitch prompt; (B) Design Spec + request → structured `[Context][Layout][Components]` prompt. Mode B is what you want for reliable results — it gives Stitch much more to work with. |
+| `stitch-ui-design-variants` | Generates 3 alternative prompt variants for A/B exploration. Useful when you want to explore before committing to one direction. |
+| `stitch-ued-guide` | Visual vocabulary reference — layout patterns, aesthetic styles, device constraints, color structure. Loaded by other skills on demand to save context. |
+
+---
+
+### Hands (`stitch-mcp-*`)
+
+One skill per Stitch MCP tool. The wrappers exist because the raw Stitch API is inconsistent about ID formats and agents get this wrong constantly.
+
+**The ID format problem:**
+
+| Tool | projectId format | screenId format |
+|------|-----------------|----------------|
+| `create_project` | Returns `projects/NUMERIC_ID` | — |
+| `list_projects` | — | — |
+| `get_project` | `projects/NUMERIC_ID` | — |
+| `generate_screen_from_text` | **Numeric only** | — |
+| `list_screens` | `projects/NUMERIC_ID` | — |
+| `get_screen` | **Numeric only** | **Numeric only** |
+
+`generate_screen_from_text` and `get_screen` need bare numbers. `get_project` and `list_screens` need the `projects/` prefix. There's no obvious reason for the inconsistency — you just have to know. The wrappers bake this in so the orchestrator doesn't have to handle it inline.
+
+Naming convention: MCP tool name with underscores replaced by hyphens, prefixed with `stitch-mcp-`. So `get_screen` → `stitch-mcp-get-screen`. Full mapping in [mcp-naming-convention.md](mcp-naming-convention.md).
+
+---
+
+### Quality
+
+Skills that run after generation, before you ship anything.
+
+| Skill | What it does |
+|-------|-------------|
+| `stitch-design-system` | Extracts design tokens from Stitch output → `design-tokens.css` with CSS custom properties for light + dark mode. Also outputs `tailwind-theme.css`. |
+| `stitch-design-md` | Analyzes a Stitch project → `DESIGN.md` with color palette, typography, atmosphere, and Section 6 (Stitch prompt snippets so the next screen matches the first). |
+| `stitch-animate` | Adds purposeful animation — CSS keyframes, Framer Motion, or Svelte transitions. Handles `prefers-reduced-motion` automatically. |
+| `stitch-a11y` | WCAG 2.1 AA audit and auto-fixes: semantic HTML, ARIA labels, keyboard navigation, focus indicators, color contrast, image alt text. |
+
+---
+
+### Loop
+
+For multi-page sites where visual consistency matters. The core problem: each Stitch generation is independent, so screen 5 can look nothing like screen 1 unless you explicitly carry design state forward.
+
+The pattern:
+1. Generate a screen
+2. `stitch-design-md` analyzes it → produces `DESIGN.md`
+3. `DESIGN.md` feeds back into the next Stitch prompt via the prompt architect
+4. Repeat — every subsequent screen inherits the visual system
+
+`stitch-loop` automates this with `next-prompt.md` (carries context from the previous screen) and `SITE.md` (tracks the overall site map).
+
+---
+
+## The orchestrator
+
+`stitch-orchestrator` is the single entry point. Describe what you want to build — it coordinates the full pipeline:
+
+```
+request → spec (Brain) → prompt (Brain) → generate (Hands) → retrieve (Hands) → tokens (Quality) → convert → [animate / a11y]
+```
+
+`agents/stitch-kit.md` wraps this into a persistent agent definition for Claude Code and Codex — a Stitch specialist that routes to the right skill, knows the ID format rules, and handles Stitch URL parsing.
+
+---
+
+## Skill directory structure
+
+Each skill has the same layout:
+
+```text
+skills/[skill-name]/
+├── SKILL.md        — name, description, when to use it, instructions
+├── examples/       — real examples the agent copies instead of guessing
+├── references/     — design contracts, checklists, style guides (on-demand)
+└── scripts/        — fetch helpers, validators, code generators
+```
+
+**Why this matters:**
+
+`SKILL.md` is what the agent reads. The YAML frontmatter declares the skill's name, description (used for discovery), and optionally `allowed-tools` to restrict which tools it can invoke while active.
+
+`examples/` is the quality multiplier. Agents copy concrete patterns instead of generating boilerplate from scratch — this is why the framework conversion output is consistent instead of creative. `fetch-stitch.sh` in `scripts/` downloads Stitch HTML before the GCS URL expires (TTL is short, and the agent can't know in advance when it'll expire).
+
+`references/` is loaded on demand. Design contracts, official docs, checklists that are only needed at specific pipeline stages don't eat context window by default.
+
+---
+
+## Why stitch-kit instead of just the official skills
+
+The [official Google Stitch Skills repo](https://github.com/google-labs-code/stitch-skills) has 6 skills. They're solid but they don't coordinate, don't handle ID formats, and don't cover the full pipeline from spec to production component. stitch-kit wraps every official skill (and improves each one), adds the orchestration layer, adds the MCP wrappers that actually make the API reliable to call, and adds the quality layer that gets you from raw Stitch output to shippable code.
+
+See [README.md](../README.md#vs-the-official-google-stitch-skills) for the full comparison table.

package/docs/color-prompt-guide.md

@@ -0,0 +1,119 @@
+# Color Prompt Guide for Stitch
+
+8 ready-to-use color palettes. Copy any block directly into the **Context & Style** section of your Stitch prompt.
+
+These are structured as: app type + background / primary / accent colors (hex) + design system / style + mood.
+
+---
+
+## How to use
+
+Paste one of these blocks into your Stitch prompt's **[Context]** section, or combine with `[Layout]` and `[Components]` for a full prompt:
+
+```
+[Context]
+<paste color block here>
+
+[Layout]
+...
+
+[Components]
+...
+```
+
+For more prompt structure guidance see `stitch-ui-prompt-architect` and `stitch-ued-guide`.
+
+---
+
+## 1. Dark productivity (developer / SaaS tools)
+
+Deep blue, high contrast, fluorescent blue accent. Works for dev tools, dashboards, and productivity apps.
+
+```
+Modern productivity app dark theme, charcoal grey background #1a1a1a, primary blue #4A90E2, secondary teal #26D0CE, neutral greys #2d2d2d to #f5f5f5, accent orange #FF6B35 for CTAs, Material Design 3 inspired, high contrast for readability, professional and focused atmosphere
+```
+
+---
+
+## 2. Enterprise blue-gray (collaboration / workspace)
+
+Slate, indigo, and emerald — professional and balanced. Suits B2B, collaboration, and admin UIs.
+
+```
+Enterprise collaboration suite colors, slate grey base #1E293B, primary indigo #6366F1, secondary emerald #10B981, neutral palette #475569 to #F8FAFC, amber accent #F59E0B, Fluent Design System inspired, balanced professional appearance, suitable for team productivity
+```
+
+---
+
+## 3. Clean light (project management / task tracking)
+
+Soft blue, purple, and green — calm and organized. Works for project tools, calendars, and kanban apps.
+
+```
+Project management app bright theme, clean white background #FFFFFF, primary royal blue #2563EB, secondary purple #7C3AED, soft grey cards #F9FAFB, green success #22C55E, red alerts #DC2626, yellow warnings #F59E0B, minimal design with subtle shadows, organized and efficient visual hierarchy
+```
+
+---
+
+## 4. Airy sky (cloud services / storage)
+
+Light blue gradient background, azure primary, teal accents. Open and trustworthy. Works for cloud apps, file storage, and SaaS.
+
+```
+Cloud storage desktop client colors, sky blue gradient #E0F2FE to #DBEAFE, primary azure #0EA5E9, secondary slate #64748B, white panels #FFFFFF with soft shadows, teal accents #14B8A6, folder yellow #FCD34D, modern airy interface, trustworthy and spacious feeling
+```
+
+---
+
+## 5. Classic business (email / communication)
+
+Neutral grays and navy — familiar and safe. Works for email clients, messaging apps, and corporate tools.
+
+```
+Email client professional palette, light grey background #F7F8FA, primary navy #1E40AF, secondary grey blue #64748B, white message cards #FFFFFF, unread indicator blue #3B82F6, important flag red #EF4444, archive green #10B981, classic business communication aesthetic
+```
+
+---
+
+## 6. Creative gradient (design / creative tools)
+
+Deep purple to electric blue, neon pink accents, dark background. Glassmorphism-ready. Works for design tools, creative apps, and portfolios.
+
+```
+Creative software gradient color palette, deep purple #6B46C1 to electric blue #2563EB, dark background #0F0F0F, neon pink accent #FF0080, lime green highlights #84CC16, glassmorphism elements with transparency, futuristic and inspiring mood, suitable for digital artists and designers
+```
+
+---
+
+## 7. Cinema / broadcast (video editing / media)
+
+True black background, amber and red accents, blue timeline tracks. Professional broadcast aesthetic. Works for video tools, media apps, and production software.
+
+```
+Video editing suite cinema theme, true black background #000000, primary amber #F59E0B, secondary red #DC2626, timeline tracks in gradient blues #1E40AF to #3B82F6, playback controls silver #E5E7EB, render progress green #10B981, professional broadcast studio inspired design
+```
+
+---
+
+## 8. Industrial precision (3D / engineering tools)
+
+Dark gray viewport, orange primary, steel blue secondary. Technical and focused. Works for 3D modeling, engineering, and high-frequency professional tools.
+
+```
+3D modeling app industrial colors, dark grey viewport #1F1F1F, primary orange #F97316, secondary steel blue #475569, grid lines subtle grey #374151, selection yellow #FDE047, tool panels charcoal #262626, metallic accents #94A3B8, technical precision focused interface
+```
+
+---
+
+## Mobile-specific notes
+
+When using these palettes for `deviceType: MOBILE` designs:
+- Increase contrast — small screens in bright sunlight need higher ratios
+- Avoid small accent colors for primary actions; use them for status only
+- Test dark mode specifically — pure `#000000` backgrounds can feel harsh on OLED; prefer `#0F0F0F` or `#18181B`
+
+## Dark mode token mapping
+
+After generation, use `stitch-design-system` to extract the exact hex values from the Stitch HTML and generate:
+- `design-tokens.css` — CSS custom properties with light + dark variants
+- `tailwind-theme.css` — Tailwind v4 `@theme` block