@cakejp/design-system 0.9.0 → 0.11.0

package/templates/CLAUDE.md

@@ -38,18 +38,46 @@ DS に該当パターンが無い場合のみカスタム実装を許可。そ
 
 ### 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

@@ -108,6 +108,13 @@
     }
   },
 
+  "breakpoints": {
+    "comment": "役割は二層。(1) 切替段=md / lg の2つだけ（値は本番 cakejp.css の境界に一致させた正本。レイアウトの変形はこの2段でのみ行う）。(2) 上限段=xl（1280。「切替段」ではなく DS が定めるコンテンツ幅の上限段。本番に 1280 の切替段は無い＝1025/1441 はある）。DS 内部はコンテナクエリ @md: / @lg: / @xl:（preset.css の --container-md / --container-lg / --container-xl）で参照し、生 CSS ではこの px 値をメディアクエリに直書きする（CSS 変数はメディアクエリに使えないため、値の配布は本トークンが担う）。独自のブレイクポイント値を発明しない",
+    "md": { "px": 768, "rem": "48rem", "container": "--container-md", "role": "切替段", "usage": "SP/PC 境界。767px 以下=SP / 768px 以上=PC。本番 cakejp.css の max-width:767px / min-width:768px と一致" },
+    "lg": { "px": 960, "rem": "60rem", "container": "--container-lg", "role": "切替段", "usage": "PC 中段。本番 cakejp.css の min-width:960px 段と一致" },
+    "xl": { "px": 1280, "rem": "80rem", "container": "--container-xl", "role": "上限段", "usage": "コンテンツ上限段（切替段ではない）。ページコンテナの標準上限で、1280px 以上では原則レイアウト変形を追加しない。本番 cakejp.css に 1280 の切替段は無い（1025 / 1441 はある）——DS が定める標準上限。実例: MypageShell の PC グリッド max-w-[1280px]" }
+  },
+
   "touchTarget": {
     "button-cta":    { "min": "40px", "recommended": "48px" },
     "icon-button":   { "min": "40px", "recommended": "44px" },