claudemesh/.context/turbostarter-framework-context/wireframes/wireframe-theming.md

TurboStarter Wireframe Theming System

Overview

The TurboStarter wireframe theming system uses token-based color references that allow Excalidraw wireframes to be themed dynamically. Instead of hardcoding hex colors directly in Excalidraw files, designers use semantic tokens like $background, $primary, etc. These tokens are later replaced with actual colors using the apply-theme.js script.

How It Works

1. Create wireframes using tokens - Use $tokenName syntax for colors in Excalidraw's strokeColor and backgroundColor properties
2. Store the template - Save the .excalidraw file with tokens intact
3. Apply a theme - Run apply-theme.js to generate a themed version with real hex colors
4. Multiple outputs - Generate different themed versions from the same template

This approach enables:

• Single source of truth for wireframes
• Consistent branding across all diagrams
• Easy theme switching without manual color updates
• Light/dark mode variants from the same template

---

Token Reference

Token	Usage	Light Mode Example	Dark Mode Example
$background	Page/screen background	#ffffff (white)	#1a1a1a (near black)
$foreground	Primary text color	#1a1a1a (dark gray)	#fafafa (near white)
$primary	Brand color, CTAs, active states	Varies by theme (e.g., #e85d04 orange)	Same or adjusted
$secondary	Secondary backgrounds, subtle fills	#f5f5f5 (light gray)	#262626 (dark gray)
$muted	Disabled states, placeholders, subtle text	#f5f5f5 (light gray)	#262626 (dark gray)
$border	Borders, dividers, outlines	#e5e5e5 (gray)	#404040 (medium gray)
$card	Card and panel backgrounds	#ffffff (white)	#1f1f1f (dark)
$destructive	Delete buttons, error states, warnings	#ef4444 (red)	#ef4444 (red)
$success	Success states, confirmations	#22c55e (green)	#22c55e (green)
$sidebar	Sidebar background	#fafafa (off-white)	#171717 (darker)
$sidebar-foreground	Sidebar text	#1a1a1a (dark)	#fafafa (light)

Token Naming Convention

• Tokens always start with $ prefix
• Names match TurboStarter CSS variable names
• Use kebab-case for multi-word tokens

---

Available Themes

The system includes 18 themes (9 color palettes x 2 modes):

Color Palettes

Color	Light Theme	Dark Theme	Primary Color
Orange	orange-light	orange-dark	#e85d04
Blue	blue-light	blue-dark	#2563eb
Green	green-light	green-dark	#16a34a
Red	red-light	red-dark	#dc2626
Rose	rose-light	rose-dark	#e11d48
Violet	violet-light	violet-dark	#7c3aed
Yellow	yellow-light	yellow-dark	#eab308
Gray	gray-light	gray-dark	#374151 / #6b7280
Stone	stone-light	stone-dark	#44403c / #78716c

Theme Structure

Each theme defines all 11 tokens. Example for orange-light:

{
  "$background": "#ffffff",
  "$foreground": "#1a1a1a",
  "$primary": "#e85d04",
  "$secondary": "#f5f5f5",
  "$muted": "#f5f5f5",
  "$border": "#e5e5e5",
  "$card": "#ffffff",
  "$destructive": "#ef4444",
  "$success": "#22c55e",
  "$sidebar": "#fafafa",
  "$sidebar-foreground": "#1a1a1a"
}

---

How to Apply Themes

Prerequisites

• Node.js installed
• wireframe-themes.json in the same directory as apply-theme.js

Basic Usage

node apply-theme.js <input.excalidraw> <theme-name> [output.excalidraw]

Examples

# Apply orange-light theme, auto-generate output filename
node apply-theme.js wireframe.excalidraw orange-light
# Output: wireframe-orange-light.excalidraw

# Apply blue-dark theme with custom output
node apply-theme.js wireframe.excalidraw blue-dark themed-wireframe.excalidraw

# Apply theme with verbose output
node apply-theme.js wireframe.excalidraw violet-light --verbose

Generating Multiple Themes

# Generate all light themes
for theme in orange blue green red rose violet yellow gray stone; do
  node apply-theme.js wireframe.excalidraw ${theme}-light
done

# Generate light and dark for one color
node apply-theme.js wireframe.excalidraw orange-light
node apply-theme.js wireframe.excalidraw orange-dark

---

For AI Assistants

Quick Reference

When creating or modifying Excalidraw wireframes:

1. Always use tokens - Never hardcode hex colors for themeable elements
2. Token format - Use $tokenName in strokeColor and backgroundColor fields
3. Common patterns:
   • Page background: "backgroundColor": "$background"
   • Text/icons: "strokeColor": "$foreground"
   • Buttons/CTAs: "backgroundColor": "$primary" + "strokeColor": "$primary"
   • Cards/panels: "backgroundColor": "$card" + "strokeColor": "$border"
   • Input fields: "backgroundColor": "$background" + "strokeColor": "$border"
   • Disabled elements: "backgroundColor": "$muted" + "strokeColor": "$muted"
   • Error states: "strokeColor": "$destructive"
   • Success states: "strokeColor": "$success"

Example Element

{
  "type": "rectangle",
  "id": "button-cta",
  "x": 100,
  "y": 200,
  "width": 120,
  "height": 40,
  "strokeColor": "$primary",
  "backgroundColor": "$primary",
  "fillStyle": "solid",
  "strokeWidth": 2,
  "roundness": { "type": 3, "value": 4 }
}

Workflow

1. Create wireframe using $tokens for all colors
2. Save as .excalidraw file
3. Run apply-theme.js to generate themed versions
4. Use themed output in documentation or presentations

---

Color Mapping to TurboStarter CSS

Wireframe tokens map directly to TurboStarter's Tailwind CSS variables:

Wireframe Token	CSS Variable	Tailwind Class
$background	--background	bg-background
$foreground	--foreground	text-foreground
$primary	--primary	bg-primary, text-primary
$secondary	--secondary	bg-secondary
$muted	--muted	bg-muted, text-muted-foreground
$border	--border	border-border
$card	--card	bg-card
$destructive	--destructive	bg-destructive, text-destructive
$success	--success	bg-success, text-success
$sidebar	--sidebar	bg-sidebar
$sidebar-foreground	--sidebar-foreground	text-sidebar-foreground

CSS Variable Definition (TurboStarter)

TurboStarter defines these in globals.css:

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-secondary: var(--secondary);
  --color-muted: var(--muted);
  --color-border: var(--border);
  --color-card: var(--card);
  --color-destructive: var(--destructive);
  --color-success: var(--success);
  --color-sidebar: var(--sidebar);
  --color-sidebar-foreground: var(--sidebar-foreground);
  /* ... additional variables */
}

---

File Locations

File	Path	Purpose
Theme definitions	_bmad-output/excalidraw-diagrams/wireframe-themes.json	All 18 theme color mappings
Theme applicator	_bmad-output/excalidraw-diagrams/apply-theme.js	Script to apply themes
Template storage	_bmad-output/excalidraw-diagrams/	Store wireframe templates here
TurboStarter themes	packages/ui/shared/src/styles/themes/	Source theme definitions (OKLCH)

---

Extending the System

Adding Custom Tokens

1. Add the token to wireframe-themes.json under each theme
2. Use the new token in wireframes as $token-name

Adding Custom Themes

Add a new entry to wireframe-themes.json:

{
  "themes": {
    "custom-brand-light": {
      "$background": "#ffffff",
      "$foreground": "#1a1a1a",
      "$primary": "#your-brand-color",
      "$secondary": "#f5f5f5",
      "$muted": "#f5f5f5",
      "$border": "#e5e5e5",
      "$card": "#ffffff",
      "$destructive": "#ef4444",
      "$success": "#22c55e",
      "$sidebar": "#fafafa",
      "$sidebar-foreground": "#1a1a1a"
    }
  }
}

---

Troubleshooting

Token Not Replaced

• Verify the token name matches exactly (case-sensitive)
• Ensure the token includes the $ prefix
• Check that the theme includes the token in wireframe-themes.json

Colors Look Wrong

• Confirm you're using the correct theme name (light vs dark)
• Verify the wireframe-themes.json file is up to date
• Check for typos in token names

Script Errors

• Ensure wireframe-themes.json is valid JSON
• Verify the input .excalidraw file is valid JSON
• Check Node.js is installed and accessible