@cakejp/design-system 0.17.0 → 0.19.0

package/CHANGELOG.md

@@ -9,6 +9,65 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.19.0] - 2026-08-20
+
+記事メディア系 consumer（cakejp-biz-mag）と仕入れサイト（cake-distributor）から上がっていた不具合・不足を一括で解消する回。**公開 API の破壊的変更はなし**（追加した prop はすべて既定値が従来の挙動）。ただし次の 4 点は既定の挙動・見た目が変わる。
+
+- `Sheet` を素で使っている画面は、開閉時にフォーカスが自動で移動するようになる（アクセシビリティの修正）
+- 利用側の `lg:` が Tailwind 既定の 1024px ではなく DS の 960px で切り替わるようになる
+- `SubNav` の PC 表示で左右の余白が 16px → 24px になる
+- `Header variant="back-search"` の戻るボタンが 32px → 44px になる
+
+> **0.18.0 は npm に公開されていません**（バージョン確定まで済んでいたが publish が走っていなかった）。npm 上の直前の版は 0.17.1 なので、0.17.x から上げると **0.18.0 の変更も同時に入ります**。0.18.0 の内容は下のセクションを参照してください。
+
+### ✨ Added
+
+- **`Prose` を追加**（primitives）: CMS（microCMS 等）のリッチテキスト HTML に、トークンで揃えた体裁を当てる部品。見出し（h2〜h5）・段落・リスト・引用・リンク・画像・図版キャプション・表・コード・区切り線の余白とサイズと線を 1 箇所に集約し、記事メディアごとに CSS Modules を書き分けて見た目がばらつくのを防ぐ。`html`（**利用側でサニタイズ済み**の HTML）か `children` のどちらでも使える。`as` で `article` / `section` に変えられる。幅は持たないので `Container size="narrow"` と組み合わせる。幅の広い表は表自身が縮む・横スクロールするのでページは横に伸びない（[#239](https://github.com/flashpark/cake-design-system/issues/239)）
+- **`ContentCard` / `ContentList` を追加**（primitives）: 記事・特集・お知らせなど「画像 + タイトル + メタ」のカード。`ProductCard`（商品）/ `ShopCard`（店舗）の兄弟で、記事メディア向け。汎用の `Card` に載せて組むと枠線・タイトル行数・カード高さが揃わない（実測で高さ 268 と 312 に割れる事例）ため部品化した。タイトルは 2 行で省略し**常に 2 行ぶんの高さ**を取るので、タイトルの長短が混ざっても一覧で下端が揃う。`orientation="vertical" | "horizontal" | "list"`、`aspect="16/10" | "16/9" | "1/1"`、画像は `imageSlot`（`next/image` / CMS / 図版を吸収）、`linkComponent` 対応。`ContentList` は区切り線つきの Medium 型リスト（[#241](https://github.com/flashpark/cake-design-system/issues/241)）
+- **`ShareButtons` に `services` を追加**（共有先の選択と並び替え）: 組み込みは `line` / `x` / `facebook` / `hatena`（はてなブックマーク）/ `copy`。既定は従来どおり `["line", "x", "copy"]`。組み込みに無い共有先は `{ key, label, href, icon }` を混ぜて足せる（`href` の `{url}` / `{text}` が URL エンコード済みの値に置換される）。事業者向けメディアで Facebook・はてなブックマークを出すために利用側が `Button asChild` で同意匠を組み直す必要がなくなる（[#238](https://github.com/flashpark/cake-design-system/issues/238)）
+- **`SocialIcon` に `platform="hatena"` を追加**: はてなブックマークの「B!」マーク。あわせて `--Third-Party-Hatena`（#00A4DE）を配布トークンに追加した
+- **`SearchBar` に `action` を追加**（`<form method="get">` モード）: 指定すると素のフォーム送信で遷移するため、**JavaScript 無効の環境やクローラでも検索が成立する**。従来は送信時に `window.location` を書き換える実装しか無く、SEO を重視する記事メディアでは採用できず `Input` + `Button` で `<form>` を手組みすることになっていた。クエリのキーは `name`（既定 `"q"`）。`role="search"` も付く。未指定なら従来どおり（[#237](https://github.com/flashpark/cake-design-system/issues/237)）
+- **`Header` / `SubNav` に `containerSize` を追加**（`page` / `wide` / `fluid`。`Container` と同じ段）: 指定すると**背景・border・sticky は全幅のまま、中身だけ**を中央寄せする。本文を `Container size="page"` で組んでいるサイトで、ロゴ・ナビの左端が本文と揃う（1440px 幅での実測: 指定前 ロゴ 24 / サブナビ 16 / 本文 104 → 指定後すべて **104**）。従来は利用側が `className="mx-auto max-w-[1280px]"` を当てると背景と線まで中央幅になって両脇が抜けるため、sticky と装飾をラッパーに持ち直す必要があった。未指定時は DOM 構造も従来どおり（内側ラッパーを足さない）（[#234](https://github.com/flashpark/cake-design-system/issues/234)）
+- **`TabsList` に `size="sm"` を追加**: セグメント（ピル型）タブの 1 項目あたりの最小幅（100px）を外し、左右の padding を詰める。既定の `size="md"` は従来どおり。サイドバー幅 266px に 3 択のセグメントを置くと右にはみ出していた（実測 `scrollWidth 308 > clientWidth 266`）のが収まる（[#235](https://github.com/flashpark/cake-design-system/issues/235)）
+- **`Button` に `size="icon-xl"` を追加**（44px / `size-11`）: `size="default"` と同じ高さなので、入力行（`Input` / `SearchBar` / `SelectTrigger`）の横にアイコンボタンを並置しても揃う。既存の icon サイズ（24 / 32 / 36 / 40px）はどれも 44px の入力コントロールと揃わず、`tokens.json` の `touchTarget["text-input"].min` = 44px も満たしていなかった
+
+### 🐛 Fixed
+
+- **`Header variant="back-search"` の戻るボタンと `centerSlot` の高さが揃っていなかった問題を修正**: 戻るボタンが `size="icon-sm"`（32px）固定で、DS が推奨する組み合わせ（`centerSlot={<SearchBar />}` = 44px）と **12px ずれていた**。`size="icon-xl"`（44px）にして揃えた。あわせて 44px のタップターゲット下限も満たすようになる
+- **`SubNav` の左右余白を `Container` と揃えた**: `px-4` 固定だったため、PC で `Container` の gutter（24px）と 8px ずれていた。SP 16 / PC 24 になる。**PC（768px 以上）で左右の余白が 16px → 24px に変わる**（[#234](https://github.com/flashpark/cake-design-system/issues/234)）
+- **`SectionHeader`（`align="start"`）で `subtitle` と右側 `action` を併用するとキャプションが早い位置で折り返される問題を修正**: タイトルとキャプションが `action` と同じ Flex 行の中に入っていたため、キャプションまで `action` の幅ぶん狭まっていた。タイトル行とキャプションを別の行に分け、キャプションはヘッダー全幅（右側アクションの下も含む）で折り返す。`moreHref` 併用時にリンクになるのは**タイトル行だけ**になり、`subtitle` はリンクの外に出る（読み上げ対象のリンク数は従来と同じ 1 つ）。`align="center"` は変更なし（[#232](https://github.com/flashpark/cake-design-system/issues/232)）
+- **`Tabs`（underbar）のトリガーに左右 padding が無く、狭幅で隣のラベルと文字が接触する問題を修正**: 既定で左右 8px を持たせた。サイドバー幅 266px の実測で余白が `1px / 1px` → `8px / 8px` になる。`scrollable` の underbar は `gap-4` で間隔を取っているため従来どおり padding 0（[#235](https://github.com/flashpark/cake-design-system/issues/235)）
+- **`SheetContent` が開閉時のフォーカス自動移動を無条件に止めていた問題を修正**（a11y / WCAG 2.4.3）: `onOpenAutoFocus` / `onCloseAutoFocus` を常に `preventDefault` していたため、素で使うと**開いてもキーボードで中に入れず、閉じてもトリガーにフォーカスが戻らない**状態だった。既定を Radix のまま（開く=中へ / 閉じる=トリガーへ戻る）に直し、止めたい用途向けに `autoFocus={false}` を追加。あわせて利用側が渡した `onOpenAutoFocus` / `onCloseAutoFocus` が DS の既定を消さずに追加で呼ばれるようにした（従来は利用側のハンドラが DS の指定ごと置き換わっていた）。`Sheet` を素で使っている画面はフォーカス挙動が変わる（[#233](https://github.com/flashpark/cake-design-system/issues/233)）
+- **`preset` がビューポートのブレイクポイント（`--breakpoint-md/lg/xl`）を配っておらず、利用側の `lg:` が Tailwind 既定の 1024px で効いていた問題を修正**: DS の切替段は `md`=768 / `lg`=**960** で、`preset.css` はコンテナクエリ用の `--container-*` しか定義していなかった。そのため `@theme` で自分で書き直したプロダクトだけが正しい位置で切り替わり、書いていないプロダクトは PC 中段が 64px ずれていた（実例: cakejp-biz-mag のトップが 1000px 幅で 1 カラムに落ちる）。`preset` を読み込むだけで `md:` / `lg:` / `xl:` が DS の段に揃う。**利用側の `globals.css` に同じ `@theme` を書いている場合は削除してよい**（値が同じなら実害はない）。`lg:` を Tailwind 既定の 1024px 前提で書いていた画面は切替位置が 960px に変わる（[#242](https://github.com/flashpark/cake-design-system/issues/242)）
+
+## [0.18.0] - 2026-08-19
+
+利用側が DS 内部 DOM を `nth-child` / `:has()` で上書きして回避していたケースを公開 props と不具合修正で解消し、あわせてリンクを描く部品に `linkComponent` を追加してフレームワークのリンク部品を差し込めるようにする回。**公開 API の破壊的変更はなし**（追加した prop はすべて既定値が従来の挙動）。ただし `navBreakpoint="lg"` を使っている場合のみ、PC 行の開始が 1024px → 960px に変わる（tokens.json の切替段に合わせた修正）。
+
+### 🐛 Fixed
+
+- **`Header` の `navBreakpoint="lg"` が 1024px で切り替わっていたのを、tokens.json の切替段 `lg`=960px に修正**: DS の切替段は `md`=768 / `lg`=960 の 2 つで、1024 は存在しない段だった。`navBreakpoint="lg"` を使っている場合、PC 行の開始が 1024px → 960px に変わる
+
+- **`Header` の navItems 自動退避で、退避した項目がページのスクロール領域に残り横スクロールが起きる問題を修正**: 計測用の複製は `absolute` + `invisible` で通常フローには影響しないが、絶対配置要素も祖先のスクロール可能領域には寄与する。利用側の実測では viewport 769px に対しページが 932px を要求していた（[#243](https://github.com/flashpark/cake-design-system/issues/243)）。0 幅 0 高 + `overflow:hidden` の器で包んで寄与を断つ。クリップは描画時のみでレイアウトは保たれるため、退避件数の計算結果は変わらない
+
+### ✨ Added
+
+- **`Footer` / `MenuDrawer` / `SubNav` / `PaginationLink` に `linkComponent` を追加**: リンクの描画に使うコンポーネントを差し替えられる（`next/link` 等）。これらの部品は素の `<a>` しか描けず、Next.js の consumer ではこの導線だけフルページ遷移になっていた。未指定なら従来どおり `<a>`。`Footer` は `external: true` のリンクだけ常に素の `<a target="_blank">` にフォールバックする（他 3 部品の項目に `external` フラグは無く、渡した href はすべて `linkComponent` で描かれる）（[#236](https://github.com/flashpark/cake-design-system/issues/236)）
+- **`Header` に `searchBreakpoint` を追加**（`md`=768px / `lg`=960px）: `searchSlot` の器を出し始めるコンテナ幅を選べる。中身だけを利用側の CSS で隠しても器は `flex-1` の幅を確保し続けてインラインナビを潰すため、狭い帯で検索を出さない場合はこの prop を使う。値は tokens.json の切替段のみで、コンテンツ上限段の `xl`(1280) は受け付けない（[#243](https://github.com/flashpark/cake-design-system/issues/243)）
+- **`HeaderAction` に `showLabel` を追加**: アイコンの右に可視ラベルを出すピル型（高さ 40px・枠線）で描画する。「ログイン」等アイコンだけでは意味が伝わらない導線向け。可視テキストがあるときは `aria-label` を付けず二重読み上げを避ける（[#245](https://github.com/flashpark/cake-design-system/issues/245)）
+- **`ProductCard` に `hoverEffect` を追加**（`zoom` / `fade` / `none`）: ホバー時の画像演出を選べる。`fade` は拡大せずわずかに明るくする本番 EC 準拠の挙動で、暗テーマでも明るくなるよう opacity ではなく brightness を使う。未指定時の既定は従来の見た目を保つため orientation ごと（`vertical` = `zoom` / `horizontal` = `none`）で、明示指定すれば `horizontal` でも効く（[#244](https://github.com/flashpark/cake-design-system/issues/244)）
+- **`ReviewCard` に `bordered` を追加**（既定 `true`）: 商品詳細などページ全体をフラットに統一する画面で枠線を外せる（[#247](https://github.com/flashpark/cake-design-system/issues/247)）
+- **`Footer` に `variant="brand-first"` と `bottomRightSlot` を追加**: ロゴ・説明文を先頭カラムに置き、その右にリンク群を並べる構成。下部バーはコピーライト左・`bottomRightSlot`（`Powered by` 等）右の左右振り分けになる。求人ケーキ屋さん.jp / 仕入れケーキ屋さん.JP のフッターをカスタムマークアップなしで組める（[#246](https://github.com/flashpark/cake-design-system/issues/246)）
+
+## [0.17.1] - 2026-08-06
+
+**0.17.0 の型定義が壊れていたため、0.17.0 は使わず 0.17.1 へ上げてください。**
+
+### 🐛 Fixed
+
+- **配布する型定義の相対パスが 1 階層ズレて、利用側で型が `any` に落ちる問題を修正**: `tsconfig.lib.json` の `outDir`（`./dist`）と `declarationDir`（`./dist/types`）がズレていたため、`tsc-alias` が `@/...` を 1 階層深い相対パスへ書き換えていた。0.16.0 までは指す先が存在せず実害が出ていなかったが、0.17.0 で `dist/components/**`（preserveModules の JS 出力）が増えたことで**誤ったパスが JS 側に当たり**、型が `any` になった。結果 `Pick<any, "size">` などが必須 prop 扱いになり、利用側の typecheck が壊れていた（cake-api で 17 件のエラーを確認）。影響していた型定義は 18 ファイル。`outDir` を `./dist/types` に揃えて解消
+- 回帰防止に `__tests__/dts-import-paths.test.ts` を追加（配布する型定義の相対 import 237 件がすべて型定義ツリー内で解決すること・`dist/types` の外を指さないことを固定）
+
 ## [0.17.0] - 2026-08-06
 
 アクセシビリティ（読み上げソフト対応）の burn-down と、利用側バンドル削減の回。**破壊的変更なし。** 公開 export 名・既定の見た目はどちらも変わらない。

package/CLAUDE.md

@@ -67,6 +67,21 @@ PdM や社長が AI（Claude 等）で HTML モックを作る際、このパッ
 
 ---
 
+## 見た目のフィードバックを受けたときのゲート（DS 起因か consumer 起因かを先に切り分ける）
+
+「崩れている」「詰まっている」「揃っていない」等の指摘を受けたら、**直す前に**起因を切り分ける。DS 起因の崩れを consumer 側の `className` だけで握りつぶすと、同じ崩れが他プロダクトで再発し、DS には何も残らない。
+
+1. **実測する**: computed style / `getBoundingClientRect` で数値を取る（padding・幅・左端座標）。見た目の印象で判断しない。
+2. **DS 部品のソースを読む**: `node_modules/@cakejp/design-system/dist/index.js` か DS リポジトリの `src/components/**` で該当部品の className を確認し、その挙動が
+   - **DS の設計上の仕様/欠落**（実例: `TabsTrigger` の underbar が padding を持たない / `Header` `SubNav` が内側コンテナを持たず全幅に描く / `SubNav` の gutter が `Container` と 8px 違う / segment タブの `min-w-[100px]` / `SheetContent` がフォーカス制御を無条件に `preventDefault`）なのか
+   - **consumer の使い方**（variant の選択ミス、`className` の当て方、ラッパーの有無、`Container` を通していない）なのか
+   を判定する。
+3. **DS 起因なら**: consumer 側は最小の回避（`className` 追加・ラッパー）に留め、コードコメントに「DS 起因。DS 側で X が直ったら削除」と書く。**同時に flashpark/cake-design-system に issue を立てる**（再現条件・実測値・期待挙動・consumer 側の回避コード）。
+4. **consumer 起因なら**: 素直に直す。同じ誤用が他に無いか grep する。
+5. **報告には「起因: DS / consumer」と根拠（読んだ DS のソース箇所・実測値）を必ず添える。** 起因を書かない「直しました」報告は不完全。
+
+---
+
 ## 技術スタック
 
 - React 19 + TypeScript

package/contracts/components.json

@@ -1,7 +1,7 @@
 {
   "meta": {
     "name": "Cake.jp Design System — Component Contracts",
-    "version": "0.17.0",
+    "version": "0.19.0",
     "description": "全コンポーネントの構造化定義。バリアント・アクセシビリティ要件・使用ルールを機械可読形式で管理。",
     "kind": "kind:\"shell\" は複数ページで再利用されるレイアウト枠（AdminShell / WorkspaceShell / MypageShell 等）。無印は部品コンポーネント。固有ページを組むときは該当 shell から始める。src/components/pages/ 配下のストーリーは特定ページ専用・非配布のため contracts の対象外。",
     "naming": "コンポーネント名は**用途ではなく機能**で付ける。用途名（QuantitySelector = カート数量）にすると、同じ機能を別の文脈で探した人が見つけられず二重実装が生まれる（実例: 用途名だったため NumberInput が別途作られ、意匠の違うステッパーが 2 つになった）。「〜Selector」「〜Picker」等の用途接尾辞を付ける前に、その部品が何をするものかで名前が付けられないかを先に検討する。既存名を機能名へ変える場合は deprecatedAliases に旧名を残す。",
@@ -9,9 +9,9 @@
     "formBinding": "react-hook-form との繋ぎ方。formBinding:\"register\"=ネイティブ form control に props/ref を透過するので {...register(\"name\")} を直接 spread できる（Input / Textarea）。formBinding:\"controller\"=Radix ベースで ref が <button> 等に着地する、または値が Date/File など非文字列のため Controller の field.value / field.onChange に繋ぐ。formBinding:\"layout\"=値を持たないレイアウト部品でバインド対象ではない（Field / Form / FormField / ProductOption）。formBinding:\"none\"=値は扱うが単一フィールドのバインド対象ではない自己完結フォーム・複合ウィジェット（DataTable / SearchBar / ReviewForm）。この切り分けは __tests__/react-hook-form-integration.test.tsx が実挙動で固定する（issue #151 / #152）。",
     "counts": {
       "foundations": 51,
-      "primitives": 49,
+      "primitives": 51,
       "ec": 24,
-      "total": 124,
+      "total": 126,
       "note": "counts は各ティアの実装ファイル数（scripts/check-drift.sh が src/components/<tier>/*.tsx と突き合わせる）。subcomponents / deprecatedAliases は含まない。"
     }
   },
@@ -117,7 +117,12 @@
         "default",
         "lg",
         "xl",
-        "hero"
+        "hero",
+        "icon-xs",
+        "icon-sm",
+        "icon",
+        "icon-lg",
+        "icon-xl"
       ],
       "accessibility": [
         "aria-label必須（アイコンのみの場合）"
@@ -125,6 +130,7 @@
       "rules": [
         "<button>を直接使わない。必ずButtonコンポーネントを使う",
         "高さは size='default'=44px（h-11） / xs=24px / sm=32px / lg=48px / xl=56px / hero=min 56px。default はフォーム入力コントロール（Input / SelectTrigger default / DatePicker trigger）と同じ 44px なので、入力行にボタンを並置しても揃う",
+        "アイコンのみは icon-xs=24px / icon-sm=32px / icon=36px / icon-lg=40px / icon-xl=44px。入力コントロール（Input / SearchBar / SelectTrigger）の横に並べるときは icon-xl を使う（他は高さが揃わず、44px のタップ領域も満たさない）",
         "⚠️ variant='secondary' はブランドアクセント意匠（Surface-Accent-Primary-Light地+Brand-Cake-Orange文字）。Material/Bootstrap/shadcn の secondary（グレー・控えめ）とは別物なので、他DSの感覚で選ばない",
         "「戻る」「キャンセル」「閉じる」「スキップ」「あとで」等の後退・中立アクションは variant='tertiary'（Surface-Tertiary地+Text-High-Emphasis文字のニュートラルなグレー）を使う。主CTAの隣に置く2番目のボタンでも、役割が後退なら secondary ではなく tertiary",
         "variant='secondary' を使うのは、主CTAと別方向の“前進”を促す副CTAのとき（例: 主='購入する' に対し 副='サンプルを見る'）",
@@ -210,7 +216,12 @@
       "formBinding": "none",
       "rules": [
         "管理画面のテーブルはui/tableでなくこちらを使う。ソート・選択行・アクションメニュー対応",
-        "ActionCellのメニュー操作は行のonClickへ伝播しない（本体でstopPropagation済み）。行クリック選択との併用時も利用側ガードは不要"
+        "ActionCellのメニュー操作は行のonClickへ伝播しない（本体でstopPropagation済み）。行クリック選択との併用時も利用側ガードは不要",
+        "見出し文字を出さない列（選択・操作・並び替えハンドル）は DataTableHead の srLabel で読み上げ用ラベルを付ける。空の <th> は列の意味が支援技術に伝わらない（axe: empty-table-header）"
+      ],
+      "accessibility": [
+        "sortable な列の押下は <button> が担い、Tab / Enter / Space で操作できる。並び替え状態は <th aria-sort>（none / ascending / descending）で伝わる。th に onClick を直接書かない",
+        "方向アイコンは装飾なので aria-hidden。列名は button の中に置き、読み上げ名にする"
       ]
     },
     {
@@ -344,7 +355,10 @@
     },
     {
       "name": "Pagination",
-      "path": "src/components/foundations/pagination.tsx"
+      "path": "src/components/foundations/pagination.tsx",
+      "rules": [
+        "linkComponent でリンク実装を差し替えられる（next/link 等）。未指定なら素の <a>。この部品の項目に external フラグは無く、渡した href はすべて linkComponent で描かれる（外部 URL を出し分けたい場合は consumer 側でラップする）（#236）"
+      ]
     },
     {
       "name": "Popover",
@@ -420,6 +434,15 @@
         "SheetDescription",
         "SheetFooter",
         "SheetClose"
+      ],
+      "props": [
+        "SheetContent: side?: top | right | bottom | left",
+        "SheetContent: showCloseButton?: boolean",
+        "SheetContent: autoFocus?: boolean"
+      ],
+      "accessibility": [
+        "SheetTitle は必須（ダイアログの読み上げ名）",
+        "フォーカスは既定で自動移動する（開く=Sheet の中へ / 閉じる=トリガーへ戻る）。WCAG 2.4.3。autoFocus={false} は止める必要がある特別な場合だけ使う（issue #233）"
       ]
     },
     {
@@ -460,7 +483,7 @@
       "name": "SocialIcon",
       "path": "src/components/foundations/social-icon.tsx",
       "props": [
-        "platform",
+        "platform: line | x | facebook | hatena | amazon | google | apple",
         "tone?: brand | mono",
         "size?: number"
       ],
@@ -497,6 +520,15 @@
         "TabsList",
         "TabsTrigger",
         "TabsContent"
+      ],
+      "variants": [
+        "TabsList variant: underbar | segment",
+        "TabsList scrollable: boolean",
+        "TabsList size: md | sm"
+      ],
+      "rules": [
+        "サイドバー等の狭い場所に segment を置くときは TabsList size=\"sm\" を使う。既定は 1 項目 100px の最小幅を持ち、3 つ並べると 266px 幅ではみ出す（issue #235）",
+        "underbar のトリガーは左右 8px の padding を持つ。className=\"px-2\" を利用側で足さない"
       ]
     },
     {
@@ -646,6 +678,35 @@
       "name": "CoachMark",
       "path": "src/components/primitives/coach-mark.tsx"
     },
+    {
+      "name": "ContentCard",
+      "path": "src/components/primitives/content-card.tsx",
+      "subcomponents": [
+        "ContentList"
+      ],
+      "props": [
+        "title: string",
+        "href: string",
+        "imageSlot?: ReactNode",
+        "tag?: { label: string; variant?: TagProps[\"variant\"] }",
+        "meta?: ReactNode",
+        "orientation?: vertical | horizontal | list",
+        "aspect?: 16/10 | 16/9 | 1/1",
+        "linkComponent?: LinkComponent"
+      ],
+      "variants": [
+        "orientation: vertical | horizontal | list",
+        "aspect: 16/10 | 16/9 | 1/1"
+      ],
+      "rules": [
+        "記事・特集・お知らせなど「画像 + タイトル + メタ」のカード。ProductCard（商品）/ ShopCard（店舗）の兄弟。Card + CardContent で組まない（枠線・タイトル行数・カード高さが揃わない。実測で高さ 268 / 312 に割れた事例あり）（issue #241）",
+        "タイトルは 2 行で省略し常に 2 行ぶんの高さを取る。文字装飾を利用側で足さない（font-bold にしない。既定は font-medium）",
+        "meta は 1 行に収める。複数行にすると一覧でカード高さが割れる",
+        "画像は imageSlot に渡す（next/image・CMS・図版を吸収する）。縦横比とクリップはカード側が持つ",
+        "Medium 型の縦リストは orientation=\"list\" + ContentList（区切り線つき）を使う",
+        "カード全体がリンク。linkComponent で next/link 等を差し込める"
+      ]
+    },
     {
       "name": "Combobox",
       "path": "src/components/primitives/combobox.tsx",
@@ -745,7 +806,15 @@
     },
     {
       "name": "Footer",
-      "path": "src/components/primitives/footer.tsx"
+      "path": "src/components/primitives/footer.tsx",
+      "rules": [
+        "variant='brand-first' でロゴ・説明文を先頭カラムに置き、その右にリンク群を並べる。下部バーはコピーライト左・bottomRightSlot 右の左右振り分けになる。linkGroups が空でもロゴ・説明文は落ちず、逆に logo/description が無いときは nav を 2 カラムへ押し込まない。この構成をカスタムマークアップで自作しない（#246）",
+        "linkComponent でリンク実装を差し替えられる（next/link 等）。未指定なら素の <a>。external:true のリンクは framework のリンク部品へ通す意味が無いため常に素の <a target=_blank> にフォールバックする（#236）"
+      ],
+      "variants": [
+        "default",
+        "brand-first"
+      ]
     },
     {
       "name": "FormField",
@@ -801,7 +870,10 @@
         "actions（HeaderAction）はカート・マイページ等の本来リンクである導線には href を指定する。href 指定時は Button asChild + <a> で描画され、中クリック/新規タブ・リンクコピーが効く。onClick と併用可（両方付与される）",
         "navItems は幅に入り切らない項目を自動で「その他」ドロップダウンへ退避する（#200）。consumer 側で項目数を手で slice して減らさない。ラベルを増やしても中幅でロゴ・actions と衝突しない",
         "navBreakpoint でインラインナビ行の開始コンテナ幅を選べる: md（既定 = @[768px]+）/ lg（@[1024px]+）。ロゴが多段で横幅を食うケースは lg にして中幅での同居自体を避ける",
-        "「その他」のラベルは navOverflowLabel で差し替えられる（既定 その他）。ハンバーガーを自前で組まない"
+        "「その他」のラベルは navOverflowLabel で差し替えられる（既定 その他）。ハンバーガーを自前で組まない",
+        "HeaderAction の showLabel=true でアイコン＋可視ラベルのピル型（h-10・枠線）になる。「ログイン」等アイコンだけでは伝わらない導線に使い、consumer 側でアイコンにテキストを差し込まない（#245）",
+        "searchBreakpoint で searchSlot の器を出し始めるコンテナ幅を選ぶ（md=768 / lg=960 の切替段のみ。xl=1280 は上限段でレイアウト切替に使わない）。狭い帯で検索を出さないときは consumer の CSS で中身を隠さずこの prop を使う。中身だけ隠しても器が flex-1 の幅を確保し、インラインナビを潰す（#243）",
+        "本文を Container size=\"page\" で中央寄せしているサイトは containerSize=\"page\" を指定する（Container と同じ段: page / wide / fluid）。背景・border・sticky は全幅のまま中身だけ中央寄せされ、ロゴ・ナビの左端が本文と揃う。consumer 側で className に max-w を当てると背景と線まで中央幅になり両脇が抜けるので使わない（issue #234）"
       ]
     },
     {
@@ -890,7 +962,10 @@
     },
     {
       "name": "MenuDrawer",
-      "path": "src/components/primitives/menu-drawer.tsx"
+      "path": "src/components/primitives/menu-drawer.tsx",
+      "rules": [
+        "linkComponent でリンク実装を差し替えられる（next/link 等）。未指定なら素の <a>。この部品の項目に external フラグは無く、渡した href はすべて linkComponent で描かれる（外部 URL を出し分けたい場合は consumer 側でラップする）（#236）"
+      ]
     },
     {
       "name": "MultiSelect",
@@ -942,6 +1017,21 @@
       "name": "ProgressSteps",
       "path": "src/components/primitives/progress-steps.tsx"
     },
+    {
+      "name": "Prose",
+      "path": "src/components/primitives/prose.tsx",
+      "props": [
+        "html?: string",
+        "as?: div | article | section"
+      ],
+      "rules": [
+        "CMS（microCMS 等）のリッチテキスト HTML を描くときは、consumer 側で h2 / p / ul の CSS を書かずこれを使う。ArticleBody.module.css のような独自 CSS を作らない（issue #239）",
+        "html に渡す HTML は利用側でサニタイズ済みであること。この部品は体裁を当てるだけで中身の無害化はしない",
+        "記事幅は Container size=\"narrow\"（760px）で決める。この部品は幅を持たない",
+        "見出しレベルは CMS の出力に従う（体裁だけを当て、階層は変えない）",
+        "幅の広い表は表自身が縮む／横スクロールするので、ページは横に伸びない"
+      ]
+    },
     {
       "name": "NumberInput",
       "path": "src/components/primitives/number-input.tsx",
@@ -987,7 +1077,20 @@
     {
       "name": "SearchBar",
       "path": "src/components/primitives/search-bar.tsx",
-      "formBinding": "none"
+      "formBinding": "none",
+      "props": [
+        "size?: sm | md",
+        "onSearch?: (query: string) => void",
+        "searchHref?: string",
+        "action?: string",
+        "name?: string"
+      ],
+      "rules": [
+        "JS 無効環境・クローラでも動かす必要がある画面（SEO 重視の記事メディア等）は action を指定する。<form method=\"get\" action> として描画され、Enter も検索ボタンも素のフォーム送信になる（issue #237）",
+        "action 指定時のクエリキーは name（既定 q）",
+        "Input + Button で <form method=get> を手組みしない",
+        "searchHref は window.location を書き換える JS 前提の導線。action と併用しない（action が優先）"
+      ]
     },
     {
       "name": "SearchPanel",
@@ -1027,7 +1130,8 @@
       "rules": [
         "タイトル+もっと見るボタンをCardTitle+Button手書き禁止。SectionHeaderを使う",
         "中央寄せ大見出し（ランディング/ガイド系）は align=\"center\" を使う。eyebrow プロップに Badge 等を載せられる。手書きの中央寄せ見出し禁止",
-        "3xl（28px）は通常ページの主見出しにも使う。4xl/5xlはLP・マーケティング系ヒーロー専用で、size=\"3xl\" に desktopSize=\"4xl\" または desktopSize=\"5xl\" を加えてPC時だけ拡大する"
+        "3xl（28px）は通常ページの主見出しにも使う。4xl/5xlはLP・マーケティング系ヒーロー専用で、size=\"3xl\" に desktopSize=\"4xl\" または desktopSize=\"5xl\" を加えてPC時だけ拡大する",
+        "align=\"start\" では subtitle はタイトル行の下に全幅で置かれ、右側 action の下の空きも使って折り返す。moreHref 併用時にリンクになるのはタイトル行だけで、subtitle はリンクの外（issue #232）"
       ]
     },
     {
@@ -1051,7 +1155,17 @@
     },
     {
       "name": "ShareButtons",
-      "path": "src/components/primitives/share-buttons.tsx"
+      "path": "src/components/primitives/share-buttons.tsx",
+      "props": [
+        "url?: string",
+        "text?: string",
+        "services?: Array<'line' | 'x' | 'facebook' | 'hatena' | 'copy' | ShareCustomService>"
+      ],
+      "rules": [
+        "共有先は services で選ぶ（既定 line / x / copy）。同じ意匠を Button asChild で組み直さない（issue #238）",
+        "組み込みに無い共有先は services に { key, label, href, icon } を混ぜて足す。href の {url} / {text} が URL エンコード済みの値に置換される",
+        "共有先のロゴは SocialIcon が持つ。SVG を手書きしない"
+      ]
     },
     {
       "name": "SideNav",
@@ -1101,7 +1215,16 @@
     },
     {
       "name": "SubNav",
-      "path": "src/components/primitives/sub-nav.tsx"
+      "path": "src/components/primitives/sub-nav.tsx",
+      "variants": [
+        "variant: text | chip",
+        "containerSize: page | wide | fluid"
+      ],
+      "rules": [
+        "linkComponent でリンク実装を差し替えられる（next/link 等）。未指定なら素の <a>。この部品の項目に external フラグは無く、渡した href はすべて linkComponent で描かれる（外部 URL を出し分けたい場合は consumer 側でラップする）（#236）",
+        "左右の余白は Container と同じ SP 16 / PC 24。利用側で px-* を足さない",
+        "本文を Container size=\"page\" で中央寄せしているサイトは containerSize=\"page\" を指定する。下線は全幅のまま中身だけ中央寄せされる（issue #234）"
+      ]
     },
     {
       "name": "Tag",
@@ -1263,8 +1386,10 @@
       "rules": [
         "captionは規格・仕様の短い自由記述（例: \"1kg / 冷蔵\"）。価格表示の直下にtypo-body-xs / Text-Medium-Emphasisで表示。tags（配送方法等のenum variant）とは別物で代替不可",
         "カード幅は列（親グリッド/flex）が決める。カード自身は min-w-0 で、固定の min-width を持たない。自前のカードを組む場合もテキスト列は grid-template-columns: minmax(0, 1fr) にし、auto にしない（nowrapのメタ行のmin-content幅が列を押し広げ、サムネイルが列からはみ出す）",
-        "商品名は line-clamp-2 + min-h-[2lh] で常に2行分の高さを確保する。1行の商品名でも下に続く価格の縦位置が一覧内で揃う"
-      ]
+        "商品名は line-clamp-2 + min-h-[2lh] で常に2行分の高さを確保する。1行の商品名でも下に続く価格の縦位置が一覧内で揃う",
+        "hoverEffect でホバー時の画像演出を選ぶ: zoom / fade（拡大せず明るく・暗テーマ対応のため brightness を使う）/ none。未指定時の既定は orientation ごと（vertical=zoom / horizontal=none）で従来の見た目を維持し、明示指定すれば horizontal でも効く。consumer 側の CSS で scale を打ち消さない。Tailwind v4 の scale-* は transform ではなく scale プロパティのため打ち消しは壊れやすい（#244）"
+      ],
+      "variants": {}
     },
     {
       "name": "ProductCarousel",
@@ -1343,6 +1468,9 @@
       "features": [
         "helpful-count",
         "like"
+      ],
+      "rules": [
+        "bordered={false} で枠線を外せる。商品詳細等ページ全体をフラットに統一する画面で consumer が border-0 を上書きしない（#247）"
       ]
     },
     {

package/contracts/composition.json

@@ -1,7 +1,7 @@
 {
   "meta": {
     "name": "Cake.jp Design System — Composition Contracts",
-    "version": "0.17.0",
+    "version": "0.19.0",
     "description": "ページ骨格・視覚階層・余白リズムの機械可読な正本。画面パターンを選んだ後の「実際の組み方」を規定する。ページの外枠（モバイル/デスクトップ/管理）、商品グリッドの列数、余白の4段リズム、Surface のネスト階層、テキスト階層、CTA の優先順位を構造化する。人間向けの解説は guidelines/composition/layout.md・guidelines/composition/hierarchy.md・guidelines/overview.md。",
     "source": "guidelines/composition/layout.md, guidelines/composition/hierarchy.md, guidelines/overview.md, guidelines/components/button.md（CTA 密度ルール）を正本化",
     "roleSeparation": "screen-patterns.json はページ種別（Standard Page / Focused Workspace / ResponsiveDialog / Dialog）を選ぶための契約。composition.json は選んだ後、その骨格をどう組むか（外枠構造・余白リズム・階層）の契約。前者=何を使うか、後者=どう並べるか。",

package/contracts/rules.json

@@ -1,7 +1,7 @@
 {
   "meta": {
     "name": "Cake.jp Design System — Rules Contracts",
-    "version": "0.17.0",
+    "version": "0.19.0",
     "description": "禁止パターン・アクセシビリティ要件・ライティングルールの構造化定義。lint-scratch.sh と check-drift.sh で自動検証。"
   },
   "prohibited": [
@@ -655,6 +655,10 @@
         "id": "A007",
         "rule": "全フォーム入力に <Label> または aria-label を紐付ける"
       },
+      {
+        "id": "A014",
+        "rule": "React Server Components 対応: client 専用 API（useState / useEffect / createContext 等）を使うモジュールは先頭に \"use client\" を宣言する。バレル（src/index.ts）には付けない — 付けるとパッケージ全体が client 扱いになり、cn / buttonVariants を Server Component から呼べなくなる。__tests__/client-boundary.test.ts が固定する"
+      },
       {
         "id": "A013",
         "rule": "Radix ベースのコントロール（Select / Switch / Checkbox / Combobox / Slider 等）は <button> や <span role=\"slider\"> として描画されるため、<Label htmlFor> や外側の <label> ラップでは名前が付かない。FormField でラップして aria-labelledby を自動付与させるか、単体利用なら日本語の aria-label をコントロール自身に書く（issue #202）"

package/contracts/screen-patterns.json

@@ -1,7 +1,7 @@
 {
   "meta": {
     "name": "Cake.jp Design System — Screen Patterns Contracts",
-    "version": "0.17.0",
+    "version": "0.19.0",
     "description": "CRUD 機能でどの画面パターンを使うかの機械可読な判断基準。5パターンの定義・CRUD 対応・決定木・編集UIの観点比較を構造化する。人間向けの解説は guidelines/foundations/screen-patterns.md。",
     "source": "GitHub issue #37 CRUDの画面設計の型化と基本パターンの整備",
     "relatedContract": "本契約はページ種別の選択（何を使うか）を担う。選んだ後の骨格の組み方（外枠構造・余白リズム・視覚階層）は contracts/composition.json を参照する。",

package/dist/components/ec/admin-shell.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsxs as r, jsx as e, Fragment as N } from "react/jsx-runtime";
 import * as d from "react";
 import { cn as k } from "../../lib/utils.js";
@@ -130,7 +131,7 @@ function ne({
   mainId: f = "main-content",
   skipLink: g
 }) {
-  const [y, h] = d.useState(!1), S = /* @__PURE__ */ r(N, { children: [
+  const [y, c] = d.useState(!1), S = /* @__PURE__ */ r(N, { children: [
     /* @__PURE__ */ r("button", { className: "relative flex items-center justify-center size-10 shrink-0 rounded-lg hover:bg-[var(--Surface-Secondary)]", "aria-label": "通知", children: [
       /* @__PURE__ */ e(j, { size: 20, className: "text-[var(--Text-High-Emphasis)]" }),
       /* @__PURE__ */ e("span", { className: "absolute top-1.5 right-1.5 size-2 rounded-full bg-[var(--Surface-Caution)]" })
@@ -154,7 +155,7 @@ function ne({
               activeKey: t,
               drawerTitle: p ?? s,
               open: y,
-              onOpenChange: h
+              onOpenChange: c
             }
           ),
           /* @__PURE__ */ r("div", { className: "@container/main flex flex-1 flex-col @md:pl-18", children: [
@@ -162,7 +163,7 @@ function ne({
               L,
               {
                 brand: b ?? `${s}管理`,
-                onMenuClick: () => h(!0),
+                onMenuClick: () => c(!0),
                 actions: v ?? S
               }
             ),
@@ -182,10 +183,10 @@ function ne({
                 }
               ),
               (n || l) && /* @__PURE__ */ r("div", { className: "mb-4 space-y-1", children: [
-                n && n.length > 0 && /* @__PURE__ */ e("nav", { className: "flex items-center gap-1 typo-body-sm text-[var(--Text-Low-Emphasis)]", "aria-label": "パンくず", children: n.map((o, c) => /* @__PURE__ */ r(d.Fragment, { children: [
-                  c > 0 && /* @__PURE__ */ e(F, { size: 12 }),
+                n && n.length > 0 && /* @__PURE__ */ e("nav", { className: "flex items-center gap-1 typo-body-sm text-[var(--Text-Low-Emphasis)]", "aria-label": "パンくず", children: n.map((o, h) => /* @__PURE__ */ r(d.Fragment, { children: [
+                  h > 0 && /* @__PURE__ */ e(F, { size: 12 }),
                   o.href ? /* @__PURE__ */ e("a", { href: o.href, className: "hover:text-[var(--Text-Accent-Primary)] transition-colors", children: o.label }) : /* @__PURE__ */ e("span", { className: "text-[var(--Text-High-Emphasis)]", children: o.label })
-                ] }, c)) }),
+                ] }, h)) }),
                 l && /* @__PURE__ */ e("h1", { className: "typo-heading-2xl text-[var(--Text-High-Emphasis)]", children: l })
               ] }),
               i