Core Concepts

This guide explains the fundamental concepts behind Turbo Themes and how it works.

Design Tokens

Design tokens are the foundation of Turbo Themes. They are CSS custom properties (variables) that represent your design decisions as reusable values.

/* Example design tokens */
:root {
  --turbo-bg-base: #1e1e2e;
  --turbo-text-primary: #cdd6f4;
  --turbo-brand-primary: #89b4fa;
}

Why Use Design Tokens?

Consistency - Same color values everywhere
Maintainability - Change once, update everywhere
Theming - Swap values to change the entire look
Semantic meaning - Names describe purpose, not appearance

Token Categories

Turbo Themes organizes tokens into semantic categories:

Backgrounds (`--turbo-bg-*`)

Token	Purpose
`--turbo-bg-base`	Main page background
`--turbo-bg-surface`	Cards, modals, elevated surfaces
`--turbo-bg-overlay`	Overlays, dropdowns, tooltips

Text (`--turbo-text-*`)

Token	Purpose
`--turbo-text-primary`	Main body text
`--turbo-text-secondary`	Muted, less important text
`--turbo-text-inverse`	Text on colored backgrounds

Brand (`--turbo-brand-*`)

Token	Purpose
`--turbo-brand-primary`	Primary accent color, CTAs

State (`--turbo-state-*`)

Token	Purpose
`--turbo-state-success`	Success messages, confirmations
`--turbo-state-warning`	Warnings, cautions
`--turbo-state-danger`	Errors, destructive actions
`--turbo-state-info`	Informational messages

Border (`--turbo-border-*`)

Token	Purpose
`--turbo-border-default`	Standard border color

Syntax (`--turbo-syntax-*`)

Tokens for code syntax highlighting:

Token	Purpose
`--turbo-syntax-comment`	Code comments
`--turbo-syntax-keyword`	Language keywords
`--turbo-syntax-string`	String literals
`--turbo-syntax-number`	Numbers
`--turbo-syntax-function`	Function names
`--turbo-syntax-type`	Type annotations

Theme Structure

Each theme defines values for all tokens. When you load a different theme CSS file, all the token values change, and your UI updates automatically.

/* catppuccin-mocha.css */
:root {
  --turbo-bg-base: #1e1e2e;
  --turbo-text-primary: #cdd6f4;
  /* ... */
}

/* dracula.css */
:root {
  --turbo-bg-base: #282a36;
  --turbo-text-primary: #f8f8f2;
  /* ... */
}

File Structure

The Turbo Themes package is organized as follows:

turbo-themes/
├── css/
│   ├── turbo-core.css      # Token variable definitions
│   ├── turbo-base.css      # Base semantic styles
│   ├── turbo-syntax.css    # Syntax highlighting
│   ├── themes/
│   │   └── turbo/
│   │       ├── catppuccin-mocha.css
│   │       ├── catppuccin-latte.css
│   │       ├── dracula.css
│   │       └── ...
│   └── adapters/
│       ├── bulma.css       # Bulma framework adapter
│       └── tailwind.css    # Tailwind preset

How Theme Switching Works

Theme switching is simple because all your CSS uses the same token names:

Your CSS references tokens: background: var(--turbo-bg-surface)
The browser resolves the current value of --turbo-bg-surface
When you load a different theme file, the value changes
The browser automatically re-renders with the new value

This means:

No JavaScript required for styling
No re-rendering of components
Instant theme changes
Works with any framework

Framework Adapters

Turbo Themes provides adapters that map tokens to framework-specific variables:

Bulma Adapter

Maps Turbo tokens to Bulma’s CSS variables so Bulma components use your theme colors automatically.

Tailwind Preset

Extends Tailwind’s color palette with Turbo token references, enabling classes like bg-turbo-surface and text-turbo-primary.

Next Steps

Now that you understand the concepts: