@cakejp/design-system 0.17.1 → 0.20.0

package/CHANGELOG.md

@@ -9,6 +9,91 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.20.0] - 2026-08-20
+
+ダークモードで浮遊レイヤー（メニュー・ポップオーバー・ダイアログ・シート）の地が半透明で、後ろのコンテンツが透けていた問題の修正を中心に、開閉アニメーションの配布漏れ・`AdminSideNav` サブメニューの標準化・`DataTable` 系の root export をまとめた回。**公開 API の破壊的変更はなし。** ただし次の 3 点は既定の見た目・挙動が変わる。
+
+- ダークモードで浮遊レイヤーの地が半透明の黒 → 不透明のグレーになる（ライトモードは変更なし）
+- 同じくダークモードで、エッジ固定バー（`Header` / `StickyActionBar` / `BottomTabBar` / `AdminHeader` / `AdminSideNav` のレール / `OrderSummary` の fixed 表示）の地も不透明のグレーになる（ライトモードは変更なし）
+- tw-animate-css を自分で入れていなかった consumer では、メニュー・ダイアログ等の**開閉アニメーションが新たに効き始める**（`prefers-reduced-motion` では従来どおり停止）
+- `AdminSideNav` の PC サブメニューが標準 overlay（`DropdownMenu` 合成）になる
+
+### ✨ Added
+
+- **`--Surface-Elevated` トークンを追加**: 浮遊レイヤー専用の**不透明**サーフェス。light は `#FFFFFF`（`Surface-Primary` と同値）、dark は `#3A3736`（`Primitive-Gray-800`）。ページ地として設計された `Surface-Primary` は dark でアルファ付き（`#000000E5`）のため、任意のコンテンツの上に重なる浮遊レイヤーには使えない。`preset-standalone.css` / `tokens.json` にも配布する
+- **`DataTable` の実装済み subcomponent と `SortDirection` 型を root export**: `DataTableTable` / `DataTableHeader` / `DataTableBody` / `DataTableRow` / `DataTableHead` / `DataTableCell` と、セル・一括操作・空状態など全19部品を `@cakejp/design-system` から直接 import できる。consumer は配布対象外の内部パスや互換 wrapper に依存せず、標準の表現を組み合わせられる（[#270](https://github.com/flashpark/cake-design-system/issues/270)）
+- **`BookmarkRibbonIcon` を root export**: `size` / `filled` を指定して、商品カードと同じブックマーク意匠を consumer から直接利用できる。互換 wrapper で同じアイコンを再実装する必要がなくなる（[#271](https://github.com/flashpark/cake-design-system/issues/271)）
+- **AI 向けルールを「コピー」から「参照」へ変更**: `init` / postinstall が consumer ルートへ置くのはルール本文ではなく、package 内の正本を指す**ポインタ**（`templates/*.stub.md`）になった。DS 側のルール更新が `npm install` だけで既存 consumer にも届く。ルール本文の正本は `node_modules/@cakejp/design-system/templates/AGENTS.md` / `CLAUDE.md`（[#263](https://github.com/flashpark/cake-design-system/issues/263)）
+
+  **既存 consumer の移行**（初回のみ手作業。以後は不要）:
+  1. 自分の `AGENTS.md` / `CLAUDE.md` から、DS 共通ルールを写した部分を削除する
+  2. 代わりに次の 1 行を置く: `DS 共通ルールは node_modules/@cakejp/design-system/templates/AGENTS.md（Claude は CLAUDE.md）を読む`
+  3. プロジェクト固有のルールはそのまま残す
+
+  移行しない場合も動作は変わらないが、DS 側のルール更新は届かないままになる。
+
+### 🐛 Fixed
+
+- **ダークモードで `DropdownMenu` / `Popover` / `Select` / `HoverCard` / `Command` / `ContextMenu` / `Menubar` のメニュー面が半透明で、後ろのコンテンツが透けていた問題を修正**: `--popover` が `--Surface-Primary`（dark = `#000000E5` = 10% 透過）を指していた。`--Surface-Elevated` に向け直して不透明にする（[#262](https://github.com/flashpark/cake-design-system/issues/262)）
+- **同じ理由で `Sheet` / `Dialog` / `AlertDialog` / `Drawer` の地も半透明だった問題を修正**: `bg-background`（= `--Surface-Primary`）から `bg-[var(--Surface-Elevated)]` へ。`Dialog` だけは以前から `dark:bg-[var(--Primitive-Gray-800)]` の個別対処が入っていたため**見た目は変わらない**（トークン経由に置き換えただけ）。他の 3 つは dark で地が変わる
+- **preset がアニメーションユーティリティ（tw-animate-css）を配っておらず、consumer で開閉アニメーションが無言で効いていなかった問題を修正**: foundations の 12 部品（Dialog / Sheet / Popover / DropdownMenu / Select / Tooltip / Drawer / AlertDialog / HoverCard / ContextMenu / Menubar / NavigationMenu）が `animate-in` / `zoom-in-95` / `slide-in-from-*` を使うが、これらは Tailwind 本体ではなく tw-animate-css のユーティリティで、DS の devDependency のままだった。たまたま自分でも tw-animate-css を入れていた consumer（cake-api / kakeyasan-jp）だけアニメーションが動き、入れていない consumer（cakejp-biz-mag）では動かなかった。`tw-animate-css` を dependency に昇格し、`preset` が `@import` して配る。**consumer 側の設定変更は不要**（既に自分で import している場合は重複しても無害。自前の import と依存は削除してよい）
+- **ダークモードでエッジ固定バーの地が半透明で、スクロールした内容が透けていた問題を修正**: `Header`（sticky） / `StickyActionBar` / `BottomTabBar` / `AdminHeader` / `AdminSideNav` のレール / `OrderSummary`（fixed 表示）が `bg-[var(--Surface-Primary)]`（dark = 10% 透過）を地にしていた。浮遊レイヤーと同じ `--Surface-Elevated` へ変更。**ライトモードは同値（`#FFFFFF`）のため変化なし**。ページ内フローに置かれる面（`OrderSummary disableFixed` / カード類）は重なりが発生しないため `Surface-Primary` のまま
+- **`AdminSideNav` のPCサブメニューを標準overlayへ統一**: 自作の絶対配置flyoutを `DropdownMenu` 合成へ置き換え、下端寄り・12件以上でもviewport内へ収まるようにした。hover時はフォーカスを奪わず、クリック・Enter・Space・ArrowDown・Escapeでも操作できる。ダークモードでは不透明な `Surface-Elevated`、標準枠・影・重なり順を使う（[#272](https://github.com/flashpark/cake-design-system/issues/272)）
+
+### 📝 Docs
+
+- **`linkComponent` の React Server Components 境界を部品別に明記**: Client Component の `Footer` / `MenuDrawer` へ Server Component から渡すと `Functions cannot be passed directly to Client Components` で落ちるため、Next.js App Router では呼び出し側を `"use client"` にする。一方、`Pagination` / `SubNav` / `ContentCard` は Server Component のまま利用でき、この prop のためだけに `"use client"` を付ける必要はない。契約・JSDoc に追記（[#264](https://github.com/flashpark/cake-design-system/issues/264)）
+
+## [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 へ上げてください。**

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
@@ -87,6 +102,7 @@ PdM や社長が AI（Claude 等）で HTML モックを作る際、このパッ
 | テキスト（中） | `var(--color-gray-600)` |
 | テキスト（弱） | `var(--color-gray-400)` |
 | エラー | `var(--color-red-500)` |
+| 浮遊レイヤーの地（メニュー・ポップオーバー・ダイアログ・シート） | `var(--Surface-Elevated)` |
 | 成功 | `var(--color-green-500)` |
 
 詳細は `tokens.json` を参照。

package/bin/init.js

@@ -11,8 +11,8 @@
 //   npx cakejp-ds init --force  # 既存ファイルを上書き
 //   npx cakejp-ds postinstall   # npm postinstall から呼ばれる silent モード
 
-import { copyFileSync, existsSync, readdirSync } from "node:fs"
-import { dirname, join, resolve } from "node:path"
+import { copyFileSync, existsSync, readFileSync, realpathSync, readdirSync } from "node:fs"
+import { dirname, join, resolve, sep } from "node:path"
 import { fileURLToPath } from "node:url"
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
@@ -94,25 +94,186 @@ if (cmd !== "init" && cmd !== "postinstall") {
 }
 
 // ─── postinstall モードのガード ─────────────────────────────
-// INIT_CWD は npm install が実行されたディレクトリ（consumer のルート）。
+function findDirectPackageInstallRoot(packageRoot) {
+  const parts = resolve(packageRoot).split(sep)
+  for (let i = parts.length - 3; i >= 0; i--) {
+    if (parts[i] !== "node_modules" || parts[i + 1] !== "@cakejp" || parts[i + 2] !== "design-system") {
+      continue
+    }
+
+    const candidate = parts.slice(0, i).join(sep) || sep
+    if (existsSync(join(candidate, "package.json"))) {
+      return candidate
+    }
+  }
+
+  return undefined
+}
+
+function readWorkspacePatterns(root) {
+  const patterns = []
+
+  try {
+    const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"))
+    if (Array.isArray(pkg.workspaces)) patterns.push(...pkg.workspaces)
+    if (Array.isArray(pkg.workspaces?.packages)) patterns.push(...pkg.workspaces.packages)
+  } catch {
+    // package.json が無い・壊れている場合は pnpm-workspace.yaml の確認へ進む。
+  }
+
+  try {
+    patterns.push(...readPnpmWorkspacePatterns(join(root, "pnpm-workspace.yaml")))
+  } catch {
+    // pnpm-workspace.yaml が無い・壊れている場合は通常の単一 package として扱う。
+  }
+
+  return [...new Set(patterns)]
+}
+
+function readPnpmWorkspacePatterns(file) {
+  if (!existsSync(file)) return []
+
+  const patterns = []
+  let inPackages = false
+  for (const rawLine of readFileSync(file, "utf8").split(/\r?\n/)) {
+    const withoutComment = rawLine.replace(/\s+#.*$/, "")
+    const line = withoutComment.trim()
+    if (!line) continue
+
+    if (!inPackages) {
+      const inlineMatch = line.match(/^packages:\s*\[(.*)\]$/)
+      if (inlineMatch) {
+        patterns.push(...parseYamlInlineSequence(inlineMatch[1]))
+        continue
+      }
+      inPackages = line === "packages:"
+      continue
+    }
+
+    if (/^\S[^:]*:/.test(withoutComment)) break
+
+    const match = line.match(/^-\s+['"]?([^'"]+)['"]?$/)
+    if (match) patterns.push(match[1])
+  }
+
+  return patterns
+}
+
+function parseYamlInlineSequence(value) {
+  return value
+    .split(",")
+    .map((item) => item.trim().replace(/^['"]|['"]$/g, ""))
+    .filter(Boolean)
+}
+
+function hasWorkspaceConfig(root) {
+  try {
+    const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"))
+    if (Array.isArray(pkg.workspaces) || Array.isArray(pkg.workspaces?.packages)) return true
+  } catch {
+    // package.json が無い・壊れている場合は pnpm-workspace.yaml の有無だけを見る。
+  }
+
+  return existsSync(join(root, "pnpm-workspace.yaml"))
+}
+
+function expandWorkspaceRoots(root) {
+  const roots = new Set([root])
+  const workspacePatterns = readWorkspacePatterns(root)
+
+  for (const pattern of workspacePatterns) {
+    if (typeof pattern !== "string") continue
+
+    if (!pattern.includes("*")) {
+      roots.add(resolve(root, pattern))
+      continue
+    }
+
+    if (pattern.endsWith("/**")) {
+      collectPackageRoots(resolve(root, pattern.slice(0, -3)), roots)
+      continue
+    }
+
+    // npm/pnpm workspaces で一般的な apps/* / packages/* を展開する。
+    // それ以外の複雑な glob は安全に無視する。
+    if (!pattern.endsWith("/*") || pattern.includes("**")) continue
+
+    const parent = resolve(root, pattern.slice(0, -2))
+    if (!existsSync(parent)) continue
+
+    for (const entry of readdirSync(parent, { withFileTypes: true })) {
+      if (entry.isDirectory()) roots.add(join(parent, entry.name))
+    }
+  }
+
+  return [...roots].filter((candidate) => existsSync(join(candidate, "package.json")))
+}
+
+function collectPackageRoots(dir, roots) {
+  if (!existsSync(dir)) return
+
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue
+    if (["node_modules", ".git", ".hg", ".svn", ".pnpm"].includes(entry.name)) continue
+
+    const full = join(dir, entry.name)
+    if (existsSync(join(full, "package.json"))) {
+      roots.add(full)
+    }
+    collectPackageRoots(full, roots)
+  }
+}
+
+function findLinkedConsumerRoots(packageRoot, requestedRoot) {
+  const realPackageRoot = realpathSync(packageRoot)
+  return expandWorkspaceRoots(requestedRoot).filter((workspaceRoot) => {
+    const installedPackage = join(workspaceRoot, "node_modules/@cakejp/design-system")
+    if (!existsSync(installedPackage)) return false
+    try {
+      return realpathSync(installedPackage) === realPackageRoot
+    } catch {
+      return false
+    }
+  })
+}
+
+function findConsumerRoots(packageRoot, requestedRoot) {
+  const roots = new Set()
+  const directRoot = findDirectPackageInstallRoot(packageRoot)
+  if (directRoot) roots.add(directRoot)
+  for (const linkedRoot of findLinkedConsumerRoots(packageRoot, requestedRoot)) {
+    roots.add(linkedRoot)
+  }
+  if (roots.size === 0 && !hasWorkspaceConfig(requestedRoot)) roots.add(requestedRoot)
+  return [...roots].filter((candidate) => existsSync(join(candidate, "package.json")))
+}
+
+// INIT_CWD は npm install が実行されたディレクトリ。
+// monorepo では root になり、実際の consumer package は frontend/node_modules 等にある
+// ため、postinstall では package の配置場所から consumer package root を優先して決める。
 // 未設定、または pkgRoot と同じ場合は DS 自身のインストールコンテキストなのでスキップ。
 const isPostinstall = cmd === "postinstall"
-const consumerRoot = process.env.INIT_CWD || process.cwd()
+const requestedRoot = resolve(process.env.INIT_CWD || process.cwd())
+const consumerRoots = isPostinstall ? findConsumerRoots(pkgRoot, requestedRoot) : [requestedRoot]
 
 if (isPostinstall) {
   // DS 自身を開発している場合（INIT_CWD が pkgRoot）はスキップ
-  if (!process.env.INIT_CWD || resolve(consumerRoot) === pkgRoot) {
+  if (!process.env.INIT_CWD || requestedRoot === pkgRoot) {
     process.exit(0)
   }
   // consumer のルートに package.json が無ければスキップ（安全のため）
-  if (!existsSync(join(consumerRoot, "package.json"))) {
+  if (consumerRoots.length === 0) {
     process.exit(0)
   }
 }
 
+// consumer へ設置するのは「正本を参照するポインタ」だけ（issue #87 / #263）。
+// ルール本文（templates/AGENTS.md / CLAUDE.md）は package 内に置いたまま読ませる。
+// 本文をコピーすると、DS 側の更新が既存 consumer へ二度と届かない
+// （postinstall は既存ファイルを上書きしないため）。
 const files = [
-  { src: "templates/AGENTS.md", dest: "AGENTS.md", label: "Codex 用" },
-  { src: "templates/CLAUDE.md", dest: "CLAUDE.md", label: "Claude Code 用" },
+  { src: "templates/AGENTS.stub.md", dest: "AGENTS.md", label: "Codex 用" },
+  { src: "templates/CLAUDE.stub.md", dest: "CLAUDE.md", label: "Claude Code 用" },
 ]
 
 if (!isPostinstall) {
@@ -123,32 +284,34 @@ if (!isPostinstall) {
 let created = 0
 let skipped = 0
 
-for (const { src, dest, label } of files) {
-  const srcPath = join(pkgRoot, src)
-  const destPath = join(consumerRoot, dest)
+for (const consumerRoot of consumerRoots) {
+  for (const { src, dest, label } of files) {
+    const srcPath = join(pkgRoot, src)
+    const destPath = join(consumerRoot, dest)
 
-  if (!existsSync(srcPath)) {
-    if (!isPostinstall) {
-      console.error(`  ✗ テンプレートが見つかりません: ${srcPath}`)
+    if (!existsSync(srcPath)) {
+      if (!isPostinstall) {
+        console.error(`  ✗ テンプレートが見つかりません: ${srcPath}`)
+      }
+      process.exit(isPostinstall ? 0 : 1)
     }
-    process.exit(isPostinstall ? 0 : 1)
-  }
 
-  if (existsSync(destPath) && !force) {
-    if (!isPostinstall) {
-      console.log(`  ⏭  ${dest} は既に存在するためスキップ（--force で上書き）`)
+    if (existsSync(destPath) && !force) {
+      if (!isPostinstall) {
+        console.log(`  ⏭  ${dest} は既に存在するためスキップ（--force で上書き）`)
+      }
+      skipped++
+      continue
     }
-    skipped++
-    continue
-  }
 
-  copyFileSync(srcPath, destPath)
-  if (isPostinstall) {
-    console.log(`[@cakejp/design-system] ${dest} をプロジェクトルートに設置しました`)
-  } else {
-    console.log(`  ✓ ${dest} を設置しました（${label}）`)
+    copyFileSync(srcPath, destPath)
+    if (isPostinstall) {
+      console.log(`[@cakejp/design-system] ${dest} をプロジェクトルートに設置しました`)
+    } else {
+      console.log(`  ✓ ${dest} を設置しました（${label}）`)
+    }
+    created++
   }
-  created++
 }
 
 if (isPostinstall) {