@cakejp/design-system 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -9,6 +9,65 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-07-17
+
+### ⚠️ Upgrade impact
+
+- **minor リリース**: コンテナクエリの正本を `@md=768px` / `@lg=960px` / `@xl=1280px` に統一したため、従来の `@md`（448px）を前提にしていた利用側は、レイアウトの変形点を確認すること。`@xl` はページ幅の上限段であり、レイアウト変形には使わない
+- **`Chip` の removable DOM 構造変更**: アクセシビリティ上の入れ子 `button` を解消し、本体と削除ボタンを兄弟要素へ変更した。内部DOMや子孫セレクタに依存する利用側は調整が必要
+
+### ✨ Added
+
+- **レスポンシブのブレイクポイントを機械可読の正本に昇格**: 境界の値（768 / 960px）が `preset.css` の `@theme`（`--container-md` / `--container-lg`）にしか無く、「PdM や AI が `tokens.json` / `contracts` を読んでモックを作る」建て付けなのに機械可読の正本に穴があった。`tokens.json` に `breakpoints`（md=768 / lg=960、意味・本番対応・注記つき）、`contracts/composition.json` の pageSkeletons 付近に参照情報、`guidelines/composition/layout.md` に節、StyleGuide に `StyleGuide/Breakpoints` ページを追加して正本化。値は既報のコンテナクエリ境界（768 / 960）と一致し、DS 内部はコンテナクエリ `@md:` / `@lg:`、生 CSS はこの px 値をメディアクエリに使う旨も明記
+- **上限段 `xl = 1280px` をブレイクポイント正本に追加**: 既存の `md=768` / `lg=960` は本番 cakejp.css の**切替段**と一致する正本。新設の `xl=1280` は役割が違い、本番に 1280 の切替段は無い（1025 / 1441 はある）——DS が定める**コンテンツ幅の上限段**（ページコンテナの標準上限で、1280px 以上では原則レイアウト変形を追加しない）。`tokens.json` / `contracts/composition.json` / `preset.css`（`--container-xl` = 80rem）/ `guidelines/composition/layout.md` / `StyleGuide/Breakpoints` に、この「切替段（md/lg）と上限段（xl）」の役割二層を明記して追加。実例は `MypageShell` の PC グリッド `max-w-[1280px]`
+- **Storybook にトップレベル `Shells` セクションを新設**。シェルは `contracts` 上 `kind:"shell"` の一級の概念なのに、サイドバー上は `Pages/Foundation` の下にカタログ表が1枚あるだけで、**5シェルとも単体ストーリーが存在しなかった**（実物を見る手段が無かった）
+  - `Shells/Overview`（旧 `Pages/Foundation/ShellsCatalog`。contracts を実行時に読む動的カタログ）
+  - `Shells/StandardPageShell` / `Shells/WorkspaceShell` / `Shells/FunnelShell` / `Shells/AdminShell` / `Shells/MypageShell` の実物デモを新設
+  - ファイルは各コンポーネントの隣（`primitives/` `ec/`）に置いたため、**公開 Storybook にそのまま載る**（シェルごとの公開リンクが持てる）。`pages/` 配下のページ実例は従来どおり非公開
+  - 汎用枠（primitives）のデモは意図的に **EC 非依存の中身**（求人検索の「検索と結果の表示」等）で組み、名前がドメイン中立であることを実物で示す
+- `WorkspaceShell` に、中央寄せの読みやすい幅で構成する1カラム集中編集ストーリーを追加
+- `AdminShell` に戻る導線 prop（`onBack` / `backLabel`）を追加。渡すとパンくずより上に戻るボタンを描画する（シェルが位置を保証。子コンテンツ内に戻るを手書きしない運用へ）
+
+### ♻️ Changed
+
+- **`Container` の `size="page"` 上限を 1200px → 1280px に統一**（＝ `breakpoints.xl` のコンテンツ上限段）。標準ページの最大幅がブレイクポイント正本と一致した。`pages/` 配下の本番写しにあるハードコード幅（`cart.stories` の `max-w-[1176px]` 等）は本番の記録なので変更しない。**利用側で `Container size="page"` を使う画面はコンテンツ最大幅が 80px 広がる**
+- **実効幅コンテナ規約を導入**: 各シェルの main に `@container` を付与し、ページ内コンテンツの `@md:` / `@lg:` を**ビューポートではなくシェル内の実効幅（サイドバー等を差し引いた本文の実描画幅）**で解決させた（`StandardPageShell` / `FunnelShell` / `MypageShell` / `WorkspaceShell`。`AdminShell` は既存の `@container/main` で対応済み）。狭い本文が誤って多カラム化して窮屈になる破綻を構造的に防ぐ。`StandardPageShell` / `FunnelShell` は main が全幅のため実効幅 ≈ ビューポートで実質不変。**影響が出るのは MypageShell / WorkspaceShell のようにサイドバーを持つシェル内コンテンツ**（例: `MypageShell` のブックマークグリッドは main が最大約 950px で `@lg`(960) に届かないため 3 列化を `@lg:` → `@md:` に変更）。割当の正本は `guidelines/composition/shells.md` の変形段割当表
+- **`WorkspaceShell` の 2 カラム化（左レール／右メタパネルの横並び）を `@md`(768) → `@lg`(960) に変更**。aside 320px を差し引くと 768px では本文が約 400px で窮屈だったため、割る幅に達してから 2 カラム化する。main の縦余白（`@md:py-6`）等は据え置き
+
+- **Storybook の `Shells` セクションの資材配置を正規化**: セクション横断カタログ `Shells/Overview` を `pages/foundation/`（＝shell を呼び出す側・非配布のページ層）から専用の `src/components/shells/` へ移動。重複していた `Pages/Cake/StandardPageShellExample`（`Shells/StandardPageShell` デモおよび `Pages/Cake/ProductList` と内容重複）を削除。公開デプロイ用 glob に `src/components/shells/**` を追加し、置き場の原則（実装＝`primitives/`・`ec/`＝npm 配布／単体デモ＝実装同居 stories＝公開／横断ドキュメント＝`src/components/shells/`＝公開／ページ実例＝`pages/`＝非配布・公開 Storybook 対象外）を `guidelines/composition/shells.md` に明文化。story の `title` は不変（`Shells/Overview`）のため利用側・公開リンクへの影響なし
+
+- **コンテナクエリ境界を本番（cakejp.css）に一致させた**: `--container-md: 48rem`（768px）/ `--container-lg: 60rem`（960px）を `preset.css` の `@theme` で定義。これまで Tailwind v4 既定（`@md`=448px / `@lg`=512px）のままで、本番の SP/PC 境界（767/768）と大きくズレていた——例: 700px 幅でシェルが PC 2カラム化しカードグリッドが崩れる、BottomTabBar が 448px で消える、Header（`@[768px]`明示）とその他（`@md`）で切替点が食い違う等。DS 内 753箇所の `@md:` と 54箇所の `@lg:` が一括で本番と同じ段になる。**利用側もこの境界変更の影響を受ける**（SP レイアウトの適用範囲が 448px→767px に広がる＝本番挙動に一致する方向）
+
+- **`ProductCard`（vertical）に最大幅 `max-w-[280px]` を追加**: 広いグリッドセルに置いてもカードが膨らみすぎないよう上限を設けた（当初 240px で導入し、マイページ等の3列グリッドで活かすため 280px に拡大）。本番の検索結果グリッド（PC 5列 ≈ カード 215〜218px）はキャップ未到達＝見た目変化なし。マイページ等の3列グリッド（実効幅 ~950px）で 3×280+gap が収まる上限として採用。`Shells/StandardPageShell` の検索結果デモは本番と同じ密度（`@[520px]:3列 / @md:4列 / @lg:5列`）に更新
+
+- **`EcPageShell` → `StandardPageShell` に改称**（非破壊）。この骨格に EC 固有の要素は無く、Cake.jp の EC ページも求人検索（jobboard）の「検索と結果の表示」のような消費者向けページも同じシェルで組むため、ドメイン中立な名前に揃えた。兄弟シェル（`WorkspaceShell` / `FunnelShell`）がパターン名で命名されているのに、これだけ面（EC）で命名されていたズレの解消でもある
+  - 旧名 `EcPageShell` / `EcPageShellProps` は **deprecated alias として引き続き export** するため、利用側は無改修で動く。次のメジャーで削除予定
+  - `contracts/components.json` / `screen-patterns.json` / `guidelines/composition/shells.md` の名称と「EC 前提」の文言も中立化
+
+- **シェルの接尾辞を `Shell` に統一（非破壊）**: `AdminLayout` → `AdminShell`、`WorkspaceLayout` → `WorkspaceShell` に改称した。`kind:"shell"` の一級概念・Storybook の `Shells` セクション・「シェル」という語彙に対し、これらだけ `Layout` 接尾辞で命名が混在していたズレの解消。旧名 `AdminLayout` / `WorkspaceLayout`（および Props 型）は `@deprecated` alias として存置するため既存の呼び出しはそのまま動く（次のメジャーで削除）
+- **`MypageShell` のメニュー等を props 化（非破壊）**: サイドバーのメニュー（`menuGroups`）と PC ヘッダーのアクション（`headerActions`）を prop で差し替え可能にした（既定値は従来の Cake.jp EC マイページメニュー）。ジョブボード等の他事業で骨格を再利用しやすくするための実体化。既定のままなら見た目・挙動は不変
+- **`FunnelShell` のヘッダー基本形を本番準拠の中央ロゴに**: `logo` prop を追加し、渡すとヘッダーを `Header variant="logo-center"`（中央ロゴのみ・戻る/タイトルなし）で描画する。ライブ本番の購入導線（cart_layout.ctp の cartHeader）に合わせ、離脱導線をロゴのみに絞る形を基本形にした。従来の `title`（＋`onBack`）による戻る付きヘッダーは、多段申込などタイトル・戻るが要るファネル向けの代替形として存置（後方互換。`title` を optional 化しただけで既存の呼び出しはそのまま動く）。購入確認のデモ（`Shells/FunnelShell` / `Pages/Cake/Checkout`）を中央ロゴ形に更新
+- **`MypageShell` の SP にパンくずを追加**: これまで SP はパンくずが無かった（PC のみ）。`AdminShell` の SP と同様に、SP ヘッダー（戻る）の直下・大タイトルの上に既存の `Breadcrumb` でコンパクトに表示する。crumbs データは PC と共通
+- **ページタイトル `h1` の階級を統一**: 消費者向けシェル（`MypageShell` / `FunnelShell` / 購入導線）の SP ページタイトルを `typo-heading-xl` に揃えた。`Shells/FunnelShell`（`typo-heading-lg` → `xl`）と `Pages/Cake/Checkout`（`typo-heading-2xl` → `xl`）の h1 を更新し、シェルをまたぐタイトルの大きさのばらつきを解消。`guidelines/composition/shells.md` に階級ルールを明文化（管理画面の `typo-heading-2xl` は別文脈として存置）
+
+### 🐛 Fixed
+
+- **`AdminHeader` / `AdminSideNav`**: レール（サイドナビ）が `top-0` 全高＋`pt-16` ハックでヘッダー帯に折り重なり、ヘッダー下線が左端で途切れる構造を解消。ヘッダーを全幅・最前面（`z-40`）、レールをヘッダー下から（`top-16 bottom-0 z-30`）に組み替え。AdminShell を使う全画面に波及する見た目修正（利用側 API 変更なし）
+- **`FunnelShell`**: 進捗インジケータの docstring が実装（ドット上・ラベル下の縦積み／SP でもラベルを省略しない）と食い違っていたのを訂正
+- **`Chip`**: `removable` 指定時に削除ボタンが本体 `<button>` の内側に入れ子でレンダリングされ、React の validateDOMNesting エラー（HTML 違反: button 内 button）が出ていたのを解消。ルートを `<span data-slot="chip">` にし、本体（`data-slot="chip-trigger"`）と削除ボタンを兄弟要素として描画する
+  - 見た目・操作は従来どおり（Tab で本体→削除の順にフォーカス、Enter/Space で発火、フォーカスリングも従来位置）。`removable` 未指定の Chip は DOM 変更なし
+  - 利用側への影響: removable な Chip の DOM 構造（入れ子 button）に依存した CSS セレクタ・テストは追随が必要。次リリースの minor バンプ対象
+- **`DataTableActionCell`**: 行アクションメニューの操作（トリガー／メニュー項目のクリック）が、行の `onClick`（行クリック選択トグル等）まで React 合成イベントとしてバブリングし誤発火していたのを本体側で遮断。Radix の DropdownMenu は DOM 上 Portal 化されても React ツリー上は行の子であるため、利用側でのガード（stories が暫定で行っていた Portal 由来クリックの除外など）は不要になった。あわせて `action.onClick` の型を実挙動に合わせ `() => void` から `(event: React.MouseEvent<HTMLElement>) => void` に拡張（既存の引数なしハンドラ `() => {}` はそのまま代入可）
+- `FunnelShell` の購入確認デモを本番のカート幅（全体1176px・サマリー280/320px）に揃え、注文サマリーの背景面を明示
+- `MypageShell` の商品一覧デモで、カードの幅上限によりPC表示の列間が不均等に見える問題を修正。SP の広め幅（実効幅 520〜767px）も `@[520px]:grid-cols-3` の3列化でセル右の空き（歯抜け）を解消
+- **AdminSideNav**: ダークモードの SP ドロワーでサイドナビ背景が透け、サブメニュー背景との差が出ていたのを修正。ドロワー面とサブメニュー面を不透明なダークサーフェスにし、閉じるボタンを DS の丸型アイコンボタン表現へ統一
+- **Product Grid**: `guidelines/composition/layout.md` と `contracts/composition.json` に残っていた Tailwind 既定のメディアクエリ（`sm` / `lg` = 640 / 1024px）を、DS のコンテナクエリ体系へ統一。ProductCard の標準グリッドは実効幅で 2列（<520px）→3列（`@[520px]`）→4列（`@md` = 768px）→5列（`@lg` = 960px）へ変形する
+
+### 🛡 Internal
+
+- **`npm run check` の型検査を実効化**: 先頭の `tsc --noEmit` がルートの solution-style な `tsconfig.json`（`files: []` + references のみ）を指し、実際には 1 ファイルも型検査していない no-op だった。`-p tsconfig.app.json` を明示指定して app 本体の型検査を実効化
+- **stories の型チェックゲート `typecheck:stories` を追加**: `tsconfig.stories.json`（新設・`tsconfig.app.json` を extends し stories 除外を無効化）で stories を含む `src` 全域を strict 型チェックし、`npm run check` に組み込み（CI は check 経由で自動適用）。現時点の stories 型エラーは 0 件
+
 ---
 
 ## [0.9.0] - 2026-07-08
@@ -152,7 +211,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 #### コンポーネント rename
 
-業界標準命名に揃えました。旧名は `@deprecated` alias として v1.0 まで動作します。
+業界標準命名に揃えました。
+**※訂正（2026-06-12）**: 当初「旧名は `@deprecated` alias として v1.0 まで動作」と記載していましたが、
+alias レイヤーはリリース前（v0.3.0-rc.1）に削除済みで、**v0.3.0 には旧名 alias は含まれていません**（破壊的変更）。
+移行は codemod（`npx @cakejp/design-system codemod v0.2-to-v0.3`）を使用してください。
 
 | Before | After | 理由 |
 |---|---|---|

package/CLAUDE.md

@@ -23,6 +23,7 @@ PdM や社長が AI（Claude 等）で HTML モックを作る際、このパッ
 | **contracts/composition.json** | ページ骨格・余白リズム・視覚階層の組み方 | レイアウト・画面構成を組む時 |
 | **tokens.json** | カラー・タイポグラフィ・スペーシング・影・角丸 | トークン値を参照する時 |
 | **CLAUDE_PRODUCTION.md** | 本番実装参照ルール・Figmaチェックリスト・本番サイト対応表 | 本番再現・新規画面作成時 |
+| **src/components/pages/** | フルページ参照実装（EC 19画面・管理 30画面、Storybook CSF 形式）。**npm 非同梱 — DS リポジトリ（private）を clone して参照** | 既存画面の改修・Next.js 移行で画面を実装する時。使い方は同ディレクトリの README.md |
 
 ---
 

package/MIGRATION.md

@@ -18,18 +18,12 @@ v0.3.0 では **3-tier 構造への再編成** と **業界標準命名への揃
 
 ### 後方互換性
 
-**v0.2.x のコードは v0.3.0 でもそのまま動きます。** 旧名はすべて `@deprecated` alias として残してあります。
+> ⚠️ **v0.3.0 は破壊的変更を含みます。旧名 alias は提供されません。**
+> 当初は `@deprecated` alias で段階的に移行する計画でしたが、リリース前（v0.3.0-rc.1）に
+> alias レイヤーを削除し、v0.3.0 は新 API のみで公開しました。
+> 旧名（`TopAppBar` 等）を import しているコードは **ビルドエラーになります**。
 
-ただし開発環境（`NODE_ENV !== 'production'`）では console に警告が出ます：
-
-```
-[@cakejp/design-system] 'TopAppBar' is deprecated and will be removed in v1.0.
-  → Use 'Header' instead.
-  → Run 'npx @cakejp/design-system codemod v0.2-to-v0.3' to auto-migrate.
-  → See https://github.com/flashpark/cake-design-system/blob/main/MIGRATION.md
-```
-
-**production ビルドには影響しません**（dead code elimination で警告は削除されます）。
+移行は下記の codemod で自動対応できます（数分で完了）。
 
 ### 自動移行
 
@@ -184,17 +178,6 @@ src/components/
 └── ec/            Cake.jp / EC 事業特化（23個）
 ```
 
-### 段階的削除スケジュール
-
-| バージョン | リリース予定 | deprecated alias の状態 |
-|---|---|---|
-| **v0.3.0** | 2026-05 | ✅ 動作（dev mode で console.warn） |
-| **v0.4.0** | 2026-07 予定 | ⚠️ 動作（production でも警告 / runtime warn 強化） |
-| **v0.5.0** | 2026-09 予定 | 🚨 動作（npm install 時 peer warning） |
-| **v1.0.0** | 2026-11 予定 | ❌ 完全削除 |
-
-利用側は **v0.4 までに移行完了** が推奨。Codemod を使えば数分で対応可能です。
-
 ### 移行進捗の自己診断
 
 利用側プロジェクトで残作業を可視化：
@@ -205,17 +188,6 @@ npx @cakejp/design-system check-migration ./src
 # → 残工数（n 件中 m 件移行済み）を報告
 ```
 
-### ESLint plugin（v0.4 で導入予定）
-
-```json
-// .eslintrc.json
-{
-  "extends": ["@cakejp/design-system/eslint"]
-}
-```
-
-旧名 import がエディタで赤線エラー、`--fix` で自動修正。
-
 ### サポート
 
 質問・問題報告は GitHub Issue: https://github.com/flashpark/cake-design-system/issues

package/README.md

@@ -41,6 +41,7 @@ import "@cakejp/design-system/dist/index.css"
 - [Storybook](https://flashpark.github.io/cake-design-system/) — 全コンポーネントのカタログ
 - [CHANGELOG.md](./CHANGELOG.md) — リリース履歴
 - [MIGRATION.md](./MIGRATION.md) — バージョン間移行ガイド
+- [UPDATING.md](./UPDATING.md) — 利用側リポジトリのアップデート手順（いつ・誰が・どうやって）
 - [PUBLISHING.md](./PUBLISHING.md) — 公開とタグ付けのクイックガイド（人向け）
 - [RELEASE.md](./RELEASE.md) — リリース運用ルール（週1手動・詳細）
 - [CLAUDE.md](./CLAUDE.md) — AI エージェント向け使用ルール

package/UPDATING.md

@@ -0,0 +1,215 @@
+# 利用側アップデートガイド（UPDATING.md）
+
+> **このファイルは `@cakejp/design-system` を利用するリポジトリ（cake-api/frontend 等）の開発者向けです。**
+> DS を npm に publish する側の手順は [RELEASE.md](./RELEASE.md) / [PUBLISHING.md](./PUBLISHING.md) を参照。
+
+DS の新バージョンが出たあと、**いつ・誰が・どうやって**利用側リポジトリのバージョンを上げるかのマニュアル。
+
+---
+
+## 前提: 勝手にバージョンは上がらない
+
+package.json の指定が `"^0.6.0"` のような **0.x + キャレット**の場合、
+`npm install` を何度叩いても **同じマイナー（0.6.x）のパッチ更新しか取り込まれません**。
+
+- `^0.6.0` → 0.6.1, 0.6.2 … は入る / **0.7.0 は入らない**
+- つまり「DS がリリースしたら利用側が壊れる」ことはない
+- 裏返すと「**利用側が明示的に作業しないと永久に古いまま**」
+
+アップデートは常に**意図的な PR 作業**として行う。これがこのマニュアルの大前提。
+
+---
+
+## バージョンの読み方（0.x 期間中）
+
+| 上がった桁 | 例 | 中身 | 利用側の対応 |
+|---|---|---|---|
+| **パッチ** | 0.6.0 → 0.6.1 | バグ修正のみ・互換性あり | すぐ上げてよい |
+| **マイナー** | 0.6.0 → 0.7.0 | 機能追加・**視覚変更や deprecated を含むことがある** | CHANGELOG / MIGRATION を読んでから |
+| **メジャー** | 0.x → 1.0.0 | 破壊的変更（deprecated alias の完全削除等） | MIGRATION 必読・計画的に |
+
+変更内容は必ず [CHANGELOG.md](./CHANGELOG.md)（`node_modules/@cakejp/design-system/CHANGELOG.md` にも同梱）で確認する。
+
+---
+
+## どのタイミングで各桁が上がるか（DS 側の bump 基準）
+
+DS チームがリリース取りまとめ時（金曜）に以下の基準で判断し、CHANGELOG に記載する。
+利用側は「次のリリースがどの桁か」をこの基準から予測できる。
+
+### パッチが上がるとき（0.6.0 → 0.6.1）
+
+- バグ修正のみ
+- 互換性のある内部改善のみ（リファクタ・依存更新・パフォーマンス改善）
+- ドキュメント修正のみ
+
+→ **見た目も API も変わらない**。利用側のコード修正は不要。
+
+### マイナーが上がるとき（0.6.0 → 0.7.0）
+
+次のいずれかが 1 つでも含まれるリリース:
+
+- **新規追加**: 新コンポーネント・新 variant・新 prop・新トークン
+- **視覚変更**: 既存コンポーネントの色・余白・角丸・フォント等、レンダリング結果が変わる変更
+- **deprecated の追加**: 旧 API はまだ動くが、新 API への移行が始まる（console 警告が出るようになる）
+- **0.x 期間中の破壊的変更**: semver の慣習上、1.0 未満では破壊的変更もマイナーで入りうる
+  （その場合は CHANGELOG に **BREAKING** と明記し、MIGRATION.md と codemod を用意する）
+
+→ **コードは動くが、画面の見た目が変わったり警告が出たりする可能性がある**。CHANGELOG 確認必須。
+
+### メジャーが上がるとき（0.x → 1.0.0、以降 1.x → 2.0.0）
+
+- **1.0.0**: API 安定宣言（以降、破壊的変更はメジャーでのみ行うことを約束する）
+- **1.0 以降**: 利用側のコード修正が必須になる変更が入るときだけ
+  - コンポーネント・prop の削除
+  - デフォルト挙動の変更
+  - peerDependencies の必須バージョン引き上げ（例: React 19 必須化）
+
+→ **上げると既存コードが壊れる前提**。MIGRATION.md に従って計画的に移行する。
+
+---
+
+## いつアップデートするか
+
+DS のリリースサイクル（[RELEASE.md](./RELEASE.md)）が前提:
+
+- **月曜**: DS チームが npm publish → Slack で告知
+- 利用側は **告知のあった週の火〜木** にアップデート PR を作るのを推奨
+
+| タイミング | やる / やらない |
+|---|---|
+| リリース告知の週（火〜木） | ✅ 推奨。問題があれば DS 側がその週内に patch 対応できる |
+| パッチリリース（バグ修正） | ✅ 気づいたら早めに |
+| 緊急パッチ（セキュリティ・本番障害修正） | ✅ 告知され次第**即日** |
+| 金曜・連休前 | ❌ 避ける（Read-Only Friday。DS 側と同じ理由） |
+| 自リポジトリの大型リリース直前 | ❌ 避ける。リリース後に落ち着いてから |
+
+**放置の上限の目安: マイナー 2 世代**。
+（例: DS が 0.8 の時に自分がまだ 0.6 なら危険信号。migration の差分が貯まるほど一度に上げるコストが跳ね上がる）
+
+---
+
+## 誰がアップデートするか
+
+> ⚠️ ここはチームで運用を確定したら書き換えること。以下はデフォルト案。
+
+| 役割 | 担当 |
+|---|---|
+| アップデート PR の作成・動作確認 | **各利用リポジトリのオーナー**（そのリポジトリにマージ権限を持つ開発者） |
+| アップデート PR のレビュー・マージ | 同リポジトリの通常のレビューフロー |
+| CHANGELOG / MIGRATION の整備・告知 | DS チーム |
+| アップデートで見つかった DS 側の不具合修正 | DS チーム（Issue を受けて patch リリース） |
+
+原則: **DS チームは利用側リポジトリの package.json を直接書き換えに行かない**。
+利用側のコードに責任を持つ人が、自分のタイミングで・自分のテストで上げる。
+
+---
+
+## どうやってアップデートするか（手順）
+
+### 1. 新バージョンと変更内容を確認
+
+```bash
+# 最新バージョン
+npm view @cakejp/design-system version
+
+# 自分が今使っているバージョン
+npm ls @cakejp/design-system
+```
+
+CHANGELOG の該当バージョンの項を読む。**視覚変更（色・余白・角丸等）の有無**は特に確認。
+
+### 2. ブランチを切って更新
+
+```bash
+git checkout -b chore/update-design-system-0.7.0
+
+# バージョンを明示して install（package.json も ^0.7.0 に更新される）
+npm install @cakejp/design-system@0.7.0
+```
+
+`@latest` でもよいが、PR に書くバージョンと一致させるため明示推奨。
+
+### 3. 移行チェック（マイナー/メジャーアップデート時のみ）
+
+```bash
+# 旧 API（deprecated）の利用箇所を可視化
+npx @cakejp/design-system check-migration ./src
+
+# 残っていれば codemod で自動移行（対象バージョンは MIGRATION.md 参照）
+npx @cakejp/design-system codemod v0.2-to-v0.3 ./src
+```
+
+手動対応が必要なケースは [MIGRATION.md](./MIGRATION.md) のリファレンスに従う。
+
+### 4. ビルド・動作確認
+
+```bash
+npm run build
+npm run lint
+npm run test   # あれば
+```
+
+- 開発サーバーで **DS コンポーネントを使っている主要画面を目視確認**
+- マイナーアップデートで視覚変更が告知されている場合は、対象画面のビフォー/アフターのスクリーンショットを PR に貼る
+- dev console に `[@cakejp/design-system] ... is deprecated` 警告が出ていないか確認
+
+### 5. PR 作成・マージ
+
+- タイトル例: `chore(deps): @cakejp/design-system 0.6.0 → 0.7.0`
+- 本文に入れるもの:
+  - CHANGELOG 該当バージョンへのリンク
+  - check-migration の結果（旧 API 残 0 件、等）
+  - 視覚変更があればスクリーンショット
+- マージ後、デプロイ先（ステージング等）でも一度確認
+
+---
+
+## していい？ダメ？早見表
+
+| 状況 | 判断 |
+|---|---|
+| パッチ（0.6.0 → 0.6.1）に上げたい | ✅ いつでも。レビューも軽くてよい |
+| マイナー（0.6 → 0.7）に上げたい | ✅ CHANGELOG / MIGRATION を読み、手順 3〜4 を実施した上で |
+| マイナーを 2 つ飛ばして上げたい（0.5 → 0.7） | ⚠️ 可能だが間の MIGRATION を全部読むこと。check-migration 必須 |
+| メジャー（→ 1.0）に上げたい | ⚠️ MIGRATION 必読。不明点は DS チームに相談してから |
+| package.json を `*` や `latest` 指定にしたい | ❌ 禁止。再現性が壊れる。`^x.y.z` 固定で明示アップデート |
+| DS の中身を node_modules 直編集 / patch-package | ❌ 禁止。DS リポジトリに Issue / PR を出す |
+| アップデートと機能開発を同じ PR でやる | ❌ 分ける。壊れた時に切り分けできなくなる |
+
+---
+
+## トラブル時
+
+### アップデートしたら壊れた
+
+```bash
+# 1. 直前のバージョンに戻す（package.json ごと戻る）
+npm install @cakejp/design-system@0.6.0
+
+# 2. DS リポジトリに Issue を立てる
+#    - 壊れたバージョン / 直前のバージョン
+#    - 再現手順・エラーメッセージ・スクリーンショット
+```
+
+https://github.com/flashpark/cake-design-system/issues
+
+DS 側で patch リリース後、改めて上げ直す。
+
+### npm に新バージョンが見えない
+
+publish 直後は npm キャッシュ反映に **30〜90 秒**かかる。少し待って再実行。
+
+### peer dependency の警告が出る
+
+DS の peerDependencies（react ^18 || ^19、radix-ui 等）と自リポジトリの依存がズレている。
+`npm ls <パッケージ名>` で衝突を確認し、CHANGELOG に peer 変更の記載がないか見る。
+
+---
+
+## 関連ドキュメント
+
+- [CHANGELOG.md](./CHANGELOG.md) — 各バージョンの変更内容
+- [MIGRATION.md](./MIGRATION.md) — バージョン間の移行手順・codemod
+- [RELEASE.md](./RELEASE.md) — DS 側のリリース運用（曜日・publish フロー）
+- [PUBLISHING.md](./PUBLISHING.md) — publish 操作のクイックガイド

package/contracts/components.json

@@ -3,7 +3,7 @@
     "name": "Cake.jp Design System — Component Contracts",
     "version": "0.1.0",
     "description": "全コンポーネントの構造化定義。バリアント・アクセシビリティ要件・使用ルールを機械可読形式で管理。",
-    "kind": "kind:\"shell\" は複数ページで再利用されるレイアウト枠（AdminLayout / WorkspaceLayout / MypageShell 等）。無印は部品コンポーネント。固有ページを組むときは該当 shell から始める。src/components/pages/ 配下のストーリーは特定ページ専用・非配布のため contracts の対象外。",
+    "kind": "kind:\"shell\" は複数ページで再利用されるレイアウト枠（AdminShell / WorkspaceShell / MypageShell 等）。無印は部品コンポーネント。固有ページを組むときは該当 shell から始める。src/components/pages/ 配下のストーリーは特定ページ専用・非配布のため contracts の対象外。",
     "counts": {
       "foundations": 47,
       "primitives": 42,
@@ -149,7 +149,8 @@
       "name": "DataTable",
       "path": "src/components/foundations/data-table.tsx",
       "rules": [
-        "管理画面のテーブルはui/tableでなくこちらを使う。ソート・選択行・アクションメニュー対応"
+        "管理画面のテーブルはui/tableでなくこちらを使う。ソート・選択行・アクションメニュー対応",
+        "ActionCellのメニュー操作は行のonClickへ伝播しない（本体でstopPropagation済み）。行クリック選択との併用時も利用側ガードは不要"
       ]
     },
     {
@@ -621,33 +622,34 @@
         "ページ内セクション移動（アンカー／目次）専用。href=\"#section-id\" のページ内スクロールに使う",
         "ページ間遷移に使わない → SideNav を使う",
         "チェブロン・矢印を足さない（遷移アフォーダンスを持たせない。同一画面内の位置移動に見せる）",
-        "WorkspaceLayout の sectionNav にはこれを使う（SideNav を流用しない）",
+        "WorkspaceShell の sectionNav にはこれを使う（SideNav を流用しない）",
         "固有幅・背景・境界を持たない（w-full）。パネル化・幅決定はシェル／利用側の責務"
       ]
     },
     {
-      "name": "EcPageShell",
-      "path": "src/components/primitives/ec-page-shell.tsx",
+      "name": "StandardPageShell",
+      "path": "src/components/primitives/standard-page-shell.tsx",
       "kind": "shell",
       "variants": [],
       "rules": [
-        "EC 標準ページ（Standard Page（View / Edit））の骨格。composition.json pageSkeletons（mobile / desktop）の実装体。min-h-dvh flex flex-col の全高コンテナに header / main / bottomTab / footer を積む",
-        "あくまで枠。Cake.jp のロゴ・タブ項目・ナビ項目・文言を焼き込まない。header / bottomTab は利用側（ec 層）が組み立てて渡す",
+        "消費者向け標準ページ（Standard Page（View / Edit））の骨格。composition.json pageSkeletons（mobile / desktop）の実装体。min-h-dvh flex flex-col の全高コンテナに header / main / bottomTab / footer を積む",
+        "名前はプロダクト・ドメインに依存しない。EC ページも求人検索のような消費者向けページも同じシェルで組む（旧名 EcPageShell は deprecated alias）",
+        "あくまで枠。プロダクトのロゴ・タブ項目・ナビ項目・文言を焼き込まない。header / bottomTab は利用側（ec 層）が組み立てて渡す",
         "bottomTab を渡すと main の下余白（pb-20 相当）はシェルが管理する。ページ側で pb-20 を書かない（付け忘れ／二重がけの構造的防止）",
         "左右 padding は持たない（Container の責務）。中身は Section（全幅背景帯）＋ Container（中央寄せ・左右余白）で組む",
-        "管理画面は AdminLayout、複数情報をまたぐ集中編集は WorkspaceLayout、マイページ配下は MypageShell を使う"
+        "管理画面は AdminShell、複数情報をまたぐ集中編集は WorkspaceShell、マイページ配下は MypageShell を使う"
       ]
     },
     {
-      "name": "WorkspaceLayout",
-      "path": "src/components/primitives/workspace-layout.tsx",
+      "name": "WorkspaceShell",
+      "path": "src/components/primitives/workspace-shell.tsx",
       "kind": "shell",
       "variants": [],
       "rules": [
         "Focused Workspace（全画面集中編集）のシェル。編集ヘッダー（Header variant=back）+ 任意のセクションナビ + 編集本体で構成",
         "グローバルナビ・パンくずを持たない（構造的に置けない）。集中を妨げる導線は出さない",
         "primaryActionはワークスペース全体の上位アクション（公開申請・承認依頼等）がある場合のみ。セクション／行単位の操作はコンテンツ内に置く",
-        "標準の編集はAdminLayoutのStandard Page（Edit）（旧Form Page）。複雑・複数情報をまたぐ集中編集・没入執筆のみWorkspaceLayoutを使う",
+        "標準の編集はAdminShellのStandard Page（Edit）（旧Form Page）。複雑・複数情報をまたぐ集中編集・没入執筆のみWorkspaceShellを使う",
         "sectionNavは編集内ナビ（アンカー／ステップ）のみ。PCでサイド表示・SPで非表示"
       ]
     },
@@ -657,11 +659,12 @@
       "kind": "shell",
       "variants": [],
       "rules": [
-        "EC 購入導線等のファネル用集中モード（Full Page）のシェル。集中ヘッダー（Header variant=back）＋進捗インジケータ（steps/activeStep）＋ステップ本体＋任意の bottomAction で構成。min-h-dvh flex flex-col の全高コンテナ",
+        "EC 購入導線等のファネル用集中モード（Full Page）のシェル。集中ヘッダー＋進捗インジケータ（steps/activeStep）＋ステップ本体＋任意の bottomAction で構成。min-h-dvh flex flex-col の全高コンテナ",
+        "ヘッダーの基本形は中央ロゴ（logo prop → Header variant=logo-center）。ライブ本番の購入導線（cart_layout.ctp の cartHeader）準拠で離脱導線をロゴのみに絞る。狙いは戻り・離脱をしづらくして途中離脱を抑制すること（＝Header の logo-center は決済・申込ページ用の既定バリアント、本番 cartHeader もロゴクリックが /cart/・thanks に限定）。title+back（Header variant=back）は多段申込等でタイトル・戻るが要る場合の代替形。logo と title はどちらか一方を渡す（logo 優先）",
         "あくまで枠。ステップ定義（名前・数）・文言・商品データを焼き込まない。steps / activeStep は利用側（ドメイン）が渡す",
         "グローバルナビ・BottomTabBar・パンくずを持たない（構造的に置けない）。離脱を誘う導線を出さず購入に集中させる",
         "bottomAction（StickyActionBar 等）を渡すと本文の下余白はシェルが管理する。ページ側で pb を書かない（付け忘れ／二重がけの構造的防止）",
-        "左右 padding は持たない（Container の責務）。管理画面の複雑な集中編集は WorkspaceLayout を使う（EC 購入導線＝FunnelShell）"
+        "左右 padding は持たない（Container の責務）。管理画面の複雑な集中編集は WorkspaceShell を使う（EC 購入導線＝FunnelShell）"
       ]
     },
     {
@@ -674,7 +677,7 @@
       "category": "navigation",
       "rules": [
         "管理画面向けサイドナビの汎用枠。PC は左端固定アイコンレール（ホバーでサブメニュー）、SP は制御ドロワー（サブメニューはアコーディオン）",
-        "項目データ（メニュー定義・文言）は全て items prop で受ける。特定事業のメニューを部品側に焼き込まない（Cake.jp 既定は AdminLayout が持つ）",
+        "項目データ（メニュー定義・文言）は全て items prop で受ける。特定事業のメニューを部品側に焼き込まない（Cake.jp 既定は AdminShell が持つ）",
         "SP ドロワー開閉は open / onOpenChange で制御する（内部 state を持たない）",
         "icon は ReactNode か描画コンテキスト（active / placement）で出し分ける関数を渡す"
       ]
@@ -691,13 +694,16 @@
   ],
   "ec": [
     {
-      "name": "AdminLayout",
-      "path": "src/components/ec/admin-layout.tsx",
+      "name": "AdminShell",
+      "path": "src/components/ec/admin-shell.tsx",
       "kind": "shell",
       "rules": [
         "管理画面のレイアウトシェル。枠は primitives の AdminSideNav / AdminHeader を組み込む",
-        "Cake.jp 管理メニュー8項目＋サブメニュー・通知ベル・プロフィール・『{shopName}管理』を既定値として内蔵する（ドメイン特化層）",
-        "navItems で既定メニューを差し替え可、headerActions でヘッダー右アクションを差し替え可"
+        "Cake.jp 管理メニュー8項目＋サブメニュー・通知ベル・プロフィール・『{shopName}管理』を既定値として同梱する（ec 層）",
+        "navItems で既定メニューを差し替え可、headerActions でヘッダー右アクションを差し替え可",
+        "戻る導線（onBack）はパンくずの上に置く。onBack を渡すとシェルが main 内・パンくずより上に戻るボタンを描画する（backLabel で文言変更・既定『戻る』）。子コンテンツ内に戻るリンクを手書きしない",
+        "タイトル直下の上位アクション（AI商品作成・PDF出力等）は h1 と同じ左端に左寄せする。右端フロートにしない",
+        "既定値は props で差し替え可能で、骨格（Header + SideNav + Main）自体は他事業（ジョブボードの管理画面等）でも再利用できる"
       ]
     },
     {
@@ -715,7 +721,8 @@
       "rules": [
         "マイページ配下の固有ページ（注文履歴 / ポイント / クーポン / 会員情報 / お届け先 / ブックマーク / 口コミ / 記念日 等）はこの shell で組む",
         "本番の mypage_layout.ctp + menu.ctp 準拠。SP は Header(variant=back)+h1+コンテンツ+BottomTabBar、PC は Header(variant=logo)+Breadcrumb+2カラム（SideNav 256px + main）",
-        "サイドナビは ec/_mypage-menu-data の mypageMenuGroups を使用。activeMenu で現在ページを強調する",
+        "サイドナビは既定で ec/_mypage-menu-data の mypageMenuGroups を使用。activeMenu で現在ページを強調する",
+        "既定値は props で差し替え可能（menuGroups / breadcrumbs / bottomNavItems / headerActions）で、骨格（ヘッダー＋2カラム＋BottomTabBar）自体は他事業（ジョブボードのマイページ等）でも再利用できる",
         "breadcrumbs 省略時は「ホーム > {ユーザー}さまのマイページ > {title}」を自動生成する",
         "マイページトップ（Dashboard）はメインカラムを白背景で持たずセクションごとにカード化する別パターンなので、この shell を使わない"
       ]

package/contracts/composition.json

@@ -12,7 +12,7 @@
     "mobile": {
       "requiredComponents": ["Header", "BottomTabBar"],
       "optionalComponents": ["StickyActionBar", "CategoryScroll", "CategoryShortcuts"],
-      "implementation": "EcPageShell（primitives, kind:\"shell\"）がこの骨格の実装体。header に Header・bottomTab に BottomTabBar を渡す。bottomTab を渡すと main の下余白（pb-20 相当）をシェルが管理するので、ページ側で pb-20 を書かない。手組みの独自シェルを作らない。",
+      "implementation": "StandardPageShell（primitives, kind:\"shell\"）がこの骨格の実装体。header に Header・bottomTab に BottomTabBar を渡す。bottomTab を渡すと main の下余白（pb-20 相当）をシェルが管理するので、ページ側で pb-20 を書かない。手組みの独自シェルを作らない。",
       "structure": [
         "ルート: div.flex.min-h-dvh.flex-col（縦フレックスの全高コンテナ。背景は bg-[var(--Surface-Primary)] を明示）",
         "上部固定: Header（title / onBack。旧称 TopAppBar）",
@@ -30,7 +30,7 @@
     "desktop": {
       "requiredComponents": ["Container"],
       "optionalComponents": ["Section", "SectionHeader"],
-      "implementation": "EcPageShell（primitives, kind:\"shell\"）が mobile と共通の実装体。PC では bottomTab（BottomTabBar）が消え下余白も外れる。左右 padding は Container・全幅背景帯は Section が持ち、シェルは持たない。手組みの独自シェルを作らない。",
+      "implementation": "StandardPageShell（primitives, kind:\"shell\"）が mobile と共通の実装体。PC では bottomTab（BottomTabBar）が消え下余白も外れる。左右 padding は Container・全幅背景帯は Section が持ち、シェルは持たない。手組みの独自シェルを作らない。",
       "structure": [
         "ルート: div.flex.min-h-screen（横フレックス。サイドバー＋本文）",
         "ナビ: aside（サイドバーまたは上部ナビ。border-r border-[var(--Border-Medium-Emphasis)] で仕切る）",
@@ -44,15 +44,15 @@
       ]
     },
     "admin": {
-      "requiredComponents": ["AdminLayout", "AdminSideNav", "AdminHeader"],
+      "requiredComponents": ["AdminShell", "AdminSideNav", "AdminHeader"],
       "optionalComponents": ["SectionHeader", "DataTable", "Section", "Container"],
       "structure": [
-        "ルート: AdminLayout（管理画面の専用シェル。サイドナビ AdminSideNav・ヘッダー AdminHeader を内包）",
-        "サイドナビ・ヘッダーは AdminLayout 経由で組み込まれる（AdminSideNav / AdminHeader を直接手組みしない）",
-        "本文: AdminLayout の children に space-y-6 のコンテナを置き、ページタイトル（typo-heading-2xl）＋管理コンテンツを並べる"
+        "ルート: AdminShell（管理画面の専用シェル。サイドナビ AdminSideNav・ヘッダー AdminHeader を内包）",
+        "サイドナビ・ヘッダーは AdminShell 経由で組み込まれる（AdminSideNav / AdminHeader を直接手組みしない）",
+        "本文: AdminShell の children に space-y-6 のコンテナを置き、ページタイトル（typo-heading-2xl）＋管理コンテンツを並べる"
       ],
       "rules": [
-        "管理画面のシェルは AdminLayout を使い、手組みしない",
+        "管理画面のシェルは AdminShell を使い、手組みしない",
         "管理画面の表は DataTable を使う（生の table 禁止）",
         "ページ直下のセクション間は space-y-6 相当（管理画面の縦リズム）"
       ]
@@ -73,18 +73,37 @@
         "グローバルナビ・BottomTabBar・パンくずを置かない（離脱を誘う導線を出さず購入に集中させる）",
         "進捗を表示する（steps / activeStep でユーザーの現在地を示す）",
         "下部 CTA（StickyActionBar）は bottomAction に渡す。本文の下余白はシェルが管理するのでページ側で pb を書かない",
-        "管理画面の複雑な集中編集は WorkspaceLayout を使う（EC 購入導線＝FunnelShell）"
+        "管理画面の複雑な集中編集は WorkspaceShell を使う（EC 購入導線＝FunnelShell）"
       ]
     }
   },
+  "breakpoints": {
+    "description": "役割は二層。切替段=md / lg の2段だけで、ページのレイアウト変形はこの2段で考える（独自のブレイクポイント値を発明しない）。上限段=xl（1280）は「切替段」ではなく DS が定めるコンテンツ幅の上限段（ページコンテナの標準上限）で、1280px 以上では原則レイアウト変形を追加しない。",
+    "sourceOfTruth": "値の正本は tokens.json の breakpoints。実装参照は preset.css の @theme（コンテナクエリ変数 --container-md / --container-lg / --container-xl）。",
+    "scale": [
+      { "token": "md", "px": 768, "container": "--container-md", "role": "切替段", "meaning": "SP/PC 境界。767px 以下=SP / 768px 以上=PC。本番 cakejp.css の max-width:767px / min-width:768px と一致" },
+      { "token": "lg", "px": 960, "container": "--container-lg", "role": "切替段", "meaning": "PC 中段。本番 cakejp.css の min-width:960px 段と一致" },
+      { "token": "xl", "px": 1280, "container": "--container-xl", "role": "上限段", "meaning": "コンテンツ上限段（切替段ではない）。ページコンテナの標準上限で、1280px 以上では原則レイアウト変形を追加しない。本番 cakejp.css に 1280 の切替段は無い——DS が定める標準上限。実例: MypageShell の PC グリッド max-w-[1280px]" }
+    ],
+    "rules": [
+      "DS 内部はコンテナクエリ @md: / @lg: を SP-first（モバイル既定→上書き）で使う（例: flex-col @md:flex-row）",
+      "生 CSS の消費者は 767 / 768 / 960 の px 値をメディアクエリに直書きする（CSS 変数はメディアクエリに使えないため）",
+      "任意値（@[520px] 等）はコンポーネント都合の例外。ページ設計では md / lg を使う",
+      "xl=1280 は切替段ではなく上限段。レイアウトの変形（カラム追加・並べ替え等）は md / lg の2段でのみ行い、xl はページコンテナの最大幅（max-w-[1280px] 等）として使う。1280px 以上で新たな変形を追加しない",
+      "コンテンツの @md: / @lg: はビューポートではなくシェルが main に提供する実効幅コンテナ（@container）基準で解決される。サイドバー等を差し引いた実際の描画幅で応答する（例: MypageShell の main は上限1280−サイド256−gap で最大約950px＝@lg には到達しない。PC で3列にしたいグリッドは @md: を使う）",
+      "シェル自身の変形（レール表示・BottomTabBar 出没・2カラム化・グリッド split）はシェルのルートコンテナ＝ビューポート基準のままにする。シェルごとの変形段の割当は guidelines/composition/shells.md の割当表が正本（StandardPageShell: header nav・BottomTabBar=md / AdminShell: レール=md / MypageShell: 2カラム=md / WorkspaceShell: 2カラム=lg / FunnelShell: サマリ横並び=md〔本番準拠〕）"
+    ]
+  },
   "productGrid": {
-    "description": "商品グリッドのブレークポイント別列数と gap。ProductCard を並べる際の標準。",
+    "description": "ProductCard を並べる標準グリッド。ビューポートではなくシェルが提供する実効幅コンテナで変形する。md / lg の値は tokens.json の breakpoints が正本。520px は ProductCard の最小幅を守るためのコンポーネント固有の例外であり、ページ全体のブレイクポイントではない。",
     "breakpoints": [
-      { "viewport": "mobile", "width": "< 640px", "columns": 2, "gap": "gap-3", "tailwind": "grid-cols-2 gap-3" },
-      { "viewport": "tablet", "width": "640–1024px", "columns": 3, "gap": "gap-4", "tailwind": "sm:grid-cols-3 sm:gap-4" },
-      { "viewport": "desktop", "width": "> 1024px", "columns": 4, "gap": "gap-4", "tailwind": "lg:grid-cols-4" }
+      { "containerWidth": "< 520px", "columns": 2, "gap": "gap-4", "tailwind": "grid-cols-2 gap-4" },
+      { "containerWidth": "520–767px", "columns": 3, "gap": "gap-4", "tailwind": "@[520px]:grid-cols-3" },
+      { "containerWidth": "768–959px", "columns": 4, "gap": "gap-4", "tailwind": "@md:grid-cols-4", "token": "breakpoints.md" },
+      { "containerWidth": "960px+", "columns": 5, "gap": "gap-4", "tailwind": "@lg:grid-cols-5", "token": "breakpoints.lg" }
     ],
-    "example": "grid grid-cols-2 gap-3 sm:grid-cols-3 sm:gap-4 lg:grid-cols-4",
+    "container": "w-full @container",
+    "example": "grid grid-cols-2 gap-4 @[520px]:grid-cols-3 @md:grid-cols-4 @lg:grid-cols-5",
     "component": "ProductCard"
   },
   "spacingRhythm": {