turbo-themes

Universal design tokens and theme management for Python applications.

Features

• 9 curated themes from Catppuccin (4 variants), Dracula, GitHub (light/dark), and Bulma (light/dark)
• Design tokens as typed Python dataclasses
• CSS variable generation for web integration
• Type-safe with full type hints and mypy strict mode
• Lightweight: single runtime dependency (python-dateutil)

Installation

pip install turbo-themes
# or
uv add turbo-themes

Quick Start

Access Theme Colors

from turbo_themes import THEMES

# Get a specific theme
mocha = THEMES["catppuccin-mocha"]
print(mocha.colors.primary)      # "#89b4fa"
print(mocha.colors.background)   # "#1e1e2e"
print(mocha.meta.name)           # "Catppuccin Mocha"
print(mocha.meta.variant)        # "dark"

Theme Manager

from turbo_themes import ThemeManager

manager = ThemeManager()

# Set and apply a theme
manager.set_theme("catppuccin-mocha")
css_vars = manager.apply_theme_to_css_variables()

# Generate CSS custom properties
for var_name, value in css_vars.items():
    print(f"--{var_name}: {value};")

List Available Themes

from turbo_themes import THEMES, list_themes

# Get all theme names
themes = list_themes()
print(themes)
# ['bulma-dark', 'bulma-light', 'catppuccin-frappe', 'catppuccin-latte',
#  'catppuccin-macchiato', 'catppuccin-mocha', 'dracula', 'github-dark', 'github-light']

# Filter by variant
dark_themes = [name for name, theme in THEMES.items() if theme.meta.variant == "dark"]

Available Themes

Theme Structure

Each theme provides:

theme.colors.primary       # Primary accent color
theme.colors.secondary     # Secondary accent color
theme.colors.background    # Background color
theme.colors.surface       # Surface/card color
theme.colors.text          # Primary text color
theme.colors.text_muted    # Muted/secondary text
theme.colors.border        # Border color
theme.colors.error         # Error state color
theme.colors.warning       # Warning state color
theme.colors.success       # Success state color
theme.colors.info          # Info state color

theme.meta.name            # Display name
theme.meta.variant         # "light" or "dark"
theme.meta.source          # Source project URL

Integration Examples

Flask/Jinja2

from flask import Flask, render_template
from turbo_themes import ThemeManager

app = Flask(__name__)
manager = ThemeManager()

@app.route("/")
def index():
    manager.set_theme("catppuccin-mocha")
    css_vars = manager.apply_theme_to_css_variables()
    return render_template("index.html", theme_vars=css_vars)

Django

from turbo_themes import THEMES

def get_theme_context(theme_name: str) -> dict:
    theme = THEMES.get(theme_name, THEMES["catppuccin-mocha"])
    return {
        "primary_color": theme.colors.primary,
        "background_color": theme.colors.background,
        "text_color": theme.colors.text,
    }

Multi-Platform

This package is part of the turbo-themes ecosystem:

• npm: @lgtm-hq/turbo-themes - TypeScript/JavaScript
• PyPI: turbo-themes - Python (this package)
• RubyGems: turbo-themes - Ruby/Jekyll
• Swift: Via Swift Package Manager

All packages share the same design tokens and color values.

Links

• GitHub Repository
• Documentation
• npm Package
• RubyGems Package

License

MIT