Design Tokens

Webspire uses a 3-layer token architecture. One central CSS file handles all colors and dark mode. Patterns stay pure Tailwind — no inline styles, no <style> blocks, no dark: classes.

🎨 Open Color Lab 20 palettes, live preview, download webspire-tokens.css →

Architecture: 3 Layers

Each layer has a clear responsibility. Override at the level that makes sense for your project.

Host / Project Tokens

Your project's existing design tokens. Optional — WebSpire doesn't require them.

/* Layer 1 — Your project's existing tokens (optional) */
:root {
  --color-primary: #2563eb;
  --color-primary-hover: #1d4ed8;
  --surface-1: #fafafa;
  --text-1: #18181b;
}

WebSpire Alias Tokens

The stable integration layer. Bridges your project tokens to component tokens. Dark mode lives here.

/* Layer 2 — WebSpire Alias Tokens (webspire-tokens.css) */
:root {
  --ws-color-surface: var(--surface-1, #ffffff);
  --ws-color-text: var(--text-1, #0f172a);
  --ws-color-primary: var(--color-primary, #4f46e5);
  --ws-color-primary-hover: var(--color-primary-hover, #4338ca);
  --ws-color-border: var(--color-border, #e2e8f0);
}

/* Dark mode — single place, not per component */
.dark {
  --ws-color-surface: var(--surface-1-dark, #0f172a);
  --ws-color-text: var(--text-1-dark, #f1f5f9);
  --ws-color-primary: var(--color-primary-dark, #818cf8);
}

Component Tokens

Per-component semantic variables. Each .ws-{family} class defines its own token interface.

/* Layer 3 — Component Tokens (webspire-components.css) */
.ws-cta {
  --ws-cta-bg: var(--ws-color-surface);
  --ws-cta-text: var(--ws-color-text);
  --ws-cta-action-bg: var(--ws-color-primary);
  --ws-cta-action-bg-hover: var(--ws-color-primary-hover);
  --ws-cta-action-text: var(--ws-color-primary-text);
}

.ws-hero {
  --ws-hero-bg: var(--ws-color-surface);
  --ws-hero-text: var(--ws-color-text);
  --ws-hero-action-bg: var(--ws-color-primary);
  /* ... */
}

HTML

Pattern Markup

Pure Tailwind utilities with component token references. No <style>, no dark:.

<!-- Pattern: pure Tailwind + component tokens. No <style> block. -->
<section class="ws-cta bg-[var(--ws-cta-bg)] py-20">
  <div class="mx-auto max-w-3xl px-6 text-center">
    <h2 class="text-[var(--ws-cta-text)] text-3xl font-bold">
      Ready to build faster?
    </h2>
    <a href="#"
       class="mt-6 inline-flex rounded-lg px-5 py-3 text-sm font-semibold
              bg-[var(--ws-cta-action-bg)]
              text-[var(--ws-cta-action-text)]
              hover:bg-[var(--ws-cta-action-bg-hover)]">
      Get started
    </a>
  </div>
</section>

Why This Works

No Collision

--ws-cta-bg doesn't collide with your project. Component tokens are namespaced by family.

Readable

A developer sees at a glance: global alias, component token, or Tailwind utility. No cryptic --_bg names.

Dark Mode Once

Alias tokens switch in one place (.dark class or media query). No per-component @media blocks.

Tailwind-Native

Tailwind v4 is built on CSS variables. Arbitrary values with var() are first-class citizens.

Getting Started

Three ways to add WebSpire tokens to your project:

Via MCP (recommended)

The AI agent writes the files directly into your project. No CDN dependency, no manual download.

// MCP: setup_tokens()
// → Returns webspire-tokens.css + webspire-components.css
// → AI agent writes them to your project. No CDN needed.

// MCP: setup_tokens({ components: ["hero", "cta", "pricing"] })
// → Only includes tokens for the families you use

// MCP: recommend_token_mapping({
//   project_tokens: "--brand-500: #2563eb; --bg-base: #fafafa"
// })
// → Suggests: --ws-color-primary: var(--brand-500); ...

Via CLI

Generate token files locally. Also runs automatically on first webspire add.

npx @webspire/cli init --tokens

Manual / CDN

Download or link the CSS files directly. Good for quick prototyping.

@import "https://webspire.de/webspire-tokens.css";
@import "https://webspire.de/webspire-components.css";

Tailwind v4 Integration

If components come from node_modules, tell Tailwind where to find them with @source.

/* Tell Tailwind to scan WebSpire components */
@import "tailwindcss";
@source "../node_modules/@webspire/ui";

@import "./webspire-tokens.css";
@import "./webspire-components.css";

Customization

Override at the level that matches your need. Alias tokens affect everything, component tokens are surgical.

Override Alias Tokens

Change brand colors once, all 683 patterns adapt.

/* Override alias tokens — all components adapt */
:root {
  --ws-color-primary: #dc2626;       /* Red brand */
  --ws-color-primary-hover: #b91c1c;
  --ws-color-surface: #fafaf9;       /* Warm white */
}

Override Component Tokens

Customize one component without affecting others.

/* Override a single component */
.ws-cta {
  --ws-cta-action-bg: linear-gradient(135deg, #6366f1, #8b5cf6);
  --ws-cta-bg: #0f172a;  /* Always dark CTA */
  --ws-cta-text: #f1f5f9;
}

Map Existing Tokens

Already have a design system? Point WebSpire aliases at your variables.

/* Map WebSpire to your existing design system */
:root {
  --ws-color-primary: var(--brand-500);
  --ws-color-primary-hover: var(--brand-600);
  --ws-color-surface: var(--bg-base);
  --ws-color-text: var(--fg-default);
  --ws-color-border: var(--border-default);
}

Naming Convention

Layer	Pattern	Example
Alias Token	--ws-color-{role}	--ws-color-primary, --ws-color-surface, --ws-color-text
Component Token	--ws-{family}-{role}	--ws-cta-bg, --ws-hero-action-bg, --ws-pricing-highlight-bg
CSS Class	ws-{family}	ws-cta, ws-hero, ws-pricing, ws-navbar

Alias Token Reference

Token	Light Default	Dark Default	Purpose
Surface
--ws-color-surface	#ffffff	#0f172a	Page / section background
--ws-color-surface-alt	#f8fafc	#1e293b	Elevated surface (cards)
--ws-color-surface-muted	#f1f5f9	#334155	Muted background
Text
--ws-color-text	#0f172a	#f1f5f9	Primary text
--ws-color-text-soft	#334155	#cbd5e1	Secondary text
--ws-color-text-muted	#64748b	#94a3b8	Tertiary text, labels
Primary & Accent
--ws-color-primary	#4f46e5	#818cf8	Brand / primary action
--ws-color-primary-hover	#4338ca	#6366f1	Primary hover state
--ws-color-accent	#06b6d4	#22d3ee	Secondary action
Borders & Semantic
--ws-color-border	#e2e8f0	#334155	Default border
--ws-color-success	#10b981	#34d399	Success
--ws-color-warning	#f59e0b	#fbbf24	Warning
--ws-color-danger	#ef4444	#f87171	Error / danger