ksk-design-system 1.62.0 → 1.63.0

package/contracts/components.json

@@ -1,15 +1,15 @@
 {
   "meta": {
     "name": "KSK Design System — Component Contracts",
-    "version": "1.62.0",
+    "version": "1.63.0",
     "description": "全コンポーネントの構造化定義。バリアント・アクセシビリティ要件・使用ルールを機械可読形式で管理。",
     "counts": {
       "ui": 68,
-      "patterns": 57,
+      "patterns": 60,
       "commerce": 12,
       "admin": 8,
       "shells": 3,
-      "total": 148
+      "total": 151
     },
     "exportNaming": {
       "_doc": "contracts の name が `import { name } from \"ksk-design-system\"` で解決できるかを示す。__tests__/contracts-export-integrity.test.ts が src/index.ts の実 export と突き合わせて固定する。",
@@ -516,6 +516,9 @@
       "name": "Pagination",
       "path": "src/components/ui/pagination.tsx",
       "description": "ページネーション。リスト・テーブルのページ送りに使用。",
+      "props": {
+        "navLabel": "string (既定 \"ページネーション\") — nav 要素の aria-label（issue #428、SimplePagination.navLabel と同名）"
+      },
       "subcomponents": [
         "PaginationContent",
         "PaginationItem",
@@ -587,10 +590,16 @@
         "保存完了・接続復旧・同期開始など一時的な操作結果は Banner ではなく toast.* helper を使う",
         "connectionRestored / saveComplete / retryStarted / retryFailed helper を提供"
       ],
+      "props": {
+        "Toaster.regionLabel": "string (既定 \"通知\") — viewport (role=\"region\") の aria-label（issue #428）",
+        "Toaster.closeLabel": "string (既定 \"閉じる\") — 各トーストの閉じるボタンの aria-label（issue #428）",
+        "configureToast({ regionLabel?, closeLabel? })": "fire-and-forget API（<Toaster> 不使用時）で同じラベルを設定する関数（issue #428）"
+      },
       "subcomponents": [
         "Toaster",
         "useToast",
-        "toast"
+        "toast",
+        "configureToast"
       ]
     },
     {
@@ -1026,7 +1035,10 @@
       ],
       "rules": [
         "3 件以上選択する用途に。少数なら CheckboxGroup を優先"
-      ]
+      ],
+      "props": {
+        "clearLabel": "string (既定 \"選択をクリア\") — クリアボタンの aria-label（issue #428）"
+      }
     },
     {
       "name": "SyncStatusBadge",
@@ -1506,7 +1518,10 @@
         "CTA を含む達成 UI は actions slot を使い、カード tap で任意 dismiss したい場合は interactive または onTapDismiss を使う",
         "カード不要の演出は cardless を使う",
         "effect は既定 \"fall\"（後方互換）。クラッカーが弾けた感じにしたい達成演出は effect=\"burst\" を使う（中央から全方位 360° に放射）"
-      ]
+      ],
+      "props": {
+        "dismissLabel": "string (既定 \"閉じる\") — タップで閉じる不可視ボタンの aria-label（issue #428）"
+      }
     },
     {
       "name": "BottomSheetForm",
@@ -1756,7 +1771,10 @@
     {
       "name": "BannerCarousel",
       "path": "src/components/patterns/banner-carousel.tsx",
-      "description": "バナーカルーセル。複数バナー画像を自動スライド表示。トップページのキービジュアルや特集告知に使用。"
+      "description": "バナーカルーセル。複数バナー画像を自動スライド表示。トップページのキービジュアルや特集告知に使用。",
+      "props": {
+        "regionLabel": "string (既定 \"バナー一覧\") — role=\"region\" スクロール領域の aria-label（issue #428）"
+      }
     },
     {
       "name": "ContentCarousel",
@@ -1779,7 +1797,11 @@
       "rules": [
         "矢印・ドットは ImageCarousel と同じ内部プリミティブを使用し、コピーしない",
         "画像だけのカルーセルには ImageCarousel、商品一覧には ProductCarousel を使う"
-      ]
+      ],
+      "props": {
+        "previousLabel": "string (既定 \"前へ\") — 前へ矢印の aria-label（issue #428）",
+        "nextLabel": "string (既定 \"次へ\") — 次へ矢印の aria-label（issue #428）"
+      }
     },
     {
       "name": "Footer",
@@ -1827,7 +1849,10 @@
         "region=jp は line/x/copy、region=us は whatsapp/x/copy を既定にする",
         "provider 別の計測には onShare(provider) を使う。コピー結果の計測には onCopy(result) を使う",
         "Clipboard API が利用不可または拒否された場合も copyErrorLabel を通知する"
-      ]
+      ],
+      "props": {
+        "groupLabel": "string (既定 \"シェア\") — role=\"group\" 全体ラッパーの aria-label（issue #428）"
+      }
     },
     {
       "name": "MediaActionCluster",
@@ -1958,7 +1983,10 @@
       ],
       "rules": [
         "フル機能は Pagination (ui/) を使う"
-      ]
+      ],
+      "props": {
+        "navLabel": "string (既定 \"ページネーション\") — nav 要素の aria-label（issue #428）"
+      }
     },
     {
       "name": "CoachMarkOverlay",
@@ -2057,6 +2085,80 @@
         "isActive 切替時に key を変えて Chip を強制再マウント (selected キャッシュ残り防止)"
       ]
     },
+    {
+      "name": "FilterPill",
+      "path": "src/components/patterns/filter-pill.tsx",
+      "description": "任意コンテンツの Popover を開くフィルタピル。value 指定で適用中（Brand 配色・\"ラベル: 値\" 表記）になり、onClear を渡すとピル内にクリアボタンが出る。パネルの中身は自由スロット。",
+      "variants": [
+        "active (value 指定)",
+        "inactive"
+      ],
+      "sizes": [
+        "sm",
+        "md"
+      ],
+      "accessibility": [
+        "トリガーは aria-expanded / aria-haspopup=\"dialog\" を部品側で持つ",
+        "クリアボタンには既定 aria-label（`{label}をクリア`）が付く",
+        "クリアは Popover トリガーの兄弟に配置し button の入れ子を作らない",
+        "Popover パネル（role=\"dialog\"）に既定の aria-label（`{label}のフィルタ` / panelLabel で上書き）が付く"
+      ],
+      "rules": [
+        "単純な on/off トグルは FilterChip、単一選択リストは DropdownFilter、任意パネル + 明示クリアは FilterPill",
+        "適用中かどうかの正本は value（active フラグを別に持たない）",
+        "value の整形（複数選択の \"渋谷 他2件\" 等）は呼び出し側の責務"
+      ]
+    },
+    {
+      "name": "ImageOverlayAction",
+      "path": "src/components/patterns/image-overlay-action.tsx",
+      "description": "画像の上に重ねる単一のアクションボタン（お気に入りトグル・カルーセル矢印・削除など）。見た目の円は sm/md で変わるが、タップ領域は常に 44px 以上。placement で四隅・左右中央に絶対配置する。",
+      "variants": [
+        "tone: surface / scrim"
+      ],
+      "sizes": [
+        "sm",
+        "md"
+      ],
+      "accessibility": [
+        "aria-label が必須（型で強制。アイコンのみの操作子のため）",
+        "pressed を渡すと aria-pressed が出る（トグル用途）",
+        "タップ領域 44px 以上を size によらず確保する"
+      ],
+      "rules": [
+        "写真の上に素のアイコンだけを置かない。半透明の面（surface）か暗いスクリム（scrim）を必ず持たせる",
+        "scrim はテーマ非依存の --Surface-VideoOverlay-* / --Text-on-Media を使う（ライト/ダークで反転させない）",
+        "親要素に relative が必要（placement=\"none\" 以外）",
+        "stretched-link のカード内では既定の stopPropagation により親の遷移を起こさない",
+        "複数操作をラベル付きでまとめる動画プレイヤー用途は MediaActionCluster を使う（本部品は静止画上の単発操作専用）"
+      ]
+    },
+    {
+      "name": "ThumbnailCard",
+      "path": "src/components/patterns/thumbnail-card.tsx",
+      "description": "サムネイル + 見出し + 補足 + meta で、カード全体が 1 つのリンク / ボタンになる汎用カード（stretched link）。secondaryAction をサムネ上に重ねられる。価格・レーティングを持たないコンテンツ（レコメンド・記事・検索結果）向け。",
+      "variants": {
+        "orientation": [
+          "vertical",
+          "horizontal"
+        ],
+        "aspect": [
+          "square",
+          "video",
+          "portrait"
+        ]
+      },
+      "accessibility": [
+        "全面リンク / ボタンの accessible name は title",
+        "サムネの alt は既定で空（リンク名の二重読み上げ回避）",
+        "secondaryAction はリンク面の前面に置かれ、押してもカードの遷移は起きない"
+      ],
+      "rules": [
+        "価格・レーティング・カート追加を持つ EC 商品は ProductCard を使う。meta に価格文字列を手組みしない",
+        "テキスト側に別リンクを置かない（リンクの入れ子になる）。別操作は secondaryAction へ",
+        "meta には押せない表示のみ置く"
+      ]
+    },
     {
       "name": "PresenceIndicator",
       "path": "src/components/patterns/presence-indicator.tsx",
@@ -2310,7 +2412,13 @@
       ],
       "rules": [
         "sm: cart compact, md: product detail page"
-      ]
+      ],
+      "props": {
+        "groupLabel": "string (既定 \"数量選択\") — role=\"group\" 全体の aria-label（issue #428）",
+        "decreaseLabel": "string (既定 \"数量を減らす\") — 減少ボタンの aria-label（issue #428）",
+        "increaseLabel": "string (既定 \"数量を増やす\") — 増加ボタンの aria-label（issue #428）",
+        "deleteLabel": "string (既定 \"削除\") — trash 状態時の減少ボタンの aria-label（issue #428）"
+      }
     },
     {
       "name": "OrderSummary",
@@ -2330,7 +2438,12 @@
         "dots",
         "arrows",
         "autoPlay"
-      ]
+      ],
+      "props": {
+        "regionLabel": "string (既定 \"画像カルーセル\") — role=\"region\" スクロール領域の aria-label（issue #428）",
+        "previousLabel": "string (既定 \"前へ\") — 「前へ」ボタンの aria-label（issue #428）",
+        "nextLabel": "string (既定 \"次へ\") — 「次へ」ボタンの aria-label（issue #428）"
+      }
     },
     {
       "name": "BottomTabBar",
@@ -2362,7 +2475,10 @@
         "Set maxWidth to the mobile web shell width when the app is centered in a desktop viewport.",
         "Use floatingPosition='left'|'right' (variant='pill' only) when a FAB is placed on the opposite side; default 'center' keeps the existing centered float.",
         "Native Expo Router / React Navigation consumers should use createExpoRouterTabBar instead of local floating tab bars."
-      ]
+      ],
+      "props": {
+        "navLabel": "string (既定 \"メインナビゲーション\") — nav 要素の aria-label（issue #428）"
+      }
     },
     {
       "name": "MobileTabBar",
@@ -2389,7 +2505,11 @@
         "chips",
         "sort",
         "count"
-      ]
+      ],
+      "props": {
+        "navLabel": "string (既定 \"フィルター\") — nav 要素の aria-label（issue #428）",
+        "moreFiltersLabel": "string (既定 \"絞り込み\") — 絞り込みボタンの aria-label（issue #428）"
+      }
     },
     {
       "name": "ReviewCard",
@@ -2458,7 +2578,12 @@
         "固定列は column.sticky だけ指定する。left/right は先行固定列の width から自動計算されるため stickyOffset の px 手計算は不要（幅が auto/flex の固定列が先行する場合のみ stickyOffset を明示する）",
         "サーバー側でページを切り替える表は manualPagination + pageCount + pageIndex + onPaginationChange を使い、rows には現在ページ分だけ渡す（DataTable は行をスライスしない）",
         "複雑なテーブル全体構成は DataTableHead, DataTableRow, DataTableCell などのサブコンポーネントを使う"
-      ]
+      ],
+      "props": {
+        "selectionColumnLabel": "string (既定 \"行選択\") — 選択列ヘッダー (th) の aria-label（issue #428）",
+        "selectAllLabel": "string (既定 \"すべて選択\") — 「すべて選択」チェックボックスの aria-label（issue #428）",
+        "DataTableActionCell.menuLabel": "string (既定 \"行メニュー\") — 行メニュー起動ボタンの aria-label（issue #428）"
+      }
     },
     {
       "name": "KebabMenu",
@@ -2468,7 +2593,10 @@
         "For table row actions only",
         "description は補足説明、shortcut は右側表示",
         "{ type: \"separator\" } で区切り線を挿入"
-      ]
+      ],
+      "props": {
+        "menuLabel": "string (既定 \"メニュー\") — トリガーボタンの aria-label（issue #428、DataTableActionCell.menuLabel と同名）"
+      }
     },
     {
       "name": "BulkActions",
@@ -2476,7 +2604,10 @@
       "description": "一括選択操作バー。選択件数表示・クリアボタン・カスタムアクションスロット。",
       "rules": [
         "Show only when rows are selected"
-      ]
+      ],
+      "props": {
+        "clearLabel": "string (既定 \"選択を解除\") — 選択解除ボタンの aria-label（issue #428）"
+      }
     },
     {
       "name": "StatusTabs",
@@ -2507,7 +2638,10 @@
         "upload",
         "delete",
         "grid-layout"
-      ]
+      ],
+      "props": {
+        "addLabel": "string (既定 \"画像を追加\") — 追加ボタンの aria-label（issue #428）"
+      }
     },
     {
       "name": "NotificationList",

package/contracts/token-hex-cache.json

@@ -1,7 +1,7 @@
 {
   "meta": {
     "name": "KSK Design System — Semantic Token Hex Cache",
-    "version": "1.62.0",
+    "version": "1.63.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",