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

Features

Catppuccin (Mocha, Macchiato, Frappé, Latte), Dracula, GitHub (light/dark), Bulma (light/dark) flavor packs
Accessible theme selector with keyboard and screen reader support
Inline or link-based CSS delivery; CSP-friendly
Tested with coverage, Lighthouse CI, and stylelint
Advanced Bulma customization (breakpoints, spacing, shadows, mixins)
Lazy-loaded themes with performance optimizations
Full Bulma Sass variable integration

Installation

Install via Bun (recommended) or npm:

# Using Bun (recommended - 5-10x faster)
bun add @turbocoder13/turbo-themes

# Using npm
npm install @turbocoder13/turbo-themes

Advanced Theming

For advanced customization options including custom breakpoints, spacing, shadows, and Bulma mixins, see the Advanced Theming Guide.

For Jekyll Sites

Install as a Ruby gem:

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

# _config.yml
theme: turbo-themes

Then run:

bundle install
bundle exec jekyll serve

Assets are automatically available - no copying needed!

Quick start

JavaScript/TypeScript Projects

Copy CSS files from node_modules/@turbocoder13/turbo-themes/assets/css/themes/ to your project:
- global.css (required)
- Flavor CSS files (e.g., catppuccin-mocha.css, dracula.css, github-dark.css) - copy the ones you want to use
Include CSS links (adjust paths to match your project structure):

<link id="theme-global-css" rel="stylesheet" href="/assets/css/themes/global.css" />
<link id="theme-flavor-css" rel="stylesheet" href="#" />

Add selector markup and initialize:

<div class="navbar-item has-dropdown is-hoverable">
  <button
    class="navbar-link"
    id="theme-flavor-trigger"
    type="button"
    aria-haspopup="true"
    aria-expanded="false"
    aria-controls="theme-flavor-menu"
  >
    <span class="icon is-small" id="theme-flavor-trigger-icon"></span>
    Theme
  </button>
  <div
    class="navbar-dropdown"
    id="theme-flavor-menu"
    aria-labelledby="theme-flavor-trigger"
  >
    <div class="dropdown-content" id="theme-flavor-items"></div>
  </div>
</div>
<div class="select is-rounded is-small is-hidden">
  <select id="theme-flavor-select" aria-label="Theme flavor" disabled></select>
</div>

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

document.addEventListener('DOMContentLoaded', () => {
  initTheme(document, window);
  wireFlavorSelector(document, window);
});

Jekyll Sites

Install the gem (see above)
Include CSS links in your layout:

<link
  id="theme-global-css"
  rel="stylesheet"
  href="{{ '/assets/css/themes/global.css' | relative_url }}"
/>
<link id="theme-flavor-css" rel="stylesheet" href="#" />

Add selector markup and initialize:

<div class="navbar-item has-dropdown is-hoverable">
  <button
    class="navbar-link"
    id="theme-flavor-trigger"
    type="button"
    aria-haspopup="true"
    aria-expanded="false"
    aria-controls="theme-flavor-menu"
  >
    <span class="icon is-small" id="theme-flavor-trigger-icon"></span>
    Theme
  </button>
  <div
    class="navbar-dropdown"
    id="theme-flavor-menu"
    aria-labelledby="theme-flavor-trigger"
  >
    <div class="dropdown-content" id="theme-flavor-items"></div>
  </div>
</div>
<div class="select is-rounded is-small is-hidden">
  <select id="theme-flavor-select" aria-label="Theme flavor" disabled></select>
</div>

<script src="{{ '/assets/js/theme-selector.js' | relative_url }}"></script>

Python (PyPI)

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

from turbo_themes import ThemeManager, THEMES

manager = ThemeManager()
manager.set_theme("catppuccin-mocha")
css_vars = manager.apply_theme_to_css_variables()
print(len(css_vars), "CSS variables ready to inject")

Swift (Swift Package Manager via GitHub)

In Xcode, add a package dependency:
URL: https://github.com/TurboCoder13/turbo-themes.git
Version: from 0.10.8
Add the library product TurboThemes to your target.

import TurboThemes

let mocha = ThemeRegistry.themes[.catppuccinMocha]
// Use ThemeDefinition values in your SwiftUI views

Supported Platforms

RubyGems (Jekyll theme)
npm (JS/TS + CSS assets)
PyPI (Python helper library)
Swift Package (SwiftUI previews/helpers)

Available Exports

Import Path	Use Case
`@turbocoder13/turbo-themes/tokens`	Platform-agnostic tokens (pure data)
`@turbocoder13/turbo-themes/tokens.json`	JSON tokens for Python/Swift or custom pipelines
`@turbocoder13/turbo-themes/css/*`	CSS files for web

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 with Bulma components	-
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)
Ruby 3.3+ with Bundler (for gem build and Jekyll example)

Quick Start

# Clone and install
git clone https://github.com/TurboCoder13/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.