@kazamitte/design-token 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kazamitte
+
+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.

package/README.md

@@ -1,3 +1,272 @@
-# Temporary Holding Version
+# @kazamitte/design-token
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A design token layer for Tailwind CSS v4 — color, typography, and style themes. Requires Tailwind v4.
+
+Every color token clears WCAG AA for normal text. No single scale can do that across every hue, so the steps differ from color to color.
+
+## Setup
+
+Install the package alongside Tailwind CSS v4, which it expects as a peer dependency.
+
+```sh
+npm install @kazamitte/design-token tailwindcss
+```
+
+### CSS
+
+Import Tailwind first, then the package. The package does not import Tailwind itself, so it is loaded once and you keep control over how it is imported.
+
+```css
+@import "tailwindcss";
+
+@import "@kazamitte/design-token/index.css";
+@import "@kazamitte/design-token/theme/color/default.css";
+@import "@kazamitte/design-token/theme/style/soft.css";
+
+@source '../node_modules/@kazamitte/design-token';
+
+body {
+  background-color: var(--r-base-bg);
+  color: var(--r-base-fg);
+}
+```
+
+The `@source` directive is required because Tailwind v4 excludes `node_modules` from scanning by default. See [Detecting classes in source files](https://tailwindcss.com/docs/detecting-classes-in-source-files) in the Tailwind docs.
+
+### JavaScript
+
+The JavaScript API exposes one function, for generating a color theme.
+
+```ts
+import { generateColorTheme } from "@kazamitte/design-token";
+```
+
+Everything the package does is delivered as CSS, so the JavaScript API is optional. Reach for it to generate several themes at once, or to swap themes at runtime from the app. See [Color theme generation](./docs/generate-color-theme.md) for usage.
+
+### Further reading
+
+- [Color theme generation](./docs/generate-color-theme.md) — writing a theme file with `generateColorTheme`
+- [Color pairings](./docs/color-pairings.md) — which secondary, base and link colors suit each primary (Japanese)
+- [Fixing class conflicts with tailwind-merge](./docs/tailwind-merge.md) — registering the package's utilities with tailwind-merge
+
+---
+
+## Layout
+
+```text
+tailwind/
+├─ base/
+│  ├─ initialize.css       clears the Tailwind color / font / text namespaces
+│  ├─ color/
+│  │  ├─ palette.css       the raw palette (every --color-*)
+│  │  ├─ semantic.css      --c-<hue>-*, 26 hues x 15 tokens, light/dark
+│  │  ├─ status.css        error / warning / success / info
+│  │  └─ utility.css       role utilities (primary-bg, base-fg, …)
+│  ├─ typography/
+│  │  ├─ font.css
+│  │  └─ utility.css
+│  └─ style/
+│     ├─ animation.css     the keyframes and the --animate-* steps on them
+│     ├─ radius.css        the radius scale
+│     ├─ shadow.css        the shadow scale and the colors it is built from
+│     └─ z-index.css       the layering scale
+├─ theme/
+│  ├─ color/               base / primary / secondary / link
+│  └─ style/               neutral / editorial / soft / dense
+└─ index.css               loads the base, the dark variant, duration utilities
+```
+
+## Color
+
+### Roles
+
+- Theme colors
+  - primary
+  - secondary
+  - base
+  - link
+- Status colors
+  - error — red
+  - warning — amber
+  - success — green
+  - info — blue
+
+Each role carries 15 tokens.
+
+| Group      | Tokens                                                             |
+| ---------- | ------------------------------------------------------------------ |
+| Text       | `fg-strong`, `fg`, `fg-muted`, `fg-subtle`                         |
+| Background | `bg`, `bg-subtle`, `bg-muted`, `bg-selected`, `bg-solid`           |
+| Border     | `border-subtle`, `border-muted`, `border-selected`, `border-solid` |
+| Contrast   | `fg-contrast`                                                      |
+| Focus ring | `focus-ring`                                                       |
+
+### Pairs that clear the contrast requirement
+
+These four clear the WCAG AA threshold for normal text (4.5:1) across all 26 hues, in both light and dark.
+
+- `fg-strong` on `bg-selected` — emphasized text on a hover surface
+- `fg` on `bg-muted` — body text on a selected surface
+- `fg-muted` on `bg` — secondary text on a tinted surface
+- `fg-contrast` on `bg-solid` — the label on a filled control
+
+`fg-subtle` is exempt from the requirement: it is meant for decoration and disabled states.
+
+Roles can take different hues, so text from one role often sits on a surface from another — base text on a primary surface, or a link on a base surface. These clear 4.5:1 for text from any hue on a surface from any other hue, in both light and dark.
+
+- `fg-strong` on `bg`, `bg-subtle` or `bg-muted`
+- `fg` on `bg` or `bg-subtle`
+- `fg-muted` on `bg`
+- `fg-contrast` on `bg-solid`
+
+For links, `link-fg` is the `fg-muted` of the link hue and `link-fg-strong` is its `fg`, so a link on any `bg` clears, and `link-fg-strong` also clears on `bg-subtle`.
+
+One exception: in dark, indigo `fg` on a yellow or lime `bg-subtle` falls to about 4.3:1.
+
+For non-text contrast (WCAG 1.4.11, 3:1), `border-solid`, `bg-solid` and `focus-ring` share a step and stand out from `bg` and `bg-subtle` of any hue, and from `bg-muted` of the same hue or of a neutral. Use them for input borders, checkboxes, progress bars, focus indicators and the like. A focus ring drawn against a solid control matches its fill, so separate the two with an offset in a `bg` color.
+
+In dark, `bg-solid` is a light fill and `fg-contrast` a dark label. No fill dark enough for a white label also stands out 3:1 from a dark surface.
+
+`fg-subtle` is not held to 3:1.
+
+Contrast is measured the way axe-core measures it: out-of-gamut colors are clipped to sRGB, nothing is rounded, and a pair passes only when its ratio is strictly greater than the threshold.
+
+### Semantic tokens
+
+All 26 hues expose the same 15 tokens under `--c-*`. Use them where a specific color is wanted directly — tags, categories, charts.
+
+```html
+<span class="bg-(--c-lime-bg-subtle) text-(--c-lime-fg)">Draft</span>
+```
+
+### Palette
+
+Adjusted from the Tailwind 4.3.0 default theme. All 26 hues are defined, including mauve, olive, mist and taupe, which Tailwind added in 4.2.
+
+Every hue also carries two steps Tailwind does not have — 350 and 750 — each the OKLCH midpoint of its neighbours. They let a semantic token sit between two Tailwind steps where neither one holds the contrast requirement across hues.
+
+## Typography
+
+Modeled on [digital-go-jp/tailwind-theme-plugin](https://github.com/digital-go-jp/tailwind-theme-plugin).
+
+Each utility sets font-size, line-height and letter-spacing together.
+
+```html
+<h1 class="text-display-48">…</h1>
+<p class="text-body-16">…</p>
+```
+
+| Utility            | Variants                  | Use              |
+| ------------------ | ------------------------- | ---------------- |
+| `text-display-*`   | 64, 56, 48, 44            | Hero, page title |
+| `text-highlight-*` | 36, 32, 28, 26, 24, 22    | Headings         |
+| `text-body-*`      | 20, 18, 16                | Body copy        |
+| `text-dense-*`     | 18, 16, 14 (+ `-compact`) | Tables, dense UI |
+| `text-oneline-*`   | 18, 16, 14                | Labels, buttons  |
+| `text-mono-*`      | 18, 16, 14                | Code             |
+
+## Style
+
+A style preset sets spacing, radius, shadow, duration and easing together, so that the whole interface reads as one.
+
+| Preset      | Character                                                              |
+| ----------- | ---------------------------------------------------------------------- |
+| `neutral`   | A balanced default                                                     |
+| `editorial` | Sharp corners and the shallowest shadows; hierarchy comes from borders |
+| `soft`      | Generous rounding and pronounced elevation                             |
+| `dense`     | Minimal rounding and elevation, for information-dense UI               |
+
+```html
+<div class="rounded-surface shadow-raised hover:shadow-raised-hover"></div>
+```
+
+Radius and easing do not name their utilities after the `@theme` namespace they live in: `--radius-*` generates `rounded-*`, and `--ease-*` generates `ease-*`.
+
+`--spacing` is the base step of the spacing scale and has no utility of its own. `p-4` is emitted as `calc(var(--spacing) * 4)`, so switching preset moves `p-*`, `m-*`, `gap-*`, `size-*` and the rest together — note that the sizing utilities read the same variable.
+
+| Utility         | Variants                                       | Sets                         |
+| --------------- | ---------------------------------------------- | ---------------------------- |
+| `p-*` `gap-*` … | every utility reads `--spacing`, the base step | spacing and sizing           |
+| `rounded-*`     | tight, control, surface, overlay, pill         | `border-radius`              |
+| `shadow-*`      | flat, raised, floating (+ `-hover`), overlay   | `box-shadow`                 |
+| `duration-*`    | instant, transition, enter                     | `transition-duration`        |
+| `ease-*`        | standard, emphasized                           | `transition-timing-function` |
+| `animate-*`     | fade / scale / slide, in and out               | `animation`                  |
+
+Every duration collapses to 1ms under `prefers-reduced-motion: reduce`.
+
+### Motion
+
+`animate-*` covers the enter and exit of the things that appear over the page.
+
+| Utility                     | Use                      |
+| --------------------------- | ------------------------ |
+| `animate-fade-in` / `-out`  | Scrims, tab panels       |
+| `animate-scale-in` / `-out` | Dialogs, menus, popovers |
+| `animate-slide-in-from-*`   | Drawers, sheets, toasts  |
+| `animate-slide-out-to-*`    | The same, leaving        |
+
+The slide steps take `top`, `right`, `bottom` and `left`, and travel the full
+size of the element unless it says otherwise.
+
+```html
+<div class="animate-slide-in-from-bottom [--slide-distance:1rem]"></div>
+```
+
+Every step is composed from the preset's duration and easing, so it follows the
+preset and collapses to 1ms under reduced motion. Tailwind's own `animate-spin`,
+`-ping`, `-pulse` and `-bounce` are untouched and keep animating under reduced
+motion.
+
+Exit animations only play while the element is still in the tree; unmount it on
+`animationend`.
+
+Collapse and expand are not included. They need a measured height, which no
+keyframe can supply.
+
+### Layering
+
+`z-*` follows [Chakra UI's z-index scale](https://chakra-ui.com/docs/theming/z-index), so the order matches what component libraries assume — notably `popover` above `modal`, since a select opened inside a dialog has to clear it.
+
+| Step       | Value | Step       | Value      |
+| ---------- | ----- | ---------- | ---------- |
+| `hide`     | -1    | `overlay`  | 1300       |
+| `base`     | 0     | `modal`    | 1400       |
+| `docked`   | 10    | `popover`  | 1500       |
+| `dropdown` | 1000  | `skip-nav` | 1600       |
+| `sticky`   | 1100  | `toast`    | 1700       |
+| `banner`   | 1200  | `tooltip`  | 1800       |
+|            |       | `max`      | 2147483647 |
+
+Layering does not vary by preset, so these are used directly rather than through
+one. `z-10` and `z-auto` still work alongside them. `<dialog>` and the Popover
+API render in the top layer, where z-index has no effect.
+
+### Shadow
+
+`--shadow-2xs` through `--shadow-2xl` are the base scale, seven steps. A preset picks one step per role and does nothing more; light and dark are resolved inside the scale, so no preset carries a dark override.
+
+Each step reads its colors through the custom properties below. These four are all that `[data-mode='dark']` swaps.
+
+| Custom property         | Light     | Dark      |
+| ----------------------- | --------- | --------- |
+| `--shadow-color-subtle` | black 5%  | black 35% |
+| `--shadow-color`        | black 10% | black 50% |
+| `--shadow-color-strong` | black 25% | black 70% |
+| `--shadow-rim-color`    | black 7%  | white 12% |
+
+A cast shadow barely reads on a dark surface, so every step opens with a `0 0 0 1px var(--shadow-rim-color)` rim. In dark it is that white rim that separates a surface from its background, while the heavier cast carries the elevation. `--shadow-2xs` is the rim alone — an edge with no elevation.
+
+To recolor the shadows, redefine those four under `:root` and `[data-mode='dark']`; the whole scale, and every preset built on it, follows.
+
+---
+
+## AI assistance
+
+The documentation and code in this package were written with AI agents — Claude and ChatGPT. Every output was reviewed by a human before it was committed.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).
+
+The color palette comes from Tailwind CSS and the typography scale from digital-go-jp/tailwind-theme-plugin, both MIT. Their notices are reproduced in [THIRD-PARTY-NOTICES.md](./THIRD-PARTY-NOTICES.md).

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,69 @@
+# Third-party notices
+
+This package contains material derived from the projects below. Both are
+distributed under the MIT License, which requires its copyright notice to
+travel with any substantial portion of the work. The notices are reproduced
+here in full.
+
+## Tailwind CSS
+
+`tailwind/base/color/palette.css` holds the 286 color values of the Tailwind
+CSS v4.3 default theme. Those colors are unchanged; only the hue component of
+the achromatic steps is written as `0` rather than `none`.
+
+The same file adds 52 colors that are not in Tailwind: a 350 and a 750 step
+for each of the 26 hues, each the OKLCH midpoint of the two Tailwind steps
+around it. They are derived from the Tailwind values above.
+
+Tailwind CSS is also the framework this package extends.
+
+> MIT License
+>
+> Copyright (c) Tailwind Labs, Inc.
+>
+> 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.
+
+## digital-go-jp/tailwind-theme-plugin
+
+The typography scale in `tailwind/base/typography/utility.css` follows the
+Digital Agency Design System as published through that plugin. The utilities
+are written from scratch for Tailwind v4; the font sizes, line heights and
+letter spacings come from the plugin's scale.
+
+> MIT License
+>
+> Copyright (c) 2023 デジタル庁
+>
+> 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.

package/dist/generate-theme.d.mts

@@ -0,0 +1,25 @@
+export type ChromaticColor =
+  | 'red' | 'orange' | 'amber' | 'yellow' | 'lime'
+  | 'green' | 'emerald' | 'teal' | 'cyan' | 'sky'
+  | 'blue' | 'indigo' | 'violet' | 'purple' | 'fuchsia'
+  | 'pink' | 'rose';
+
+export type BaseColor =
+  | 'slate' | 'gray' | 'zinc' | 'neutral' | 'stone'
+  | 'mauve' | 'olive' | 'mist' | 'taupe';
+
+export type Palette = ChromaticColor | BaseColor;
+
+export interface ColorTheme {
+  base: Palette;
+  primary: Palette;
+  secondary: Palette;
+  link: Palette;
+}
+
+/**
+ * Generates the contents of a color theme stylesheet.
+ *
+ * Returns CSS as a string.
+ */
+export declare const generateColorTheme: (theme: ColorTheme) => string;

package/dist/generate-theme.mjs

@@ -0,0 +1,60 @@
+// indent width: 2 half-width spaces
+const INDENT = " ".repeat(2);
+
+/**
+ * Role token names.
+ *
+ * These mirror the `--r-<role>-*` custom properties that
+ * `theme/color/default.css` defines and `base/color/utility.css`
+ * consumes, so generated themes are drop-in replacements for it.
+ */
+const ROLE_TOKENS = [
+  "bg",
+  "bg-subtle",
+  "bg-muted",
+  "bg-selected",
+  "bg-solid",
+  "border-subtle",
+  "border-muted",
+  "border-selected",
+  "border-solid",
+  "fg-strong",
+  "fg",
+  "fg-muted",
+  "fg-subtle",
+  "fg-contrast",
+  "focus-ring",
+];
+
+const roleBlock = (role, color) => {
+  const lines = ROLE_TOKENS.map(
+    (t) => `${INDENT}--r-${role}-${t}: var(--c-${color}-${t});`,
+  );
+  return lines.join("\n");
+};
+
+const linkBlock = (color) =>
+  [
+    `${INDENT}--r-link-fg: var(--c-${color}-fg-muted);`,
+    `${INDENT}--r-link-fg-strong: var(--c-${color}-fg);`,
+  ].join("\n");
+
+/** Generates the contents of a color theme stylesheet. */
+export const generateColorTheme = (theme) => {
+  const { base, primary, secondary, link } = theme;
+
+  return `:root {
+${INDENT}/* base - ${base} */
+${roleBlock("base", base)}
+
+${INDENT}/* primary - ${primary} */
+${roleBlock("primary", primary)}
+
+${INDENT}/* secondary - ${secondary} */
+${roleBlock("secondary", secondary)}
+
+${INDENT}/* link - ${link} */
+${linkBlock(link)}
+}
+`;
+};

package/docs/color-pairings.md

@@ -0,0 +1,220 @@
+# 配色の組み合わせ
+
+primaryを決めたあとに、secondary・base・linkをどこから選ぶかの一覧である。出発点として使い、最終判断はデザインに委ねる。
+
+## 推奨の組み合わせ表
+
+SecondaryとBase (harmonized)は推奨順に並べている。Base (achromatic)とLinkはどの候補を選んでもよく、既定値は列の1番目である。
+
+| Primary | Secondary | Base (harmonized) | Base (achromatic) | Link |
+| --------- | ------------------------------- | ------------------- | ------------------- | ---------------------------- |
+| `red` | indigo, fuchsia, purple, violet | taupe, stone | neutral, zinc, gray | indigo, violet, purple, blue |
+| `orange` | indigo, purple, violet, fuchsia | taupe, stone | neutral, zinc, gray | indigo, violet, purple, blue |
+| `amber` | indigo, violet, purple, blue | stone, taupe, olive | neutral, zinc, gray | indigo, violet, purple, blue |
+| `yellow` | indigo, violet, purple, blue | olive, stone | neutral, zinc, gray | indigo, violet, purple, blue |
+| `lime` | indigo, violet, purple, blue | olive, stone | neutral, gray, zinc | indigo, violet, purple, blue |
+| `green` | indigo, blue, violet, purple | olive, mist | neutral, gray, zinc | indigo, violet, purple, blue |
+| `emerald` | indigo, blue, violet, purple | mist, olive | neutral, gray, zinc | indigo, violet, purple, blue |
+| `teal` | lime, orange, amber, yellow | mist, slate | neutral, gray, zinc | indigo, violet, purple, blue |
+| `cyan` | lime, yellow, amber, orange | mist, slate | neutral, gray, zinc | indigo, violet, purple, blue |
+| `sky` | lime, yellow, amber, orange | slate, mist | neutral, gray, zinc | indigo, violet, purple, blue |
+| `blue` | lime, yellow, amber, orange | slate, mist | neutral, gray, zinc | indigo, violet, purple, blue |
+| `indigo` | lime, yellow, amber, orange | slate, mauve | neutral, zinc, gray | indigo, violet, purple, blue |
+| `violet` | yellow, lime, amber, orange | mauve, slate | neutral, zinc, gray | indigo, violet, purple, blue |
+| `purple` | yellow, amber, lime, orange | mauve, slate | neutral, zinc, gray | indigo, violet, purple, blue |
+| `fuchsia` | amber, yellow, orange, lime | mauve, slate | neutral, zinc, gray | indigo, violet, purple, blue |
+| `pink` | orange, amber, yellow, red | mauve, taupe | neutral, zinc, gray | indigo, violet, purple, blue |
+| `rose` | indigo, fuchsia, purple, violet | taupe, stone | neutral, zinc, gray | indigo, violet, purple, blue |
+
+## Secondary の選び方
+
+Secondaryは、P型・D型の色覚シミュレーション後でもprimaryとできるだけ離れて見える色を選ぶ。
+
+- P型（1型色覚/protan）: 赤系の光に対する感度が低い、または欠けるタイプ
+- D型（2型色覚/deutan）: 緑系の光に対する感度が低い、または欠けるタイプ
+
+primary以外の16色すべてについて、P型・D型に変換した後の色差を、ΔE2000（CIEDE2000）指標を用いて、2色の知覚的な違いを数値化する。0に近いほど似ており、値が大きいほど違って見える。
+
+なお、T型（3型色覚/tritan）は、青系の色に対応するが、まれな色覚特性であるため今回の評価からは除外している。
+
+評価には次の4つの表示条件を使う。
+
+- ライトモードの`bg-solid`（step 700）
+- ダークモードの`bg-solid`（step 350）
+- ライトモードの`fg-subtle`
+- ダークモードの`fg-subtle`
+
+P型・D型それぞれで測るため、合計8条件になる。そのうち最も小さいΔE2000値を、そのprimaryとsecondaryの組み合わせのスコアとする。
+
+つまり、ある条件だけで大きく離れて見える色ではなく、P型・D型やライト・ダークをまたいでも安定して見分けやすい色を優先している。
+
+そのスコアが大きい順に上位4色をSecondary候補とした。
+
+### P型・D型での見え方
+
+赤と緑を見分けにくい色覚（P型・D型）では、このパレットの多くの色が「黄っぽく見える色」と「青っぽく見える色」に大きく分かれる。
+
+- 黄グループ: `rose`, `red`, `orange`, `amber`, `yellow`, `lime`, `green`, `emerald`
+- 青グループ: `cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`, `fuchsia`
+- 境界にある色: `teal`, `pink`
+
+`teal`と`pink`はP型とD型で見え方の方向が異なるため、どちらか一方のグループには固定していない。
+
+同じ側にある色どうしはP型・D型への変換後に色相差が小さくなり、主に明るさや鮮やかさの違いとして知覚されやすい。たとえば`red`と`green`は、通常色覚では大きく異なるが、P型・D型ではどちらも黄寄りに見える。
+
+### 数値での評価
+
+P型・D型の見え方の変換にはMachado et al. (2009) の行列を使う。severityは1.0で、Chromium DevToolsの色覚エミュレーションで使われている行列と同じものである。
+
+変換手順は次のとおり。
+
+```text
+OKLCH
+→ sRGB 8bit
+→ 線形RGB
+→ Machado 2009 行列
+→ CIELAB
+→ ΔE2000
+```
+
+2色の違いはΔE2000で測る。0に近いほど似ており、値が大きいほど離れている。
+
+この評価では、十分な余裕を持たせるため20以上をひとつの目安としている。これはP型・D型における一般的な知覚閾値を意味するものではなく、この配色評価のための基準である。
+
+評価には、実際にsemantic tokenが参照する次の条件を使う。
+
+- ライトモードの`bg-solid`: step 700
+- ダークモードの`bg-solid`: step 350
+- ライトモードの`fg-subtle`: 色ごとにstep 500または600
+- ダークモードの`fg-subtle`: 色ごとにstep 500または600
+
+P型・D型それぞれについて4つの表示条件を測り、8条件のうち最も小さいΔE2000をその組み合わせの値とする。
+
+代表的な結果は次のとおり。
+
+- `teal`と`pink`を除く15色では、表の上位4候補はすべて26以上（`rose`が26〜27、`red`と`emerald`が35前後、ほかは40以上）
+- `teal`では23〜24程度
+- `pink`では最大でも16程度
+- `red` × `green`: 6
+- `orange` × `green`: 7
+- `rose` × `green`: 3
+
+`pink`は、この評価で採用した20の目安を満たすSecondary候補がない。PrimaryとSecondaryを色だけで明確に区別する必要がある用途では注意が必要である。
+
+## Base の選び方
+
+Baseは、primaryに色みを寄せるharmonizedと、色みを抑えるachromaticの2系統から選ぶ。
+
+### harmonized — primaryに寄せた灰色
+
+primaryと色相の近い灰色を選ぶ。画面全体に統一感を持たせながら、地の色としては灰色に近い見た目を保つ。
+
+候補は次の6色である。
+
+- `taupe`
+- `stone`
+- `olive`
+- `mist`
+- `slate`
+- `mauve`
+
+順位にはstep 500のOKLCH hueを使い、primaryとの色相角の差が小さい順に並べる。
+
+候補には常に上位2色を載せる。3番目の色もprimaryとの色相差が40°以内であれば候補に加える。
+
+### achromatic — 色みを抑えた灰色
+
+primaryを灰色の上で目立たせたい場合や、画面内ですでに多くの色を使っている場合に使う。
+
+候補は次の3色で固定する。
+
+- `neutral`
+- `zinc`
+- `gray`
+
+既定値は色みを持たない`neutral`である。
+
+残りの`zinc`と`gray`は、step 500のOKLCH hueがprimaryから近い順に並べる。順位は選択時の参考であり、どちらを使ってもよい。
+
+## Link の選び方
+
+Linkはprimaryとは独立して選ぶ。
+
+`link-fg`と`link-fg-strong`の2トークンを使い、それぞれ選んだ色の`fg-muted`と`fg`を参照する。
+
+表に載せた4色で、参照するstepは次のとおり。
+
+| Mode | `link-fg` | `link-fg-strong` |
+| ----- | --------- | ---------------- |
+| Light | 600 | 700 |
+| Dark | 400 (indigoのみ350) | 300 |
+
+### Link の順位
+
+各色について、P型・D型変換後のリンク色と本文色との差を測る。
+
+評価対象は次の4条件である。
+
+- Lightの`link-fg`
+- Lightの`link-fg-strong`
+- Darkの`link-fg`
+- Darkの`link-fg-strong`
+
+さらにP型・D型の両方を評価し、その中で最も小さいΔE2000をその色の値とする。
+
+青グループの結果は次のとおり。
+
+- `indigo`: 23
+- `violet`: 22
+- `purple`: 20
+- `blue`: 20
+- `sky`: 17
+- `cyan`: 12
+- `teal`: 5
+
+このうち上位4色を候補として表に載せる。
+
+- `indigo`, `violet`, `purple`, `blue`
+
+既定値は`indigo`である。
+
+どの候補でも、最小値はダークモードのhover時に使うstep 300で発生する。
+
+黄グループでは`lime`、`yellow`、`amber`もダークモードで本文との色差を取りやすい。ただし、一般的なリンク色としての慣習を優先し、標準候補には含めていない。ダークモード主体のUIでは選択肢になり得る。
+
+一方、`red`、`rose`、`teal`、`pink`はP型・D型変換後に本文との差が小さくなりやすいため、リンク色としては避ける。特に`teal`はダークモードで無彩色に近づき、本文との差が小さくなる。
+
+### 色以外でもリンクを示す
+
+リンクは下線など、色以外の視覚的な目印を付ける前提とする。
+
+WCAG 2.2 Success Criterion 1.4.1 Use of Colorに従い、色だけでリンクであることを伝えない。
+
+## ステータスカラーとの競合
+
+ステータスカラーは慣例に沿って次の色を使う。
+
+- Error: `red`
+- Warning: `amber`
+- Success: `green`
+- Info: `blue`
+
+PrimaryやSecondaryがこれらと同色または近い色になる場合、ブランド表現と状態表現を色だけでは区別しにくくなる。
+
+特に`red`、`amber`、`green`、`blue`はステータスカラーと直接競合する。`rose`や`orange`などの近似色も、用途によっては同じ意味の色に見えることがある。
+
+### 回避策
+
+1. ステータス色とブランド色を近接して配置しない。
+2. アイコン、形状、ラベルなど色以外の視覚要素を併用する。
+3. 必要に応じてステータスカラーの変数を個別に上書きする。
+4. Warningでは、黄と黒の高コントラストな意匠を使う方法もある。
+
+色だけで状態を伝えず、意味の違いを他の視覚表現でも示すことを基本とする。
+
+## 参考文献
+
+- カラーユニバーサルデザイン機構（CUDO）『カラーユニバーサルデザイン推奨配色セット ガイドブック』ver.4、2018年。[配布ページ](https://jfly.uni-koeln.de/colorset/)
+- Machado, G. M., Oliveira, M. M., Fernandes, L. A. F. (2009). A Physiologically-based Model for Simulation of Color Vision Deficiency. _IEEE TVCG_ 15(6)
+- Chromium, [Simulating color vision deficiencies in the Blink Renderer](https://developer.chrome.com/docs/chromium/cvd)
+- W3C, [WCAG 2.2 Success Criterion 1.4.1 Use of Color](https://www.w3.org/TR/WCAG22/#use-of-color)