ksk-design-system 1.49.2 → 1.51.0

package/NATIVE_RECIPES.md

@@ -117,6 +117,19 @@ import {
 
 Web/PWA consumer は `ksk-design-system` の `MobileAppShell` と `BottomTabBar variant="pill"` / `MobileFloatingActionButton` を組み合わせます。`bottomNavMode="fixed"` では shell が fixed wrapper と safe-area padding を持ちます。既に fixed な nav を渡す場合は `bottomNavMode="external"` を指定します。
 
+### Liquid Glass の FAB
+
+写真・地図・リストの上に FAB を浮かせるときは `variant="glass"` を使います。`GlassView` にブランド色をほぼ不透明（light 95%）で敷いた Liquid Glass で、web の `Button variant="glass-accent"` と同じ質感です。塗り・縁・上辺ハイライトの色は `src/native/glass-accent-fill.ts` の純関数がテーマの `brand.primary` から導出するので、テーマを差し替えれば自動で追従します。
+
+```tsx
+<MobileFloatingActionButton label="追加" variant="glass" onPress={openCreate} />
+```
+
+- 既定は `variant="default"`（ブランド色のソリッド塗り）。既存画面の見た目は変わりません。
+- 塗りを薄くしないでください。低透明度ティントにすると明るい背景で白前景（`text.on-inverse`）が読めなくなります。
+- `glass` に外側の `shadow` を重ねないでください。glass 側が縁・ハイライトを内包しており、影が二重になります。
+- 実際のぼかしは `GlassView` の 4-tier（iOS 26 Liquid Glass → expo-blur → RN Web の backdrop-filter → 半透明 surface）に従います。Android / optional peer 未導入でも塗りは成立します。
+
 ## Fullscreen screen / photo onboarding
 
 `Screen` は header / internal scroll body / footer CTA の骨組みです。写真背景のオンボーディングや入口画面は `PhotoHero` の compound slots を使います。consumer 側で safe-area footer や写真上 typography を再実装しません。
@@ -237,3 +250,130 @@ const POLICY_SECTIONS = [
   <Prose sections={POLICY_SECTIONS} />
 </DocumentScreen>
 ```
+
+## Tappable icon buttons
+
+押せる円形/角丸アイコンは `IconButton` を使います。`IconBadge` は装飾専用（非タップ）なので、ヘッダの設定ギア・カード右上の閉じる・一覧行のアクションを `Button` + `containerStyle` で自作しないでください。Web 側の相当物は `<Button size="icon">` です。
+
+`accessibilityLabel` は必須（型で強制）。視覚サイズが 44pt 未満の `size="sm"` でも、実タップ領域は `hitSlop` で 44pt 以上が確保されます。`icon` に関数を渡すと variant/tone/size から解決済みの色とサイズを受け取れるため、consumer 側で色をハードコードしません。
+
+```tsx
+import { IconButton } from "ksk-design-system/native/ui"
+
+// ヘッダの設定ギア（薄いサーフェス背景）
+<IconButton
+  accessibilityLabel="設定"
+  variant="tertiary"
+  size="sm"
+  icon={({ color, size }) => <SettingIcon color={color} size={size} />}
+  onPress={() => navigation.navigate("Settings")}
+/>
+
+// カード右上の閉じる（地の上、背景なし）
+<IconButton
+  accessibilityLabel={`${offer.title}の提案を閉じる`}
+  variant="ghost"
+  icon={({ color, size }) => <CloseIcon color={color} size={size} />}
+  onPress={dismiss}
+/>
+```
+
+`variant` は `ghost`（既定・背景なし）/ `tertiary`（薄いサーフェス背景）/ `outline`（境界線）/ `primary`（ブランド色の塗り）で、名前は `Button` の variant 語彙に揃えています。`tone` は `neutral` / `accent` / `caution`（`primary` では無視）、`shape` は `circle`（既定）/ `square` です。
+
+## Controlled disclosure (Collapsible / Accordion)
+
+`Collapsible` と `Accordion` は制御・非制御の両対応です。外部 state（他セクションとの排他、解答表示との連動、アナリティクス送信）と同期したいときは `open` / `openKeys` を渡します。渡している間は内部 state を無視するため、二重管理になりません。
+
+トグル右端の `trailing` スロットは開閉状態を受け取る関数も渡せるので、「表示する / 閉じる」のラベル切り替えを consumer 側で自作しなくて済みます。
+
+```tsx
+import { Accordion, Collapsible } from "ksk-design-system/native/ui"
+
+const [open, setOpen] = useState(false)
+
+<Collapsible
+  title="他の選択肢はなぜ違う？"
+  open={open}
+  onOpenChange={setOpen}
+  trailing={(isOpen) => (isOpen ? "閉じる" : "表示する")}
+>
+  <Text variant="body.md">{otherWrongChoices.map((c) => c.whyWrong).join("\n")}</Text>
+</Collapsible>
+
+<Accordion
+  type="multiple"
+  openKeys={openSections}
+  onOpenChange={setOpenSections}
+  items={[
+    { key: "field", title: "分野別の正答率", content: <Text variant="body.md">分野別の内訳</Text>, trailing: (o) => (o ? "閉じる" : "表示する") },
+  ]}
+/>
+```
+
+`defaultOpen` / `defaultOpenKeys` だけを渡した場合は従来どおり非制御で動きます。
+
+## Composed accessibility labels
+
+`ListItem` / `ActionTile` / `EmptyState` / `ErrorState` は `AccessibilityProps` を継承しているため、`accessibilityLabel` / `accessibilityHint` をそのまま渡せます。「タイトル＋状態」を合成した読み上げラベル（例: 「模試2（要解放）」）を付けたいときに使います。
+
+```tsx
+<ListItem
+  title="模試2"
+  description="未受験"
+  accessibilityLabel="模試2（要解放）"
+  accessibilityHint="タップで解放画面へ移動します"
+  onPress={openPaywall}
+/>
+```
+
+`EmptyState` / `ErrorState` では、ラベル指定時に icon / title / description だけが1要素にまとまり、`action` のボタンは個別にフォーカスできる位置に残ります。
+
+## Japanese calendars
+
+`Calendar` は日本のカレンダー慣習に必要な表現を prop で持ちます。曜日の色分け（日=赤 / 土=青）は既存の見た目を変えないよう opt-in（`weekendTone`）です。
+
+```tsx
+import { Calendar } from "ksk-design-system/native/ui"
+
+<Calendar
+  value={examDate}
+  onChange={setExamDate}
+  weekendTone           // 日=赤 / 土=青
+  todayEmphasis="dot"   // "ring"（既定）| "dot" | "none"
+  disablePast           // 今日より前を選択不可（minDate と併用時は遅い方が効く）
+  dayAccessibilityLabel={(day) =>
+    `${day.date.getFullYear()}年${day.date.getMonth() + 1}月${day.date.getDate()}日を受験日に設定`
+  }
+/>
+```
+
+セルの見た目を丸ごと差し替えたい場合は `renderDay` を使います。`renderDay` は `{ date, weekday, selected, today, disabled, tone }` を受け取ります（タップ・読み上げ・選択不可制御は DS 側が持ったままです）。月移動ボタンは `minDate` / `maxDate` / `disablePast` の範囲外へは自動で disabled になります。
+
+### ブランド色を注入する（ThemeProvider を使わない consumer 向け）
+
+`ThemeProvider` を使わず、アプリごとのブランドトークンを props で流し込む設計（exam-kit 系が app/theme/brand.ts から各コンポーネントへ色を渡している方式）では、`colors` で日セルの色だけを差し替えられます。指定しなかったキーは DS theme の既定色に落ちるので、既存の呼び出しは見た目が変わりません。
+
+```tsx
+<Calendar
+  value={examDate}
+  onChange={setExamDate}
+  weekendTone
+  colors={{
+    selected: brand.primary,        // 選択セルの背景
+    selectedText: brand.onPrimary,  // 選択セルの文字
+    today: brand.accent,            // today リング / ドット
+    sunday: brand.caution,          // weekendTone=true のときだけ効く
+    saturday: brand.primary,
+  }}
+/>
+```
+
+`colors` で足りない見た目（角丸・枠線の太さ・影など）は `dayStyle` で器ごと差し替えます。DS の既定 style の**後ろに**合成されるので確実に勝ちます。
+
+```tsx
+<Calendar
+  dayStyle={(day) => (day.selected ? { borderRadius: 8, borderWidth: 2, borderColor: brand.primary } : null)}
+/>
+```
+
+`renderDay` がセルの「中身」、`dayStyle` がセルの「器」です。色だけなら `colors` で足ります。

package/contracts/components.json

@@ -1,7 +1,7 @@
 {
   "meta": {
     "name": "KSK Design System — Component Contracts",
-    "version": "1.49.2",
+    "version": "1.51.0",
     "description": "全コンポーネントの構造化定義。バリアント・アクセシビリティ要件・使用ルールを機械可読形式で管理。",
     "counts": {
       "ui": 67,
@@ -1445,8 +1445,9 @@
     {
       "name": "MobileFloatingActionButton",
       "path": "src/components/patterns/mobile-floating-action-button.tsx",
-      "description": "モバイル固定 FAB。BottomTabBar と safe-area を考慮した bottom offset、start/end/center placement、keyboard hide/lift/stay を内包する。",
+      "description": "モバイル固定 FAB。BottomTabBar と safe-area を考慮した bottom offset、start/end/center placement、keyboard hide/lift/stay を内包する。variant=glass で Brand ティントの Liquid Glass 表現になる。",
       "variants": [
+        "variant: default / glass",
         "placement: start / end / center",
         "bottomOffset: none / bottom-nav / bottom-nav-pill / bottom-nav-pill-inline",
         "keyboardBehavior: hide / lift / stay"
@@ -1456,9 +1457,11 @@
       ],
       "rules": [
         "画面側で fixed bottom/right と Button size=icon-lg を手組みしない",
+        "glass-fab 等の独自クラス + 生 button で Liquid Glass FAB を手組みせず variant=glass を使う",
         "BottomTabBar 併用時は bottomOffset=bottom-nav を使う",
         "pill BottomTabBar の上に重ねる場合は bottomOffset=bottom-nav-pill、横並びに置く場合は bottomOffset=bottom-nav-pill-inline を使う",
-        "keyboard 表示中に入力を邪魔する場合は keyboardBehavior=hide を使う"
+        "keyboard 表示中に入力を邪魔する場合は keyboardBehavior=hide を使う",
+        "variant=glass に shadow-* を重ねない（glass-accent が inset 3層 + drop shadow を内包するため二重になる）"
       ]
     },
     {

package/contracts/token-hex-cache.json

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