diff --git a/README.md b/README.md index dce9c46..68a30fe 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,8 @@ # colbrush -#### A React theme switching library that makes it easy to apply color-blind accessible UI themes. -Angular Gradient +#### A React theme switching library that makes it easy to apply color-blind accessible UI themes. + +스크린샷 2025-10-27 오전 9 05 44 --- @@ -11,9 +12,18 @@ - ⚙️ Automatic CSS variable generation via PostCSS (`@theme` syntax supported) - 🎛 Provides a `ThemeProvider` based on React Context - 🎨 Accessible `ThemeSwitcher` component included -- 🧩 Built-in hooks for runtime updates: - - `useUpdateTheme` – change the current theme (including color-blind modes) - - `useUpdateLanguage` – change the language context +- 🧩 Built-in hook for runtime updates: + - `useTheme()` – provides access to theme and language states + + ```js + 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 --- @@ -27,46 +37,56 @@ npm install colbrush ``` --- + ## Usage + ### 1. Define CSS variables (index.css or global CSS) + ```css @theme { - --color-primary-500: #7fe4c1; - --color-secondary-yellow: #fdfa91; - --color-default-gray-500: #c3c3c3; + --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`): + ```css @theme { - --color-primary-500: #7fe4c1; - --color-secondary-yellow: #fdfa91; - --color-default-gray-500: #c3c3c3; + --color-primary-500: #7fe4c1; + --color-secondary-yellow: #fdfa91; + --color-default-gray-500: #c3c3c3; } ``` + Then run the generator: #### Default: reads/writes to src/index.css -``` + +```bash npx colbrush --generate ``` + Use a different file (optional): -``` + +```bash npx colbrush --generate --css=path/to/your.css ``` #### Notes -Only HEX values are processed (e.g., #7fe4c1). Named colors, rgb()/hsl() are ignored. -If --css is omitted, Colbrush uses src/index.css by default. +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'; @@ -78,16 +98,36 @@ function App() { ); } ``` -### 4. Use the ThemeSwitcher component + +### 4. Import colbrush/styles.css + +``` +// index.css +@import 'colbrush/styles.css'; +``` + +### 5. Use the ThemeSwitcher component + ``` import { ThemeSwitcher } from 'colbrush/client'; -import 'colbrush/styles.css'; function Settings() { - return ; + return ( + + ); } ``` -### 5. Use hooks for theme and language switching + +| **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'; @@ -102,7 +142,9 @@ export default function TestPage() { ); } ``` + ### 6. Apply SimulationFilter for vision simulation + ``` import { SimulationFilter } from 'colbrush/devtools'; @@ -118,31 +160,60 @@ function App() { ); } + ``` -| **SimulationFilterProp** | **Type** | **Default** | **Description** | -| ----------------- | ----------------------------------------------------------------- | ------------- | ------------------------- | -| `initialMode?` | `"normal"` / `"protanopia"` / `"deuteranopia"` / `"tritanopia"` | `"normal"` | initial simulation mode | -| `toolbarPosition?` | `"top-left"` / `"top-right"` / `"bottom-left"` / `"bottom-right"` | `"top-right"` | toolbar position | -| `shortcut?` | `boolean` | `true` | enable keyboard shortcuts (⌘/Ctrl + Alt + D) | -| `productionGuard?` | `boolean` | `false` | block usage in production | +| **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 | 청색맹 | +| --------------- | -------- | +| 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=` | Specifies the target CSS file path for theme generation. | `src/index.css` | +| `--no-color` | Disables colored output in the CLI. | — | +| `--json=` | Saves a detailed generation report as a JSON file at the specified path. | — | + +For more details, visit the **[👉 Colbrush Official Website](https://www.colbrush.site)**. ## 👥 Team | ![suho](https://github.com/user-attachments/assets/10c25151-e122-4ddb-8d8c-8b802c01c738) | ![hayoung](https://github.com/user-attachments/assets/7b7b453e-82f1-4f8e-bcc9-edba4d6fa279) | ![yeonjin](https://github.com/user-attachments/assets/55a2e27b-cb75-4115-a0ff-cfe97610ca97) | ![hyeseong](https://github.com/user-attachments/assets/9cdf9354-0d31-4410-ad94-f57ffc684849) | ![junhee](https://github.com/user-attachments/assets/aeebf2cc-5aaa-4eac-bbe4-e093dac3d60a) | -| ---------------------------------------- | ------------------------------------------- | ------------------------------------------- | -------------------------------------------- | ------------------------------------------ | -| **윤수호** | **노하영** | [**김연진**](https://github.com/yeonjin719) | [**윤혜성**](https://github.com/hyesngy) | [**이준희**](https://github.com/jjjuni) | -| PM | Designer | Frontend · Library Engineer | Frontend · Library Engineer | Frontend · Library Engineer | - +| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | +| **윤수호** | **노하영** | [**김연진**](https://github.com/yeonjin719) | [**윤혜성**](https://github.com/hyesngy) | [**이준희**](https://github.com/jjjuni) | +| PM | Designer | Frontend · Library Engineer | Frontend · Library Engineer | Frontend · Library Engineer | -# 📜 License +## 📜 License MIT License @@ -165,6 +236,3 @@ 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. - - -