Theme System and Migration

Semantic surface token system and migration from hardcoded Tailwind colors

Status

Migration in progress. The assembly editor components have been fully migrated to semantic theme tokens. The remaining instances are being migrated in phases.

For the complete semantic surface system rules, banned patterns, and migration reference, see CLAUDE.md at the project root.

Migration Rules

Replace ALL hardcoded Tailwind colors with semantic surface classes
Fix surface mismatches — text classes must match their container’s surface
Remove legacy theme-classes imports (backgrounds, text, borders, status, buttons, legacySurfaces, styleVars, componentStyles)
Remove legacy CSS class usage (bg-base, bg-card, text-base, text-secondary, btn-primary, input-base, etc.)
After all migration is complete: Remove legacy exports from theme-classes.ts, legacy CSS from globals.css, and generateLegacyProperties from SettingsContext.tsx

Semantic Token Mapping Guide

Background Colors

Hardcoded	Semantic Token
`bg-gray-50`, `bg-gray-100`	`bg-surface-base`
`bg-gray-200`, `bg-gray-300`	`bg-surface-secondary`
`bg-gray-600` through `bg-gray-900`	`bg-surface-elevated`
`bg-blue-50`, `bg-blue-100`	`bg-surface-info`
`bg-blue-500` through `bg-blue-700`	`bg-surface-primary`, `bg-surface-primary-hover`
`bg-green-50`, `bg-green-100`	`bg-surface-success`
`bg-green-500` through `bg-green-700`	`bg-surface-success`, `bg-surface-success-hover`
`bg-red-50`, `bg-red-100`	`bg-surface-error`
`bg-red-500` through `bg-red-700`	`bg-surface-error`, `bg-surface-error-hover`
`bg-yellow-50`, `bg-yellow-100`	`bg-surface-warning`
`bg-yellow-500`, `bg-yellow-600`	`bg-surface-warning`, `bg-surface-warning-hover`
`bg-purple-50`, `bg-purple-100`	`bg-surface-accent`
`bg-purple-500` through `bg-purple-700`	`bg-surface-accent`, `bg-surface-accent-hover`
`bg-orange-50`, `bg-orange-100`	`bg-surface-warning` or `bg-surface-accent`
`bg-orange-500`, `bg-orange-600`	`bg-surface-warning` or `bg-surface-accent`

Text Colors

Hardcoded	Semantic Token
`text-white` (on colored bg)	`text-surface-primary-text` (on solid primary bg)
`text-gray-100`, `text-gray-200`	`text-surface-elevated-text`
`text-gray-300`, `text-gray-400`	`text-surface-elevated-text-secondary`
`text-gray-500`, `text-gray-600`	`text-surface-base-text-secondary`
`text-gray-700` through `text-gray-900`	`text-surface-base-text`
`text-blue-400` through `text-blue-700`	`text-surface-primary-color` or `text-surface-info-text`
`text-green-600` through `text-green-800`	`text-surface-success-text`
`text-red-600` through `text-red-800`	`text-surface-error-text`
`text-yellow-600`, `text-yellow-800`	`text-surface-warning-text`
`text-purple-600` through `text-purple-800`	`text-surface-accent-text`
`text-orange-600`, `text-orange-700`	`text-surface-warning-text` or `text-surface-accent-text`
`text-indigo-600`	`text-surface-accent-text`
`text-teal-600`	`text-surface-info-text`

Border Colors

Hardcoded	Semantic Token
`border-gray-200`, `border-gray-300`	`border-surface-base-border` or `border-surface-elevated-border`
`border-gray-600`, `border-gray-700`	`border-surface-elevated-border`
`border-blue-200` through `border-blue-500`	`border-surface-primary-border` or `border-surface-info-border`
`border-green-300`, `border-green-500`	`border-surface-success-border`
`border-red-500`	`border-surface-error-border`
`border-purple-300` through `border-purple-700`	`border-surface-accent-border`
`border-yellow-300`	`border-surface-warning-border`
`border-orange-300`, `border-orange-500`	`border-surface-warning-border`

Ring Colors

Hardcoded	Semantic Token
`ring-blue-500`	`ring-surface-primary`
`ring-green-500`	`ring-surface-success`
`ring-red-500`	`ring-surface-error`
`ring-purple-500`	`ring-surface-accent`

Common Patterns

Button Actions

Primary (Edit, View, Create): bg-surface-primary text-surface-primary-text hover:bg-surface-primary-hover
Success (Save, Approve): bg-surface-success text-surface-success-text hover:bg-surface-success-hover
Destructive (Delete, Remove): bg-surface-error text-surface-error-text hover:bg-surface-error-hover
Secondary (Cancel, Back): bg-surface-secondary text-surface-secondary-text hover:bg-surface-secondary-hover
AI/Special (Generate, Chat): bg-surface-accent text-surface-accent-text hover:bg-surface-accent-hover

Status Badges

Status	Surface Classes
Draft	`bg-surface-secondary text-surface-secondary-text`
Concept	`bg-surface-warning text-surface-warning-text`
WIP	`bg-surface-info text-surface-info-text`
Review	`bg-surface-accent text-surface-accent-text`
Approved	`bg-surface-success text-surface-success-text`
Final	`bg-surface-primary text-surface-primary-text`
Archived	`bg-surface-base text-surface-base-text`

Rarity Levels

Rarity	Surface Classes
Common	`bg-surface-secondary text-surface-secondary-text`
Uncommon	`bg-surface-success text-surface-success-text`
Rare	`bg-surface-info text-surface-info-text`
Legendary	`bg-surface-accent text-surface-accent-text`
Unique	`bg-surface-warning text-surface-warning-text`

Faction Types

Faction Type	Token Category
Corporation	info surface tokens
Government	secondary surface tokens
Underground	accent surface tokens
Criminal	error surface tokens
Neutral	success surface tokens
Religious	warning surface tokens
Military	warning surface tokens

Important Note: text-surface-primary-text vs text-surface-primary-color

text-surface-primary-text = white (#ffffff) — use ONLY on solid bg-surface-primary backgrounds (buttons, badges)
text-surface-primary-color = brand blue (uses var(--surface-primary-bg)) — use on regular bg-surface-base/bg-surface-elevated backgrounds when you want branded/highlighted text

These are CSS utility classes defined in globals.css:

.text-surface-primary-color { color: var(--surface-primary-bg); }
.text-surface-secondary-color { color: var(--surface-secondary-bg); }
.text-surface-accent-color { color: var(--surface-accent-bg); }

Migration Progress

Phase 1 — High Priority (13 files, ~1,266 instances, 51% of total)

The highest-impact files for migration include the visual editors (DistrictVisualEditor, LocationVisualEditor, BrandVisualEditor, FactionVisualEditor), entity detail pages (locations/[id], items/[id], factions/[id]), list pages (assets, factions, items), and shared components (EntityAssets, ContextPreview).

Phase 2 — Medium Priority (32 files, 20-49 instances each)

Includes remaining visual editors, AI components (TokenBudgetVisualizer, BasicCollaborativeInterface, ContextConfigPanel), utility pages, and shared UI components.

Phase 3 — Low Priority (61 files, under 20 instances each)

Smaller files with fewer hardcoded color references, including single-instance occurrences across various components.

Plugin Iframe Protocol Export System Architecture