ksk-design-system 1.51.2 → 1.53.0

package/AGENTS.md

@@ -40,6 +40,17 @@ UI を書く前に必ず確認すること:
 - [ ] `.tsx` 編集後に `bash scripts/lint-scratch.sh`、コンポーネント増減時は `npm run check` を実行したか
 - [ ] `FormField` を import する前にどちらか確認したか（react-hook-form の Controller と統合するなら `RhfFormField`＝`ui/form` の `FormField` を index.ts で別名 export したもの。単純な label+error 表示は `patterns/form-field` の `FormField`。迷ったら後者）
 
+### 新規・変更するコンポーネントの API チェック（2026-08 の consumer 実機点検で3件連続した型）
+
+「DS 部品の既定値が consumer の想定とズレていた」不具合が同じ週に3件出た（#308 / #311 / exam-kit 側で発覚した ChipSelector の複数選択既定）。部品の props を設計・変更するときは次を確認する:
+
+- [ ] **押せる要素は、押せると見て分かる面を既定で持つか**。素の Pressable + テキストだけの操作子を作らない。面・タップ領域（44pt）は `IconButton` 等の既存部品に委ねる（#308: Calendar の月送り矢印が面を持たず、consumer から差し替え口も無かった）
+- [ ] **インタラクティブな部品は a11y 既定値を自分で持つか**。`accessibilityRole` と、状態（selected / disabled / checked）の `accessibilityState` 反映は**呼び出し側の義務にしない**。呼び出し側の明示値が優先される形で部品が既定を持つ（#311: Chip が role を持たず、スクリーンリーダーにただのテキストとして扱われた）
+- [ ] **モードを持つ部品（単一/複数選択・開閉など）の既定値は、間違えて使うと壊れる側にしていないか**。既定で済ませた呼び出しが静かに誤動作する組み合わせ（例: ChipSelector の既定 `multiple=true` を単一選択のつもりで使うと、押しても values[0] が現在値のまま切り替わらない）は、既定を安全側へ倒すか、必須 prop にして省略をコンパイルエラーにする
+- [ ] **名前付きスロット（meta / description 等）は「何を・どこに置くか」を JSDoc に書いたか**。書いていないスロットは consumer に流用され、想定外の位置崩れになる（#309: ActionTile の meta に選択チェックを入れられ、左下に浮いた）
+
+いずれも lint では拾えない設計判断なので、レビューではこの4点を明示的に見る。
+
 ---
 
 ## このDSについて

package/CLAUDE.md

@@ -40,6 +40,17 @@ UI を書く前に必ず確認すること:
 - [ ] `.tsx` 編集後に `bash scripts/lint-scratch.sh`、コンポーネント増減時は `npm run check` を実行したか
 - [ ] `FormField` を import する前にどちらか確認したか（react-hook-form の Controller と統合するなら `RhfFormField`＝`ui/form` の `FormField` を index.ts で別名 export したもの。単純な label+error 表示は `patterns/form-field` の `FormField`。迷ったら後者）
 
+### 新規・変更するコンポーネントの API チェック（2026-08 の consumer 実機点検で3件連続した型）
+
+「DS 部品の既定値が consumer の想定とズレていた」不具合が同じ週に3件出た（#308 / #311 / exam-kit 側で発覚した ChipSelector の複数選択既定）。部品の props を設計・変更するときは次を確認する:
+
+- [ ] **押せる要素は、押せると見て分かる面を既定で持つか**。素の Pressable + テキストだけの操作子を作らない。面・タップ領域（44pt）は `IconButton` 等の既存部品に委ねる（#308: Calendar の月送り矢印が面を持たず、consumer から差し替え口も無かった）
+- [ ] **インタラクティブな部品は a11y 既定値を自分で持つか**。`accessibilityRole` と、状態（selected / disabled / checked）の `accessibilityState` 反映は**呼び出し側の義務にしない**。呼び出し側の明示値が優先される形で部品が既定を持つ（#311: Chip が role を持たず、スクリーンリーダーにただのテキストとして扱われた）
+- [ ] **モードを持つ部品（単一/複数選択・開閉など）の既定値は、間違えて使うと壊れる側にしていないか**。既定で済ませた呼び出しが静かに誤動作する組み合わせ（例: ChipSelector の既定 `multiple=true` を単一選択のつもりで使うと、押しても values[0] が現在値のまま切り替わらない）は、既定を安全側へ倒すか、必須 prop にして省略をコンパイルエラーにする
+- [ ] **名前付きスロット（meta / description 等）は「何を・どこに置くか」を JSDoc に書いたか**。書いていないスロットは consumer に流用され、想定外の位置崩れになる（#309: ActionTile の meta に選択チェックを入れられ、左下に浮いた）
+
+いずれも lint では拾えない設計判断なので、レビューではこの4点を明示的に見る。
+
 ---
 
 ## 必須: セッション開始時に読み込むファイル

package/contracts/components.json

@@ -1,7 +1,7 @@
 {
   "meta": {
     "name": "KSK Design System — Component Contracts",
-    "version": "1.51.2",
+    "version": "1.53.0",
     "description": "全コンポーネントの構造化定義。バリアント・アクセシビリティ要件・使用ルールを機械可読形式で管理。",
     "counts": {
       "ui": 67,
@@ -244,7 +244,8 @@
       "description": "チェックボックス。label/description/count を渡すと自動で行型レイアウトに（filter sidebar 型）。",
       "variants": [],
       "accessibility": [
-        "Must pair with <Label>"
+        "Must pair with <Label>",
+        "native (src/native/components/CheckboxField.tsx, RadioGroup.tsx): accessibilityState に加え aria-checked / aria-disabled を既定で併記する（react-native-web 0.21 は accessibilityState を aria-* へ変換しないため。RN peerDependency >=0.74.0 の aria-* props を直接渡す）。行内の装飾用インナー Checkbox/丸印は aria-hidden も併記して二重の role=checkbox/radio を防ぐ"
       ],
       "rules": [
         "label を渡すと <label> でラップされ行全体がクリッカブルになる",
@@ -780,7 +781,8 @@
       ],
       "accessibility": [
         "role=\"status\"",
-        "aria-label=\"読み込み中\""
+        "aria-label=\"読み込み中\"",
+        "native (src/native/components/Spinner.tsx): label prop（既定 \"読み込み中\"）を持ち、accessibilityLabel / aria-label の両方に既定で渡す。呼び出し側の明示値が優先される"
       ],
       "rules": [
         "--Brand-Primary 色で回転"
@@ -2052,7 +2054,7 @@
       "name": "QuickActionGrid / ActionTile",
       "exported": false,
       "path": "src/components/patterns/quick-action-grid.tsx",
-      "description": "ショートカット/絵文字 action の button tile と grid。icon/emoji、label、description、meta、selected/disabled/loading state、2/3/4 column または auto-fit を持つ。",
+      "description": "ショートカット/絵文字 action の button tile と grid。icon/emoji、label、description、meta、indicator、selected/disabled/loading state、2/3/4 column または auto-fit を持つ。",
       "variants": [
         "neutral",
         "selected",
@@ -2064,13 +2066,19 @@
       ],
       "accessibility": [
         "button semantics",
-        "aria-pressed when selected"
+        "aria-pressed when selected (selected prop または variant=\"selected\" のどちらでも true)",
+        "選択状態は色だけでなく既定チェック(indicator省略時)でも伝える(WCAG 1.4.1)",
+        "既定チェックは読み上げ対象外(aria-hidden / accessibilityElementsHidden)。選択状態の正本は aria-pressed(web) / accessibilityState.selected(native)"
       ],
       "rules": [
         "card + button の hybrid を consumer 側で手組みしない",
         "shortcut row/grid の columns/gap を consumer 側で決め打ちしない",
         "children には ActionTile を使う",
-        "選択状態は selected prop を使う"
+        "選択状態は selected prop を使う",
+        "meta はカード下段右端の補足情報専用。選択インジケータには indicator prop を使う(issue #309)",
+        "indicator はラベル行右端(loading 時 Spinner の位置)に表示。省略時は選択状態でDS標準チェックが既定表示される。null/undefined/falseはいずれも「指定なし」として扱われ、選択中なら既定チェックへフォールバックする",
+        "loading は indicator / 既定チェックより優先して表示される",
+        "native では indicator に文字列・数値を渡してもよい(DS 側が Text にラップする)。それ以外の ReactNode はそのまま描画されるため、consumer が Text 相当で包む"
       ],
       "subcomponents": [
         "QuickActionGrid",

package/contracts/token-hex-cache.json

@@ -1,7 +1,7 @@
 {
   "meta": {
     "name": "KSK Design System — Semantic Token Hex Cache",
-    "version": "1.51.2",
+    "version": "1.53.0",
     "description": "semantic / semanticDark トークン（var(--Primitive-*) 参照）を実 hex に解決したサイドカー生成物。hex はデフォルト（Blue）テーマでの解決値であり、Brand 系（meta.themeDependentKeys に列挙）はテーマ差し替え（orange/green/violet 等）で実色が変わる。テーマ別の完全解決値は `ksk-design-system/native` エクスポート（バンドル済み native トークンモジュール）の themes を参照。tokens.json 本体のスキーマは変更せず、AI がこのファイルだけで実色を把握できるようにし、primitive 値の変更による semantic 実色のドリフトを --check で機械検出する。",
     "generatedBy": "scripts/generate-token-hex-cache.mjs",
     "theme": "default",