@cakejp/design-system 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -9,6 +9,91 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-07-22
+
+### ⚠️ Upgrade impact
+
+- **minor リリース・破壊的変更なし**: 追加はすべて後方互換（新 prop はデフォルト値が現行挙動）。視覚変更もなし。`^0.10.0` からは `npm install @cakejp/design-system@0.11.0` で安全に上げられる
+- consumer 統合カスケード（#83 / #86 / #87 / #88）を収録。他ブランド consumer（仕入れEC等）が `MypageShell` を手組みシェルの代わりに採用できる状態になる回
+
+### ✨ Added
+
+- **`MypageShell` に PC ヘッダーの `logo` / `navItems` prop を追加**: これまで PC ヘッダーのロゴが内蔵 `CakeLogo` にハードコードされ、グローバルナビの差し込み口も無かったため、他ブランドの consumer がこのシェルを採用すると**マイページ配下だけ Cake.jp ロゴにブランドが割れて**採用を見送っていた（手組みのマイページシェルに退行）。`logo?: ReactNode`（既定=`CakeLogo`）と `navItems?: HeaderNavItem[]`（既定=なし）を追加し、自社ロゴ・自社グローバルナビへ差し替え可能にした。命名・建て付けは同じ `Header` を使う `FunnelShell` の `logo` prop と整合。既定値は現行のままで**後方互換**（既存の Cake.jp マイページは無変更）。これで既存の `menuGroups` / `headerActions` / `breadcrumbs` / `bottomNavItems` と合わせ PC ヘッダーまでブランド差し替えが揃い、consumer は手組みシェルを DS `MypageShell` に置換できる。※ SP ヘッダーは `variant="back"`（戻るボタン）でロゴを表示しないため `logo` は PC のみに作用する（[#88](https://github.com/flashpark/cake-design-system/issues/88)）
+- **`SideNav` のアクティブ判定を「key 完全一致のみ」から拡張**: `MypageShell` 化で各ページが `activeMenu`（string）でサイドバーのアクティブ項目を指定する形になったが、`SideNav` が `item.key === activeMenu` の完全一致でしか判定できず、詳細・配下ページ（`/mypage/orders/123/` 等）で「どの項目もアクティブにならない」か、一覧と同じ `activeMenu` を無理に渡して実 URL と乖離していた。`SideNav` に3段階の判定を追加（優先順位: 述語 > URL 照合 > key 完全一致）: **`currentPath?: string`**（現在 URL を href と照合して自動判定）、**`activeMatch?: "exact" | "prefix"`**（既定 `exact`。`prefix` は配下ページ全体でアクティブにし、複数一致時は最長 href の1項目のみ＝親子の二重アクティブを防ぐ）、**`isActive?: (item) => boolean`**（consumer 固有の URL 集約ロジックを注入）。`MypageShell` にも `currentPath` / `activeMatch` / `isActiveMenuItem` を透過追加し、`activeMenu` を optional 化（URL 自動判定時は不要）。既定は完全一致のままで**後方互換**（[#86](https://github.com/flashpark/cake-design-system/issues/86)）
+
+### 🐛 Fixed
+
+- **#83 ハードニング — CSS セットアップ反転（PR #84）後に残った穴を3点塞いだ**（アーキ変更なし。`@source` 単一ビルド方式の確実化）:
+  1. **dist CSS ファイル名の誤設定を修正**: `vite.config.lib.ts` の `cssFileName: "styles"` は公開 exports（`./dist/index.css`・`./styles.css`→`index.css`）とドキュメントの降格パス案内が指す `dist/index.css` と食い違っていた。実測では Vite が entry 名で `dist/index.css` を出力し設定は無視されていた（＝現状 404 は起きていない）が、将来 Vite がこの設定を尊重し始めると Tailwind 非使用 consumer の `@import ".../dist/index.css"` が静かに壊れる罠のため、実出力・exports と一致する `"index"` に修正
+  2. **guidelines の反転漏れを修正**: `guidelines/setup.md`（Required CSS）と `guidelines/overview.md` が PR #84 前の `preset` 単独 import のままで、setup.md には「preset に Tailwind 設定が含まれる」という誤記もあった（実際 `src/preset.css` は `@import "tailwindcss"` を含まない）。両方を `@source` 単一ビルド方式＋降格パス＋併用警告に更新し、README の警告実害例にも `MenuDrawer` を追記して templates と一致させた
+  3. **整合ガードテストを新設**（`__tests__/css-setup-integrity.test.ts`）: ①`cssFileName` と exports の dist CSS 参照の一致 ②consumer 向け全ドキュメント（README / templates 2種 / guidelines 2種）に `@source` 推奨スニペットが存在 ③併用警告の実害例（Header/Footer/MenuDrawer）が全ファイルで一致——を静的に固定し、反転状態の再ドリフトを防ぐ（[#83](https://github.com/flashpark/cake-design-system/issues/83)）
+- **optional 依存 6 種を通常 `dependencies` に昇格し、未インストールの利用側でのビルド破綻を解消**: `dist/index.js`（単一バンドル）が `cmdk` / `next-themes` / `react-day-picker` / `react-hook-form` / `sonner` / `vaul` を**静的 import** しているのに、これらは optional な `peerDependencies` 扱いだった。そのため利用側がこの 6 種を入れずに DS の任意コンポーネント（例: `Footer`）を import すると、Vite/Rollup が解決に失敗してビルドが落ちていた（`"getDefaultClassNames" is not exported by "__vite-optional-peer-dep:react-day-picker..."` 等。[#84](https://github.com/flashpark/cake-design-system/pull/84) の検証で判明）。6 種を `peerDependencies` / `peerDependenciesMeta` から外し、同じ semver レンジのまま通常 `dependencies` に移した。**利用側の対応は不要**——`npm install @cakejp/design-system` で 6 種が自動的に入る。`@hookform/resolvers` / `date-fns` / `zod` は引き続き optional peer（実際に使う画面のみ導入すればよい）
+
+### 📝 Docs
+
+- **SectionHeader の適用範囲を明確化＋consumer 向け AI 参照の存在を保証**: cake-api の設計書で「SectionHeader 手書き禁止」が**通常の文書見出しまで一律禁止**と読める形で広く適用されていた。実際に必須なのは SectionHeader が担う2パターン（①「タイトル + もっと見る/すべて見るアクション」②中央寄せ大見出し）だけで、素の semantic heading は対象外。AI 向け要約（`CLAUDE.md` / `AGENTS.md`）と `contracts/rules.json`（R48）の表現をこの区別に統一（正典は `contracts/components.json` の SectionHeader `rules`）。あわせて **consumer 向け AI ルールファイルの参照整合**を整理: `npx cakejp-ds init` が置く `AGENTS.md` / `CLAUDE.md` は薄いポインタで、正典は `node_modules/@cakejp/design-system/{CLAUDE.md,contracts/*,tokens.json}`（すべて npm 同梱・複製なし）。`node_modules/@cakejp/design-system/AGENTS.md` は**同梱されない**（DS リポ内部の dev 用）ため参照先は `CLAUDE.md` に統一。既存 consumer の更新手順（`npx cakejp-ds init --force`）を `UPDATING.md` に明記し、テンプレの参照先が全て `files` で配布・実在することを固定するテスト（`__tests__/consumer-ref-integrity.test.ts`）を追加。SectionHeader の公開 API は不変（[#87](https://github.com/flashpark/cake-design-system/issues/87)）
+- **CSS セットアップの推奨構成を反転**: 従来推奨だった「プリビルド `dist/index.css` + consumer の `@import "tailwindcss"`」は**独立した 2 ビルド**になり、consumer が DS と同名ユーティリティ（`.hidden` 等）を 1 箇所でも使うと、同一 `@layer utilities` 内の宣言順で consumer の基底ルールが DS のバリアント（`@lg:block` 等）を打ち消す構造的欠陥があった（`Header` / `Footer` の永久モバイル表示・タブのアクティブ下線消失など）。推奨を **`@source` 単一ビルド方式**（`@import "tailwindcss"` + `preset` + `@source ".../dist/index.js"`）へ変更し、`dist/index.css` 方式は「consumer が Tailwind を使わない場合のみ」に降格。併用時の警告も明記。対象: `README.md` / `templates/CLAUDE.md` / `templates/AGENTS.md`。パッケージ同梱物（`dist/index.js` / `preset`）だけで成立し、実体変更は不要（[#83](https://github.com/flashpark/cake-design-system/issues/83)）
+
+## [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
+
+- プロトタイプビューアー、既存モック、`/mock` スキル、スクリーンショットスクリプトを専用の `cake-prototypes` リポジトリへ分離。DS 本体はコンポーネント・contracts・Storybook の提供に専念し、プロトタイプ側は公開パッケージ `@cakejp/design-system` を consumer として利用する構成へ変更
+- **`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 +237,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 |
 
 ---
 
@@ -82,4 +83,4 @@ PdM や社長が AI（Claude 等）で HTML モックを作る際、このパッ
 - **aria-label**: 日本語で記述 — 英語 aria-label 禁止
 - **input type="date"**: 使用禁止 — Popover と Calendar を組み合わせる
 - **Tag に onClick**: 禁止 — 押せるものは Chip を使う
-- **SectionHeader 手書き**: 禁止 — `SectionHeader` コンポーネントを使う
+- **SectionHeader が担う「パターン」の手書き**: 禁止 — 次の2パターンは `SectionHeader` を使う。①「タイトル + もっと見る/すべて見るアクション」の並び、②中央寄せの大見出し（ランディング/ガイド系。`align="center"`、eyebrow に Badge 等）。**通常の文書見出し（`<h1>`〜`<h6>` 相当の素の semantic heading）まで SectionHeader に置き換える意味ではない** — 見出し単体なら `typo-heading-*` を付けた素の heading 要素でよい。正典は `contracts/components.json` の SectionHeader `rules`

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

@@ -12,17 +12,42 @@ npm install @cakejp/design-system
 
 ```tsx
 import { Button, ProductCard, Header } from "@cakejp/design-system"
-import "@cakejp/design-system/dist/index.css"
 
 <Header logo={<MyLogo />} variant="logo" />
 <ProductCard ... />
 <Button>カートに入れる</Button>
 ```
 
-> **`dist/index.css` の import は必須。**
-> このCSSにはカラートークン定義に加え、Tailwind v4 のベースレイヤー（`* { border-color: var(--border) }` 等）が含まれます。
-> import しないと、Tailwind v4 の border-color 既定が `currentColor` のままになり、コンポーネントの罫線や枠線がその要素の文字色に化けます（例: テーブルの行罫線が黒くなる）。
-> 自前の Tailwind 設定にマージしたい場合は `@cakejp/design-system/preset`（base レイヤー込み）を参照してください。
+### CSS のセットアップ
+
+**consumer が Tailwind v4 を使う場合（推奨）** — エントリ CSS で単一ビルドに統一する:
+
+```css
+@import "tailwindcss";
+@import "@cakejp/design-system/preset";                          /* トークン・typo-*・コンテナ段・dark variant */
+@source "../node_modules/@cakejp/design-system/dist/index.js";   /* DS の className を consumer と同一ビルドで生成 */
+```
+
+ユーティリティのビルドが 1 つに統一されるため「基底→バリアント」の整列が保証され、
+consumer が DS と同名のユーティリティ（`.hidden` 等）を使っても DS のバリアント
+（`@lg:block` 等）が正しく後勝ちする。`@source` のパスは CSS ファイルからの相対で、
+`node_modules/@cakejp/design-system/dist/index.js` を指すこと。
+
+**consumer が Tailwind を使わない場合のみ** — プリビルド CSS を import:
+
+```tsx
+import "@cakejp/design-system/dist/index.css"
+```
+
+このCSSにはカラートークン定義に加え、Tailwind v4 のベースレイヤー
+（`* { border-color: var(--border) }` 等）が含まれます。
+
+> ⚠️ **Tailwind v4 を併用する構成でプリビルド `dist/index.css` を使わないこと。**
+> DS のプリビルド CSS と consumer の Tailwind は独立した 2 ビルドで、同名ユーティリティを
+> 同じ `@layer utilities` へ二重出力する。後段（consumer）の基底ルールが DS のバリアント
+> ルールを宣言順で打ち消し、`Header` / `Footer` / `MenuDrawer` がデスクトップ幅でも永久モバイル表示に
+> なる等の不具合が出る（import 順の入れ替えでは解決しない）。Tailwind 併用時は上の
+> `@source` 方式を使う。詳細は [#83](https://github.com/flashpark/cake-design-system/issues/83)。
 
 ## 構造
 
@@ -41,6 +66,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,251 @@
+# 利用側アップデートガイド（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 件、等）
+  - 視覚変更があればスクリーンショット
+- マージ後、デプロイ先（ステージング等）でも一度確認
+
+---
+
+## AI ルールファイル（AGENTS.md / CLAUDE.md）の更新
+
+利用側リポジトリのルートにある `AGENTS.md`（Codex 用）/ `CLAUDE.md`（Claude Code 用）は、
+`npx cakejp-ds init`（または postinstall）が設置した**薄いポインタ**。禁止パターン・props・variant・
+トークンといったルールの実体は**複製していない**——正典は常に node_modules 側にある。
+
+### 参照すべき正典（package 内に実在するもの）
+
+| 参照先 | 内容 |
+|---|---|
+| `node_modules/@cakejp/design-system/CLAUDE.md` | DS 利用ガイド・禁止パターンの要点 |
+| `node_modules/@cakejp/design-system/contracts/*.json` | components / rules / screen-patterns / composition |
+| `node_modules/@cakejp/design-system/tokens.json` | カラー・余白・角丸・影・タイポ |
+
+- **Codex 用の `AGENTS.md` も、Claude 用の `CLAUDE.md` も、同じ上記 `CLAUDE.md` + `contracts` を指すポインタ**。
+  ルールの一次情報は 1 箇所（DS 同梱の `CLAUDE.md` + `contracts`）に集約されている。
+- ⚠️ **`node_modules/@cakejp/design-system/AGENTS.md` は同梱されない**（それは DS リポジトリ内部の
+  開発者向け Codex ファイル）。利用側の生成済み `AGENTS.md` がこのパスを参照していたら、
+  参照先を `node_modules/@cakejp/design-system/CLAUDE.md` に直すか、下記 `--force` で再設置する。
+
+### DS を更新したあと
+
+ルールの実体は node_modules 側なので、**DS のバージョンを上げれば禁止パターン等は自動的に最新**になる
+（ポインタ側の再設置は通常不要）。ただし**テンプレート自体が更新された**とき——参照先パスの追加や
+CSS セットアップ手順の変更（例: `@source` 単一ビルド方式への移行）——は、ポインタを貼り直す:
+
+```bash
+# 既存の AGENTS.md / CLAUDE.md を最新テンプレートで上書き再設置
+npx cakejp-ds init --force
+```
+
+`--force` を付けないと既存ファイルはスキップされる（上書きされない）。CHANGELOG に
+「`templates/AGENTS.md` / `templates/CLAUDE.md` を更新」と記載があった回だけ実行すればよい。
+
+---
+
+## していい？ダメ？早見表
+
+| 状況 | 判断 |
+|---|---|
+| パッチ（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 操作のクイックガイド