@k8ordo/ui 1.0.0 → 2.1.0

package/docs/references/color.md

@@ -1,121 +1,266 @@
-# カラーシステム
-
-k8ordo UI のカラーは OKLCH 色空間で定義され、穏やかなトーンでUIに出る。
-
-## 設計思想
-
-- **OKLCH パレット**: 全色を OKLCH で定義。明度（L）を全色相で統一し、同じステップ番号同士のコントラストが揃う
-- **鮮やかなパレット、穏やかなトークン**: パレット自体は鮮やかに保ち、セマンティックトークンで抑えたトーンにマッピング
-- **WCAG AAA 準拠**: fg/bg の組み合わせで 7:1 以上のコントラスト比を確保
-- **60-30-10 ルール**: 60% ニュートラル（グレー系）、30% サポート（bg-subtle 等）、10% アクセント（primary）
-- Primary に Teal（H:180）、Secondary に Cyan（H:210）を使用
-- ダークモードは「ライトモードの反転」ではなく、独立したトーンで設計
-
-## OKLCH パレット設計
-
-明度スケール（全色相で共通）:
-
-| Step | L     | 用途                       |
-| ---- | ----- | -------------------------- |
-| 50   | 0.975 | 最も薄い背景               |
-| 100  | 0.945 | 薄い背景                   |
-| 200  | 0.900 | 控えめな背景               |
-| 300  | 0.840 | サポートカラー             |
-| 400  | 0.750 | 中間トーン                 |
-| 500  | 0.660 | コアカラー                 |
-| 600  | 0.575 | やや暗い                   |
-| 700  | 0.490 | 暗いトーン                 |
-| 800  | 0.410 | テキスト用（AAA on white） |
-| 900  | 0.370 | 最も暗い                   |
-
-Chroma は色相ごとに最適化（gamut 内で最大化）。
-
-## セマンティックカラー（前景）
-
-| Tailwind クラス   | Light      | Dark       | 用途             |
-| ----------------- | ---------- | ---------- | ---------------- |
-| `text-fg-base`    | gray-900   | gray-50    | 基本テキスト     |
-| `text-fg-subtle`  | gray-400   | gray-500   | プレースホルダー |
-| `text-fg-mute`    | gray-700   | gray-300   | 補足テキスト     |
-| `text-fg-inverse` | gray-50    | gray-900   | 反転テキスト     |
-| `text-fg-info`    | blue-800   | blue-200   | 情報             |
-| `text-fg-success` | green-800  | green-200  | 成功             |
-| `text-fg-warning` | yellow-800 | yellow-200 | 警告             |
-| `text-fg-error`   | red-800    | red-200    | エラー           |
-
-## セマンティックカラー（背景）
-
-| Tailwind クラス   | Light      | Dark       | 用途             |
-| ----------------- | ---------- | ---------- | ---------------- |
-| `bg-bg-base`      | white      | gray-900   | カード背景       |
-| `bg-bg-subtle`    | gray-100   | gray-800   | ページ背景       |
-| `bg-bg-mute`      | gray-200   | gray-700   | ホバー状態用     |
-| `bg-bg-emphasize` | gray-300   | gray-600   | アクティブ状態用 |
-| `bg-bg-inverse`   | gray-900   | white      | 反転背景         |
-| `bg-bg-info`      | blue-100   | blue-900   | 情報背景         |
-| `bg-bg-success`   | green-100  | green-900  | 成功背景         |
-| `bg-bg-warning`   | yellow-100 | yellow-900 | 警告背景         |
-| `bg-bg-error`     | red-100    | red-900    | エラー背景       |
-
-## セマンティックカラー（ボーダー）
-
-| Tailwind クラス           | Light      | Dark       | 用途           |
-| ------------------------- | ---------- | ---------- | -------------- |
-| `border-border-base`      | gray-400   | gray-600   | 標準ボーダー   |
-| `border-border-subtle`    | gray-100   | gray-900   | 薄いボーダー   |
-| `border-border-mute`      | gray-200   | gray-800   | 控えめボーダー |
-| `border-border-emphasize` | gray-500   | gray-500   | 強調ボーダー   |
-| `border-border-inverse`   | gray-700   | gray-300   | 反転ボーダー   |
-| `border-border-info`      | blue-500   | blue-500   | 情報ボーダー   |
-| `border-border-success`   | green-500  | green-500  | 成功ボーダー   |
-| `border-border-warning`   | yellow-500 | yellow-500 | 警告ボーダー   |
-| `border-border-error`     | red-500    | red-500    | エラーボーダー |
-
-## ブランドカラー（Primary: Teal H:180）
-
-| Tailwind クラス           | Light    | Dark     | 用途                |
-| ------------------------- | -------- | -------- | ------------------- |
-| `text-primary-fg`         | teal-800 | teal-100 | Primary テキスト    |
-| `bg-primary-bg`           | teal-200 | teal-800 | Primary 背景        |
-| `bg-primary-bg-subtle`    | teal-50  | teal-900 | 薄い Primary 背景   |
-| `bg-primary-bg-mute`      | teal-100 | teal-800 | 控えめ Primary 背景 |
-| `bg-primary-bg-emphasize` | teal-200 | teal-700 | 強調 Primary 背景   |
-| `border-primary-border`   | teal-500 | teal-500 | Primary ボーダー    |
-
-## ブランドカラー（Secondary: Cyan H:210）
-
-| Tailwind クラス           | Light    | Dark     | 用途                |
-| ------------------------- | -------- | -------- | ------------------- |
-| `text-secondary-fg`       | cyan-700 | cyan-300 | Secondary テキスト  |
-| `bg-secondary-bg`         | cyan-300 | cyan-700 | Secondary 背景      |
-| `bg-secondary-bg-subtle`  | cyan-100 | cyan-900 | 薄い Secondary 背景 |
-| `border-secondary-border` | cyan-600 | cyan-600 | Secondary ボーダー  |
-
-## 使い方の例
+# Color system
+
+The colors in `@k8ordo/ui` are defined in the OKLCH color space and reach the UI
+in a calm tone.
+
+## Design intent
+
+- **An OKLCH palette**: every color is defined in OKLCH. The chromatic hues share one lightness (L) scale, so a step number gives close to the same contrast whatever the hue; gray has a scale of its own
+- **A vivid palette, calm tokens**: the palette itself stays vivid; the semantic tokens map it down to a restrained tone
+- **Contrast**: text tokens hold WCAG AAA (7:1 or better) on the page and card grounds; `fg-subtle` and brand text on `*-bg` / `*-bg-mute` / `*-bg-emphasize` stop short of it but hold AA for normal text, in light and in dark — see [Contrast](#contrast)
+- **The 60-30-10 rule**: 60% neutral (greys), 30% supporting (`bg-subtle`, …), 10% accent (primary)
+- Primary is teal (H:180), secondary is cyan (H:210)
+- Dark mode is designed as its own tone, not as an inversion of light mode
+
+## OKLCH palette design
+
+The lightness scale. Every chromatic hue uses the first L column, except that
+teal and cyan put 100 at 0.955; gray uses the second:
+
+| Step | L (chromatic) | L (gray) | Use                     |
+| ---- | ------------- | -------- | ----------------------- |
+| 50   | 0.975         | 0.975    | The lightest background |
+| 100  | 0.945         | 0.955    | A light background      |
+| 200  | 0.900         | 0.925    | A restrained background |
+| 300  | 0.840         | 0.840    | Supporting color        |
+| 400  | 0.750         | 0.750    | Mid tone                |
+| 500  | 0.660         | 0.660    | The core color          |
+| 600  | 0.575         | 0.520    | Slightly dark           |
+| 700  | 0.490         | 0.420    | Dark tone               |
+| 800  | 0.410         | 0.300    | For text (AAA on white) |
+| 900  | 0.370         | 0.250    | Very dark               |
+| 950  | 0.180         | 0.180    | The darkest             |
+
+Chroma is set per hue and per step. Many steps lie outside the sRGB gamut, so
+the browser maps them to what the display can show.
+
+## Semantic colors (foreground)
+
+| Token                | Light      | Dark       | Use             |
+| -------------------- | ---------- | ---------- | --------------- |
+| `--color-fg-base`    | gray-900   | gray-50    | Body text       |
+| `--color-fg-subtle`  | gray-600   | gray-400   | Placeholders    |
+| `--color-fg-mute`    | gray-700   | gray-300   | Supporting text |
+| `--color-fg-inverse` | gray-50    | gray-900   | Inverted text   |
+| `--color-fg-info`    | blue-800   | blue-200   | Information     |
+| `--color-fg-success` | green-800  | green-200  | Success         |
+| `--color-fg-warning` | yellow-800 | yellow-200 | Warning         |
+| `--color-fg-error`   | red-800    | red-200    | Error           |
+
+## Semantic colors (background)
+
+| Token                  | Light      | Dark       | Use                                                                         |
+| ---------------------- | ---------- | ---------- | --------------------------------------------------------------------------- |
+| `--color-bg-base`      | white      | gray-800   | Card background                                                             |
+| `--color-bg-raised`    | white      | gray-800   | Overlays (Modal, Dialog, DropdownMenu, ListBox, Autocomplete's option list) |
+| `--color-bg-surface`   | gray-50    | gray-950   | Outermost ground: lighter than `bg-subtle` in light, darker in dark         |
+| `--color-bg-subtle`    | gray-100   | gray-900   | Page background                                                             |
+| `--color-bg-mute`      | gray-200   | gray-700   | For the hover state                                                         |
+| `--color-bg-emphasize` | gray-300   | gray-600   | For the active state                                                        |
+| `--color-bg-inverse`   | gray-900   | white      | Inverted background                                                         |
+| `--color-bg-info`      | blue-100   | blue-900   | Information ground                                                          |
+| `--color-bg-success`   | green-100  | green-900  | Success ground                                                              |
+| `--color-bg-warning`   | yellow-100 | yellow-900 | Warning ground                                                              |
+| `--color-bg-error`     | red-100    | red-900    | Error ground                                                                |
+
+## Semantic colors (border)
+
+| Token                      | Light      | Dark       | Use                |
+| -------------------------- | ---------- | ---------- | ------------------ |
+| `--color-border-base`      | gray-400   | gray-600   | Standard border    |
+| `--color-border-subtle`    | gray-100   | gray-700   | Light border       |
+| `--color-border-mute`      | gray-200   | gray-600   | Restrained border  |
+| `--color-border-emphasize` | gray-500   | gray-500   | Emphasized border  |
+| `--color-border-inverse`   | gray-700   | gray-300   | Inverted border    |
+| `--color-border-info`      | blue-500   | blue-400   | Information border |
+| `--color-border-success`   | green-500  | green-400  | Success border     |
+| `--color-border-warning`   | yellow-500 | yellow-400 | Warning border     |
+| `--color-border-error`     | red-500    | red-400    | Error border       |
+
+## Brand color (primary: teal H:180)
+
+| Token                          | Light    | Dark     | Use                       |
+| ------------------------------ | -------- | -------- | ------------------------- |
+| `--color-primary-fg`           | teal-800 | teal-300 | Primary text              |
+| `--color-primary-bg`           | teal-200 | teal-900 | Primary background        |
+| `--color-primary-bg-subtle`    | teal-50  | teal-950 | Light primary background  |
+| `--color-primary-bg-mute`      | teal-100 | teal-900 | Restrained primary ground |
+| `--color-primary-bg-emphasize` | teal-300 | teal-800 | Emphasized primary ground |
+| `--color-primary-border`       | teal-500 | teal-500 | Primary border            |
+
+## Brand color (secondary: cyan H:210)
+
+| Token                            | Light    | Dark     | Use                         |
+| -------------------------------- | -------- | -------- | --------------------------- |
+| `--color-secondary-fg`           | cyan-800 | cyan-300 | Secondary text              |
+| `--color-secondary-bg`           | cyan-200 | cyan-900 | Secondary background        |
+| `--color-secondary-bg-subtle`    | cyan-50  | cyan-950 | Light secondary background  |
+| `--color-secondary-bg-mute`      | cyan-100 | cyan-900 | Restrained secondary ground |
+| `--color-secondary-bg-emphasize` | cyan-300 | cyan-800 | Emphasized secondary ground |
+| `--color-secondary-border`       | cyan-500 | cyan-500 | Secondary border            |
+
+## Data visualization and backdrop
+
+| Token                      | Light              | Dark       | Use                     |
+| -------------------------- | ------------------ | ---------- | ----------------------- |
+| `--color-group-primary`    | teal-800           | teal-200   | First data series       |
+| `--color-group-secondary`  | cyan-800           | cyan-200   | Second data series      |
+| `--color-group-tertiary`   | pink-800           | pink-200   | Third data series       |
+| `--color-group-quaternary` | purple-800         | purple-200 | Fourth data series      |
+| `--color-back-drop`        | `rgb(0 0 0 / 0.5)` | (same)     | The backdrop of a modal |
+
+Every color is a custom property, so it goes into any CSS property that takes a
+color: `color: var(--color-fg-mute)`, `fill: var(--color-group-primary)`. With
+`tailwind.css`, each one is also a color utility without its `--color-` prefix
+(`bg-bg-base`, `text-fg-mute`, `fill-group-primary`, …).
+
+Under forced colors, paint with the system colors through
+`--color-system-canvas-text`, `--color-system-gray-text`,
+`--color-system-highlight` and `--color-system-highlight-text` (see
+[forced colors](#forced-colors-active)).
+
+## Contrast
+
+WCAG 2 contrast ratios of the color tokens, as axe measures them, for the
+lowest pair in each row (rounded down). The tokens drop their `--color-` prefix
+in this table and the next. Every pair holds at least AA for
+normal text in light and in dark. The story `styles/contrast` renders each pair,
+and the test suite runs axe over it in both color schemes — AAA where the table
+says AAA — so a token change that breaks a row fails the build:
+
+| Text                                                                  | Ground                                            | Light | Dark | Level                                                  |
+| --------------------------------------------------------------------- | ------------------------------------------------- | ----- | ---- | ------------------------------------------------------ |
+| `fg-base`, `fg-mute`, the status `fg-*`, `primary-fg`, `secondary-fg` | `bg-base`, `bg-raised`, `bg-surface`, `bg-subtle` | 7.0   | 8.3  | AAA                                                    |
+| A status `fg-*`                                                       | Its own `bg-*` (`bg-error` for `fg-error`, …)     | 6.9   | 7.5  | AAA, except `fg-success` on `bg-success` in light (AA) |
+| `primary-fg` / `secondary-fg`                                         | `*-bg-subtle`                                     | 7.5   | 11.9 | AAA                                                    |
+| `fg-base`                                                             | `bg-mute`                                         | 12.8  | 7.8  | AAA                                                    |
+| `fg-mute`                                                             | `bg-mute`                                         | 6.7   | 5.2  | AA                                                     |
+| `fg-base`                                                             | `bg-emphasize`                                    | 9.7   | 5.1  | AA                                                     |
+| `fg-subtle`                                                           | `bg-base`, `bg-raised`, `bg-surface`, `bg-subtle` | 4.8   | 6.1  | AA                                                     |
+| `primary-fg` / `secondary-fg`                                         | `*-bg`, `*-bg-mute`                               | 6.1   | 6.3  | AA                                                     |
+| `primary-fg` / `secondary-fg`                                         | `*-bg-emphasize`                                  | 5.2   | 5.2  | AA                                                     |
+
+In dark, `*-bg` is 900 (the same step as `*-bg-mute`) and `*-bg-emphasize` is
+800, a step darker than the rest of the dark scale would suggest, so the brand
+text stays AA on the hover and active grounds of a solid `Button` /
+`IconButton`.
+
+## High contrast and forced colors
+
+The stylesheet follows the two contrast settings a user makes in the OS. Neither
+is a preference an application stores, so `@k8ordo/color-scheme` leaves them
+alone: there is nothing to toggle or persist.
+
+### `prefers-contrast: more`
+
+`styles.css` moves the text and border tokens further from the ground, in light
+and in dark. Text then holds AAA on the page, card, and status grounds, and
+borders hold 3:1 against the grounds they sit on.
+
+| Token                                 | Light       | Dark     |
+| ------------------------------------- | ----------- | -------- |
+| `fg-base`                             | gray-950    | white    |
+| `fg-mute`                             | gray-900    | gray-100 |
+| `fg-subtle`                           | gray-800    | gray-200 |
+| The status `fg-*`                     | 900         | 100      |
+| `primary-fg` / `secondary-fg`         | 900         | 100      |
+| `border-base`                         | gray-600    | gray-400 |
+| `border-subtle`                       | gray-500    | gray-500 |
+| `border-mute`                         | gray-500    | gray-400 |
+| `border-emphasize`                    | gray-800    | gray-200 |
+| The status `border-*`                 | 700         | 300      |
+| `primary-border` / `secondary-border` | 700         | 300      |
+| `bg-emphasize`                        | (unchanged) | gray-700 |
+
+In dark, `bg-emphasize` moves a step darker as well, because white text on the
+usual gray-600 would stay near 5:1.
+
+Surfaces outlined only by a shadow or a ground — `Card`'s `shadow` variant,
+`Modal`, `Drawer`, `Dialog`, `Alert`, `Callout` and `Toast`, a user `Message` — gain a
+1px `border-base` outline, as do the `Switch` track and thumb and the `Slider`
+and `Progress` tracks. A focused `DropdownMenu` or `ListBox` item and the
+active `Autocomplete` option draw a 2px outline on top of their ground.
+
+### `forced-colors: active`
+
+Under forced colors the browser repaints every color from the user's palette,
+drops shadows, and flattens grounds to one color. The components keep their
+boundaries, focus rings, and selected states visible:
+
+- **Boundaries**: the same outline as under `prefers-contrast: more`; controls with a border keep it
+- **Focus rings**: the `box-shadow` ring disappears and a 2px outline shows instead (the components draw a transparent outline under forced colors, which the browser paints)
+- **Selected states** are painted with system colors: `Highlight` for the selected tab's indicator, a checked `Switch` track, the `Progress` and `Slider` fill, and a selected `Autocomplete` option; `CanvasText` for the dot of a checked `Radio` / `RadioCard` and the thumb of a `Switch`
+- `Separator` is painted `CanvasText` and `Skeleton` `GrayText`
+- A color swatch in `Code` keeps its real color (`forced-color-adjust: none`), because the color is the content
+
+### In your own UI
+
+- Write the two settings as media queries: `@media (prefers-contrast: more)` and `@media (forced-colors: active)` (with `tailwind.css`, the `contrast-more:` and `forced-colors:` variants). Under forced colors only system colors survive, so paint state with them (`background-color: var(--color-system-highlight)`)
+- Do not draw a boundary or a focus ring with `box-shadow` alone
+- Do not hide something with a transparent color: forced colors paints it. Use `visibility: hidden`
+- To tune the high-contrast values, redefine the tokens inside `@media (prefers-contrast: more)`, on `:root` and on `.dark`, in CSS loaded after the library stylesheet
+
+## Usage examples
+
+```css
+/* page.module.css: float a card on the page background */
+.page {
+  min-height: 100vh;
+  background-color: var(--color-bg-subtle);
+}
+
+.body {
+  padding: calc(var(--spacing) * 6);
+}
+
+.title {
+  color: var(--color-fg-base);
+  font-weight: var(--font-weight-bold);
+}
+
+.lead {
+  margin-top: calc(var(--spacing) * 2);
+  color: var(--color-fg-mute);
+}
+
+.accent {
+  color: var(--color-primary-fg);
+}
+
+/* the hover state */
+.row {
+  background-color: var(--color-bg-base);
+  transition: background-color var(--duration-fast) var(--easing-out);
+}
+
+@media (hover: hover) {
+  .row:hover {
+    background-color: var(--color-bg-mute);
+  }
+}
+```
 
 ```tsx
-// ページ背景にカードを浮かせる
-<div className="bg-bg-subtle min-h-screen">
-  <Card appearance="shadow">
-    <div className="p-8">
-      <h2 className="text-fg-base font-bold">タイトル</h2>
-      <p className="text-fg-mute mt-2">補足テキスト</p>
-      <span className="text-primary-fg">アクセントテキスト</span>
+<div className={styles.page}>
+  <Card variant="shadow">
+    <div className={styles.body}>
+      <h2 className={styles.title}>Title</h2>
+      <p className={styles.lead}>Supporting text</p>
+      <span className={styles.accent}>Accent text</span>
     </div>
   </Card>
 </div>
-
-// ホバー状態
-<button className="bg-bg-base hover:bg-bg-mute transition-colors">
-  ボタン
-</button>
 ```
 
-## やってはいけないこと
+With `tailwind.css` the same reads `bg-bg-subtle`, `p-6`, `text-fg-base
+font-bold`, `mt-2 text-fg-mute`, `text-primary-fg`, and `bg-bg-base
+hover:bg-bg-mute transition-colors duration-150 ease-out`.
+
+## What not to do
 
-- グラデーション背景（`bg-gradient-to-*`）
-- 彩度の高い色の広範囲使用（アクセントは小面積で）
-- 透明度による状態表現（`/90`, `/80` など）— 専用のセマンティックカラーを使う
-- ホバーに `bg-primary-bg` を使う — `bg-bg-mute` を優先
-- 生のパレット色（`bg-teal-500`）を直接使う — セマンティックトークンを使う
-- ダークモードで単純にカラーを反転させる
+- Gradient backgrounds
+- Saturated color over large areas (keep accents small)
+- Expressing state with opacity (`color-mix(… 90%, transparent)`, `/90`) — use the dedicated semantic color
+- Using `--color-primary-bg` on hover — prefer `--color-bg-mute`
+- Using a palette color (`--teal-500`) directly — use a semantic token. The palette is what the tokens are built from, not part of the API
+- Simply inverting the colors for dark mode