colbrush

colbrush

A React theme switching library that makes it easy to apply color-blind accessible UI themes.

Features

• ✅ Support for color blindness types: protanopia, deuteranopia, tritanopia
• ⚙️ Automatic CSS variable generation via PostCSS (@theme syntax supported)
• 🎛 Provides a ThemeProvider based on React Context
• 🎨 Accessible ThemeSwitcher component included
• 🧩 Built-in hook for runtime updates:

  • useTheme() – provides access to theme and language states

    const { theme, useUpdateTheme, language, useUpdateLanguage } =
        useTheme();
    

    • theme: currently active theme name
    • updateTheme(theme: ThemeType): update the current theme (supports color-blind modes)
    • language: current language setting (currently supports Korean and English)
    • updateLanguage(language: TLanguage): update the language context
• 🧪 Customizable color scales and transformation algorithms

Installation

pnpm add colbrush
# or
npm install colbrush

Usage

1. Define CSS variables (index.css or global CSS)

@theme {
    --color-primary-500: #7fe4c1;
    --color-secondary-yellow: #fdfa91;
    --color-default-gray-500: #c3c3c3;
}

2. Generate color-blind themes

Prerequisite: Define your base palette in a CSS file (e.g., src/index.css) using HEX colors (#RRGGBB).
Variables can be declared inside an @theme { ... } block (recommended) or :root { ... }.

Example (src/index.css):

@theme {
    --color-primary-500: #7fe4c1;
    --color-secondary-yellow: #fdfa91;
    --color-default-gray-500: #c3c3c3;
}

Then run the generator:

Default: reads/writes to src/index.css

npx colbrush --generate

Use a different file (optional):

npx colbrush --generate --css=path/to/your.css

Notes

Colbrush now supports all color formats — HEX, RGB, HSL, HWB, LAB, LCH, OKLCH, and named CSS colors.
If --css is omitted, Colbrush uses src/index.css by default.
Generated color-blind variants are appended to the same file below your @theme block.

3. Wrap your app with ThemeProvider

import { ThemeProvider } from 'colbrush/client';

function App() {
  return (
    <ThemeProvider>
      <YourApp />
    </ThemeProvider>
  );
}

4. Import colbrush/styles.css

// index.css
@import 'colbrush/styles.css';

5. Use the ThemeSwitcher component

import { ThemeSwitcher } from 'colbrush/client';

function Settings() {
  return (
    <ThemeSwitcher
      position="right-bottom"
      ...
    />
  );
}

Prop	Type	Default	Description
options?	{ key: ThemeKey; label: string; }[]	undefined	Defines the selectable themes shown in the dropdown. Each object contains: • key: theme identifier (ThemeKey) • label: display name for the theme.
position?	left-top / right-top / left-bottom / right-bottom	right-bottom	Determines where the ThemeSwitcher dropdown appears.

6. Use hooks for theme and language switching

import { useTheme } from 'colbrush/client';

export default function TestPage() {
    const { theme, updateTheme, language, updateLanguage } = useTheme();

    return (
        <div className="flex">
            <button onClick={() => updateTheme('tritanopia')}>Change to tritanopia</button>
            <button onClick={() => updateLanguage('English')}>Change to English</button>
        </div>
    );
}

6. Apply SimulationFilter for vision simulation

import { SimulationFilter } from 'colbrush/devtools';

function App() {
    return (
        <ThemeProvider>
            <SimulationFilter
                initialMode="normal"
                toolbarPosition="left-bottom"
                ...>
                <YourApp />
            </SimulationFilter>
        </ThemeProvider>
    );
}

SimulationFilterProp	Type	Default	Description
initialMode?	none / protanopia / deuteranopia / tritanopia	none	initial simulation mode
position?	left-top / right-top / left-bottom / right-bottom	left-bottom	toolbar position
allowInProd?	boolean	false	Forces the filter to be available in production (for debugging)
storageKey?	string	colbrush-filter	Customizes the localStorage key used to store the simulation state.
devHostPattern?	string	localhost / 127 / 192.168.x	Defines a custom regular expression for allowed development hosts.

Supported Vision Types

Vision Type	설명
protanopia	적색맹
deuteranopia	녹색맹
tritanopia	청색맹

CLI (Command-Line Interface)

Description:
Colbrush provides a command-line tool that automatically generates accessibility-optimized color themes for
Protanopia (red-blindness), Deuteranopia (green-blindness), and Tritanopia (blue-blindness)
based on developer-defined CSS variables.
The generated themes are appended directly to the existing CSS file.

Commands and Usage

Command	Description
colbrush --generate	Generates accessibility color themes for users with color vision deficiencies (default command).
colbrush --doctor	Runs a system diagnostic to detect environment or configuration issues.
colbrush --help	Displays all available commands and usage options.
colbrush --version	Shows the currently installed version of Colbrush (e.g., v1.6.0).

Options

Option	Description	Default
--css=<path>	Specifies the target CSS file path for theme generation.	src/index.css
--no-color	Disables colored output in the CLI.	—
--json=<path>	Saves a detailed generation report as a JSON file at the specified path.	—

For more details, visit the 👉 Colbrush Official Website.

👥 Team

윤수호	노하영	김연진	윤혜성	이준희
PM	Designer	Frontend · Library Engineer	Frontend · Library Engineer	Frontend · Library Engineer

🤝 Contributing

We welcome contributions from the community! Colbrush is an open-source project, and we'd love your help to make it better.

How to Contribute

• 🐛 Report bugs - Found a bug? Open an issue
• ✨ Suggest features - Have an idea? Share it with us
• 📝 Improve documentation - Help us make our docs better
• 💻 Submit pull requests - Fix bugs or add new features

Please read our Contributing Guide for detailed information on how to contribute.

📜 License

MIT License

Copyright (c) 2025 colbrush

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.