ksk-design-system 1.40.0 → 1.40.1

package/AGENTS.md

@@ -17,6 +17,7 @@
 ```
 contracts/rules.json                     # 禁止パターン32件・AIアンチパターン10件・a11y要件
 contracts/components.json               # 全112コンポーネントの定義・バリアント・ルール
+contracts/design-context.json           # DESIGN.md と正本ファイルの関係・AI向け検査方針
 tokens.json                             # カラー・スペーシング・シャドウトークン
 src/components/COMPONENT_LOOKUP.md      # バリアント・インポートパス一覧（自動生成）
 ```
@@ -92,6 +93,7 @@ Brand色を差し替え（10行）→ Primitive Layer → Semantic Layer → Bri
 | **AGENTS.md**（本ファイル） | 概要・技術スタック・コマンド・クイックスタート |
 | **contracts/components.json** | 全112コンポーネントの構造化定義（バリアント・アクセシビリティ要件） |
 | **contracts/rules.json** | 禁止パターン32件・AIアンチパターン10件・アクセシビリティ要件 |
+| **contracts/design-context.json** | `DESIGN.md` の役割・正本ファイル・外部 DESIGN.md 参照方針 |
 | **tokens.json** | カラー・スペーシング・シャドウトークンの機械可読定義 |
 | **src/components/COMPONENT_LOOKUP.md** | 全112コンポーネントのバリアント・インポートパス（自動生成） |
 | **DESIGN.md** | AI エージェント向け視覚言語サマリ（トークン＋意図・voice・motion） |

package/CLAUDE.md

@@ -59,6 +59,7 @@ Brand色を差し替え（10行）→ Primitive Layer → Semantic Layer → Bri
 | **AGENTS.md** | 同上（Codex用。セッション開始時の読み込み指示・編集後コマンドを明記） |
 | **contracts/components.json** | 全112コンポーネントの構造化定義（バリアント・アクセシビリティ要件） |
 | **contracts/rules.json** | 禁止パターン32件・AIアンチパターン10件・アクセシビリティ要件 |
+| **contracts/design-context.json** | `DESIGN.md` の役割・正本ファイル・外部 DESIGN.md 参照方針 |
 | **tokens.json** | カラー・スペーシング・シャドウトークンの機械可読定義 |
 | **src/components/COMPONENT_LOOKUP.md** | 全112コンポーネントのバリアント・インポートパス一覧（自動生成） |
 | **DESIGN.md** | AI エージェント向け視覚言語サマリ（トークン＋意図・voice・motion） |
@@ -66,8 +67,9 @@ Brand色を差し替え（10行）→ Primitive Layer → Semantic Layer → Bri
 **セッション開始時 / コードを書く前に必ず読む:**
 1. `contracts/rules.json` の `prohibited` と `aiPatterns`（AIが典型的に犯すパターン集）を確認
 2. `contracts/components.json` でコンポーネント定義・バリアントを確認
-3. `src/components/COMPONENT_LOOKUP.md` で既存コンポーネントを確認（手書き・再定義の防止）
-4. `tokens.json` でカラー・余白・影・タイポのトークンを確認
+3. `contracts/design-context.json` で `DESIGN.md` と正本ファイルの関係を確認
+4. `src/components/COMPONENT_LOOKUP.md` で既存コンポーネントを確認（手書き・再定義の防止）
+5. `tokens.json` でカラー・余白・影・タイポのトークンを確認
 
 **`.tsx` を編集したら `bash scripts/lint-scratch.sh`、コンポーネント増減時は `npm run check` を実行すること。**
 
@@ -114,6 +116,9 @@ bash scripts/check-drift.sh
 # COMPONENT_LOOKUP.md 再生成（コンポーネント追加後に実行）
 npm run generate:lookup
 
+# DESIGN.md contract 検査
+npm run lint:design
+
 # 全チェック（tsc + lint + drift + lookup 一括）
 npm run check
 ```

package/DESIGN.md

@@ -32,7 +32,7 @@ colors:
   info: "#2563EB"
 typography:
   fontFamily: "system-ui, -apple-system, 'Hiragino Sans', 'Noto Sans JP', sans-serif"
-  display:  { fontSize: "48px", lineHeight: "1.2",  fontWeight: 700 }   # typo-display-xl
+  display:  { fontSize: "48px", lineHeight: "1.25", fontWeight: 700 }   # typo-display-xl
   heading:  { fontSize: "18px", lineHeight: "1.5",  fontWeight: 700 }   # typo-heading-lg（基準）
   body:     { fontSize: "14px", lineHeight: "1.75", fontWeight: 400 }   # typo-body-md（基準）
   label:    { fontSize: "12px", lineHeight: "1.5",  fontWeight: 500 }   # typo-label-sm
@@ -45,12 +45,12 @@ rounded:
   full: "9999px"   # Button / Chip
 spacing:
   unit: "4px"      # 4px グリッド（scale: 0,4,8,12,16,20,24,28,32,36,40,44,48,...）
-  page: "16px"     # 画面端マージン var(--page-px)
+  page: "16px"     # 基準画面端マージン。実レイアウトは Screen / Shell の padding contract を優先
 elevation:                                          # 影色は neutral（Gray-900 ベース rgba(17,24,39,…)）でテーマ非依存
-  sm: "0 1px 2px rgba(0,0,0,0.05)"
-  md: "0 0 8px rgba(20,20,20,0.08)"
-  lg: "0 12px 32px -4px rgba(17,24,39,0.12), 0 8px 16px -6px rgba(17,24,39,0.12)"
-  dialog: "0 12px 32px -4px rgba(17,24,39,0.12), 0 8px 16px -6px rgba(17,24,39,0.12), 0 1px 4px 1px rgba(0,0,0,0.2)"
+  sm: "0 1px 2px 0 rgba(0, 0, 0, 0.05)"
+  md: "0 0 8px rgba(20, 20, 20, 0.08)"
+  lg: "0px 12px 32px -4px rgba(17, 24, 39, 0.12), 0px 8px 16px -6px rgba(17, 24, 39, 0.12)"
+  dialog: "0px 12px 32px -4px rgba(17, 24, 39, 0.12), 0px 8px 16px -6px rgba(17, 24, 39, 0.12), 0px 1px 4px 1px rgba(0, 0, 0, 0.2)"
 motion:
   microIn: "150ms ease-out"                       # fade-in / scale-in
   enter: "200ms ease-out"                          # fade-in-up / slide-in
@@ -93,6 +93,21 @@ EC/BtoC 系）を回すのが狙い。
 - **基盤**: React 19 + Tailwind v4 + shadcn/Radix + iconsax。
 - **判断基準**: 色・余白・タイポは必ずトークン経由。生の値を書かない（後述 Do/Don't）。
 
+## Source Of Truth
+
+`DESIGN.md` は Google DESIGN.md の「front matter + rationale」形式を参考にした **AI 向け配布サマリ**であり、
+実装正本ではない。KSK の正本は次のファイルに置く。
+
+- `tokens.json`: primitive / semantic / dark semantic / typography / spacing / shadow / touch target。
+- `src/styles/*.css`: 実際に publish される CSS custom properties と typography / glass utilities。
+- `contracts/rules.json`: 禁止パターン、AI anti-pattern、a11y、consumer lint の正本。
+- `contracts/components.json`: component 名、variant、subcomponent、usage rule、件数の正本。
+- `src/components/COMPONENT_LOOKUP.md`: import map、Storybook coverage、DS-first recipe の生成済み索引。
+
+Google DESIGN.md は互換フォーマットと検査観点の参照に留める。Google 側の alpha schema / CLI を
+KSK の必須正本・publish 依存にせず、KSK 固有の multi-theme / native / categorical / component contract は
+`contracts/design-context.json` と repo 内 checker で管理する。
+
 ## Colors
 
 3層トークン。コンポーネントは**必ず Semantic 層を `var()` で参照**する（Primitive 直参照・生 hex 禁止）。
@@ -125,7 +140,7 @@ EC/BtoC 系）を回すのが狙い。
 ## Layout & Spacing
 
 - **4px グリッド**。余白・サイズは 4 の倍数（scale 0–60）。
-- 画面端マージン: `var(--page-px)`（既定 16px）。
+- 画面端マージン: 16px を基準にしつつ、実レイアウトでは `Screen` / shell component の padding contract を優先する。
 - **タッチターゲット**（モバイル）: WCAG 2.5.5 / Apple HIG に従い主要操作（ボタン/アイコンボタン/入力/ナビ）の
   **min は 44px** 以上、推奨 48px。44 未満が避けられない **チップ（min 32px）は hitSlop**（不可視の拡張タップ領域）で
   実効 44px を確保する。値の正本は `tokens.json` の `touchTargets`。

package/contracts/components.json

@@ -317,9 +317,16 @@
     {
       "name": "Progress",
       "path": "src/components/ui/progress.tsx",
-      "description": "進捗バー。color variant (default/success/warning/caution) + transition duration (none/sm/md/lg) 拡張済。",
+      "description": "進捗バー。color variant (default/success/warning/caution) + transition duration (none/sm/md/lg) + autoColor 閾値切替に対応。",
+      "features": [
+        "color-variants",
+        "transition-duration",
+        "auto-color-thresholds"
+      ],
       "rules": [
-        "値超過で variant を切替: 100% 超なら caution",
+        "値に応じた色切替は autoColor を使い、consumer 側で個別に if 文と className を重ねない",
+        "autoColor=true の既定閾値は 80% 以上 warning、100% 以上 caution",
+        "しきい値がアプリごとに違う場合は autoColor={{ successBelow, warningFrom, warningBelow, cautionFrom }} を使う",
         "達成カード等は transitionDuration=\"lg\" で緩やかに"
       ]
     },
@@ -1728,18 +1735,30 @@
         "edit-trigger",
         "rich-column-helpers",
         "date-column",
+        "date-cell",
         "chip-column",
         "select-column",
+        "select-popper-position",
         "sort",
         "checkbox",
         "actions",
+        "row-click",
+        "full-cell-hit-area",
         "inline-edit",
+        "flexible-column-width",
         "drag",
-        "section-row"
+        "section-row",
+        "section-sticky-left",
+        "section-heading-emphasis"
       ],
       "rules": [
         "rows/columns API は最短実装向け",
         "DateField / Chip cluster / typed Select などのリッチ列は cell と edit.trigger、または createDataTableDateColumn / createDataTableChipColumn / createDataTableSelectColumn を使う",
+        "行全体をクリック可能にする場合は DataTable の onRowClick または DataTableRow の onRowClick を使い、独自の tr/td クリック実装を作らない",
+        "Select セルは DataTableSelectCell または createDataTableSelectColumn を使い、ポップオーバー位置は contentPosition で調整する",
+        "日付編集セルは DataTableDateCell または createDataTableDateColumn を使う",
+        "残り幅を受け持つ列は width=\"flex\" を使い、手書き className の w-full/min-w 再実装を避ける",
+        "セクション見出しを横スクロール中も左に残す場合は DataTableSectionRow stickyLeft / headingSize を使う",
         "複雑なテーブル全体構成は DataTableHead, DataTableRow, DataTableCell などのサブコンポーネントを使う"
       ]
     },

package/contracts/design-context.json

@@ -0,0 +1,136 @@
+{
+  "meta": {
+    "name": "KSK Design System — Agent Design Context",
+    "version": "1.0.0",
+    "description": "AI エージェント向け DESIGN.md の扱いと、KSK 固有の正本・検査方針を定義する。Google DESIGN.md は互換入口として参照し、KSK の正本は tokens / contracts / CSS に置く。"
+  },
+  "canonicalSources": [
+    {
+      "path": "tokens.json",
+      "owns": [
+        "primitive colors",
+        "semantic colors",
+        "dark semantic colors",
+        "typography",
+        "spacing scale",
+        "border radius scale",
+        "shadows",
+        "touch targets"
+      ]
+    },
+    {
+      "path": "src/styles/*.css",
+      "owns": [
+        "published CSS custom properties",
+        "typography utilities",
+        "glass utilities",
+        "categorical token CSS"
+      ]
+    },
+    {
+      "path": "contracts/rules.json",
+      "owns": [
+        "prohibited patterns",
+        "AI anti-patterns",
+        "accessibility rules",
+        "consumer lint rules"
+      ]
+    },
+    {
+      "path": "contracts/components.json",
+      "owns": [
+        "component names",
+        "variants",
+        "subcomponents",
+        "usage rules",
+        "component counts"
+      ]
+    },
+    {
+      "path": "src/components/COMPONENT_LOOKUP.md",
+      "owns": [
+        "generated import map",
+        "storybook coverage hints",
+        "DS-first recipes"
+      ]
+    }
+  ],
+  "designMd": {
+    "role": "AI 向けの視覚言語サマリ。実装正本ではなく、正本から検査される配布・参照レイヤー。",
+    "frontMatterRole": "Google DESIGN.md 互換の機械可読サマリ。KSK の主要 token を抽出して agent が読みやすい粒度にする。",
+    "bodyRole": "KSK の設計意図、使い分け、禁止事項を説明する rationale。",
+    "updatePolicy": "tokens.json / contracts/*.json / src/styles/*.css の変更で DESIGN.md の記述が古くなる場合は同じ PR で更新する。",
+    "googleDesignMdPolicy": "Google DESIGN.md の思想・検査観点・export 形式は参照する。ただし alpha 仕様や CLI を KSK の必須正本・runtime 依存にしない。"
+  },
+  "externalReferences": [
+    {
+      "name": "Google DESIGN.md",
+      "url": "https://github.com/google-labs-code/design.md",
+      "status": "optional-reference",
+      "adopt": [
+        "front matter + markdown rationale の二層構造",
+        "broken token reference check",
+        "section order check",
+        "agent-readable JSON findings",
+        "Tailwind v4 / DTCG export という互換出口の考え方"
+      ],
+      "doNotAdoptAsCanonical": [
+        "Google schema を KSK の完全正本にすること",
+        "Google CLI を publish / CI の必須依存にすること",
+        "KSK 固有の multi-theme / native / component contracts を Google alpha schema に従属させること"
+      ]
+    }
+  ],
+  "guardrails": {
+    "requiredSections": [
+      "Overview",
+      "Source Of Truth",
+      "Colors",
+      "Typography",
+      "Layout & Spacing",
+      "Elevation & Depth",
+      "Shapes",
+      "Motion",
+      "Components",
+      "Voice & Tone",
+      "Do's and Don'ts"
+    ],
+    "requiredSourceMentions": [
+      "tokens.json",
+      "src/styles/*.css",
+      "contracts/rules.json",
+      "contracts/components.json",
+      "src/components/COMPONENT_LOOKUP.md",
+      "Google DESIGN.md"
+    ],
+    "requiredFrontMatterPaths": [
+      "version",
+      "name",
+      "colors.primary",
+      "colors.primaryAction",
+      "colors.surface",
+      "colors.textHigh",
+      "colors.border",
+      "colors.focus",
+      "typography.display.fontSize",
+      "typography.display.lineHeight",
+      "typography.body.fontSize",
+      "rounded.surface",
+      "rounded.modal",
+      "rounded.sheet",
+      "spacing.unit",
+      "elevation.md",
+      "components.button.background",
+      "components.card.background",
+      "components.dialog.rounded"
+    ],
+    "checks": [
+      "DESIGN.md front matter が存在すること",
+      "front matter 内の {path.to.token} 参照が解決できること",
+      "主要 colors / typography / radius / elevation が tokens.json と src/preset.css から導出した値と一致すること",
+      "body の ## セクションが requiredSections の順序を保つこと",
+      "body が KSK の正本ファイルと Google DESIGN.md の参照方針を明示すること",
+      "front matter の components.* が contracts/components.json に存在する component を指すこと"
+    ]
+  }
+}