@cakejp/design-system 0.10.0 → 0.12.0

package/src/preset-standalone.css

@@ -26,11 +26,312 @@
  * 以下の「Typography Helper」セクションで提供する。
  * ============================================ */
 
-/* --- Layer 1: Primitive Colors --- */
-@import "./styles/primitive.css";
+/* --- Layer 1: Primitive Colors ---
+ *
+ * 正本 src/styles/primitive.css のメインカラーファミリー（Orange/Gray/Forest/
+ * Sun/Teal/Sea/Wood/Berry/Black）は `@theme { ... }` ブロック内にあり、Tailwind CSS v4 の
+ * ビルド時変数解決に依存するため、Tailwind を通さない consumer（素の HTML + `<link>`）では
+ * ブロックごと無効な CSS として破棄され、`var(--Primitive-Gray-900)` 等が一切解決されない
+ * （`@import` するだけでは効かない。#113 と同根で、実機 Chromium で `getComputedStyle` を
+ * 検証して確認済み。primitive.css の alpha 変数は素の `:root` にあるので効いている）。
+ * そのため、primitive.css の全トークン（@theme のカラーファミリー全量 + :root の alpha 全量）を
+ * 素の `:root` として値ごと逐語展開している。
+ *
+ * primitive.css を変更した場合は、このブロックも合わせて更新すること
+ * （整合は __tests__/preset-standalone-coverage.test.ts でガードしている）。
+ */
+:root {
+  /* Orange */
+  --Primitive-Orange-50: #FFECD9FF;
+  --Primitive-Orange-100: #FFD4B2FF;
+  --Primitive-Orange-200: #FFBA84FF;
+  --Primitive-Orange-300: #FFA66BFF;
+  --Primitive-Orange-400: #FF8E4CFF;
+  --Primitive-Orange-500: #F97732FF;
+  --Primitive-Orange-600: #F16311FF;
+  --Primitive-Orange-700: #E04B00FF; /* primary */
+  --Primitive-Orange-800: #BD3200FF;
+  --Primitive-Orange-900: #A62700FF;
+
+  /* Gray */
+  --Primitive-Gray-50: #FBF9F8FF;
+  --Primitive-Gray-100: #F4F2F1FF;
+  --Primitive-Gray-200: #EBE9E8FF;
+  --Primitive-Gray-300: #DBD9D8FF;
+  --Primitive-Gray-400: #B7B5B4FF;
+  --Primitive-Gray-500: #979594FF;
+  --Primitive-Gray-600: #787675FF;
+  --Primitive-Gray-700: #575352FF;
+  --Primitive-Gray-800: #3A3736FF;
+  --Primitive-Gray-900: #1C1A1AFF;
+
+  /* Forest */
+  --Primitive-Forest-50: #E6F5ECFF;
+  --Primitive-Forest-100: #C2E5D1FF;
+  --Primitive-Forest-200: #9BD4B5FF;
+  --Primitive-Forest-300: #71C598FF;
+  --Primitive-Forest-400: #51B883FF;
+  --Primitive-Forest-500: #2CAC6EFF;
+  --Primitive-Forest-600: #259D63FF;
+  --Primitive-Forest-700: #1D8B56FF;
+  --Primitive-Forest-800: #197A4BFF; /* primary */
+  --Primitive-Forest-900: #115A36FF;
+
+  /* Sun */
+  --Primitive-Sun-50: #FFE7E6FF;
+  --Primitive-Sun-100: #FFC8B8FF;
+  --Primitive-Sun-200: #FFA28BFF;
+  --Primitive-Sun-300: #FF7B5CFF;
+  --Primitive-Sun-400: #FF5838FF;
+  --Primitive-Sun-500: #FF4B36FF;
+  --Primitive-Sun-600: #FF220DFF;
+  --Primitive-Sun-700: #FA1606FF;
+  --Primitive-Sun-800: #EC0000FF; /* primary */
+  --Primitive-Sun-900: #D50000FF;
+
+  /* Teal */
+  --Primitive-Teal-50: #F0FCF8FF;
+  --Primitive-Teal-100: #D0F6E9FF;
+  --Primitive-Teal-200: #ACEED8FF;
+  --Primitive-Teal-300: #81E6C4FF;
+  --Primitive-Teal-400: #59D9AEFF;
+  --Primitive-Teal-500: #51C79FFF;
+  --Primitive-Teal-600: #49B18EFF;
+  --Primitive-Teal-700: #3E987AFF;
+  --Primitive-Teal-800: #317860FF; /* primary */
+  --Primitive-Teal-900: #1D4739FF;
+
+  /* Sea */
+  --Primitive-Sea-50: #E8F1FEFF;
+  --Primitive-Sea-100: #C5D7FBFF;
+  --Primitive-Sea-200: #9DB7F9FF;
+  --Primitive-Sea-300: #7096F8FF;
+  --Primitive-Sea-400: #4979F5FF;
+  --Primitive-Sea-500: #295FF3FF;
+  --Primitive-Sea-600: #003EE5FF; /* primary */
+  --Primitive-Sea-700: #0031D8FF;
+  --Primitive-Sea-800: #0024CEFF;
+  --Primitive-Sea-900: #0017B6FF;
+
+  /* Wood */
+  --Primitive-Wood-50: #F8F1E0FF;
+  --Primitive-Wood-100: #EFDBB1FF;
+  --Primitive-Wood-200: #E5C47FFF;
+  --Primitive-Wood-300: #DCAC4DFF;
+  --Primitive-Wood-400: #D69C2BFF;
+  --Primitive-Wood-500: #D18D0FFF;
+  --Primitive-Wood-600: #CD820AFF;
+  --Primitive-Wood-700: #C87504FF;
+  --Primitive-Wood-800: #C16800FF; /* primary */
+  --Primitive-Wood-900: #B65200FF;
+
+  /* Berry */
+  --Primitive-Berry-50: #FBD4E0FF;
+  --Primitive-Berry-100: #F7B1C8FF;
+  --Primitive-Berry-200: #F491B2FF;
+  --Primitive-Berry-300: #F1749EFF;
+  --Primitive-Berry-400: #EE598BFF;
+  --Primitive-Berry-500: #EC407AFF;
+  --Primitive-Berry-600: #EA296AFF;
+  --Primitive-Berry-700: #E5175CFF; /* primary */
+  --Primitive-Berry-800: #B5175CFF;
+  --Primitive-Berry-900: #9E103FFF;
+
+  /* Black */
+  --Primitive-Black-2-1000: #000000FF;
 
-/* --- Layer 2: Semantic Colors (+ dark mode) --- */
-@import "./styles/semantic.css";
+  /* Gray alpha */
+  --Primitive-Gray-alpha-50: #0000000D;
+  --Primitive-Gray-alpha-100: #0000001A;
+  --Primitive-Gray-alpha-200: #00000033;
+  --Primitive-Gray-alpha-300: #0000004D;
+  --Primitive-Gray-alpha-400: #00000066;
+  --Primitive-Gray-alpha-500: #00000080;
+  --Primitive-Gray-alpha-600: #00000099;
+  --Primitive-Gray-alpha-700: #000000B2;
+  --Primitive-Gray-alpha-800: #000000CC;
+  --Primitive-Gray-alpha-900: #000000E5;
+  --Primitive-Gray-alpha-1000: #000000FF;
+
+  /* White alpha */
+  --Primitive-White-alpha-50: #FFFFFF0D;
+  --Primitive-White-alpha-100: #FFFFFF1A;
+  --Primitive-White-alpha-200: #FFFFFF33;
+  --Primitive-White-alpha-300: #FFFFFF4D;
+  --Primitive-White-alpha-400: #FFFFFF66;
+  --Primitive-White-alpha-500: #FFFFFF80;
+  --Primitive-White-alpha-600: #FFFFFF99;
+  --Primitive-White-alpha-700: #FFFFFFB2;
+  --Primitive-White-alpha-800: #FFFFFFCC;
+  --Primitive-White-alpha-900: #FFFFFFE5;
+  --Primitive-White-alpha-1000: #FFFFFFFF;
+}
+
+/* --- Layer 2: Semantic Colors (+ dark mode) ---
+ *
+ * 正本 src/styles/semantic.css は `@theme inline` 構文（Tailwind CSS v4 の
+ * ビルド時変数解決に依存）のため、Tailwind を通さない consumer では
+ * ブロックごと無視され、CSS変数として一切展開されない（`@import` するだけでは効かない）。
+ * そのため、以下は semantic.css の light/dark 値を tokens.json の hex キャッシュ
+ * （および tokens.json 未収録グループは primitive 実値）まで解決し、
+ * 素の `:root` / `.dark` として展開したもの。
+ *
+ * 展開対象（全 76 semantic トークン名）: Surface-* / Text-* / Object-* / Hover-* /
+ * Active-* / Border-* / Brand-* / Overlay-* / Surface-Glass-* / Caution-* /
+ * Focus-High-Emphasis / Third-Party-*。一覧・hex 整合は
+ * __tests__/preset-standalone-coverage.test.ts でガードしている。
+ *
+ * semantic.css を変更した場合は、この2ブロックも合わせて再生成すること
+ * （tokens.json の hex キャッシュ + src/styles/semantic.css の var() チェーンを
+ * 解決するスクリプトで手で写経せず生成し、貼り直す）。
+ */
+:root {
+  --Surface-Primary: #FFFFFF;
+  --Surface-Secondary: #FBF9F8;
+  --Surface-Tertiary: #F4F2F1;
+  --Surface-Caution: #EC0000;
+  --Surface-Caution-Light: #FFE7E6;
+  --Surface-Accent-Primary: #E04B00;
+  --Surface-Accent-Primary-Light: #FFECD9;
+  --Surface-Success: #259D63;
+  --Surface-Warning: #F8F1E0;
+  --Surface-Info: #003EE5;
+  --Surface-Info-Light: #E8F1FE;
+  --Text-High-Emphasis: #1C1A1A;
+  --Text-Medium-Emphasis: #575352;
+  --Text-Low-Emphasis: #787675;
+  --Text-Disable: #B7B5B4;
+  --Text-Accent-Primary: #E04B00;
+  --Text-Accent-Secondary: #FFBA84;
+  --Text-on-Inverse: #FFFFFF;
+  --Text-Success: #259D63;
+  --Text-Caution: #EC0000;
+  --Text-Warning: #C16800;
+  --Text-Info: #003EE5;
+  --Object-Favorite: #E04B00;
+  --Object-Accent-Primary: #E04B00;
+  --Object-Accent-Primary-Light: #FFECD9;
+  --Object-High-Emphasis: #1C1A1A;
+  --Object-Medium-Emphasis: #575352;
+  --Object-Low-Emphasis: #787675;
+  --Object-Disable: #B7B5B4;
+  --Object-High-Emphasis-on-Inverse: #FFFFFF;
+  --Object-Caution: #EC0000;
+  --Object-Warning: #C16800;
+  --Object-Success: #259D63;
+  --Object-Info: #003EE5;
+  --Hover-Primary-Button: #BD3200;
+  --Hover-Secondary-Button: #FFD4B2;
+  --Hover-Tertiary-Button: #EBE9E8;
+  --Hover-Text-Button: #EBE9E8;
+  --Hover-Caution-Button: #FFC8B8;
+  --Active-Primary-Button: #BD3200;
+  --Active-Secondary-Button: #FFD4B2;
+  --Active-Tertiary-Button: #EBE9E8;
+  --Active-Text-Button: #F4F2F1;
+  --Active-Caution-Button: #FFC8B8;
+  --Border-High-Emphasis: #575352;
+  --Border-Medium-Emphasis: #DBD9D8;
+  --Border-Low-Emphasis: #FBF9F8;
+  --Border-Accent-Primary: #E04B00;
+  --Border-Favorite: #E04B00;
+  --Border-Caution: #EC0000;
+  --Border-Info: #003EE5;
+  --Brand-Cake-Orange: #E04B00;
+  --Brand-Cake-Orange-Light: #FFD4B2;
+  --Brand-Cake-Orange-Ultra-Light: #FFECD9;
+  --Overlay-Dark: #000000CC;
+  --Overlay-Medium: #00000099;
+  --Overlay-Light: #00000033;
+  --Overlay-Scrim: rgba(17, 17, 17, 0.28);
+  --Surface-Glass: #FFFFFFCC;
+  --Surface-Glass-Soft: rgba(255, 255, 255, 0.76);
+  --Surface-Glass-Faint: #FFFFFFB2;
+  --Surface-Brand-Ghost: rgba(255, 236, 217, 0.7);
+  --Surface-Overlay-Light: #FFFFFFCC;
+  --Surface-Overlay-Dark: #00000066;
+  --Border-Hairline: rgba(28, 26, 26, 0.08);
+  --Border-Brand-Subtle: rgba(224, 75, 0, 0.16);
+  --Caution-Base: #EC0000;
+  --Caution-Light: #FFA28B;
+  --Caution-Ultra-Light: #FFE7E6;
+  --Focus-High-Emphasis: #0C9E66;
+  --Third-Party-Youtube: #FF0000;
+  --Third-Party-Facebook: #1877F2;
+  --Third-Party-Twitter: #1DA1F2;
+  --Third-Party-Instagram-Pink: #F20076;
+  --Third-Party-Amazon: #FAD676;
+  --Third-Party-LINE: #06C755;
+  --Third-Party-Apple: #000000;
+  --Third-Party-X: #000000;
+}
+
+.dark {
+  --Surface-Primary: #000000E5;
+  --Surface-Secondary: #FFFFFF1A;
+  --Surface-Tertiary: #FFFFFF33;
+  --Surface-Caution: #EC0000;
+  --Surface-Caution-Light: #FFE7E6;
+  --Surface-Accent-Primary: #E04B00;
+  --Surface-Accent-Primary-Light: #E04B0026;
+  --Surface-Success: #259D63;
+  --Surface-Warning: #F8F1E0;
+  --Surface-Info: #003EE5;
+  --Surface-Info-Light: #E8F1FE;
+  --Text-High-Emphasis: #FFFFFF;
+  --Text-Medium-Emphasis: #FFFFFFCC;
+  --Text-Low-Emphasis: #FFFFFF99;
+  --Text-Disable: #FFFFFF4D;
+  --Text-Accent-Primary: #F16311;
+  --Text-Accent-Secondary: #FFD4B2;
+  --Text-on-Inverse: #FFFFFF;
+  --Text-Success: #259D63;
+  --Text-Caution: #FF5838;
+  --Text-Warning: #C16800;
+  --Text-Info: #4979F5;
+  --Object-Favorite: #F16311;
+  --Object-Accent-Primary: #F16311;
+  --Object-Accent-Primary-Light: #FFECD9;
+  --Object-High-Emphasis: #FFFFFF;
+  --Object-Medium-Emphasis: #FFFFFFCC;
+  --Object-Low-Emphasis: #FFFFFF99;
+  --Object-Disable: #FFFFFF66;
+  --Object-High-Emphasis-on-Inverse: #FFFFFF;
+  --Object-Caution: #FFA28B;
+  --Object-Warning: #C16800;
+  --Object-Success: #259D63;
+  --Object-Info: #4979F5;
+  --Hover-Primary-Button: #BD3200;
+  --Hover-Secondary-Button: #FFFFFF1A;
+  --Hover-Tertiary-Button: #FFFFFF0D;
+  --Hover-Text-Button: #FFFFFF33;
+  --Hover-Caution-Button: #FFE7E6;
+  --Active-Primary-Button: #BD3200;
+  --Active-Secondary-Button: #FFFFFF1A;
+  --Active-Tertiary-Button: #FFFFFF0D;
+  --Active-Text-Button: #FFFFFF1A;
+  --Active-Caution-Button: #FFE7E6;
+  --Border-High-Emphasis: #FFFFFF80;
+  --Border-Medium-Emphasis: #FFFFFF33;
+  --Border-Low-Emphasis: #FFFFFF0D;
+  --Border-Accent-Primary: #F16311;
+  --Border-Favorite: #F16311;
+  --Border-Caution: #EC0000;
+  --Border-Info: #4979F5;
+  --Brand-Cake-Orange: #E04B00;
+  --Brand-Cake-Orange-Light: #FFD4B2;
+  --Brand-Cake-Orange-Ultra-Light: #FFECD9;
+  --Overlay-Dark: #FFFFFF4D;
+  --Overlay-Medium: #FFFFFF33;
+  --Overlay-Light: #FFFFFF1A;
+  --Overlay-Scrim: rgba(0, 0, 0, 0.48);
+  --Surface-Glass: #FFFFFF1A;
+  --Surface-Glass-Soft: #FFFFFF1A;
+  --Surface-Glass-Faint: #FFFFFF0D;
+  --Surface-Brand-Ghost: rgba(224, 75, 0, 0.12);
+  --Border-Hairline: #FFFFFF1A;
+  --Border-Brand-Subtle: rgba(224, 75, 0, 0.24);
+}
 
 /* --- Bridge: Semantic → shadcn tokens --- */
 :root {
@@ -104,6 +405,7 @@
  */
 
 /* Heading */
+.typo-heading-4xl { font-size: 32px; line-height: 1.4; letter-spacing: 0.04em; font-weight: 700; }
 .typo-heading-3xl { font-size: 28px; line-height: 1.5; letter-spacing: 0.04em; font-weight: 700; }
 .typo-heading-2xl { font-size: 24px; line-height: 1.5; letter-spacing: 0.04em; font-weight: 700; }
 .typo-heading-xl  { font-size: 21px; line-height: 1.5; letter-spacing: 0.04em; font-weight: 700; }

package/src/styles/semantic.css

@@ -90,6 +90,13 @@
   --Surface-Glass-Faint: var(--Primitive-White-alpha-700);   /* rgba(255,255,255,0.698≈0.7) */
   --Surface-Brand-Ghost: rgba(255, 236, 217, 0.7);           /* Orange-50 at 70%。閉じるボタン等 */
 
+  /* Overlay surfaces（画像・メディアの上に載せる半透過サーフェス）
+   * Surface-Glass と同じ半透過白でも用途を分けて命名: こちらは「画像上のボタン/ピル下地」専用。
+   * メディアの上に載るため、可読性を保つ目的で light/dark で切替えない（下は :root のみで .dark 上書きなし）。
+   * Button variant="overlay" / カルーセル矢印系の意匠に接続する。 */
+  --Surface-Overlay-Light: var(--Primitive-White-alpha-800); /* rgba(255,255,255,0.8) 半透過白の下地 */
+  --Surface-Overlay-Dark: var(--Primitive-Gray-alpha-400);   /* rgba(0,0,0,0.4) 半透過黒の下地 */
+
   /* Border alphas */
   --Border-Hairline: rgba(28, 26, 26, 0.08);       /* Gray-900 8%。微細ボーダー */
   --Border-Brand-Subtle: rgba(224, 75, 0, 0.16);   /* Brand-Orange 16%。SNSリンクボーダー等 */

package/src/styles/typography.css

@@ -8,7 +8,7 @@
  *
  * 命名規則: typo-{category}-{size}
  *   category: heading | body | label
- *   size: 3xl | 2xl | xl | lg | md | sm | xs
+ *   size: 4xl | 3xl | 2xl | xl | lg | md | sm | xs
  *
  * ── 使い分けガイド ──
  *
@@ -32,6 +32,13 @@
 
 /* ─── Heading ─── */
 
+@utility typo-heading-4xl {
+  font-size: 2rem;           /* 32px */
+  line-height: 1.4;          /* 44.8px */
+  letter-spacing: 0.04em;
+  font-weight: 700;
+}
+
 @utility typo-heading-3xl {
   font-size: 1.75rem;        /* 28px */
   line-height: 1.5;          /* 42px */

package/templates/AGENTS.md

@@ -32,22 +32,58 @@ Codex（および他の AI エージェント）は UI 作業を始める前に
 
 DS に該当パターンが無い場合のみカスタム実装を許可。その場合は**必ずコメントで理由を記載**すること。
 
+## ❓「DS に無い」と思ったときのゲート（ローカル台帳禁止・issue 直行）
+
+部品が DS に無いと思っても、**手元の台帳・TODO リストで「昇格候補」を管理しないこと**。台帳は必ず drift する（実例: cake-api の昇格候補台帳が DS 0.10.0 で追加された `ImageUploader` / `ResponsiveDialog` / `DataTable` 等を反映せず、既に DS にある部品を「無い」と誤認してローカル実装を保持し続けた）。次の順で確認する:
+
+1. `node_modules/@cakejp/design-system/contracts/components.json` を名前で検索する（正典はここ）。
+2. `npx cakejp-ds check-duplicates` を実行し、ローカルに DS 同名の実装が無いか機械検出する（`--strict` で検出時 exit 1、CI に組み込める）。
+3. それでも無ければ、手元に台帳を作らず **flashpark/cake-design-system に issue を立てる**。
+4. やむを得ずローカル実装する場合は、「DS に X が追加されたら削除」の条件コメントを必ず添える。
+
 ## 使用方法
 
 ### CSS のセットアップ（重要）
 
-DS のプリビルド CSS（`dist/index.css`）を**必ず**プロジェクトのエントリ CSS で
-`@import` すること。これにより consumer の Tailwind 設定に依存せず、DS と同じ
-見た目が保証される。
+#### ✅ 推奨（consumer が Tailwind v4 を使う場合）: `@source` 単一ビルド方式
+
+consumer のエントリ CSS で Tailwind を読み込み、`preset`（トークン・`typo-*`・
+コンテナクエリ段・dark variant）を足したうえで、DS の className を **consumer と
+同じ Tailwind ビルド**でスキャン・生成させる。
+
+```css
+/* globals.css / app.css など。@source のパスは この CSS ファイルからの相対で
+   node_modules/@cakejp/design-system/dist/index.js を指す */
+@import "tailwindcss";
+@import "@cakejp/design-system/preset";                          /* トークン・typo-*・コンテナ段・dark variant */
+@source "../node_modules/@cakejp/design-system/dist/index.js";   /* DS の className を consumer と同一ビルドで生成 */
+```
+
+**なぜこれが推奨か:** ユーティリティのビルドが 1 つに統一されるため、Tailwind の
+「基底ユーティリティ→バリアント」の並び順が保証される。consumer が `.hidden` /
+`.border-transparent` 等 DS と同名のユーティリティを 1 箇所でも使っても、DS の
+コンテナクエリ・データ属性バリアント（`@lg:block`・
+`group-data-[state=active]:border-…` 等）が同一 `@layer utilities` 内で正しく後勝ち
+する。
+
+> `@source` のパスは CSS ファイルからの相対。深さが違う場合は `../` の数を調整して
+> 必ず `node_modules/@cakejp/design-system/dist/index.js` を指すこと。Tailwind v4 は
+> 既定で `node_modules` をスキャンしないため、この明示 `@source` が要（かなめ）。
+
+#### プリビルド CSS 方式（`dist/index.css`）: **consumer が Tailwind を使わない場合のみ**
 
 ```css
-/* globals.css / app.css など */
 @import "@cakejp/design-system/dist/index.css"; /* DS のコンポーネントスタイル・トークン・preflight */
-@import "tailwindcss";                          /* consumer 自身の utility */
 ```
 
-> ❌ `@source` ディレクティブで DS を再ビルドする方式は非推奨。consumer の
-> Tailwind 設定次第で出力がズレるリスクがある（トークン値の差・preflight の差等）。
+> ⚠️ **consumer が Tailwind v4 を併用する構成でこの方式を使ってはいけない。**
+> DS のプリビルド CSS と consumer の Tailwind は**独立した 2 つのビルド**で、同名
+> ユーティリティ（`.hidden` 等）を別々に同じ `@layer utilities` へ二重出力する。
+> 後段（consumer）の基底ルールが前段（DS）のバリアントルールを宣言順で打ち消し、
+> **DS のバリアントが効かなくなる**。実害例: `Header` / `Footer` / `MenuDrawer` が
+> デスクトップ幅でも永久にモバイル表示になる（consumer の `.hidden` が DS の
+> `@lg:block` に後勝ちする）。import 順を入れ替えても解決しない。**Tailwind 併用時は
+> 上の `@source` 方式を使うこと。**
 
 ### コンポーネントの使用
 

package/templates/CLAUDE.md

@@ -34,22 +34,59 @@ Codex（および他の AI エージェント）は UI 作業を始める前に
 
 DS に該当パターンが無い場合のみカスタム実装を許可。その場合は**必ずコメントで理由を記載**すること。
 
+## ❓「DS に無い」と思ったときのゲート（ローカル台帳禁止・issue 直行）
+
+部品が DS に無いと思っても、**手元の台帳・TODO リストで「昇格候補」を管理しないこと**。台帳は必ず drift する（実例: cake-api の昇格候補台帳が DS 0.10.0 で追加された `ImageUploader` / `ResponsiveDialog` / `DataTable` 等を反映せず、既に DS にある部品を「無い」と誤認してローカル実装を保持し続けた）。次の順で確認する:
+
+1. `node_modules/@cakejp/design-system/contracts/components.json` を名前で検索する（正典はここ）。
+2. `npx cakejp-ds check-duplicates` を実行し、ローカルに DS 同名の実装が無いか機械検出する（`--strict` で検出時 exit 1、CI に組み込める）。
+3. それでも無ければ、手元に台帳を作らず **flashpark/cake-design-system に issue を立てる**。
+4. やむを得ずローカル実装する場合は、「DS に X が追加されたら削除」の条件コメントを必ず添える。
+
 ## 使用方法
 
 ### CSS のセットアップ（重要）
 
-DS のプリビルド CSS（`dist/index.css`）を**必ず**プロジェクトのエントリ CSS で
-`@import` すること。これにより consumer の Tailwind 設定に依存せず、DS と同じ
-見た目が保証される。
+#### ✅ 推奨（consumer が Tailwind v4 を使う場合）: `@source` 単一ビルド方式
+
+consumer のエントリ CSS で Tailwind を読み込み、`preset`（トークン・`typo-*`・
+コンテナクエリ段・dark variant）を足したうえで、DS の className を **consumer と
+同じ Tailwind ビルド**でスキャン・生成させる。
+
+```css
+/* globals.css / app.css など。@source のパスは この CSS ファイルからの相対で
+   node_modules/@cakejp/design-system/dist/index.js を指す */
+@import "tailwindcss";
+@import "@cakejp/design-system/preset";                          /* トークン・typo-*・コンテナ段・dark variant */
+@source "../node_modules/@cakejp/design-system/dist/index.js";   /* DS の className を consumer と同一ビルドで生成 */
+```
+
+**なぜこれが推奨か:** ユーティリティのビルドが 1 つに統一されるため、Tailwind の
+「基底ユーティリティ→バリアント」の並び順が保証される。consumer が `.hidden` /
+`.border-transparent` 等 DS と同名のユーティリティを 1 箇所でも使っても、DS の
+コンテナクエリ・データ属性バリアント（`@lg:block`・
+`group-data-[state=active]:border-…` 等）が同一 `@layer utilities` 内で正しく後勝ち
+する。プリビルド CSS 方式（下記）はこの整列が破れる（詳細は警告を参照）。
+
+> `@source` のパスは CSS ファイルからの相対。深さが違う場合は `../` の数を調整して
+> 必ず `node_modules/@cakejp/design-system/dist/index.js` を指すこと。Tailwind v4 は
+> 既定で `node_modules` をスキャンしないため、この明示 `@source` が DS の className を
+> 拾わせる要（かなめ）になる。
+
+#### プリビルド CSS 方式（`dist/index.css`）: **consumer が Tailwind を使わない場合のみ**
 
 ```css
-/* globals.css / app.css など */
 @import "@cakejp/design-system/dist/index.css"; /* DS のコンポーネントスタイル・トークン・preflight */
-@import "tailwindcss";                          /* consumer 自身の utility */
 ```
 
-> ❌ `@source` ディレクティブで DS を再ビルドする方式は非推奨。consumer の
-> Tailwind 設定次第で出力がズレるリスクがある（トークン値の差・preflight の差等）。
+> ⚠️ **consumer が Tailwind v4 を併用する構成でこの方式を使ってはいけない。**
+> DS のプリビルド CSS と consumer の Tailwind は**独立した 2 つのビルド**で、同名
+> ユーティリティ（`.hidden` 等）を別々に同じ `@layer utilities` へ二重出力する。
+> 後段（consumer）の基底ルールが前段（DS）のバリアントルールを宣言順で打ち消し、
+> **DS のバリアントが効かなくなる**。実害例: `Header` / `Footer` / `MenuDrawer` が
+> デスクトップ幅でも永久にモバイル表示になる（consumer の `.hidden` が DS の
+> `@lg:block` に後勝ちする）。import 順を入れ替えても被害者が DS↔consumer で
+> 入れ替わるだけで解決しない。**Tailwind 併用時は上の `@source` 方式を使うこと。**
 
 ### コンポーネントの使用
 

package/tokens.json

@@ -26,7 +26,9 @@
         "accent-primary":       { "value": "Primitive-Orange-700",      "hex": "#E04B00", "usage": "アクセント背景" },
         "accent-primary-light": { "value": "Primitive-Orange-50",       "hex": "#FFECD9", "usage": "アクセント背景（薄）" },
         "success":              { "value": "Primitive-Forest-600",      "hex": "#259D63", "usage": "成功背景" },
-        "warning":              { "value": "Primitive-Wood-50",         "hex": "#F8F1E0", "usage": "警告背景" }
+        "warning":              { "value": "Primitive-Wood-50",         "hex": "#F8F1E0", "usage": "警告背景" },
+        "overlay-light":        { "value": "Primitive-White-alpha-800", "hex": "#FFFFFFCC", "usage": "画像上の半透過白サーフェス（Button overlay / カルーセル矢印）" },
+        "overlay-dark":         { "value": "Primitive-Gray-alpha-400",  "hex": "#00000066", "usage": "画像上の半透過黒サーフェス" }
       },
       "text": {
         "high-emphasis":    { "value": "Primitive-Gray-900",  "hex": "#1C1A1A", "usage": "本文テキスト" },
@@ -56,6 +58,13 @@
 
   "typography": {
     "heading": {
+      "4xl": {
+        "fontSize": "32px",
+        "lineHeight": 1.4,
+        "letterSpacing": "0.04em",
+        "fontWeight": 700,
+        "usage": "ヒーロー・ページ大見出し"
+      },
       "3xl": { "fontSize": "28px", "lineHeight": 1.5, "letterSpacing": "0.04em", "fontWeight": 700, "usage": "ページタイトル" },
       "2xl": { "fontSize": "24px", "lineHeight": 1.5, "letterSpacing": "0.04em", "fontWeight": 700, "usage": "主要セクション見出し" },
       "xl":  { "fontSize": "21px", "lineHeight": 1.5, "letterSpacing": "0.04em", "fontWeight": 700, "usage": "サブセクション見出し" },