ksk-design-system 1.40.0 → 1.41.0

package/AGENTS.md

@@ -17,6 +17,7 @@
 ```
 contracts/rules.json                     # 禁止パターン32件・AIアンチパターン10件・a11y要件
 contracts/components.json               # 全112コンポーネントの定義・バリアント・ルール
+contracts/design-context.json           # DESIGN.md と正本ファイルの関係・AI向け検査方針
 tokens.json                             # カラー・スペーシング・シャドウトークン
 src/components/COMPONENT_LOOKUP.md      # バリアント・インポートパス一覧（自動生成）
 ```
@@ -92,6 +93,7 @@ Brand色を差し替え（10行）→ Primitive Layer → Semantic Layer → Bri
 | **AGENTS.md**（本ファイル） | 概要・技術スタック・コマンド・クイックスタート |
 | **contracts/components.json** | 全112コンポーネントの構造化定義（バリアント・アクセシビリティ要件） |
 | **contracts/rules.json** | 禁止パターン32件・AIアンチパターン10件・アクセシビリティ要件 |
+| **contracts/design-context.json** | `DESIGN.md` の役割・正本ファイル・外部 DESIGN.md 参照方針 |
 | **tokens.json** | カラー・スペーシング・シャドウトークンの機械可読定義 |
 | **src/components/COMPONENT_LOOKUP.md** | 全112コンポーネントのバリアント・インポートパス（自動生成） |
 | **DESIGN.md** | AI エージェント向け視覚言語サマリ（トークン＋意図・voice・motion） |

package/CLAUDE.md

@@ -59,6 +59,7 @@ Brand色を差し替え（10行）→ Primitive Layer → Semantic Layer → Bri
 | **AGENTS.md** | 同上（Codex用。セッション開始時の読み込み指示・編集後コマンドを明記） |
 | **contracts/components.json** | 全112コンポーネントの構造化定義（バリアント・アクセシビリティ要件） |
 | **contracts/rules.json** | 禁止パターン32件・AIアンチパターン10件・アクセシビリティ要件 |
+| **contracts/design-context.json** | `DESIGN.md` の役割・正本ファイル・外部 DESIGN.md 参照方針 |
 | **tokens.json** | カラー・スペーシング・シャドウトークンの機械可読定義 |
 | **src/components/COMPONENT_LOOKUP.md** | 全112コンポーネントのバリアント・インポートパス一覧（自動生成） |
 | **DESIGN.md** | AI エージェント向け視覚言語サマリ（トークン＋意図・voice・motion） |
@@ -66,8 +67,9 @@ Brand色を差し替え（10行）→ Primitive Layer → Semantic Layer → Bri
 **セッション開始時 / コードを書く前に必ず読む:**
 1. `contracts/rules.json` の `prohibited` と `aiPatterns`（AIが典型的に犯すパターン集）を確認
 2. `contracts/components.json` でコンポーネント定義・バリアントを確認
-3. `src/components/COMPONENT_LOOKUP.md` で既存コンポーネントを確認（手書き・再定義の防止）
-4. `tokens.json` でカラー・余白・影・タイポのトークンを確認
+3. `contracts/design-context.json` で `DESIGN.md` と正本ファイルの関係を確認
+4. `src/components/COMPONENT_LOOKUP.md` で既存コンポーネントを確認（手書き・再定義の防止）
+5. `tokens.json` でカラー・余白・影・タイポのトークンを確認
 
 **`.tsx` を編集したら `bash scripts/lint-scratch.sh`、コンポーネント増減時は `npm run check` を実行すること。**
 
@@ -114,6 +116,9 @@ bash scripts/check-drift.sh
 # COMPONENT_LOOKUP.md 再生成（コンポーネント追加後に実行）
 npm run generate:lookup
 
+# DESIGN.md contract 検査
+npm run lint:design
+
 # 全チェック（tsc + lint + drift + lookup 一括）
 npm run check
 ```

package/DESIGN.md

@@ -32,7 +32,7 @@ colors:
   info: "#2563EB"
 typography:
   fontFamily: "system-ui, -apple-system, 'Hiragino Sans', 'Noto Sans JP', sans-serif"
-  display:  { fontSize: "48px", lineHeight: "1.2",  fontWeight: 700 }   # typo-display-xl
+  display:  { fontSize: "48px", lineHeight: "1.25", fontWeight: 700 }   # typo-display-xl
   heading:  { fontSize: "18px", lineHeight: "1.5",  fontWeight: 700 }   # typo-heading-lg（基準）
   body:     { fontSize: "14px", lineHeight: "1.75", fontWeight: 400 }   # typo-body-md（基準）
   label:    { fontSize: "12px", lineHeight: "1.5",  fontWeight: 500 }   # typo-label-sm
@@ -45,12 +45,12 @@ rounded:
   full: "9999px"   # Button / Chip
 spacing:
   unit: "4px"      # 4px グリッド（scale: 0,4,8,12,16,20,24,28,32,36,40,44,48,...）
-  page: "16px"     # 画面端マージン var(--page-px)
+  page: "16px"     # 基準画面端マージン。実レイアウトは Screen / Shell の padding contract を優先
 elevation:                                          # 影色は neutral（Gray-900 ベース rgba(17,24,39,…)）でテーマ非依存
-  sm: "0 1px 2px rgba(0,0,0,0.05)"
-  md: "0 0 8px rgba(20,20,20,0.08)"
-  lg: "0 12px 32px -4px rgba(17,24,39,0.12), 0 8px 16px -6px rgba(17,24,39,0.12)"
-  dialog: "0 12px 32px -4px rgba(17,24,39,0.12), 0 8px 16px -6px rgba(17,24,39,0.12), 0 1px 4px 1px rgba(0,0,0,0.2)"
+  sm: "0 1px 2px 0 rgba(0, 0, 0, 0.05)"
+  md: "0 0 8px rgba(20, 20, 20, 0.08)"
+  lg: "0px 12px 32px -4px rgba(17, 24, 39, 0.12), 0px 8px 16px -6px rgba(17, 24, 39, 0.12)"
+  dialog: "0px 12px 32px -4px rgba(17, 24, 39, 0.12), 0px 8px 16px -6px rgba(17, 24, 39, 0.12), 0px 1px 4px 1px rgba(0, 0, 0, 0.2)"
 motion:
   microIn: "150ms ease-out"                       # fade-in / scale-in
   enter: "200ms ease-out"                          # fade-in-up / slide-in
@@ -93,6 +93,21 @@ EC/BtoC 系）を回すのが狙い。
 - **基盤**: React 19 + Tailwind v4 + shadcn/Radix + iconsax。
 - **判断基準**: 色・余白・タイポは必ずトークン経由。生の値を書かない（後述 Do/Don't）。
 
+## Source Of Truth
+
+`DESIGN.md` は Google DESIGN.md の「front matter + rationale」形式を参考にした **AI 向け配布サマリ**であり、
+実装正本ではない。KSK の正本は次のファイルに置く。
+
+- `tokens.json`: primitive / semantic / dark semantic / typography / spacing / shadow / touch target。
+- `src/styles/*.css`: 実際に publish される CSS custom properties と typography / glass utilities。
+- `contracts/rules.json`: 禁止パターン、AI anti-pattern、a11y、consumer lint の正本。
+- `contracts/components.json`: component 名、variant、subcomponent、usage rule、件数の正本。
+- `src/components/COMPONENT_LOOKUP.md`: import map、Storybook coverage、DS-first recipe の生成済み索引。
+
+Google DESIGN.md は互換フォーマットと検査観点の参照に留める。Google 側の alpha schema / CLI を
+KSK の必須正本・publish 依存にせず、KSK 固有の multi-theme / native / categorical / component contract は
+`contracts/design-context.json` と repo 内 checker で管理する。
+
 ## Colors
 
 3層トークン。コンポーネントは**必ず Semantic 層を `var()` で参照**する（Primitive 直参照・生 hex 禁止）。
@@ -125,7 +140,7 @@ EC/BtoC 系）を回すのが狙い。
 ## Layout & Spacing
 
 - **4px グリッド**。余白・サイズは 4 の倍数（scale 0–60）。
-- 画面端マージン: `var(--page-px)`（既定 16px）。
+- 画面端マージン: 16px を基準にしつつ、実レイアウトでは `Screen` / shell component の padding contract を優先する。
 - **タッチターゲット**（モバイル）: WCAG 2.5.5 / Apple HIG に従い主要操作（ボタン/アイコンボタン/入力/ナビ）の
   **min は 44px** 以上、推奨 48px。44 未満が避けられない **チップ（min 32px）は hitSlop**（不可視の拡張タップ領域）で
   実効 44px を確保する。値の正本は `tokens.json` の `touchTargets`。

package/NATIVE_RECIPES.md

@@ -1,6 +1,14 @@
 # KSK Design System Native Recipes
 
-Native / Expo consumer は、新規 UI を作る前に `ksk-design-system/native/ui` の既存コンポーネントを確認してください。ローカル `ds/` に独自 wrapper を増やす前に、このファイルの recipe を使います。
+Native / Expo consumer は、新規 UI を作る前に `ksk-design-system/native/ui` の既存コンポーネントを確認してください。ローカル `ds/` に独自 wrapper を増やす前に、`src/native/COMPONENT_LOOKUP.md` とこのファイルの recipe を使います。
+
+## Component lookup
+
+RN 側の公開 export 一覧は `src/native/COMPONENT_LOOKUP.md` で確認できます。Web 側の `src/components/COMPONENT_LOOKUP.md` と同じく、consumer 実装前の DS-first チェックに使います。
+
+```tsx
+import { Button, Screen, PhotoHero } from "ksk-design-system/native/ui"
+```
 
 ## Expo Router / React Navigation bottom tabs
 
@@ -102,6 +110,43 @@ import {
 
 Web/PWA consumer は `ksk-design-system` の `MobileAppShell` と `BottomTabBar variant="pill"` / `MobileFloatingActionButton` を組み合わせます。`bottomNavMode="fixed"` では shell が fixed wrapper と safe-area padding を持ちます。既に fixed な nav を渡す場合は `bottomNavMode="external"` を指定します。
 
+## Fullscreen screen / photo onboarding
+
+`Screen` は header / internal scroll body / footer CTA の骨組みです。写真背景のオンボーディングや入口画面は `PhotoHero` の compound slots を使います。consumer 側で safe-area footer や写真上 typography を再実装しません。
+
+```tsx
+import { Button, PhotoHero, Screen } from "ksk-design-system/native/ui"
+
+<Screen scroll={false} padding="none">
+  <PhotoHero src={{ uri: heroUrl }} overlay="dark" align="bottom">
+    <PhotoHero.Eyebrow>WELCOME</PhotoHero.Eyebrow>
+    <PhotoHero.Title>今日の準備を始める</PhotoHero.Title>
+    <PhotoHero.Body>写真の上でも読める DS typography と overlay をまとめて扱います。</PhotoHero.Body>
+    <PhotoHero.Actions>
+      <Button variant="glass" onPress={start}>始める</Button>
+    </PhotoHero.Actions>
+  </PhotoHero>
+</Screen>
+```
+
+## Media action cluster
+
+動画・写真上の Like / Share / Save などの操作群は `MediaActionCluster` を使います。`position="fixed"` は RN では absolute と同等に扱い、`href` は `Linking.openURL` に委譲します。
+
+```tsx
+<View style={{ flex: 1 }}>
+  <PhotoHero src={{ uri: mediaUrl }} overlay="medium">
+    <MediaActionCluster
+      anchor="bottom-right"
+      items={[
+        { label: "いいね", icon: <HeartIcon />, active: liked, onPress: toggleLike },
+        { label: "シェア", icon: <ShareIcon />, onPress: share },
+      ]}
+    />
+  </PhotoHero>
+</View>
+```
+
 ## Settings screens
 
 設定画面は `SettingsSection` と `SettingsListRow` を使います。`Card + SectionHeader + ListItem` のローカル wrapper を consumer 側で複製しないでください。

package/README.md

@@ -14,7 +14,7 @@
 - **アクセシブル** — shadcn/ui（Radix UI ベース）+ `@storybook/addon-a11y` で a11y を担保
 - **Tailwind CSS v4 ネイティブ** — `@theme` ベースのトークン設計
 - **型安全** — React 19 + TypeScript、CVA によるバリアント管理
-- **125 + 96 コンポーネント** — Web 125（UI 57 / EC 11 / 管理 8 / シェル 3 / パターン 46）+ React Native 96
+- **125 Web コンポーネント + 126 React Native exports** — Web 125（UI 57 / EC 11 / 管理 8 / シェル 3 / パターン 46）+ RN `native/ui` 公開 export 126
 - **iOS 26 Liquid Glass 対応** — RN 側 `GlassView` + `Button variant="glass"`、Web 側 `.glass` CSS マテリアル
 
 ## 🎨 テーマ
@@ -131,7 +131,7 @@ import { BottomTabBar } from "ksk-design-system"
 
 ### React Native / Expo
 
-`ksk-design-system/native/ui` から直接 RN 用コンポーネント（91 個）を import できます。iOS 26 の **Liquid Glass** にも対応:
+`ksk-design-system/native/ui` から直接 RN 用コンポーネント export（126 個）を import できます。iOS 26 の **Liquid Glass** にも対応:
 
 ```tsx
 import { ThemeProvider, Button, Card, GlassView } from "ksk-design-system/native/ui"
@@ -144,7 +144,7 @@ npx expo install expo-glass-effect expo-blur
 
 Web は backdrop-filter で擬似、Android は半透明 surface でフォールバックします。
 
-Expo Router / React Navigation の tab bar、native `GlassView`、Button loading、settings/attachment/mobile shell recipes は `NATIVE_RECIPES.md` を参照してください。
+既存コンポーネントの確認は `src/native/COMPONENT_LOOKUP.md`、Expo Router / React Navigation の tab bar、native `GlassView`、Button loading、fullscreen/media/settings/attachment/mobile shell recipes は `NATIVE_RECIPES.md` を参照してください。
 
 ## 🧪 試してみる（1コマンドお試し）
 

package/contracts/components.json

@@ -4,19 +4,19 @@
     "version": "1.34.0",
     "description": "全コンポーネントの構造化定義。バリアント・アクセシビリティ要件・使用ルールを機械可読形式で管理。",
     "counts": {
-      "ui": 57,
-      "patterns": 46,
-      "commerce": 11,
+      "ui": 58,
+      "patterns": 51,
+      "commerce": 12,
       "admin": 8,
       "shells": 3,
-      "total": 125
+      "total": 132
     }
   },
   "ui": [
     {
       "name": "Button",
       "path": "src/components/ui/button.tsx",
-      "description": "アクションボタン。最重要CTAにはdefault、Liquid Glass背景にはglass、暗背景上のLiquid Glassにはglass-inverse。アイコン単独はiconサイズ群。",
+      "description": "アクションボタン。最重要CTAにはdefault、Liquid Glass背景にはglass、暗背景上のLiquid Glassにはglass-inverse、ブランドカラーをティントしたglassはglass-accent（FAB等）。アイコン単独はiconサイズ群。",
       "variants": [
         "default",
         "secondary",
@@ -27,6 +27,7 @@
         "destructive",
         "glass",
         "glass-inverse",
+        "glass-accent",
         "accent",
         "inverse",
         "ghost-inverse"
@@ -42,6 +43,7 @@
         "icon-sm",
         "icon-lg",
         "icon-xl",
+        "icon-fab",
         "match"
       ],
       "accessibility": [
@@ -97,6 +99,20 @@
         "Use DateRangePicker for date range selection"
       ]
     },
+    {
+      "name": "DateField",
+      "path": "src/components/ui/date-field.tsx",
+      "description": "DatePicker を \"YYYY-MM-DD\" ISO 文字列 API でラップする adapter。バックエンド/store が ISO date 文字列で日付を保持する場合に使う。value=\"\" が未選択を表す。",
+      "variants": [],
+      "accessibility": [
+        "Must pair with <Label>",
+        "aria-expanded on trigger button（内部 DatePicker 由来）"
+      ],
+      "rules": [
+        "value/onChange は常に \"YYYY-MM-DD\" 文字列。Date オブジェクトを直接渡さない",
+        "strToDate/dateToStr は new Date(y, m-1, d) のローカルタイム方式（TZ ずれ回避）"
+      ]
+    },
     {
       "name": "Textarea",
       "path": "src/components/ui/textarea.tsx",
@@ -317,9 +333,16 @@
     {
       "name": "Progress",
       "path": "src/components/ui/progress.tsx",
-      "description": "進捗バー。color variant (default/success/warning/caution) + transition duration (none/sm/md/lg) 拡張済。",
+      "description": "進捗バー。color variant (default/success/warning/caution) + transition duration (none/sm/md/lg) + autoColor 閾値切替に対応。",
+      "features": [
+        "color-variants",
+        "transition-duration",
+        "auto-color-thresholds"
+      ],
       "rules": [
-        "値超過で variant を切替: 100% 超なら caution",
+        "値に応じた色切替は autoColor を使い、consumer 側で個別に if 文と className を重ねない",
+        "autoColor=true の既定閾値は 80% 以上 warning、100% 以上 caution",
+        "しきい値がアプリごとに違う場合は autoColor={{ successBelow, warningFrom, warningBelow, cautionFrom }} を使う",
         "達成カード等は transitionDuration=\"lg\" で緩やかに"
       ]
     },
@@ -1049,7 +1072,7 @@
     {
       "name": "Celebration",
       "path": "src/components/patterns/celebration.tsx",
-      "description": "マイルストーン達成・大目標達成などの祝い演出。confetti / emoji 表示、actions slot、interactive card tap、cardless モード、tap dismiss、prefers-reduced-motion 対応。",
+      "description": "マイルストーン達成・大目標達成などの祝い演出。confetti / emoji 表示、actions slot、interactive card tap、cardless モード、tap dismiss、prefers-reduced-motion 対応。confetti の duration / colors / driftRange をカスタマイズ可能。effect で confetti の演出モード（fall / burst）を切り替え可能（Issue #111）。",
       "variants": [
         "confetti",
         "emoji",
@@ -1061,18 +1084,25 @@
         "interactive",
         "cardless",
         "tap-dismiss",
-        "duration-control"
+        "duration-control",
+        "custom-duration",
+        "custom-colors",
+        "custom-drift-range",
+        "emoji-animation-pop-or-bounce",
+        "effect-fall-or-burst",
+        "confetti-burst-radial-360"
       ],
       "accessibility": [
         "role=status",
         "aria-live=polite",
-        "prefers-reduced-motion で confetti を抑制"
+        "prefers-reduced-motion で confetti を抑制（emojiAnimation=bounce も含む。effect=burst も同様にスキップ）"
       ],
       "rules": [
         "一時的な達成演出に使用",
         "ローディングや常時表示の装飾用途には使わない",
         "CTA を含む達成 UI は actions slot を使い、カード tap で任意 dismiss したい場合は interactive または onTapDismiss を使う",
-        "カード不要の演出は cardless を使う"
+        "カード不要の演出は cardless を使う",
+        "effect は既定 \"fall\"（後方互換）。クラッカーが弾けた感じにしたい達成演出は effect=\"burst\" を使う（中央から全方位 360° に放射）"
       ]
     },
     {
@@ -1184,6 +1214,81 @@
         "Do not patch selected flicker in consumer CSS; Chip handles Android tap highlight and touch transition behavior."
       ]
     },
+    {
+      "name": "CollapsibleChipField",
+      "path": "src/components/patterns/collapsible-chip-field.tsx",
+      "description": "折りたたみ式の単一選択チップフィールド。未選択時は全選択肢を展開表示し、選択後は選択中の1チップのみに折りたたむ。再タップで解除（onClear）または再選択用に再展開する。belle-todo 移植（Issue #106）。ChipSelector（複数選択）とは別 API・別用途。",
+      "features": [
+        "single-select",
+        "collapse-on-select",
+        "always-expanded-mode",
+        "leading-icon-or-label"
+      ],
+      "rules": [
+        "ChipSelector（chip-selector.tsx）とは別コンポーネント。混同して置き換えない。",
+        "onClear 未指定時、選択済み chip の再タップは解除でなく再選択用の再展開のみ（required field 対応）。",
+        "label 指定時は幅 w-20 固定でフィールドリストの他行とラベル幅を揃える。"
+      ]
+    },
+    {
+      "name": "ChipFilterBar",
+      "path": "src/components/patterns/chip-filter-bar.tsx",
+      "description": "Chip を横スクロール表示するフィルターバーパターン。sticky モード・結果件数表示・bare（ラッパーなし）モードを持つ。belle-todo 移植（Issue #104）。",
+      "features": [
+        "horizontal-scroll",
+        "sticky-mode",
+        "result-count",
+        "bare-mode"
+      ],
+      "rules": [
+        "commerce/FilterBar（filters/sortOptions 統合型）とは別コンポーネント。children に任意の Chip 群を渡すシンプルなラッパー。",
+        "sticky 時の top オフセットは stickyOffset prop で指定する（固定ヘッダー高さの相殺用）。",
+        "resultCountLabel 未指定時は \"{n}件\" を表示。i18n が必要な場合は関数 props で差し替える。",
+        "bare=true 時は overflow/padding ラッパーを付けない。外側スクロールコンテナと共有する場合に使う。"
+      ]
+    },
+    {
+      "name": "CelebrationDialog",
+      "path": "src/components/patterns/celebration-dialog.tsx",
+      "description": "達成演出用の Dialog + Celebration confetti + emoji/title/description/actions スロット合成パターン。belle-todo の MilestoneCelebration を参考に、MILESTONES 定義・アップセル CTA・store・i18n・analytics は持ち込まずスロット化（Issue #110）。confetti の既定 effect は \"burst\"（クラッカー演出）（Issue #111）。",
+      "features": [
+        "dialog-based",
+        "confetti-overlay",
+        "emoji-slot",
+        "actions-slot",
+        "auto-dismiss",
+        "emoji-animation-pop-or-bounce",
+        "confetti-props-passthrough",
+        "effect-burst-default"
+      ],
+      "accessibility": [
+        "DS Dialog（Radix）ベースのため Esc / overlay クリックで閉じる",
+        "prefers-reduced-motion で confetti・emoji bounce を抑制"
+      ],
+      "rules": [
+        "MILESTONES 定義・アップセル文言・分析トラッキングは呼び出し側で actions スロットに組み込む。コンポーネント内部に業務ロジックを持たせない。",
+        "autoDismissMs 指定時は経過後に onOpenChange(false) を呼ぶだけで、closeロジック自体は呼び出し側に委譲する。",
+        "effect 既定は \"burst\"（達成演出はクラッカーが標準）。fall に戻したい場合は effect=\"fall\" を明示する。",
+        "confetti 系 props（particleCount/duration/colors/driftRange）は Celebration へそのままパススルー。"
+      ]
+    },
+    {
+      "name": "CountdownHero",
+      "path": "src/components/patterns/countdown-hero.tsx",
+      "description": "装飾的な serif 数字で目標日までの残日数を表示するヒーロー表示。belle-todo の CountdownSection を参考に、日付編集フォーム・wedding イラスト・i18n・store は持ち込まず表示専用に再設計（Issue #110）。",
+      "features": [
+        "large-serif-number",
+        "today-past-active-states",
+        "illustration-slot",
+        "iso-string-or-date-target"
+      ],
+      "rules": [
+        "既存の CountdownTimer（残日数ピル表示）とは別コンポーネント。装飾ヒーロー表示専用で置き換えない。",
+        "日付編集フォームは持ち込まない。表示専用コンポーネント。",
+        "illustration スロットに wedding 画像等のドメイン固有アセットを直接埋め込まない。呼び出し側が用意する。",
+        "serif フォントは --font-display-serif トークン未定義環境向けに Georgia / Noto Serif JP / serif へフォールバックする。"
+      ]
+    },
     {
       "name": "StickyActionBar",
       "path": "src/components/patterns/sticky-action-bar.tsx",
@@ -1265,7 +1370,8 @@
         "safe-area anchor",
         "idle auto-hide",
         "glass buttons",
-        "text-on-media"
+        "text-on-media",
+        "React Native port"
       ],
       "accessibility": [
         "role=group",
@@ -1277,7 +1383,8 @@
         "メディア上の操作群に使用する。通常画面の下部 CTA には StickyActionBar を使う",
         "items[].label は必須。アイコン単独にしない",
         "暗い写真・動画・濃色面上では glass-inverse / text-on-media を維持する",
-        "autoHideMs=null で idle fade を無効化できる"
+        "autoHideMs=null で idle fade を無効化できる",
+        "React Native consumer は ksk-design-system/native/ui の MediaActionCluster を使い、ローカル overlay action を再実装しない"
       ]
     },
     {
@@ -1290,7 +1397,8 @@
         "min-h-0 guard",
         "fixed header slot",
         "fixed footer slot",
-        "safe-area bottom"
+        "safe-area bottom",
+        "React Native port"
       ],
       "accessibility": [
         "main landmark",
@@ -1300,7 +1408,8 @@
         "body スクロールを使わないアプリのフルスクリーン画面に使う",
         "本文が長い画面では scroll=true のまま使う",
         "写真ヒーローなど 1 画面固定では scroll=false と padding=none を組み合わせる",
-        "footer には主要 CTA を置き、safe-area 余白を消費側で再実装しない"
+        "footer には主要 CTA を置き、safe-area 余白を消費側で再実装しない",
+        "React Native consumer は ksk-design-system/native/ui の Screen を使い、header/body/footer shell をローカル再実装しない"
       ]
     },
     {
@@ -1312,7 +1421,8 @@
         "medium / dark overlay",
         "bottom / center align",
         "on-image typography",
-        "compound slots"
+        "compound slots",
+        "React Native port"
       ],
       "subcomponents": [
         "PhotoHero.Eyebrow",
@@ -1326,8 +1436,9 @@
       ],
       "rules": [
         "オンボーディング入口・写真スライド・メディア上 CTA に使う",
-        "写真上の CTA には Button variant=glass-inverse / ghost-inverse を使う",
-        "本文が長い場合は Screen scroll=true 側で内部スクロールを確保する"
+        "写真上の CTA には Web では Button variant=glass-inverse / ghost-inverse、React Native では Button variant=glass を使う",
+        "本文が長い場合は Screen scroll=true 側で内部スクロールを確保する",
+        "React Native consumer は ksk-design-system/native/ui の PhotoHero compound slots を使い、写真上 typography をローカル再実装しない"
       ]
     },
     {
@@ -1426,7 +1537,8 @@
       "rules": [
         "loadingLabel prop で i18n",
         "ListSkeleton: rowHeight で 1 行高",
-        "GridSkeleton: columns 1-4 + cardHeight で調整"
+        "GridSkeleton: columns 1-4 + cardHeight で調整",
+        "React Native consumer は ksk-design-system/native/ui の ListSkeleton / GridSkeleton alias を使う"
       ]
     },
     {
@@ -1443,6 +1555,21 @@
         "isActive 切替時に key を変えて Chip を強制再マウント (selected キャッシュ残り防止)"
       ]
     },
+    {
+      "name": "PresenceIndicator",
+      "path": "src/components/patterns/presence-indicator.tsx",
+      "description": "「誰か（何か）が今いる/見ている」ことを示す汎用インジケーター。Avatar（イニシャル）+ 右下ステータスドット + statusText + Badge（badgeLabel 指定時）。realtime 取得ロジックや i18n は持ち込まず表示専用。",
+      "variants": [],
+      "sizes": [],
+      "accessibility": [
+        "role=\"status\" + aria-label で name/statusText を読み上げ",
+        "ステータスドットは aria-hidden（色だけに依存させない）"
+      ],
+      "rules": [
+        "online=false は中立色（--Object-Low-Emphasis）、online=true（既定）は --Object-Success",
+        "レスポンシブ非表示は呼び出し側の責務（className でユーティリティを渡す）"
+      ]
+    },
     {
       "name": "BottomSheetFrame",
       "path": "src/components/patterns/bottom-sheet-frame.tsx",
@@ -1655,7 +1782,7 @@
     {
       "name": "BottomTabBar",
       "path": "src/components/patterns/commerce/bottom-tab-bar.tsx",
-      "description": "SP 下部固定タブナビゲーション。default と pill（iOS 26 Liquid Glass）バリアント。pill は centerAction・ラベル表示・inverse tone・mobile shell max-width に対応。",
+      "description": "SP 下部固定タブナビゲーション。default と pill（iOS 26 Liquid Glass）バリアント。pill は centerAction・ラベル表示・inverse tone・mobile shell max-width・floatingPosition（left/center/right）に対応。",
       "features": [
         "badge",
         "centerAction",
@@ -1665,6 +1792,7 @@
         "fixed-or-absolute",
         "maxWidth",
         "inverse-tone",
+        "floatingPosition",
         "native Expo Router tabBar adapter",
         "native hidden routes"
       ],
@@ -1677,9 +1805,27 @@
         "Use tone='inverse' over dark photo/video/gradient backgrounds.",
         "Use pillPosition='absolute' only inside controlled shells or Storybook demos; fixed is the app default.",
         "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."
       ]
     },
+    {
+      "name": "MobileTabBar",
+      "path": "src/components/patterns/commerce/mobile-tab-bar.tsx",
+      "description": "BottomTabBar の consumer-friendly ラッパー。tabs/activeTab/onSelect のジェネリック API から iconsax Linear/Bulk アイコンの自動切替・pill navigation・addAction 中央 CTA を組み立てる。belle-todo の MobileTabBar を移植。",
+      "features": [
+        "generic tab key",
+        "iconsax Linear/Bulk auto-switch",
+        "addAction center CTA",
+        "pointer capture blur",
+        "floatingPosition passthrough"
+      ],
+      "rules": [
+        "tabs は BottomTabBarItem を手組みせず MobileTabItem<T>[]（key/label/Icon）で渡す",
+        "addAction 指定時はブランド色丸背景 + Add アイコンが自動で centerAction になる",
+        "floatingPosition='left'|'right' を使う場合は FAB を反対側に併置する"
+      ]
+    },
     {
       "name": "FilterBar",
       "path": "src/components/patterns/commerce/filter-bar.tsx",
@@ -1728,18 +1874,30 @@
         "edit-trigger",
         "rich-column-helpers",
         "date-column",
+        "date-cell",
         "chip-column",
         "select-column",
+        "select-popper-position",
         "sort",
         "checkbox",
         "actions",
+        "row-click",
+        "full-cell-hit-area",
         "inline-edit",
+        "flexible-column-width",
         "drag",
-        "section-row"
+        "section-row",
+        "section-sticky-left",
+        "section-heading-emphasis"
       ],
       "rules": [
         "rows/columns API は最短実装向け",
         "DateField / Chip cluster / typed Select などのリッチ列は cell と edit.trigger、または createDataTableDateColumn / createDataTableChipColumn / createDataTableSelectColumn を使う",
+        "行全体をクリック可能にする場合は DataTable の onRowClick または DataTableRow の onRowClick を使い、独自の tr/td クリック実装を作らない",
+        "Select セルは DataTableSelectCell または createDataTableSelectColumn を使い、ポップオーバー位置は contentPosition で調整する",
+        "日付編集セルは DataTableDateCell または createDataTableDateColumn を使う",
+        "残り幅を受け持つ列は width=\"flex\" を使い、手書き className の w-full/min-w 再実装を避ける",
+        "セクション見出しを横スクロール中も左に残す場合は DataTableSectionRow stickyLeft / headingSize を使う",
         "複雑なテーブル全体構成は DataTableHead, DataTableRow, DataTableCell などのサブコンポーネントを使う"
       ]
     },