ksk-design-system 2.9.0 → 2.10.0

package/AGENTS.md

@@ -28,10 +28,10 @@ UI を書く前に必ず確認すること:
 - [ ] 既存コンポーネントを `src/components/COMPONENT_LOOKUP.md` で確認したか（手書き・再定義は禁止）
 - [ ] 色は semantic token（`var(--Surface-*)` / `var(--Brand-Primary)` 等）か。Tailwind標準色・生 `#hex` は禁止
 - [ ] `border` は色を併記したか（`border-[var(--Border-Low-Emphasis)]` 等）。Tailwind v4 では無色 border は currentColor になり、消費側の濃色テキストで黒ずむ（preset.css の base layer が保険だが明示が原則）
-- [ ] **文脈非依存**か（テキスト要素に `text-[var(--Text-*)]`、サーフェス/オーバーレイに `bg-[var(--Surface-*)]` を明示）。親の継承や currentColor に頼ると消費側の色文脈で崩れる。Storybook ツールバーの **Hostile ctx** を loud にして、文字/アイコンがマゼンタ化・背景が透けないか確認する
+- [ ] **文脈非依存**か（テキスト要素に `text-[var(--Text-High-Emphasis)]`、サーフェス/オーバーレイに `bg-[var(--Surface-Primary)]` を明示）。親の継承や currentColor に頼ると消費側の色文脈で崩れる。Storybook ツールバーの **Hostile ctx** を loud にして、文字/アイコンがマゼンタ化・背景が透けないか確認する
 - [ ] typography は `typo-*` クラスか（`font-bold` 等の直書きは禁止）
-- [ ] アニメーションは `duration-[var(--Motion-Duration-*)]` / `ease-[var(--Motion-Easing-*)]` か（`duration-200` や生 `cubic-bezier` の直書きは禁止。トークン参照でないと `prefers-reduced-motion` の一括制御から漏れる）
-- [ ] 重なり順は `z-[var(--Z-*)]` か（`z-50` 一律だと Portal のマウント順で勝敗が決まる。`z-10` / `z-20` のコンポーネント内部の重なりは対象外。順序は DESIGN.md の Layering 節）
+- [ ] アニメーションは Motion トークン参照か（例: `duration-[var(--Motion-Duration-Base)]` / `ease-[var(--Motion-Easing-Standard)]`）（`duration-200` や生 `cubic-bezier` の直書きは禁止。トークン参照でないと `prefers-reduced-motion` の一括制御から漏れる）
+- [ ] 重なり順は用途に合うトークン（例: `z-[var(--Z-Modal)]` / `z-[var(--Z-Popover)]`）か（`z-50` 一律だと Portal のマウント順で勝敗が決まる。`z-10` / `z-20` のコンポーネント内部の重なりは対象外。順序は DESIGN.md の Layering 節）
 - [ ] アイコンは `iconsax-reactjs` か（`lucide-react` / `heroicons` は使わない）
 - [ ] **選んだアイコンの「絵」を実際に見たか**。iconsax は名前と絵が一致しないものがある。`Check` は小切手（checkbook）でチェックマークではない（PR #349 で出荷直前まで残った）。チェックマークは `TickSquare` / `TickCircle`。また **"i" のグリフは iconsax に存在せず**、`InfoCircle` / `Information` / `Danger` / `Warning2` はすべて感嘆符「!」の器違いなので、情報アイコンは DS 自前の `InfoCircleIcon` を使う。名前で選んだら描画結果を目視し、意味が変わると困る箇所は path で固定するテストを書く <!-- docs-drift-ignore: Check TickSquare TickCircle InfoCircle Information Danger Warning2 InfoCircleIcon -->
 - [ ] 生タグ（`<button>` / `<input>` / `<a href>`）でなく DS コンポーネントを使ったか
@@ -179,6 +179,21 @@ afterEach フックが全ストーリー（tags フィルタなし）に対し
 （AA 未達トークンの darken と opacity 減衰の廃止により全ストーリー通過。
 トークンペアの正本チェックは `scripts/check-contrast.mjs`）。CI では常時実行される。
 
+**WebKit（Safari 系）でも実行できる:**
+
+```bash
+npx playwright install webkit   # 初回のみ
+npm run test:interaction:webkit
+npm run test:a11y:webkit
+```
+
+同じ設定（`vitest.storybook.config.ts` / `vitest.a11y.config.ts`）を環境変数
+`KSK_BROWSER=webkit` で WebKit に切り替えて回す。Chromium では見えない差
+（フォーカス・スクロール・描画差）を拾う。CI では専用ジョブ `webkit` で Chromium 側と
+並列に常時実行される。現状は全ストーリーが WebKit でも通っており、**除外している
+ストーリー・検査はない**（WebKit 固有の制限で除外が必要になったら、理由付きでここに一覧を残す）。
+ボタン・リンク・Select 等のフォーカス/キーボード操作を触ったときは WebKit 側も回すこと。
+
 **Button など、フォーカス表示の `outline-none` / `outline-hidden` 系クラスを触ったら `npm run test:forced-colors` も実行:**
 
 ```bash
@@ -287,6 +302,9 @@ npm run storybook
 # ビルド
 npm run build-storybook
 
+# 初回のみ: mcp-server のテスト（npm test に含まれる）が MCP SDK を使うため依存を入れる
+npm ci --prefix mcp-server
+
 # スクラッチ検出（実装後に必ず実行）
 bash scripts/lint-scratch.sh
 
@@ -302,6 +320,9 @@ npm run lint:design
 # 非推奨 API 台帳の整合検査（台帳 ⇔ 実ソースの @deprecated JSDoc）
 npm run lint:deprecations
 
+# 未定義 CSS 変数の参照検査（変数名のタイプミス検出。実行時注入の変数は scripts/check-css-vars.mjs の ALLOWLIST）
+npm run lint:css-vars
+
 # `Closes #N` 誤リンク監査（gh 必須。npm run check には入っていない）
 npm run audit:issue-links -- --recent 60
 
@@ -352,8 +373,10 @@ npm run test:forced-colors
   v1.48.x で連続した種類の不具合をここで落とす。
 - **play 関数のあるコンポーネント（Button / Dialog / AlertDialog / Sheet / Select /
   DropdownMenu / Combobox / Tabs / Form / Toast）を触ったら `npm run test:interaction` を回すこと。**
-- ビジュアル回帰（スクリーンショット差分）は未導入。`.claude/skills/audit-pages/SKILL.md` による
-  手動の視覚監査が現状の代替。
+- ビジュアル回帰（画像比較）は固定場面 + `tags: ["vrt"]` を付けた主要部品の代表ストーリー
+  × light/dark だけを撮る（全ストーリーは撮らない）。手順・基準画像の撮り直し・使われなく
+  なった基準画像の検出は `docs/visual-and-docs-checks.md`。横断の視覚監査は
+  `.claude/skills/audit-pages/SKILL.md`。
 
 **a11y 機械検証について（issue #261）:**
 
@@ -362,7 +385,9 @@ npm run test:forced-colors
 - color-contrast ルールも有効（全ストーリー対象）。当初はトークン債務のため無効化していたが、
   AA 未達トークンの darken（Success/Warning-Base・Text-Caution/Warning・Text-Low-Emphasis）と
   opacity 減衰の廃止で解消済み。無効状態デモ等 WCAG 1.4.3 の inactive 例外だけ、ストーリー側で
-  理由コメント付きの rule 除外を許可（`.storybook/preview.ts` 参照）。トークンペアの正本チェックは
+  理由コメント付きの rule 除外を許可（`.storybook/preview.ts` 参照）。除外は
+  `test/known-exceptions.json` に理由・issue・見直し期限（reviewBy）付きで登録し、未登録・
+  期限切れ・使われていない登録は `npm run check` と `npm run test:a11y` が落とす。トークンペアの正本チェックは
   `scripts/check-contrast.mjs`（`npm run check` 経由）。
 - rules.json の `accessibility.requirements` に `machineVerified` / `verifiedBy` を追加済み。
   axe でカバーできない項目（フォーカスリング視認・タッチターゲット実測・エラー表示の

package/CLAUDE.md

@@ -28,10 +28,10 @@ UI を書く前に必ず確認すること:
 - [ ] 既存コンポーネントを `src/components/COMPONENT_LOOKUP.md` で確認したか（手書き・再定義は禁止）
 - [ ] 色は semantic token（`var(--Surface-*)` / `var(--Brand-Primary)` 等）か。Tailwind標準色・生 `#hex` は禁止
 - [ ] `border` は色を併記したか（`border-[var(--Border-Low-Emphasis)]` 等）。Tailwind v4 では無色 border は currentColor になり、消費側の濃色テキストで黒ずむ（preset.css の base layer が保険だが明示が原則）
-- [ ] **文脈非依存**か（テキスト要素に `text-[var(--Text-*)]`、サーフェス/オーバーレイに `bg-[var(--Surface-*)]` を明示）。親の継承や currentColor に頼ると消費側の色文脈で崩れる。Storybook ツールバーの **Hostile ctx** を loud にして、文字/アイコンがマゼンタ化・背景が透けないか確認する
+- [ ] **文脈非依存**か（テキスト要素に `text-[var(--Text-High-Emphasis)]`、サーフェス/オーバーレイに `bg-[var(--Surface-Primary)]` を明示）。親の継承や currentColor に頼ると消費側の色文脈で崩れる。Storybook ツールバーの **Hostile ctx** を loud にして、文字/アイコンがマゼンタ化・背景が透けないか確認する
 - [ ] typography は `typo-*` クラスか（`font-bold` 等の直書きは禁止）
-- [ ] アニメーションは `duration-[var(--Motion-Duration-*)]` / `ease-[var(--Motion-Easing-*)]` か（`duration-200` や生 `cubic-bezier` の直書きは禁止。トークン参照でないと `prefers-reduced-motion` の一括制御から漏れる）
-- [ ] 重なり順は `z-[var(--Z-*)]` か（`z-50` 一律だと Portal のマウント順で勝敗が決まる。`z-10` / `z-20` のコンポーネント内部の重なりは対象外。順序は DESIGN.md の Layering 節）
+- [ ] アニメーションは Motion トークン参照か（例: `duration-[var(--Motion-Duration-Base)]` / `ease-[var(--Motion-Easing-Standard)]`）（`duration-200` や生 `cubic-bezier` の直書きは禁止。トークン参照でないと `prefers-reduced-motion` の一括制御から漏れる）
+- [ ] 重なり順は用途に合うトークン（例: `z-[var(--Z-Modal)]` / `z-[var(--Z-Popover)]`）か（`z-50` 一律だと Portal のマウント順で勝敗が決まる。`z-10` / `z-20` のコンポーネント内部の重なりは対象外。順序は DESIGN.md の Layering 節）
 - [ ] アイコンは `iconsax-reactjs` か（`lucide-react` / `heroicons` は使わない）
 - [ ] **選んだアイコンの「絵」を実際に見たか**。iconsax は名前と絵が一致しないものがある。`Check` は小切手（checkbook）でチェックマークではない（PR #349 で出荷直前まで残った）。チェックマークは `TickSquare` / `TickCircle`。また **"i" のグリフは iconsax に存在せず**、`InfoCircle` / `Information` / `Danger` / `Warning2` はすべて感嘆符「!」の器違いなので、情報アイコンは DS 自前の `InfoCircleIcon` を使う。名前で選んだら描画結果を目視し、意味が変わると困る箇所は path で固定するテストを書く <!-- docs-drift-ignore: Check TickSquare TickCircle InfoCircle Information Danger Warning2 InfoCircleIcon -->
 - [ ] 生タグ（`<button>` / `<input>` / `<a href>`）でなく DS コンポーネントを使ったか
@@ -159,6 +159,21 @@ afterEach フックが全ストーリー（tags フィルタなし）に対し
 （AA 未達トークンの darken と opacity 減衰の廃止により全ストーリー通過。
 トークンペアの正本チェックは `scripts/check-contrast.mjs`）。CI では常時実行される。
 
+**WebKit（Safari 系）でも実行できる:**
+
+```bash
+npx playwright install webkit   # 初回のみ
+npm run test:interaction:webkit
+npm run test:a11y:webkit
+```
+
+同じ設定（`vitest.storybook.config.ts` / `vitest.a11y.config.ts`）を環境変数
+`KSK_BROWSER=webkit` で WebKit に切り替えて回す。Chromium では見えない差
+（フォーカス・スクロール・描画差）を拾う。CI では専用ジョブ `webkit` で Chromium 側と
+並列に常時実行される。現状は全ストーリーが WebKit でも通っており、**除外している
+ストーリー・検査はない**（WebKit 固有の制限で除外が必要になったら、理由付きでここに一覧を残す）。
+ボタン・リンク・Select 等のフォーカス/キーボード操作を触ったときは WebKit 側も回すこと。
+
 **Button など、フォーカス表示の `outline-none` / `outline-hidden` 系クラスを触ったら `npm run test:forced-colors` も実行:**
 
 ```bash
@@ -287,6 +302,9 @@ npm run storybook
 # ビルド
 npm run build-storybook
 
+# 初回のみ: mcp-server のテスト（npm test に含まれる）が MCP SDK を使うため依存を入れる
+npm ci --prefix mcp-server
+
 # スクラッチ検出（実装後に必ず実行）
 bash scripts/lint-scratch.sh
 
@@ -302,6 +320,9 @@ npm run lint:design
 # 非推奨 API 台帳の整合検査（台帳 ⇔ 実ソースの @deprecated JSDoc）
 npm run lint:deprecations
 
+# 未定義 CSS 変数の参照検査（変数名のタイプミス検出。実行時注入の変数は scripts/check-css-vars.mjs の ALLOWLIST）
+npm run lint:css-vars
+
 # `Closes #N` 誤リンク監査（gh 必須。npm run check には入っていない）
 npm run audit:issue-links -- --recent 60
 
@@ -352,8 +373,10 @@ npm run test:forced-colors
   v1.48.x で連続した種類の不具合をここで落とす。
 - **play 関数のあるコンポーネント（Button / Dialog / AlertDialog / Sheet / Select /
   DropdownMenu / Combobox / Tabs / Form / Toast）を触ったら `npm run test:interaction` を回すこと。**
-- ビジュアル回帰（スクリーンショット差分）は未導入。`.claude/skills/audit-pages/SKILL.md` による
-  手動の視覚監査が現状の代替。
+- ビジュアル回帰（画像比較）は固定場面 + `tags: ["vrt"]` を付けた主要部品の代表ストーリー
+  × light/dark だけを撮る（全ストーリーは撮らない）。手順・基準画像の撮り直し・使われなく
+  なった基準画像の検出は `docs/visual-and-docs-checks.md`。横断の視覚監査は
+  `.claude/skills/audit-pages/SKILL.md`。
 
 **a11y 機械検証について（issue #261）:**
 
@@ -362,7 +385,9 @@ npm run test:forced-colors
 - color-contrast ルールも有効（全ストーリー対象）。当初はトークン債務のため無効化していたが、
   AA 未達トークンの darken（Success/Warning-Base・Text-Caution/Warning・Text-Low-Emphasis）と
   opacity 減衰の廃止で解消済み。無効状態デモ等 WCAG 1.4.3 の inactive 例外だけ、ストーリー側で
-  理由コメント付きの rule 除外を許可（`.storybook/preview.ts` 参照）。トークンペアの正本チェックは
+  理由コメント付きの rule 除外を許可（`.storybook/preview.ts` 参照）。除外は
+  `test/known-exceptions.json` に理由・issue・見直し期限（reviewBy）付きで登録し、未登録・
+  期限切れ・使われていない登録は `npm run check` と `npm run test:a11y` が落とす。トークンペアの正本チェックは
   `scripts/check-contrast.mjs`（`npm run check` 経由）。
 - rules.json の `accessibility.requirements` に `machineVerified` / `verifiedBy` を追加済み。
   axe でカバーできない項目（フォーカスリング視認・タッチターゲット実測・エラー表示の

package/DESIGN.md

@@ -145,6 +145,29 @@ KSK の必須正本・publish 依存にせず、KSK 固有の multi-theme / nati
 - **Dark mode**: `.dark` で Semantic 層が自動反転（コンポーネント側の変更不要）。テーマ差し替え（Brand）と
   light/dark は**直交2軸**。dark の semantic 値は `src/styles/semantic.css` の `.dark` が実装で、`tokens.json` の
   `colors.semanticDark` に機械可読ミラーを持つ（契約テストで同期を保証）。
+- **操作部品のコントラスト（issue #636）**: 入力・選択の枠、スイッチ（オフ）の地、スライダーの溝は、
+  通常の light/dark から WCAG 1.4.11（非テキスト 3:1）を満たす専用ロールを使う。
+  入力系の枠は `var(--Border-Control, var(--Border-Medium-Emphasis))`、スイッチ（オフ）の地は
+  `var(--Surface-Switch-Off, var(--Surface-Quaternary))`、hover は `--Surface-Switch-Off-Hover`、
+  スライダーの溝は `var(--Surface-Slider-Track, var(--Surface-Tertiary))` を参照する。
+  専用ロールは `:root` / `.dark` に宣言済み。`prefers-contrast: more` と `data-contrast="more"` でも
+  同じ基準値を維持する。フォールバックは専用ロールが無い旧プリセットとの互換用。
+  対象は Input / Textarea / Select / Checkbox / Radio / Combobox / MultiSelect / DatePicker / TimePicker /
+  NumberInput / SearchBar / TagInput / CheckboxCard / Chip（outline）/ FileUpload / ImageUploader /
+  ChartControls / QuantitySelector / StarRating（入力用）/ Switch（オフ）/ Slider の溝。
+  非操作の区切り線・表示用の枠の `--Border-Medium-Emphasis` は従来の色を維持する。
+  consumer が色を変更する場合は専用ロールを上書きし、変更後の背景との 3:1 を再確認する。
+
+  | 操作部品専用ロール | light | dark |
+  |---|---|---|
+  | 枠 `--Border-Control` | Gray-500（4.83:1） | White-Alpha-500 を Gray-900 へ合成（3.33:1） |
+  | オフ地 `--Surface-Switch-Off` / 溝 `--Surface-Slider-Track` | Gray-500（4.83:1） | Gray-500（3.67:1） |
+  | オフ hover `--Surface-Switch-Off-Hover` | Gray-600（7.73:1） | Gray-400（6.91:1） |
+
+  値の正本は `src/styles/semantic.css` と `tokens.json` の `colors.semantic` / `colors.semanticDark`。
+  `colors.semanticContrastMore` は高コントラスト指定時の同値ミラーで、契約テストが同期を保証する。
+  `scripts/check-contrast.mjs` が通常表示・高コントラスト指定とも例外なしで 3:1 を必須にする。
+  dark の枠は hover（`--Border-High-Emphasis`）と同値のため、フォーカスの枠・リングで状態を示す。
 - **Categorical（質的）**: `var(--Categorical-{1..16})` ＋ `-Subtle`(背景) / `-Bold`(文字)。
   カテゴリの色分け専用でテーマ非依存。WCAG/色覚多様性を検証済み。文字には必ず `-Bold`。
 

package/MIGRATION.md

@@ -39,6 +39,18 @@ npx ksk-ds check-migration ./src
 
 ---
 
+## v2.10.0
+
+APIの削除・改名はありません。次の表示・操作の既定値変更は、取り込み時に利用画面で確認してください。
+
+- Webの操作枠は `--Border-Control`、Switchオフ地は `--Surface-Switch-Off` / `--Surface-Switch-Off-Hover`、Slider溝は `--Surface-Slider-Track` を通常表示から宣言します。従来の `--Border-Medium-Emphasis` / `--Surface-Quaternary` 等の上書きでは操作部品を変更しません。独自テーマは専用ロールを上書きし、背景との3:1を再検証してください。非操作区切りは従来どおりです。Native部品本体の既存枠色を一括変更するリリースではありません。
+- AlertDialogは既定でCancelにフォーカスし、閉じると開く前の要素へ戻ります。画面独自の移動が必要なら `onOpenAutoFocus` / `onCloseAutoFocus` で `preventDefault()`、自動復帰の無効化は `restoreFocusOnClose={false}` を使ってください。
+- DataTableRowのhover背景は操作可能な行だけに付き、選択行の背景はhover中も維持します。Chipのhover背景とAlert成功枠も変更されます。
+- Shadow DOMの対応範囲とRadix由来の制約は [利用上の注意](https://github.com/ekusiek716/ksk-design-system/blob/main/docs/shadow-dom.md) を参照してください。ToastをShadow内に描画するときはProvider配下にToasterを明示してください。
+- CLIのP052/P053検査は部品の形の上書き・`@layer`外のグローバルCSSを新たに検出します。既存コードで検出された場合は正本ルールと例外の理由を確認してください。
+
+---
+
 ## v2.0.0
 
 **破壊変更は peerDependencies の要件変更 1 点のみ。** 識別子 / prop の削除・rename は

package/README.md

@@ -299,6 +299,67 @@ Footer を別コンポーネントに切り出した構成、preset 経路（`mo
 対象外です。P046 と同じく TypeScript の構文解析を使うため、`typescript` が無いプロジェクトでは
 P051 だけ skip して案内を1行出します。
 
+#### P052: DS 部品の `className` で形（角丸・高さ・左右 padding）を上書きしない
+
+`Button` / `Input` / `Textarea` / `SelectTrigger` / `DateField` / `Chip` / `Skeleton` などの角丸・高さ・
+左右 padding は DS が token（`--Control-Radius` / `--Field-Radius` / `--Field-Height-*` /
+`--Field-Padding-X-*`）と prop（`size` / `rounded` / `unstyled` / `startAdornment`）で持っています。
+部品ごとに `rounded-2xl` / `h-12` / `px-4` を被せると、同じ画面の他の部品と形が揃わなくなるため
+P052 が warn します（belle-todo で、ボタンが pill と角丸長方形で混在し、入力欄も欄ごとに角丸・高さが
+ずれていた事例が由来）。
+
+```tsx
+// ❌ 部品単位で形を被せる
+<Button className="w-full rounded-2xl">保存</Button>
+<Input className="h-12 rounded-2xl pl-8" />      // ¥ を自前で絶対配置
+
+// ✅ 既定に任せ、変えたいときは product theme で 1 箇所だけ
+<Button className="w-full">保存</Button>
+<Input startAdornment="¥" />
+```
+
+アプリ全体でボタンや入力欄の角丸を変えたいときは、`--Control-Radius` / `--Field-Radius` を
+product theme（P049 の許可リスト）で上書きします。枠なしのインライン編集欄は `unstyled`、
+`Skeleton` の角丸は `rounded` prop を使います。
+
+`"ksk-design-system"` から import した部品の `className` に書かれた文字列リテラル（`cn()` / 三項 /
+テンプレートの固定部分を含む）だけを見ます。`unstyled` を付けた部品、`h-auto` / `h-full` / `min-h-0`
+等のレイアウト用の高さ、変数経由のクラスは対象外です。ボタンをカード状のタイルとして使う等の
+正当な例外は `// ksk-ds-lint-ignore P052 -- 理由` で外します。P046 / P051 と同じく
+`typescript` が無いプロジェクトでは skip します。
+
+#### P053: `@layer` の外のグローバル CSS で DS 部品の形を変えない
+
+CSS の仕様上、`@layer` の外に書いた宣言は `@layer` の中の宣言（Tailwind / DS のユーティリティは
+`@layer utilities`）に**詳細度と無関係に勝ちます**。消費側の `globals.css` に layer 外で
+タグ / role / 汎用属性セレクタの寸法・余白・角丸・文字サイズ・outline を書くと、DS 部品の
+`className` では打ち消せず、DS 部品の形が壊れます。belle-todo では次がすべてこれでした。
+
+| layer 外のルール | 起きたこと |
+|---|---|
+| `[role="radio"] { min-height: var(--touch-min) }` | DS Chip（32px）が 44〜52px に膨らむ |
+| `:focus-visible { border-radius: 8px }` | pill のボタンがフォーカス中だけ角ばる / DS 部品のフォーカス枠が二重 |
+| `input:focus-visible { border-radius: 16px }` | 入力欄の角丸がフォーカス中だけ変わる |
+| `nav { padding-bottom: env(safe-area-inset-bottom) }` | 浮いたタブバーに safe-area が二重 |
+
+```css
+/* ❌ layer 外 */
+:focus-visible { outline: 2px solid var(--Brand-Primary); }
+
+/* ✅ base に置けば DS 部品は DS のフォーカスリングが勝ち、素の要素だけにこの outline が当たる */
+@layer base {
+  :focus-visible { outline: 2px solid var(--Brand-Primary); }
+}
+
+/* ✅ layer 外に残すなら DS 部品を外す */
+a:not([data-slot]) { min-height: 44px; }
+```
+
+`@layer` / `@theme` の中、クラスで始まるセレクタ（消費側の独自クラス）、`html` / `body` / `:root` /
+`*`、keyframes、`data-slot` を含むセレクタ（DS の公開 data-slot を明示的に狙う・外す）は対象外です。
+DS 自身 / ベンダリングされた DS の CSS も P049 と同じく対象外。例外は
+`/* ksk-ds-lint-ignore P053 -- 理由 */` で外します。
+
 #### ルールごとの除外（rules.json の excludes 系）
 
 `contracts/rules.json` の除外指定は、当てる対象ごとに 3 つに分かれています。
@@ -524,6 +585,22 @@ Claude Code をこのリポで開いて:
 
 DS コンポーネントを最大限活用したモックが `src/prototypes/` に生成され、`http://localhost:5173` のプレビューに即反映されます。スクラッチで UI を組まず、既存コンポーネントを組み合わせて作るのでブレません。
 
+## 🤖 MCP サーバー（AI エージェント向け）
+
+`mcp-server/`（`ksk-ds-mcp`）は DS の正本を MCP で配信する。リポジトリを clone した環境で `npm run mcp:build` → `npm run mcp:start`（stdio）。
+
+| 種別 | 名前 | 内容 |
+|------|------|------|
+| tool | `get_component` / `get_token` / `check_rule` / `search` | コンポーネント・トークン・禁止ルールの照会と横断検索 |
+| tool | `list_contracts` | 配信している正本の名前・説明・URI の一覧 |
+| tool | `get_contract` | 正本を名前で取得。JSON は `path`（例: `meta.counts`）、Markdown は `section`（見出しの部分一致）で部分取得。大きい契約は目次のみ返し、`full: true` で全文 |
+| resource | `ksk-ds://contracts/<name>` | `contracts/*.json`・`tokens.json`（components / rules / tokens / composition / screen-patterns 等） |
+| resource | `ksk-ds://docs/<name>` | `DESIGN.md`・`COMPONENT_LOOKUP.md`（web / native） |
+
+- resources を読めないクライアントでも `get_contract` で同じ内容を取得できる。
+- 配信するのは npm パッケージ（`package.json` の `files`）に同梱されるファイルだけ。新しい `contracts/*.json` を足したら `mcp-server/src/tools/get-contract.ts` の一覧にも追加する（`mcp-server/__tests__/get-contract.test.ts` が登録漏れと同梱漏れを検出する）。
+- テストは MCP SDK のクライアントを使うため、先に `npm ci --prefix mcp-server` が要る。
+
 ## 📖 ドキュメント
 
 - **ライブ Storybook**: https://ksk-design-system.vercel.app — 全コンポーネントのバリアント・テーマ切り替えを操作可能

package/RELEASE.md

@@ -2,6 +2,19 @@
 
 `ksk-design-system` のリリーススケジュール・運用ルール。
 
+## v2.10.0（2026-10-16）
+
+2.9.0以降の未公開13コミットをまとめたminorリリース。既存APIの削除はなく、操作部品の見た目とフォーカスの既定動作を改善しています。
+
+- Buttonの処理中表示、`useConfirm`、Dialog/Sheetの幅指定、ルーターLinkへの差し替えなど、既存コードと併用できるAPIを追加しました（#638・#642）。
+- 入力・選択部品の枠、オフのSwitch、Sliderの溝を通常light/darkでも背景との3:1以上へ改善しました。区切り線など非操作要素の色は維持します（#636・#645・#662）。
+- キーボード操作、確認ダイアログの初期フォーカスと復帰、Shadow DOM内のフォーカス検出、選択行hover、Chipのdark hover、成功Alertの色を修正しました（#640・#662）。
+- Portal/Toastの描画先、NumberInputの入力属性、ErrorBoundaryのresetKeys、NavigationBarの操作属性、データ表のラベル指定などconsumer APIの不足を補いました（#662）。
+- リポジトリをcloneした開発環境向けのMCP正本参照（DSのnpm配布物には含めない）、未定義CSS変数・形の上書き・グローバルCSSの検査を追加し、実測レイアウト修正、WebKit検証、画像比較、AI向けルールの配布検査を強化しました（#635・#637・#639・#641・#643・#644）。
+- consumer更新ツールは依存指定の完全固定・`^`・`~`を維持します。公開通知台帳への修正PR登録も含みます（#633・#634）。
+
+導入時は [2.10.0の注意](./MIGRATION.md#v2100) を確認してください。npm公開・タグ・GitHub Releaseはversion変更のmainマージ後に `publish.yml` が実行します。consumerへの取り込みとアプリ配布は別工程で、今回のDS公開準備には含めません。独立したMCPサーバーパッケージのnpm公開も今回の対象外です。
+
 ## 通常リリースサイクル
 
 | 種類 | 頻度 | 曜日 |

package/bin/ds-shape-override.js

@@ -0,0 +1,149 @@
+import ts from "typescript"
+
+/**
+ * P052: DS 部品の className で「形」（角丸・高さ・左右 padding）を上書きしない
+ *
+ * 由来: belle-todo（2026-10-01）。Button に rounded-2xl / rounded-lg を部品ごとに
+ * 被せた結果、同じ画面でボタンの角丸が pill と角丸長方形で混在し、入力欄も
+ * TextInput / DateField だけ rounded-2xl で他の欄とずれていた。形は DS が
+ * token（--Control-Radius / --Field-Radius / --Field-Height-* / --Field-Padding-X-*）と
+ * prop（size / rounded / unstyled / startAdornment）で持っているので、部品単位で被せると
+ * 必ず他の部品と揃わなくなる。アプリ全体で変えたいなら product theme override API で
+ * 1 箇所だけ変える。
+ *
+ * 検査範囲（誤検知を出さない方を優先）:
+ * - "ksk-design-system"（サブパス含む）から import した部品だけを見る。DS 内部の相対 import や
+ *   consumer 自作の同名部品は対象外
+ * - className 属性の中の文字列リテラル（cn() / 三項 / テンプレートの固定部分を含む）から
+ *   クラスを拾う。変数経由で渡すクラスや実行時に組み立てる文字列は追えない
+ * - `unstyled` を付けた部品は DS の見た目を出力しないので対象外
+ * - h-auto / h-full / min-h-0 等のレイアウト用の高さ指定は許可
+ */
+
+/** 部品 → 検査するクラスの種類（radius: rounded-* / height: h-* min-h-* size-* / padX: px-* pl-* pr-*） */
+export const SHAPE_TARGETS = {
+  Button: { radius: true, height: true },
+  Input: { radius: true, height: true, padX: true },
+  Textarea: { radius: true, padX: true },
+  AutoGrowTextarea: { radius: true, padX: true },
+  CommitInput: { radius: true, height: true, padX: true },
+  CommitTextarea: { radius: true, padX: true },
+  CommitAutoGrowTextarea: { radius: true, padX: true },
+  SelectTrigger: { radius: true, height: true, padX: true },
+  DateField: { radius: true, height: true, padX: true },
+  DatePicker: { radius: true, height: true, padX: true },
+  TimePicker: { radius: true, height: true, padX: true },
+  Combobox: { radius: true, height: true, padX: true },
+  Chip: { radius: true, height: true },
+  ChipSelector: { radius: true },
+  SettingsListRow: { radius: true, height: true },
+  // Skeleton は rounded prop（sm / lg / 2xl / full）を持つので className で渡さない
+  Skeleton: { radius: true, hint: 'rounded prop を使う（例: <Skeleton rounded="2xl" />）' },
+}
+
+const DS_MODULE_RE = /^(?:ksk-design-system|@ksk\/design-system)(?:\/.*)?$/
+const VARIANT_PREFIX = String.raw`(?:[a-z0-9-]+:|\[[^\]]*\]:)*`
+const RADIUS_RE = new RegExp(`^${VARIANT_PREFIX}rounded(?:-[trblxyse]{1,2})?(?:-[a-z0-9]+|-\\[[^\\]]+\\])?$`)
+const HEIGHT_RE = new RegExp(`^${VARIANT_PREFIX}(?:h|min-h|size)-\\S+$`)
+const LAYOUT_HEIGHT_RE = new RegExp(`^${VARIANT_PREFIX}(?:h|min-h|size)-(?:auto|full|screen|fit|min|max|dvh|svh|lvh|0)$`)
+const PAD_X_RE = new RegExp(`^${VARIANT_PREFIX}p[xlr]-\\S+$`)
+
+export function classifyShapeClass(token, rule) {
+  if (rule.radius && RADIUS_RE.test(token)) return true
+  if (rule.height && HEIGHT_RE.test(token) && !LAYOUT_HEIGHT_RE.test(token)) return true
+  if (rule.padX && PAD_X_RE.test(token)) return true
+  return false
+}
+
+/** import { Button as Btn } from "ksk-design-system" → Map("Btn" => "Button") */
+function collectDsImports(sourceFile) {
+  const local = new Map()
+  for (const statement of sourceFile.statements) {
+    if (!ts.isImportDeclaration(statement)) continue
+    if (!ts.isStringLiteral(statement.moduleSpecifier)) continue
+    if (!DS_MODULE_RE.test(statement.moduleSpecifier.text)) continue
+    const bindings = statement.importClause?.namedBindings
+    if (!bindings || !ts.isNamedImports(bindings)) continue
+    for (const element of bindings.elements) {
+      if (element.isTypeOnly) continue
+      const imported = (element.propertyName ?? element.name).text
+      if (Object.hasOwn(SHAPE_TARGETS, imported)) local.set(element.name.text, imported)
+    }
+  }
+  return local
+}
+
+function attributeOf(opening, name) {
+  return opening.attributes.properties.find(
+    (property) => ts.isJsxAttribute(property) && property.name.getText() === name,
+  )
+}
+
+/** `unstyled` / `unstyled={true}` なら true。`unstyled={cond}` 等の式は判定できないので true 扱い（誤検知回避） */
+function isUnstyled(opening) {
+  const attribute = attributeOf(opening, "unstyled")
+  if (!attribute) return false
+  const init = attribute.initializer
+  if (!init) return true
+  if (ts.isJsxExpression(init) && init.expression?.kind === ts.SyntaxKind.FalseKeyword) return false
+  return true
+}
+
+/** className の式から文字列リテラルの中身だけを集める */
+function collectClassTokens(attribute) {
+  const texts = []
+  function visit(node) {
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+      texts.push(node.text)
+      return
+    }
+    if (ts.isTemplateExpression(node)) {
+      texts.push(node.head.text)
+      for (const span of node.templateSpans) {
+        visit(span.expression)
+        texts.push(span.literal.text)
+      }
+      return
+    }
+    ts.forEachChild(node, visit)
+  }
+  const init = attribute.initializer
+  if (!init) return []
+  if (ts.isStringLiteral(init)) texts.push(init.text)
+  else if (ts.isJsxExpression(init) && init.expression) visit(init.expression)
+  return texts.join(" ").split(/\s+/).filter(Boolean)
+}
+
+export function inspectDsShapeOverrides(source, filePath = "source.tsx") {
+  const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX)
+  const local = collectDsImports(sourceFile)
+  const findings = []
+  if (local.size === 0) return findings
+
+  function check(opening) {
+    if (!ts.isIdentifier(opening.tagName)) return
+    const component = local.get(opening.tagName.text)
+    if (!component) return
+    if (isUnstyled(opening)) return
+    const classAttribute = attributeOf(opening, "className")
+    if (!classAttribute) return
+    const rule = SHAPE_TARGETS[component]
+    const classes = collectClassTokens(classAttribute).filter((token) => classifyShapeClass(token, rule))
+    if (classes.length === 0) return
+    const position = sourceFile.getLineAndCharacterOfPosition(opening.getStart(sourceFile))
+    findings.push({
+      line: position.line + 1,
+      tag: component,
+      classes,
+      detail: `<${component}> ${classes.join(" ")}${rule.hint ? `（${rule.hint}）` : ""}`,
+    })
+  }
+
+  function walk(node) {
+    if (ts.isJsxElement(node)) check(node.openingElement)
+    else if (ts.isJsxSelfClosingElement(node)) check(node)
+    ts.forEachChild(node, walk)
+  }
+  walk(sourceFile)
+  return findings
+}

package/bin/lint.js

@@ -6,6 +6,7 @@ import {
   inspectProductThemeOverrides,
   loadProductThemeContract,
 } from "./product-theme-override.js"
+import { inspectUnlayeredGlobalOverrides } from "./unlayered-global-override.js"
 
 // card-child-spacing.js / overlay-footer-padding.js は `import ts from "typescript"` している
 // （P046 / P051 専用エンジン）。typescript は 24MB 前後あり、AST が要るのはこの2ルールだけなので、
@@ -40,6 +41,11 @@ const TS_ENGINES = {
     exportName: "inspectOverlayFooterPadding",
     label: "P051（ResponsiveOverlayFrame + Footer の padding={false} 付け忘れ）",
   },
+  "ds-shape-override": {
+    module: "./ds-shape-override.js",
+    exportName: "inspectDsShapeOverrides",
+    label: "P052（DS 部品の className での角丸・高さ・左右 padding の上書き）",
+  },
 }
 
 const DEFAULT_EXTENSIONS = new Set([".js", ".jsx", ".ts", ".tsx"])
@@ -381,7 +387,8 @@ export async function runLintCli(argv, { cwd = process.cwd(), pkgRoot = resolve(
   // CSS 専用エンジン一覧。P049（product-theme-override）と P050（parallel-palette、
   // issue #393）はどちらも .css だけを対象にした独自エンジンで、TSX 向けの
   // 正規表現エンジンとは別の走査経路（lintCssFile）を通す。
-  const CSS_ENGINES = new Set(["product-theme-override", "parallel-palette"])
+  // P053（unlayered-global-override）も .css だけを見る独自エンジン。
+  const CSS_ENGINES = new Set(["product-theme-override", "parallel-palette", "unlayered-global-override"])
   const rules = loadRules(rulesPath)
   const cssRules = rules.filter((rule) => CSS_ENGINES.has(rule.engine))
   let sourceRules = rules.filter((rule) => !CSS_ENGINES.has(rule.engine))
@@ -735,6 +742,18 @@ function lintCssFile(file, cwd, cssRules, contract, dsCssIdentity = null, pkgRoo
     // capability タグを含まないので、この判定でも従来どおり P049/P050 が当たる。
     if (!ruleAppliesTo(rule, { capabilities: CSS_CAPABILITIES, filePath: rel })) continue
 
+    if (rule.engine === "unlayered-global-override") {
+      for (const violation of inspectUnlayeredGlobalOverrides(source)) {
+        if (matchesRuleExclude(rule, { file: rel, line: violation.selector, isDsFile })) continue
+        if (ignores.suppresses(rule.id ?? "UNKNOWN", violation.line)) continue
+        findings.push({
+          ...toFinding(rule, rel, violation.line, "web"),
+          message: `${rule.message ?? "@layer 外のグローバル CSS が DS 部品の形を変えています"}: ${violation.selector} { ${violation.property} }`,
+        })
+      }
+      continue
+    }
+
     if (rule.engine === "parallel-palette") {
       // contract が読めない（DS の名前空間一覧が無い）と何が DS 名前空間かを
       // 判定できず false positive しか出せないので、その場合は skip する。
@@ -808,7 +827,9 @@ function lintFile(file, cwd, rules, options = {}) {
         const line = lines[finding.line - 1] ?? ""
         if (ignores.suppresses(rule.id ?? "UNKNOWN", finding.line)) continue
         if (!matchesRuleExclude(rule, { file: rel, line, isDsFile })) {
-          findings.push(toFinding(rule, rel, finding.line, platform))
+          const base = toFinding(rule, rel, finding.line, platform)
+          // エンジンが該当箇所の具体（どの部品のどのクラスか等）を返すときはメッセージに添える（P052）
+          findings.push(finding.detail ? { ...base, message: `${base.message}: ${finding.detail}` } : base)
         }
       }
       continue

package/bin/unlayered-global-override.js

@@ -0,0 +1,96 @@
+/**
+ * P053: @layer の外で、タグ / role / 汎用属性セレクタに寸法・余白・角丸・文字サイズ・outline を当てない
+ *
+ * 由来: belle-todo（2026-10-01）。消費側の globals.css に @layer 無しで書いた
+ *   `[role="radio"] { min-height: 44〜52px }`   → DS Chip（32px）が見た目ごと膨らむ
+ *   `:focus-visible { outline; border-radius: 8px }` → pill のボタンがフォーカス中だけ角ばる・
+ *                                                     DS 部品でフォーカス枠が二重になる
+ *   `input:focus-visible { border-radius: 16px }`    → 入力欄の角丸がフォーカス中だけ変わる
+ *   `nav { padding-bottom: env(safe-area-inset-bottom) }` → 浮いたタブバーに safe-area が二重
+ * がいずれも DS の見た目を壊した。CSS の仕様上、layer 外の宣言は @layer の中の宣言
+ * （Tailwind / DS のユーティリティは @layer utilities）に詳細度と無関係に勝つため、
+ * DS 部品の className では打ち消せない。
+ *
+ * 報告しないもの（誤検知を出さない方を優先）:
+ * - @layer の中（base に置けば DS のユーティリティが勝つ）・@theme の中
+ * - クラスで始まるセレクタ（消費側の独自クラス）、html / body / :root / *、keyframes
+ * - data-slot を含むセレクタ（DS の公開 data-slot を明示的に狙う・:not([data-slot]) で外すのは意図的）
+ */
+
+const PROPS = ["min-height", "height", "padding", "border-radius", "font-size", "line-height", "outline"]
+// 接尾辞 (-bottom / -left 等) は全候補に掛ける (padding-bottom / outline-offset 等)
+const PROP_RE = new RegExp(String.raw`(?:^|[;{\s])((?:${PROPS.join("|")})(?:-[a-z]+)?)\s*:`)
+
+/** コメントを同じ長さの空白に置き換える（行番号を保つ） */
+function maskCssComments(css) {
+  return css.replace(/\/\*[\s\S]*?\*\//g, (comment) => comment.replace(/[^\n]/g, " "))
+}
+
+/** セレクタ群をカンマで分ける。:is(a, button) / :not(...) / [a="b,c"] の中のカンマでは分けない */
+export function splitSelectors(prelude) {
+  const out = []
+  let depth = 0
+  let current = ""
+  for (const ch of prelude) {
+    if (ch === "(" || ch === "[") depth++
+    else if (ch === ")" || ch === "]") depth--
+    if (ch === "," && depth === 0) {
+      out.push(current)
+      current = ""
+      continue
+    }
+    current += ch
+  }
+  out.push(current)
+  return out.map((selector) => selector.trim()).filter(Boolean)
+}
+
+/** DS 部品にも当たりうるセレクタか */
+export function isBroadSelector(selector) {
+  if (/^(?:html|body|:root|::selection|\*)(?![\w-])/.test(selector)) return false
+  if (/^\./.test(selector)) return false
+  if (/^(?:\d+(?:\.\d+)?%|from|to)$/.test(selector)) return false
+  if (/data-slot/.test(selector)) return false
+  return true
+}
+
+/**
+ * @returns {{ line: number, selector: string, property: string }[]}
+ */
+export function inspectUnlayeredGlobalOverrides(source) {
+  const css = maskCssComments(source)
+  const findings = []
+  const stack = []
+  let segmentStart = 0
+  for (let index = 0; index < css.length; index++) {
+    const ch = css[index]
+    if (ch === "{") {
+      const prelude = css.slice(segmentStart, index)
+      const trimmed = prelude.trim()
+      const kind = /^@layer\b/.test(trimmed) ? "layer" : /^@theme\b/.test(trimmed) ? "theme" : /^@/.test(trimmed) ? "at" : "rule"
+      // 行番号はセレクタの先頭（前置の空白・改行を除いた位置）で数える
+      const leading = prelude.length - prelude.trimStart().length
+      stack.push({ kind, prelude: trimmed, bodyStart: index + 1, selectorStart: segmentStart + leading })
+      segmentStart = index + 1
+    } else if (ch === "}") {
+      const block = stack.pop()
+      if (block && block.kind === "rule") {
+        const insideLayer = stack.some((entry) => entry.kind === "layer" || entry.kind === "theme")
+        const body = css.slice(block.bodyStart, index)
+        const match = !insideLayer && body.match(PROP_RE)
+        if (match) {
+          const broad = splitSelectors(block.prelude).filter(isBroadSelector)
+          if (broad.length > 0) {
+            const line = css.slice(0, block.selectorStart).split("\n").length
+            findings.push({ line, selector: broad.join(", "), property: match[1] })
+          }
+        }
+      }
+      segmentStart = index + 1
+    } else if (ch === ";" && stack.length === 0) {
+      // @import / @charset 等の文
+      segmentStart = index + 1
+    }
+  }
+  return findings
+}