Storybook を導入し、デザイントークンのカタログと a11y の自動検査を足す (ADR-0022)

.claude/rules/directory-structure.md

@@ -22,6 +22,8 @@ paths:
 - `routes/<path>/-` で始まるディレクトリ (`-components/` `-lib/` `-hooks/`) の中の import は相対パスで書く
 - 一覧テーブルは `DataTable` (`src/components/parts/`) に列定義と data を渡す。列定義は `createColumnHelper` で `-lib/<画面>-columns.ts` (横断なら `src/features/<domain>/`) に書き、cell の描画は `-components/` の部品を参照で渡す (ADR-0019)
 - 部品と画面の取り違えは機械で止まらない。判断軸は役割: registry や自作部品を包んで外見そのものを定義するなら `parts/`、既存の部品を並べて画面を組むだけなら `screens/`。消費者が 1 つでも、外見の定義を担うなら `parts/` (ADR-0020)
+- story は部品と同じディレクトリに `<部品>.stories.tsx` で置く。`src/components/ui/` も同じで、baseline の対象外になる (ADR-0006 / ADR-0022)
+- story を置けるのは `src/components/` 配下だけ。`.storybook/main.ts` の `stories` がそこしか見ないので、`features/` や `routes/**/-components/` へ置いても無言で対象から外れる (ADR-0022)
 - className を書きたくなったこと自体は `parts/` への移動理由にならない。静的か動的かを問わない。層の規則から外れるために移すのは逆 (ADR-0020 / ADR-0021)
 - `routes/` の階層は URL の設計であってドメインの区切りではない。ドメインの画面が 1 つの URL サブツリーに収まる保証は無いので、ドメイン固有の共有部品を `routes/` 側へ置かない (ADR-0012)
 - route ファイルの rename / 移動時、`createFileRoute` のパス文字列は plugin が自動更新する。手で書き換えない
@@ -53,10 +55,13 @@ paths:
 | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | ドメインを跨ぐもの (render の型、a11y、mock) | `src/test/`                                                                                                                                                               |
 | 特定の部品の locator や fixture              | 部品と同じディレクトリの `<部品>.test-helpers.ts`。`routes/` 配下では対象と同じ `-components/` か `-lib/` に置き、route ファイル自身の helper は route ファイルの隣に置く |
+| story だけが使うロジック                     | story と同じディレクトリの `<名前>.story-helpers.ts`。`src/lib/` へ置かない。プロダクトコードと読まれ、誰かが import すれば出荷される (ADR-0022)                          |
 
-- `*.test-helpers.ts` は `vp test` の include に一致せず、coverage からも除外する (`vitest.config.ts`)
+- 付随ファイル (`*.test.*` / `*.test-helpers.*` / `*.story-helpers.*` / `*.stories.*`) の種別は `scripts/lib/companion-files.ts` が唯一の定義で、lint の適用外・coverage の除外・registry baseline の突き合わせはそこから導出する。種別を足すときはそこだけを直す
+- `*.test-helpers.ts` / `*.story-helpers.ts` は `vp test` の include (`vitest.config.ts`) に一致せず、テストとして収集されない
 - route ファイルの隣に置いた `*.test-helpers.ts` は `routeFileIgnorePattern` (`vite.config.ts`) が route ファイル扱いから外す。`-` で始まるディレクトリの中は元から除外される
-- `*.test-helpers.ts` と `src/test/` をアプリのコードから import しない。型しか引かない helper は build を壊さず、fixture が bundle に入る。lint の `no-restricted-imports` が止め、テストと helper と `src/test/` は対象外 (ADR-0004)
+- `*.test-helpers.ts` / `*.story-helpers.ts` / `src/test/` をアプリのコードから import しない。型しか引かない helper は build を壊さず、fixture が bundle に入る。lint の `no-restricted-imports` が止め、テストと story と helper は対象外 (ADR-0004)
+- helper のテストの置き方は対象の実行環境で決める。DOM が要るものは `*.test.tsx` (browser project)、純粋なものは `*.test.ts` (unit project)
 
 ## shadcn コンポーネント導入時のチェック
 

.claude/rules/styling.md

@@ -2,6 +2,7 @@
 paths:
   - "src/**/*.tsx"
   - "src/**/*.css"
+  - ".storybook/**"
 ---
 
 # スタイリング規約
@@ -37,6 +38,7 @@ Why: token 経由なら dark mode 対応とデザイン変更が `styles.css` 
 - 1 層目の `@theme` は import より後ろ、`@theme inline` より前に置く。後ろへ動かすと semantic token まで消える
 - `black` と `white` だけは 1 層目で再登録してある。registry の overlay が scrim を `bg-black/10` で描いており、消すとモーダルの背景が素通しになる
 - 2 層目はテストファイルにも効く。字面走査の頃と違って `.test.*` / `.gen.*` の除外は無い
+- `styles.css` に `static` を付けない。Storybook のカタログのために `.storybook/preview.css` が同じファイルを `theme(static)` 付きで読み直す。本番の CSS は未参照の宣言を持たない (ADR-0022)
 
 ## typography 階層
 

.mise.toml

@@ -5,13 +5,25 @@
 disable_tools = ["node", "pnpm"]
 
 [env]
-DEV_PORT = "{{ exec(command='bash scripts/dev-env/derive-dev-port.sh 3000') }}"
 DB_FILE_NAME = ".data/dev.sqlite"
 
+# port は worktree ごとに分ける。固定すると 2 つ目の worktree が bind に失敗する。
+# 導出はタスクの env に置く。要るのはこの 2 つのタスクだけなのに、トップレベルの [env] へ
+# 置くと mise が env を解決するたび (シェル hook 下ではディレクトリへ入るたび) に git の
+# サブプロセスが走る。run の引数へ $(...) を直接書く形も採らない。script が実行できなかった
+# ときに空文字が渡り、Vite の既定 port で起動して worktree の分離が無言で外れる。タスクの
+# env なら、そのタスクを叩いたときだけ走り、シェル hook の有無にも依存しない。script が
+# 失敗すればタスクごと止まる (2026-09-20 実測)
 [tasks.serve]
 description = "dev server を起動する"
+env = { DEV_PORT = "{{ exec(command='bash scripts/dev-env/derive-dev-port.sh 3000') }}" }
 run = "vp dev --port $DEV_PORT"
 
+[tasks.storybook]
+description = "Storybook を起動する"
+env = { STORYBOOK_PORT = "{{ exec(command='bash scripts/dev-env/derive-dev-port.sh 6006') }}" }
+run = "vp exec storybook dev --port $STORYBOOK_PORT --no-open"
+
 [tasks."db:generate"]
 description = "Drizzle スキーマから migration を生成する"
 run = "vp exec drizzle-kit generate"

.storybook/main.ts

@@ -0,0 +1,15 @@
+import type { StorybookConfig } from "@storybook/tanstack-react";
+
+const config: StorybookConfig = {
+  // story は部品と同じディレクトリに置く (ADR-0022)。src/components/ の外は対象にしない
+  stories: ["../src/components/**/*.stories.@(ts|tsx)"],
+  addons: ["@storybook/addon-a11y", "@storybook/addon-themes", "@storybook/addon-vitest"],
+  framework: "@storybook/tanstack-react",
+  // telemetry は既定で有効で、実行したコマンド・バージョン・addon 一覧・story と
+  // コンポーネントの件数などを送る (storybook.js.org/docs/configure/telemetry)。
+  // このリポジトリは暗黙の挙動を明示で潰す方針なので切る。設定を読む前に出る boot
+  // イベントだけはこの設定の対象外である
+  core: { disableTelemetry: true },
+};
+
+export default config;

.storybook/preview.css

@@ -0,0 +1,19 @@
+/* Storybook だけ theme(static) を掛けて、定義した全トークンを :root へ出させる。
+   Tailwind は既定では utility から参照されている変数しか出力しないため、実際に使って
+   いるトークンでもカタログに現れない。theme() は import 単位で効くので、本番の CSS は
+   src/styles.css をそのまま読み、未参照の宣言を持たない (ADR-0022)。
+   出典: 参照された変数だけを出力する既定と static は tailwindcss.com/docs/theme
+   「Generating all CSS variables」、theme() が import 単位で効くことは
+   tailwindcss.com/docs/preflight「Disabling Preflight」
+
+   代償として Tailwind 既定 theme の未定義トークンが一覧に混ざる
+   (2026-09-20 実測: Radius に --radius-3xl / --radius-xs、Typography に --font-serif と
+   --font-weight-* の 6 件。Colors は --color-*: initial が効いていて増えない) */
+@import "../src/styles.css" theme(static);
+
+/* src/styles.css の source() が見ない場所で utility の class を書くならここに足す。足さないと、
+   class を書いた人が生成されないことに気付けない。@source のパスは書いた stylesheet からの
+   相対で、scan の対象は CSS entry ごとに閉じる。本番の entry (src/styles.css) は
+   この行を持たないため、Storybook 用の utility が出荷 CSS へ混ざらない
+   (tailwindcss.com/docs/detecting-classes-in-source-files「Explicitly registering sources」) */
+@source ".";

.storybook/preview.tsx

@@ -0,0 +1,21 @@
+import { withThemeByClassName } from "@storybook/addon-themes";
+import type { Preview } from "@storybook/tanstack-react";
+
+import "./preview.css";
+
+const preview: Preview = {
+  decorators: [
+    // styles.css の @custom-variant dark (&:is(.dark *)) に合わせて html へ class を当てる
+    withThemeByClassName({
+      themes: { light: "", dark: "dark" },
+      defaultTheme: "light",
+      parentSelector: "html",
+    }),
+  ],
+  parameters: {
+    // 違反を警告で留めない。expectNoA11yViolations が持つ「違反ゼロ」と基準を揃える (ADR-0022)
+    a11y: { test: "error" },
+  },
+};
+
+export default preview;

AGENTS.md

@@ -18,6 +18,14 @@ mise run verify   # vp check → vp test run → vp build → ビルド成果物
 - ブラウザテスト用の chromium は `vp install` では入らない（`playwright` が install スクリプトを持たない）。`vp exec playwright install chromium --only-shell` で取得する
 - 依存の追加と更新には公開後 3 日の待機が効く（`pnpm-workspace.yaml` の `minimumReleaseAge`）。前倒しの条件は ADR-0005
 
+## Storybook の skill と tools
+
+UI と story を触る前に `vp exec storybook skills` を実行し、`stories` skill の手順に従う。**`vp exec storybook --help` の一覧に `skills` と `tools` は出ない**ので、見落としやすい。
+
+- 部品の props・API・使い方は `vp exec storybook tools docs list` / `docs show` で答える。ソースや型定義から答えない
+- `vp exec storybook tools stories find-by-component` は Storybook を起動してから `--port` で指す。未起動でも走るが結果が空で返り、story が無いのと区別が付かない
+- MCP (`@storybook/addon-mcp`) は入れない。理由と起動の要否は ADR-0023
+
 ## 仕様書・設計判断
 
 - `docs/decisions/` - ADR（インフラ・ツールチェーン等の構造変更に着手する前に必ず参照）

README.md

@@ -53,12 +53,14 @@ vp install                                        # 依存パッケージ
 vp exec playwright install chromium --only-shell  # browser mode 用の chromium
 mise run db:migrate                               # drizzle/ の migration を DB へ適用する
 mise run serve                                    # dev server
+mise run storybook                                # 部品とデザイントークンのカタログ
 ```
 
 - Node.js と pnpm は `vp` が `package.json` から解決して用意する。`mise install` が要るのは tasks と `[env]` のため
 - 素の `pnpm` を叩くなら `corepack enable` を一度実行する。Vite+ の shim は `node` / `npm` / `npx` / `corepack` までで `pnpm` を含まない
 - chromium は `vp install` では入らない (`playwright` が install スクリプトを持たない)。未取得のまま `vp test run` すると browser project が落ちる
-- dev server の port は worktree ごとに変わる。main checkout は 3000、linked worktree は 3001-3999 (`.mise.toml` の `DEV_PORT`)
+- port は worktree ごとに変わる。main checkout は base のまま、linked worktree は base+1 から base+999 (`.mise.toml` の `serve` が base 3000、`storybook` が base 6006)
+- Storybook は部品の状態とデザイントークンを並べる。story は部品と同じディレクトリに置き、a11y を axe で自動検査する (ADR-0022)
 
 ### 3. 名前を置換する
 

docs/decisions/0002-dev-environment-toolchain.md

@@ -3,6 +3,7 @@
 - Status: Accepted
 - Date: 2026-08-17
 - Revised: 2026-09-02 (runtime と package manager の版の出所を `package.json` へ一本化し、mise は tasks と環境変数だけを持つようにした。型検査を tsgolint に委ね `typescript` を依存から外した。アプリ名を環境変数からモジュール定数へ戻した)
+- Revised: 2026-09-20 (dev server と Storybook の port の導出を、トップレベルの `[env]` からタスクの `env` へ移した)
 
 ## Context
 
@@ -29,13 +30,18 @@ CI は mise を要さない。`.mise.toml` の `[tasks.verify]` と同じ順序
 
 ### 値の置き場所を 3 つに分ける
 
-| 種別                       | 置き場所                         | 例                          |
-| -------------------------- | -------------------------------- | --------------------------- |
-| 環境で変わらない値         | モジュール定数                   | `src/lib/app-name.ts`       |
-| 環境で変わるが秘密でない値 | `.mise.toml` の `[env]`          | `DEV_PORT` / `DB_FILE_NAME` |
-| 秘密                       | 暗号化して commit + 実行時に復号 | 現時点で該当なし            |
+| 種別                       | 置き場所                         | 例                    |
+| -------------------------- | -------------------------------- | --------------------- |
+| 環境で変わらない値         | モジュール定数                   | `src/lib/app-name.ts` |
+| 環境で変わるが秘密でない値 | `.mise.toml` の `[env]`          | `DB_FILE_NAME`        |
+| 秘密                       | 暗号化して commit + 実行時に復号 | 現時点で該当なし      |
 
 アプリ名のように環境ごとに値が変わらないものは環境変数にしない。
+
+毎回の解決にコストがかかる値も `[env]` へ置かない。
+dev server と Storybook の port は worktree ごとに git から導出するため、`[env]` に置くと mise が env を解決するたび (シェル hook の下ではディレクトリへ入るたび) に git のサブプロセスが走る。
+読み手が `serve` と `storybook` のタスクしかいないので、タスクの `env` で導出する。`run` の引数へ `$(...)` を書くと、script が実行できなかったときに空文字が渡って既定 port で起動する。タスクの `env` なら script の失敗がタスクの失敗になる。
+2026-09-20 の実測で `mise hook-env` は 70ms から 28ms になった。タスク側なら、シェル hook を入れていない手元でも port が決まる。
 初版 (2026-08-17) は `VITE_APP_NAME` を `.mise.toml` の `[env]` に置いていたが、値の定義・型宣言・未設定の検出・CI への受け渡しが芋づるで要り、CI が mise に依存する原因になっていた。
 
 ### `envDir: false` で Vite の `.env` 読み込みを切る
@@ -110,7 +116,7 @@ runtime は Vite+ が同じ宣言から解決して持っているので 2 つ
 版の解決を Vite+ へ移した後も、タスクランナーと `[env]` の担い手として mise を採る判断は変わらない。
 
 宣言だけでは効かないので、mise のシェル hook を導入手順に含める。
-hook を入れていない手元では `[env]` が読まれず、`DEV_PORT` と `DB_FILE_NAME` が未設定のまま走る。
+hook を入れていない手元では `[env]` が読まれず、`DB_FILE_NAME` が未設定のまま走る。
 
 ### Vite+ を選ぶ理由
 

docs/decisions/0006-shadcn-registry-deviation-list.md

@@ -178,6 +178,7 @@ sidebar の依存として CLI が `src/hooks/` へ出力するファイルで
 - registry コードが依存するパッケージの選定は上流に従う。`class-variance-authority` は 12 コンポーネントが、`tw-animate-css` の `animate-in` / `animate-out` は 7 コンポーネントが使う (2026-09-02 時点、いずれも baseline 側にも同じ import がある)。どちらも更新が細っている (`class-variance-authority` は最終公開 2024-11-26 の 0.7.1 のまま。`tw-animate-css` は 1.4.0 が 2026-02-28 で、リポジトリの最終 push も同日。2026-09-02 確認)。乗り換えは上流が動いたときにしか成立しない。`shadcn/tailwind.css` は `animate-in` を供給しないため、`tw-animate-css` の撤去は registry コードを壊す
 - registry が `cn` の提供元を `@/lib/utils` から npm の `cn` パッケージへ移したため、`src/lib/utils.ts` を削除して消費側の import を差し替えた。`components.json` の `aliases.utils` は shadcn のスキーマが必須項目にしているので値は残すが、現行 registry は参照しない (`src/lib/utils.ts` が無くても `shadcn add` は成功する。2026-09-11 実測)
 - baseline を自前で持つのは、上流に生成時点を特定する手段が無いあいだの代替である。shadcn が生成時点の記録や registry item の版数フィールドを持つようになったら、そちらへの移行を検討する (shadcn-ui/ui#10374)
+- registry 由来でない付随ファイル (`*.test.*` / `*.stories.*` / `*.test-helpers.*` / `*.story-helpers.*`) は `src/components/ui/` に置いてよい。`shadcn add` の出力に含まれないため baseline を持たず、網羅検査の対象外になる
 
 ## 出典
 

docs/decisions/0020-component-layers.md

@@ -29,6 +29,8 @@
 | `src/components/screens/` | 部品を並べて画面を組む共有コンポーネント                       | 適用する     |
 | `src/components/` (直下)  | 上のどれでもないもの。実例は `live-regions.tsx`                | 適用する     |
 
+`src/components/` の外では `.storybook/` も適用する側に置く。decorator は design system component を包んで `className` を渡す置き場になるため、`src/components/screens/` と同じ扱いにする。`vite.config.ts` の override は `files` に `src/**` と `.storybook/**` の 2 つを持つ (PR #35)。
+
 直下を既定として残すのは、役割を決めきれないものの置き場所を無くさないためである。既定を「規則を適用する」側に置くので、著作として扱わせたいときだけ `parts/` を選ぶことになり、判断を省略した新規ファイルは規則が効く安全側に倒れる。
 
 `action/` を `parts/` の下へ移さないのは、分ける軸が違うためである。`parts/` は外見を定義する層で、`action/` は振る舞い (Transition と pending) を与える層である。どちらも design system の著作側なので `no-restyle` の扱いは同じだが、外見の変更と振る舞いの変更は別の理由で起きる。