Semantic Theme Engine

Wardian features a robust, semantic theme engine that supports Dark, Light, and System modes. The system is built using CSS Variables and Tailwind CSS v4, ensuring high performance and ease of customization.

🏛️ Architecture

1. The Variable Layer

Located in src/styles/App.css, the theme is defined using a series of CSS variables prefixed with --color-wardian-*.

Structural Variables: Define the background, card, and sidebar colors (--color-wardian-bg, --color-wardian-sidebar-primary).
Semantic Variables: Define colors for system statuses (--color-wardian-success, --color-wardian-processing, --color-wardian-error).
Typography Variables: Define colors for primary, muted, and bright text.

2. The Theme Switcher

The App.tsx component manages the active theme state and persists it to localStorage.

System Sync: Uses window.matchMedia("(prefers-color-scheme: light)") to automatically switch between light and dark modes when the "System" theme is selected.
Data Attribute: The active theme is applied to the <html> element via the data-theme attribute (e.g., <html data-theme="dark">).

🎨 Design Tokens

Semantic Statuses

Always use these tokens for status indicators to ensure consistency across themes:

Status	Variable	Default (Dark)	Light Mode
Idle	`--color-wardian-success`	`#10b981`	`#059669`
Processing	`--color-wardian-processing`	`#22d3ee`	`#0891b2`
Warning	`--color-wardian-warning`	`#f59e0b`	`#d97706`
Error	`--color-wardian-error`	`#ef4444`	`#dc2626`
Off	`--color-wardian-off`	`#4b5563`	`#4b5563`

Workflow Colors

Specific colors are reserved for the Visual Builder nodes:

Agent Node: --color-workflow-agent (#3b82f6)
Command Node: --color-workflow-command (#10b981)
Logic Node: --color-workflow-logic (#f59e0b)
Comm Node: --color-workflow-comm (#8b5cf6)

🛠️ Developer Usage

Using Theme Variables

When building new components, NEVER use hardcoded hex values or standard Tailwind colors (e.g., text-blue-500). Instead, use the theme variables or the mapped utility classes:

tsx

// ✅ Correct
<div className="bg-wardian-card text-primary border-wardian-border">...</div>

// ❌ Incorrect
<div className="bg-gray-900 text-white border-gray-700">...</div>

Extending the Theme

To add a new theme color:

Define the variable in the @theme block in App.css.
Provide a light-mode override in the [data-theme='light'] block.
(Optional) Create a mapped Tailwind utility class for ease of use.

Semantic Theme Engine ​

🏛️ Architecture ​

1. The Variable Layer ​

2. The Theme Switcher ​

🎨 Design Tokens ​

Semantic Statuses ​

Workflow Colors ​

🛠️ Developer Usage ​

Using Theme Variables ​

Extending the Theme ​