bulma-turbo-themes

Modern, accessible theme packs and a drop-in theme selector for Bulma 1.x.

Features

• Catppuccin, Dracula, GitHub (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

For Jekyll Sites (Recommended)

Install as a Ruby gem:

# Gemfile
gem "bulma-turbo-themes", "~> 0.4"

# _config.yml
theme: bulma-turbo-themes

Then run:

bundle install
bundle exec jekyll serve

Assets are automatically available - no copying needed!

Advanced Theming

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

For Non-Jekyll Projects

Install via Bun (recommended) or npm:

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

# Using npm
npm install @turbocoder13/bulma-turbo-themes

Quick start

Jekyll Sites

1. Install the gem (see above)
2. 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="#" />

1. 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>

Non-Jekyll Projects

1. Copy CSS files from node_modules/@turbocoder13/bulma-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
2. 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="#" />

1. 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/bulma-turbo-themes';

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

React Native / Cross-Platform

This package provides platform-agnostic design tokens that work in React Native, Expo, and other non-web environments.

Installation

bun add @turbocoder13/bulma-turbo-themes
# or
npm install @turbocoder13/bulma-turbo-themes

Basic Usage (Without Context)

import { useTheme, useThemeColors } from '@turbocoder13/bulma-turbo-themes/tokens/react-native';

function MyComponent() {
  const { colors, styles, theme } = useTheme('catppuccin-mocha');

  return (
    <View style={styles.container}>
      <Text style={styles.h1}>{theme.label}</Text>
      <Text style={[styles.text, { color: colors.brandPrimary }]}>
        Primary color text
      </Text>
    </View>
  );
}

With ThemeProvider (Recommended)

import { ThemeProvider, useThemeContext } from '@turbocoder13/bulma-turbo-themes/tokens/react-native';
import { useColorScheme } from 'react-native';

// Wrap your app with ThemeProvider
function App() {
  return (
    <ThemeProvider
      useColorScheme={useColorScheme}
      followSystem
      lightTheme="catppuccin-latte"
      darkTheme="catppuccin-mocha"
    >
      <MyApp />
    </ThemeProvider>
  );
}

// Use the theme in any component
function MyApp() {
  const { colors, styles, setTheme, toggleAppearance, appearance } = useThemeContext();

  return (
    <View style={styles.container}>
      <Text style={styles.h1}>Welcome!</Text>
      <Button
        title={`Switch to ${appearance === 'dark' ? 'light' : 'dark'}`}
        onPress={toggleAppearance}
      />
    </View>
  );
}

Available Exports

| Import Path | Use Case | |-------------|----------| | @turbocoder13/bulma-turbo-themes/tokens | Platform-agnostic tokens (pure data) | | @turbocoder13/bulma-turbo-themes/tokens/react-native | React Native utilities, hooks, and context | | @turbocoder13/bulma-turbo-themes/tokens.json | JSON tokens for Flutter, Swift, Kotlin | | @turbocoder13/bulma-turbo-themes/css/* | CSS files for web |

Pre-built Styles

The React Native module includes pre-built styles for common components:

• Layout: container, safeArea, centered, row
• Typography: h1-h6, text, textSecondary, caption, label, link
• Components: card, cardElevated, button, buttonOutline, input, listItem, badge, tag, divider
• State Colors: success, warning, danger, info

Plus design tokens for spacing, typography, borderRadius, and shadows.

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 Jekyll demo site)

Quick Start

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