turbo-themes

Universal, accessible theme packs and a drop-in theme selector.

Included Theme Packs

Built on Bulma CSS framework with color palettes from these amazing projects:

| Theme | Variants | Source | | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------- | | Catppuccin | Mocha, Macchiato, Frappé, Latte | catppuccin.com | | Dracula | Dark | draculatheme.com | | GitHub | Light, Dark | primer.style | | Bulma | Light, Dark | bulma.io | | Nord | Nord | nordtheme.com | | Solarized | Dark, Light | ethanschoonover.com/solarized | | Rosé Pine | Rosé Pine, Moon, Dawn | rosepinetheme.com | | Gruvbox | Dark Hard, Dark, Dark Soft, Light Hard, Light, Light Soft | github.com/morhetz/gruvbox | | Tokyo Night | Night, Storm, Light | tokyo-night-vscode-theme |

Features

• 24 curated themes from Catppuccin, Gruvbox, Dracula, GitHub, Solarized, Tokyo Night, Nord, Rosé Pine, and Bulma
• Multi-platform: npm, PyPI, RubyGems, Swift Package Manager
• Design tokens: Platform-agnostic JSON tokens for any framework
• Accessible: WCAG-compliant with keyboard and screen reader support
• Framework-agnostic: Works with React, Vue, Svelte, vanilla JS, or native apps
• Type-safe: Full TypeScript, Python type hints, and Swift types
• Tested: Unit tests, E2E tests, Lighthouse CI, and visual regression

Installation

| Platform | Package Manager | Install Command | | ------------------------- | --------------- | ------------------------------------------------- | | JavaScript/TypeScript | npm / bun | npm install @lgtm-hq/turbo-themes | | Python | pip / uv | pip install turbo-themes | | Ruby | bundler | gem "turbo-themes", "~> 0.12" | | Swift | SPM | Add https://github.com/lgtm-hq/turbo-themes.git |

JavaScript/TypeScript

# Using Bun (recommended)
bun add @lgtm-hq/turbo-themes

# Using npm
npm install @lgtm-hq/turbo-themes

Python

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

Ruby (Jekyll)

# Gemfile
gem "turbo-themes", "~> 0.12"

Swift

Add via Xcode: https://github.com/lgtm-hq/turbo-themes.git (version 0.12.0+)

Quick Start

Using Design Tokens (Recommended)

Access theme colors as platform-agnostic JSON tokens:

import tokens from '@lgtm-hq/turbo-themes/tokens.json';

const mocha = tokens.themes['catppuccin-mocha'];
console.log(mocha.tokens.brand.primary); // "#89b4fa"

JavaScript/TypeScript

import { initTheme, wireFlavorSelector } from '@lgtm-hq/turbo-themes';

// Initialize theme system
initTheme(document, window);
wireFlavorSelector(document, window);

Python

from turbo_themes import ThemeManager, THEMES

manager = ThemeManager()
manager.set_theme("catppuccin-mocha")
css_vars = manager.apply_theme_to_css_variables()

Swift

import TurboThemes

let mocha = ThemeRegistry.themes[.catppuccinMocha]
// Use theme colors in SwiftUI views

Available Exports

| Import Path | Use Case | | ----------------------------------- | ----------------------------- | | @lgtm-hq/turbo-themes/tokens.json | Platform-agnostic JSON tokens | | @lgtm-hq/turbo-themes/tokens | TypeScript tokens with types | | @lgtm-hq/turbo-themes/css/* | Pre-built CSS files |

Examples

Complete, working examples demonstrating Turbo Themes integration with various frameworks:

| Example | Framework | Description | Try It | | ------------------------------------- | ------------ | ------------------------------------------ | ------------------------------------------------------------------------------------------------ | | HTML Vanilla | HTML/JS | Zero-dependency vanilla JavaScript | StackBlitz | | React | React 18 | TypeScript with custom useTheme hook | StackBlitz | | Vue | Vue 3 | Composition API with useTheme composable | StackBlitz | | Tailwind | Tailwind CSS | Preset integration with utility classes | StackBlitz | | Bootstrap | Bootstrap 5 | SCSS integration with light/dark mode | StackBlitz | | Jekyll | Jekyll | Ruby gem integration | - | | SwiftUI | SwiftUI | iOS/macOS native app | - |

Each example includes theme switching, localStorage persistence, and FOUC prevention. See the examples directory for full documentation.

Testing

This project includes comprehensive testing:

• Unit Tests: Vitest with coverage reporting
• E2E Tests: Playwright with Page Object Model pattern
• Accessibility Tests: axe-core integration for WCAG compliance
• Visual Regression: Playwright screenshots and snapshots

Run tests:

# Using Bun (recommended)
bun run test          # Unit tests with coverage
bun run e2e           # All E2E tests
bun run e2e:smoke     # Smoke tests only
bun run e2e:visual    # Visual regression tests
bun run e2e:a11y      # Accessibility tests
bun run e2e:ui        # Playwright UI mode

# Using npm (also works)
npm test              # Unit tests with coverage
npm run e2e           # All E2E tests

For detailed E2E testing documentation, see docs/E2E-TESTING.md.

Development Setup

Prerequisites

• Bun 1.3+ (recommended) - Install Bun
• Node.js 22+ (alternative to Bun)
• Python 3.11+ with uv (for Python package development)
• Ruby 3.4+ with Bundler (optional, for gem builds)

Quick Start

# Clone and install
git clone https://github.com/lgtm-hq/turbo-themes.git
cd turbo-themes
bun install
bundle install

# Build and serve
bun run build
bun run build:themes
bun run serve

Why Bun?

This project uses Bun as its primary JavaScript runtime for:

• 5-10x faster package installation
• 10x faster script startup time
• ~40% reduction in CI build times
• Full npm compatibility (works with all existing packages)

Documentation

• Code of Conduct: see CODE_OF_CONDUCT.md
• Contributing Guide: see CONTRIBUTING.md
• Security Policy: see SECURITY.md
• Release process: see docs/RELEASE-TRAIN.md
• E2E Testing: see docs/E2E-TESTING.md
• Workflows & Actions: see .github/workflows/README.md and .github/actions/README.md
• Scripts: see scripts/README.md

Governance

See GOVERNANCE.md and MAINTAINERS.md.

License

MIT © Turbo Coder