Skip to content

[Deploy] Readme 수정 #69

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
yeonjin719 merged 2 commits into from
Oct 27, 2025
Merged

[Deploy] Readme 수정 #69

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
edc143f
docs: readme 파일 수정
yeonjin719 Oct 27, 2025
4509037
Merge pull request #68 from 2025-OSDC/docs/#67
yeonjin719 Oct 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
142 changes: 105 additions & 37 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
# colbrush
#### A React theme switching library that makes it easy to apply color-blind accessible UI themes.
<img width="1440" height="900" alt="Angular Gradient" src="https://github.com/user-attachments/assets/37e4ffb9-1840-4828-949c-0ffe5e14903e" />

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

<img width="1434" height="314" alt="스크린샷 2025-10-27 오전 9 05 44" src="https://github.com/user-attachments/assets/c009bd8c-974c-4e99-b28b-86acb9df26d9" />

---

Expand All @@ -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

---
Expand All @@ -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.<br/>
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';

Expand All @@ -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 <ThemeSwitcher />;
return (
<ThemeSwitcher
position="right-bottom"
...
/>
);
}
```
### 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.<br>Each object contains:<br>• `key`: theme identifier (`ThemeKey`)<br>• `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';

Expand All @@ -102,7 +142,9 @@ export default function TestPage() {
);
}
```

### 6. Apply SimulationFilter for vision simulation

```
import { SimulationFilter } from 'colbrush/devtools';

Expand All @@ -118,31 +160,60 @@ function App() {
</ThemeProvider>
);
}

```
| **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=<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](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

Expand All @@ -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.