ksk-design-system 1.35.0

package/AGENTS.md

@@ -0,0 +1,190 @@
+# KSK Design System — 設計ルールブック（Codex向け）
+
+## このDSについて
+
+**KSK Design System** は、フリーランスデザイナー / エンジニア / PdM が **複数クライアント案件を1つのDSで高速に回す** ために設計された統合デザインシステムです。
+
+2つのドメインの設計思想を統合:
+- BtoB / SaaS / リクルート系（信頼感・業務効率を重視）
+- EC / BtoC / コマース系（購買体験・温かみを重視）
+
+---
+
+## 必須: セッション開始時に読み込むファイル
+
+コードを書く前に、以下を必ず読み込むこと:
+
+```
+contracts/rules.json                     # 禁止パターン32件・AIアンチパターン10件・a11y要件
+contracts/components.json               # 全110コンポーネントの定義・バリアント・ルール
+tokens.json                             # カラー・スペーシング・シャドウトークン
+src/components/COMPONENT_LOOKUP.md      # バリアント・インポートパス一覧（自動生成）
+```
+
+**必ず `contracts/rules.json` の `prohibited` と `aiPatterns` を確認してから実装すること。**
+特に `aiPatterns` は AI が典型的に犯すパターン集 — 自分が生成しようとしているコードと照合すること。
+
+コンポーネントを新規作成する前に `COMPONENT_LOOKUP.md` で同等品がないか確認すること。
+
+---
+
+## 必須: ファイル編集後に実行するコマンド
+
+**.tsx ファイルを作成・編集した後は必ず実行:**
+
+```bash
+bash scripts/lint-scratch.sh
+```
+
+**.css を編集した後は必ず実行:**
+
+```bash
+node scripts/check-prefix-order.mjs
+```
+
+ベンダープレフィックスは **`-webkit-` を先・標準形を後** に書く（消費側の
+minifier が同一プロパティとして dedupe し後勝ちのみ残すため、逆順だと
+標準形が消えて Firefox で静かに無効化される）。
+
+**コンポーネントを追加・削除した後は必ず実行:**
+
+```bash
+bash scripts/check-drift.sh
+node scripts/generate-component-lookup.mjs
+```
+
+エラーが出た場合は修正してから次に進むこと。
+
+---
+
+## 最大の特徴: マルチテーマ対応
+
+**Brand色の10行を差し替えるだけで、全コンポーネントの見た目が自動的に切り替わります。**
+
+```
+Brand色を差し替え（10行）→ Primitive Layer → Semantic Layer → Bridge Layer → 全コンポーネント
+```
+
+| テーマ | Brand-500 | 想定業種 |
+|--------|-----------|---------|
+| Default (Blue) | `#3B82F6` | 汎用・SaaS・BtoB |
+| Orange | `#F97316` | EC・フード・エンタメ |
+| Green | `#16A34A` | ヘルスケア・サステナ・金融 |
+| Violet | `#7C3AED` | プレミアム・クリエイティブ・教育 |
+
+---
+
+## 技術スタック
+
+- React 19 + TypeScript / Vite / **Tailwind CSS v4**（`@import "tailwindcss"` 構文）
+- shadcn/ui（Radix UI ベース） / CVA（バリアント管理）
+- **iconsax-reactjs**（アイコン。lucide-react や heroicons は使わない）
+- Storybook（ドキュメント）
+
+> **注意**: Tailwind CSS は v4 です。`@tailwind base` 等の v3 構文は使わないこと。
+
+---
+
+## ドキュメント構成
+
+| ファイル | 内容 |
+|---------|------|
+| **AGENTS.md**（本ファイル） | 概要・技術スタック・コマンド・クイックスタート |
+| **contracts/components.json** | 全110コンポーネントの構造化定義（バリアント・アクセシビリティ要件） |
+| **contracts/rules.json** | 禁止パターン32件・AIアンチパターン10件・アクセシビリティ要件 |
+| **tokens.json** | カラー・スペーシング・シャドウトークンの機械可読定義 |
+| **src/components/COMPONENT_LOOKUP.md** | 全110コンポーネントのバリアント・インポートパス（自動生成） |
+| **DESIGN.md** | AI エージェント向け視覚言語サマリ（トークン＋意図・voice・motion） |
+
+---
+
+## ディレクトリ構成
+
+```
+src/
+├── components/
+│   ├── ui/           # 汎用UIコンポーネント 55個
+│   ├── patterns/
+│   │   ├── commerce/ # EC系 11個
+│   │   ├── admin/    # 管理画面系 8個
+│   │   ├── shells/   # レイアウトシェル 3個
+│   │   └── ...       # 汎用パターン 33個
+│   └── icons/
+├── styles/
+│   ├── primitive.css  # Layer 1: 原色パレット
+│   ├── semantic.css   # Layer 2: 用途別トークン
+│   └── typography.css # typo-* ユーティリティ 17クラス
+├── themes/            # default / orange / green / violet / blue
+├── preset.css         # 外部プロジェクト向けプリセット
+└── index.ts           # Public API（110コンポーネント）
+```
+
+---
+
+## カラートークン体系（3層構造）
+
+```
+Layer 1 — Primitive  : --Primitive-{ColorName}-{Shade}  （10色ファミリー × 10シェード）
+Layer 2 — Semantic   : --{Category}-{Role}              （Surface / Text / Border / Brand / Focus 等）
+Layer 3 — Bridge     : --primary / --secondary 等        （shadcn/ui 互換マッピング）
+```
+
+セマンティックトークン早見表:
+
+| 用途 | トークン |
+|------|---------|
+| 背景（白） | `var(--Surface-Primary)` |
+| 背景（薄灰） | `var(--Surface-Secondary)` |
+| テキスト（強） | `var(--Text-High-Emphasis)` |
+| テキスト（中） | `var(--Text-Medium-Emphasis)` |
+| テキスト（弱） | `var(--Text-Low-Emphasis)` |
+| テキスト（白抜き） | `var(--Text-on-Inverse)` |
+| ブランド色 | `var(--Brand-Primary)` |
+| フォーカス | `var(--Focus-High-Emphasis)` |
+
+**カテゴリ識別色（質的パレット・テーマ非依存）:**
+`var(--Categorical-{1..16})`（ドット/アイコン）/ `-Subtle`（背景ティント）/ `-Bold`（文字・ラベル）。
+Brand に連動しない固定値で、カレンダー予定ドット・カテゴリ chip・グラフ系列など「N 番目のカテゴリ」を色で区別する用途専用。
+文字には必ず `-Bold` を使う（base は明色相だと白背景でコントラスト不足）。詳細・WCAG/CVD 注記は `src/styles/categorical.css`。
+
+---
+
+## クイックスタート（新規クライアント案件）
+
+**1. テーマファイルを作成:**
+
+```css
+/* src/themes/my-client.css */
+@theme {
+  --Primitive-Brand-500: #0EA5E9;  /* ← クライアントのブランドカラー */
+  /* ... Brand-50 〜 900 の10行 */
+}
+```
+
+**2. プロジェクトで import:**
+
+```css
+@import "ksk-design-system/preset";
+@import "./themes/my-client.css";
+```
+
+**3. コンポーネントを使う:**
+
+```tsx
+import { Button, Card, Input, FormField } from "ksk-design-system"
+```
+
+以上で完了。全コンポーネントがクライアントのブランドカラーで動作します。
+
+---
+
+## コンポーネント追加時のチェックリスト
+
+新しいコンポーネントを追加したら、以下を必ず更新:
+
+- [ ] `src/index.ts` にエクスポートを追加
+- [ ] `contracts/components.json` にコンポーネント定義を追加
+- [ ] `contracts/components.json` の `meta.counts` を更新
+- [ ] `bash scripts/check-drift.sh` を実行して乖離がないことを確認
+- [ ] Storybook のストーリーファイル（`.stories.tsx`）を作成
+- [ ] `node scripts/generate-component-lookup.mjs` を実行して COMPONENT_LOOKUP.md を更新

package/CLAUDE.md

@@ -0,0 +1,189 @@
+# KSK Design System — 設計ルールブック
+
+## 実装前セルフチェック（AI必読・最優先）
+
+UI を書く前に必ず確認すること:
+
+- [ ] 既存コンポーネントを `src/components/COMPONENT_LOOKUP.md` で確認したか（手書き・再定義は禁止）
+- [ ] 色は semantic token（`var(--Surface-*)` / `var(--Brand-Primary)` 等）か。Tailwind標準色・生 `#hex` は禁止
+- [ ] `border` は色を併記したか（`border-[var(--Border-Low-Emphasis)]` 等）。Tailwind v4 では無色 border は currentColor になり、消費側の濃色テキストで黒ずむ（preset.css の base layer が保険だが明示が原則）
+- [ ] **文脈非依存**か（テキスト要素に `text-[var(--Text-*)]`、サーフェス/オーバーレイに `bg-[var(--Surface-*)]` を明示）。親の継承や currentColor に頼ると消費側の色文脈で崩れる。Storybook ツールバーの **Hostile ctx** を loud にして、文字/アイコンがマゼンタ化・背景が透けないか確認する
+- [ ] typography は `typo-*` クラスか（`font-bold` 等の直書きは禁止）
+- [ ] アイコンは `iconsax-reactjs` か（`lucide-react` / `heroicons` は使わない）
+- [ ] 生タグ（`<button>` / `<input>` / `<a href>`）でなく DS コンポーネントを使ったか
+- [ ] CSS でベンダープレフィックス併記する場合、**`-webkit-` を先・標準形を後**に書いたか（消費側の minifier が同一プロパティとして dedupe し後勝ちのみ残すため。逆順だと Firefox で静かに無効化。`node scripts/check-prefix-order.mjs` が CI で検出）
+- [ ] `.tsx` 編集後に `bash scripts/lint-scratch.sh`、コンポーネント増減時は `npm run check` を実行したか
+
+---
+
+## このDSについて
+
+**KSK Design System** は、フリーランスデザイナー / エンジニア / PdM が **複数クライアント案件を1つのDSで高速に回す** ために設計された統合デザインシステムです。
+
+2つのドメインの設計思想を統合:
+- BtoB / SaaS / リクルート系（信頼感・業務効率を重視）
+- EC / BtoC / コマース系（購買体験・温かみを重視）
+
+---
+
+## 最大の特徴: マルチテーマ対応
+
+**Brand色の10行を差し替えるだけで、全コンポーネントの見た目が自動的に切り替わります。**
+
+```
+Brand色を差し替え（10行）→ Primitive Layer → Semantic Layer → Bridge Layer → 全コンポーネント
+```
+
+| テーマ | Brand-500 | 想定業種 |
+|--------|-----------|---------|
+| Default (Blue) | `#3B82F6` | 汎用・SaaS・BtoB |
+| Orange | `#F97316` | EC・フード・エンタメ |
+| Green | `#16A34A` | ヘルスケア・サステナ・金融 |
+| Violet | `#7C3AED` | プレミアム・クリエイティブ・教育 |
+
+---
+
+## 技術スタック
+
+- React 19 + TypeScript / Vite / **Tailwind CSS v4**（`@import "tailwindcss"` 構文。`@tailwind base` 等の v3 構文は使わない）
+- shadcn/ui（Radix UI ベース） / CVA（バリアント管理）
+- **iconsax-reactjs**（アイコン。`lucide-react` / `heroicons` は使わない） / Storybook（ドキュメント）
+
+---
+
+## ドキュメント構成
+
+| ファイル | 内容 |
+|---------|------|
+| **CLAUDE.md**（本ファイル） | 概要・技術スタック・コマンド・クイックスタート（Claude Code用） |
+| **AGENTS.md** | 同上（Codex用。セッション開始時の読み込み指示・編集後コマンドを明記） |
+| **contracts/components.json** | 全110コンポーネントの構造化定義（バリアント・アクセシビリティ要件） |
+| **contracts/rules.json** | 禁止パターン32件・AIアンチパターン10件・アクセシビリティ要件 |
+| **tokens.json** | カラー・スペーシング・シャドウトークンの機械可読定義 |
+| **src/components/COMPONENT_LOOKUP.md** | 全110コンポーネントのバリアント・インポートパス一覧（自動生成） |
+| **DESIGN.md** | AI エージェント向け視覚言語サマリ（トークン＋意図・voice・motion） |
+
+**セッション開始時 / コードを書く前に必ず読む:**
+1. `contracts/rules.json` の `prohibited` と `aiPatterns`（AIが典型的に犯すパターン集）を確認
+2. `contracts/components.json` でコンポーネント定義・バリアントを確認
+3. `src/components/COMPONENT_LOOKUP.md` で既存コンポーネントを確認（手書き・再定義の防止）
+4. `tokens.json` でカラー・余白・影・タイポのトークンを確認
+
+**`.tsx` を編集したら `bash scripts/lint-scratch.sh`、コンポーネント増減時は `npm run check` を実行すること。**
+
+---
+
+## ディレクトリ構成
+
+```
+src/
+├── components/
+│   ├── ui/           # 汎用UIコンポーネント 55個
+│   ├── patterns/
+│   │   ├── commerce/ # EC系 11個
+│   │   ├── admin/    # 管理画面系 8個
+│   │   ├── shells/   # レイアウトシェル 3個
+│   │   └── ...       # 汎用パターン 33個
+│   └── icons/
+├── styles/
+│   ├── primitive.css  # Layer 1: 原色パレット
+│   ├── semantic.css   # Layer 2: 用途別トークン
+│   └── typography.css # typo-* ユーティリティ 17クラス
+├── themes/            # default / orange / green / violet / blue
+├── preset.css         # 外部プロジェクト向けプリセット
+└── index.ts           # Public API（110コンポーネント）
+```
+
+---
+
+## コマンド
+
+```bash
+# 開発サーバー（Storybook）
+npm run storybook
+
+# ビルド
+npm run build-storybook
+
+# スクラッチ検出（実装後に必ず実行）
+bash scripts/lint-scratch.sh
+
+# ドリフト検出（コンポーネント追加後に実行）
+bash scripts/check-drift.sh
+
+# COMPONENT_LOOKUP.md 再生成（コンポーネント追加後に実行）
+npm run generate:lookup
+
+# 全チェック（tsc + lint + drift + lookup 一括）
+npm run check
+```
+
+---
+
+## カラートークン体系（3層構造）
+
+```
+Layer 1 — Primitive  : --Primitive-{ColorName}-{Shade}  （10色ファミリー × 10シェード）
+Layer 2 — Semantic   : --{Category}-{Role}              （Surface / Text / Border / Brand / Focus 等）
+Layer 3 — Bridge     : --primary / --secondary 等        （shadcn/ui 互換マッピング）
+```
+
+セマンティックトークン早見表:
+
+| 用途 | トークン |
+|------|---------|
+| 背景（白） | `var(--Surface-Primary)` |
+| 背景（薄灰） | `var(--Surface-Secondary)` |
+| テキスト（強） | `var(--Text-High-Emphasis)` |
+| テキスト（中） | `var(--Text-Medium-Emphasis)` |
+| テキスト（弱） | `var(--Text-Low-Emphasis)` |
+| テキスト（白抜き） | `var(--Text-on-Inverse)` |
+| ブランド色 | `var(--Brand-Primary)` |
+| フォーカス | `var(--Focus-High-Emphasis)` |
+
+**カテゴリ識別色（質的パレット・テーマ非依存）:**
+`var(--Categorical-{1..16})`（ドット/アイコン）/ `-Subtle`（背景ティント）/ `-Bold`（文字・ラベル）。
+Brand に連動しない固定値で、カレンダー予定ドット・カテゴリ chip・グラフ系列など「N 番目のカテゴリ」を色で区別する用途専用。
+文字には必ず `-Bold` を使う（base は明色相だと白背景でコントラスト不足）。詳細・WCAG/CVD 注記は `src/styles/categorical.css`。
+
+---
+
+## クイックスタート（新規クライアント案件）
+
+**1. テーマファイルを作成:**
+
+```css
+/* src/themes/my-client.css */
+@theme {
+  --Primitive-Brand-500: #0EA5E9;  /* ← クライアントのブランドカラー */
+  /* ... Brand-50 〜 900 の10行 */
+}
+```
+
+**2. プロジェクトで import:**
+
+```css
+@import "ksk-design-system/preset";
+@import "./themes/my-client.css";
+```
+
+**3. コンポーネントを使う:**
+
+```tsx
+import { Button, Card, Input, FormField } from "ksk-design-system"
+```
+
+以上で完了。全コンポーネントがクライアントのブランドカラーで動作します。
+
+---
+
+## コンポーネント追加時のチェックリスト
+
+新しいコンポーネントを追加したら、以下を必ず更新:
+
+- [ ] `src/index.ts` にエクスポートを追加
+- [ ] `contracts/components.json` にコンポーネント定義を追加
+- [ ] `contracts/components.json` の `meta.counts` を更新
+- [ ] `bash scripts/check-drift.sh` を実行して乖離がないことを確認
+- [ ] Storybook のストーリーファイル（`.stories.tsx`）を作成
+- [ ] `npm run generate:lookup` を実行して COMPONENT_LOOKUP.md を更新

package/DESIGN.md

@@ -0,0 +1,190 @@
+---
+version: alpha
+name: KSK Design System
+description: >-
+  フリーランス / 受託で複数案件を1つのDSで高速に回すためのマルチテーマ対応
+  デザインシステム。Brand 色を差し替えるだけで全コンポーネントの見た目が
+  切り替わる。デフォルトは信頼感のある Blue。
+colors:
+  # --- Brand（テーマ差し替え対象。下記は default=Blue） ---
+  primary: "#2563EB"          # Brand-Primary / var(--Brand-Primary)
+  primaryAction: "#1D4ED8"    # Brand-Action（hover/active）
+  onPrimary: "#FFFFFF"
+  # --- Neutral scale ---
+  neutral0: "#FFFFFF"
+  neutral50: "#F9FAFB"
+  neutral100: "#F3F4F6"
+  neutral200: "#E5E7EB"
+  neutral500: "#6B7280"
+  neutral900: "#111827"
+  # --- Surface / Text / Border（semantic） ---
+  surface: "#FFFFFF"          # var(--Surface-Primary)
+  surfaceMuted: "#F9FAFB"     # var(--Surface-Secondary)
+  textHigh: "#111827"         # var(--Text-High-Emphasis)
+  textMedium: "#374151"       # var(--Text-Medium-Emphasis)
+  textLow: "#6B7280"          # var(--Text-Low-Emphasis)
+  border: "#E5E7EB"           # var(--Border-Low-Emphasis)
+  focus: "#60A5FA"            # var(--Focus-High-Emphasis)
+  # --- Semantic（status） ---
+  success: "#16A34A"
+  warning: "#EA580C"
+  error: "#DC2626"            # Caution
+  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
+  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
+  caption:  { fontSize: "11px", lineHeight: "1.5",  fontWeight: 400 }   # typo-caption（注釈/法的表記専用。本文の下限は body=12px。10px の typo-body-xs は補助ラベル専用で本文禁止）
+rounded:
+  sm: "4px"
+  surface: "8px"   # Card / Input / Popover  → var(--Radius-Surface)
+  modal: "24px"    # 中央 Dialog / AlertDialog → var(--Radius-Modal)
+  sheet: "32px"    # bottom / float Sheet     → var(--Radius-Sheet)
+  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)
+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)"
+motion:
+  microIn: "150ms ease-out"                       # fade-in / scale-in
+  enter: "200ms ease-out"                          # fade-in-up / slide-in
+  sheetSpring: "280ms cubic-bezier(0.32,0.72,0,1)" # Sheet / Dialog のドラッグ・展開
+components:
+  button:
+    background: "{colors.primary}"
+    color: "{colors.onPrimary}"
+    rounded: "{rounded.full}"
+    minHeight: "48px"
+  card:
+    background: "{colors.surface}"
+    border: "{colors.border}"
+    rounded: "{rounded.surface}"
+    elevation: "{elevation.md}"
+  dialog:
+    rounded: "{rounded.modal}"
+    elevation: "{elevation.dialog}"
+  sheet:
+    rounded: "{rounded.sheet}"
+  input:
+    border: "{colors.border}"
+    rounded: "{rounded.surface}"
+    minHeight: "48px"
+---
+
+# KSK Design System — DESIGN.md
+
+> AI コーディングエージェント向けの視覚言語サマリ。**1ファイルで KSK の見た目を
+> 再現できる**ことを目的に、トークン（front-matter）と「なぜ・どう使うか」（本文）を併記する。
+> 実装で実際に使う正準ソースは `tokens.json` と `src/styles/*.css`。本ファイルはその要約＋意図。
+
+## Overview
+
+KSK は **マルチテーマ統合 DS**。Brand 色（10行）を差し替えるだけで、Primitive → Semantic →
+Bridge の3層を伝って全コンポーネントの色が切り替わる。1つの DS で複数案件（BtoB/SaaS 系、
+EC/BtoC 系）を回すのが狙い。
+
+- **既定の人格**: 端正・信頼感（Blue）。情報密度は中、余白で呼吸させる。角は適度に丸い（ピル型ボタン＋丸い面）。
+- **基盤**: React 19 + Tailwind v4 + shadcn/Radix + iconsax。
+- **判断基準**: 色・余白・タイポは必ずトークン経由。生の値を書かない（後述 Do/Don't）。
+
+## Colors
+
+3層トークン。コンポーネントは**必ず Semantic 層を `var()` で参照**する（Primitive 直参照・生 hex 禁止）。
+
+| 用途 | トークン | 既定値(Blue) |
+|---|---|---|
+| ブランド | `var(--Brand-Primary)` | `#2563EB` |
+| 背景(白/薄灰) | `var(--Surface-Primary)` / `-Secondary` | `#FFFFFF` / `#F9FAFB` |
+| 文字(強/中/弱) | `var(--Text-High/Medium/Low-Emphasis)` | `#111827` / `#374151` / `#6B7280` |
+| 罫線 | `var(--Border-Low-Emphasis)` | `#E5E7EB` |
+| 状態 | `--Success/Warning/Caution/Info-Base` | `#16A34A` / `#EA580C` / `#DC2626` / `#2563EB` |
+
+- **状態色の正本**: 上記は `*-Base`（テキスト/アイコン基準＝Primitive **600**）。`tokens.json` を正本とし、本表はその要約。
+  バッジ/ピル等の強調 **fill** は別ロール `--Surface-*-Strong`（Primitive **500**）で、わざと一段明るい。役割が違うだけで矛盾ではない。
+- **Dark mode**: `.dark` で Semantic 層が自動反転（コンポーネント側の変更不要）。テーマ差し替え（Brand）と
+  light/dark は**直交2軸**。dark の semantic 値は `src/styles/semantic.css` の `.dark` が実装で、`tokens.json` の
+  `colors.semanticDark` に機械可読ミラーを持つ（契約テストで同期を保証）。
+- **Categorical（質的）**: `var(--Categorical-{1..16})` ＋ `-Subtle`(背景) / `-Bold`(文字)。
+  カテゴリの色分け専用でテーマ非依存。WCAG/色覚多様性を検証済み。文字には必ず `-Bold`。
+
+## Typography
+
+`typo-*` ユーティリティ1クラスに size/line-height/weight/tracking を集約。`text-sm`/`font-bold` 等の個別指定は禁止。
+
+- 見出し: `typo-heading-{sm..3xl}`（14→28px, line-height 1.5, 700）
+- 本文: `typo-body-{xs..lg}`（10→16px, line-height 1.75 系）
+- ラベル: `typo-label-{xs..lg}`（10→16px, 500）/ 特大: `typo-display-xl`(48px)
+- 色は別指定: `className="typo-body-sm text-[var(--Text-Low-Emphasis)]"`
+
+## Layout & Spacing
+
+- **4px グリッド**。余白・サイズは 4 の倍数（scale 0–60）。
+- 画面端マージン: `var(--page-px)`（既定 16px）。
+- **タッチターゲット**（モバイル）: WCAG 2.5.5 / Apple HIG に従い主要操作（ボタン/アイコンボタン/入力/ナビ）の
+  **min は 44px** 以上、推奨 48px。44 未満が避けられない **チップ（min 32px）は hitSlop**（不可視の拡張タップ領域）で
+  実効 44px を確保する。値の正本は `tokens.json` の `touchTargets`。
+
+## Elevation & Depth
+
+影は5段（`--shadow-sm/md/lg/dialog/tooltip`）。面は md、浮く要素（dropdown/popover）は lg、
+モーダルは dialog。**境界は影＋1px罫線**で表現し、濃い影の多用は避ける。
+
+## Shapes
+
+角丸はトークン化（ベタ書き禁止）。**面 < モーダル < シート**の順で丸くなる。
+
+| 用途 | トークン | 値 |
+|---|---|---|
+| Card / Input / Popover | `var(--Radius-Surface)` | 8px |
+| 中央 Dialog / AlertDialog | `var(--Radius-Modal)` | 24px |
+| Sheet（下/フロート） | `var(--Radius-Sheet)` | 32px |
+| Button / Chip | `rounded-full` | 9999px |
+
+> 素の `rounded-*` を使う場合、キーは **Tailwind v4 のユーティリティ名**と一致し値もその実描画 px と同じ
+> （`tokens.json` の `borderRadius`: none→sm(4)→md(6)→lg(8)→xl(12)→2xl(16)→full の連続スケール）。
+> 独自の `--radius-*` 上書きはしていないため、`rounded-md`/`rounded-xl` は Tailwind v4 既定の 6px/12px を描画する。
+
+## Motion
+
+- マイクロ(出現/スケール): **150ms ease-out**。
+- 入場(fade-up/slide): **200ms ease-out**。
+- Sheet/Dialog の展開・ドラッグ: **cubic-bezier(0.32, 0.72, 0, 1)（iOS 風スプリング）**。
+- 控えめが基本。バウンドや派手な動きはしない。`prefers-reduced-motion` を尊重。
+
+## Components
+
+代表例（トークン参照で構成）。
+
+- **Button**: bg `{colors.primary}` / text 白 / `rounded-full` / 高さ 48px。variant: default·secondary·tertiary·ghost·destructive·link。
+- **Card**: bg `{colors.surface}` ＋ 1px `{colors.border}` ＋ `{elevation.md}` ＋ `{rounded.surface}`。
+- **Dialog（中央モーダル）**= タスク面（フォーム/絞り込み）。`role="dialog"`、`{rounded.modal}`。
+- **AlertDialog / ConfirmDialog（割り込み確認）**= 削除等の"止める"操作。`role="alertdialog"`、背景タップで閉じない・中央表示。
+- **Sheet（端寄せ）**: `side="bottom"` でボトムシート。`swipeToClose` で全面下スワイプ閉じ。`{rounded.sheet}`。
+- **Input**: 1px `{colors.border}` ＋ `{rounded.surface}` ＋ 高さ 48px。
+
+## Voice & Tone
+
+- UI コピー: 日本語・**敬体（ですます）**・簡潔。専門用語を避け、操作の結果を端的に。
+- 確認/破壊操作は明示的に選ばせる（"削除する" 等、動詞で）。
+- テーマ別の人格: **Blue=端正/信頼**（BtoB·SaaS）, **Orange=温かみ**（EC·フード）, **Green=安心**（ヘルス·金融）, **Violet=上質**（プレミアム·教育）。
+
+## Do's and Don'ts
+
+**Do**
+- 色は Semantic トークン `var(--Surface-*)` / `var(--Brand-Primary)` を使う。
+- タイポは `typo-*` クラス。角丸は `var(--Radius-*)`。
+- アイコンは `iconsax-reactjs`。UI は DS コンポーネント（`<Button>`/`<Input>` 等）。
+- **文脈非依存に保つ**: 見た目を自前で固定する。テキストを描く要素は `text-[var(--Text-*)]`、サーフェス（カード/ポップオーバー/シート/ダイアログ等）は `bg-[var(--Surface-*)]`、枠線は `border-[var(--Border-*)]` を明示。親の継承や Tailwind v4 既定（`border`/`ring`/`outline` = currentColor）に依存しない。
+
+**Don't**
+- 生 `#hex` / Tailwind 標準色（`bg-blue-500` 等）を直書きしない。
+- `font-bold` / `text-sm` / `rounded-lg` / `rounded-[24px]` 等のベタ書きをしない（トークン経由）。
+- `lucide-react` / `heroicons` を使わない。生の `<button>`/`<input>`/`<a>` を使わない。
+- 確認ダイアログを `Dialog`（タスク面）で作らない（割り込みは `AlertDialog`/`ConfirmDialog`）。
+- 色なし `border` / 色未指定の text・bg を親の継承や currentColor 任せにしない。漏れは Storybook の **Hostile ctx** トグルで検出できる。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 奥野圭祐 (Keisuke Okuno)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.