ksk-design-system 1.35.0

package/MIGRATION.md

@@ -0,0 +1,107 @@
+# Migration Guide — `ksk-design-system`
+
+メジャーバージョン間の移行ガイド。
+patch / minor は原則破壊変更なし、自動アップグレード可（例外: **v1.34.0 で npm パッケージ名を変更**。import の置換が必要。下記参照）。
+
+## v2.0 (未リリース)
+
+まだメジャー破壊変更の予定はなし。
+
+破壊変更を入れる際にはここに以下を書く:
+1. 削除した識別子 / prop の一覧（rename テーブル）
+2. before / after コード例
+3. 自動移行コマンド: `npx ksk-design-system codemod v1-to-v2 ./src`
+4. 手動対応が必要な項目（codemod では拾えないケース）
+
+---
+
+## v1 系内の minor 変更（参考）
+
+### v1.34.0 — パッケージ名変更（要対応）＋ RN/Expo 対応
+
+**npm パッケージ名を `@ksk/design-system` → `ksk-design-system` に変更**（npm スコープ除去・OSS 公開準備）。機能面の破壊はないが、**import の一括置換が必要**:
+
+- TS/JS: `from "@ksk/design-system"` → `from "ksk-design-system"`
+- CSS: `@import "@ksk/design-system/preset"` → `@import "ksk-design-system/preset"`（`/themes/*` も同様）
+- 依存名: package.json の `@ksk/design-system` → `ksk-design-system`（vendoring の tgz 差し替え時）
+
+消費リポでの一括置換例:
+
+```bash
+git grep -lz '@ksk/design-system' -- src \
+  | xargs -0 sed -i '' 's#@ksk/design-system#ksk-design-system#g'
+```
+
+あわせて追加（いずれも破壊変更なし）:
+
+- **RN/Expo 対応**: `ksk-design-system/native`（解決済みトークン）と `ksk-design-system/native/ui`（RN コンポーネント）を新設
+- **CheckboxField** コンポーネント追加
+- 角丸トークンに `md`(6px) / `xl`(12px) を許可セットへ追加
+
+### v1.16.0 (予定)
+
+新機能追加のみ・破壊変更なし:
+
+- **Button** に `inverse` / `ghost-inverse` バリアント追加
+- **Button** に `hero` サイズ追加
+- **Checkbox** に `label` / `description` / `count` props 追加（polymorphic 化）
+- **Alert** に prop ベース API 追加（`title` / `description` / `icon` / `action`）
+- **Chip** に `soldOut` / `count` / `href` 状態追加
+- **Storybook** で autodocs グローバル化、guidelines.mdx 追加
+- **scripts/check-deps.sh** で ui → patterns 階層の逆依存を CI でブロック
+- **Vitest** 最小導入 + backwards-compat スイート
+- 全コンポーネントに `data-slot` / `data-variant` / `data-size` を徹底
+- **preset.css**: Tailwind v4 の `currentColor` 既定対策として、border-color / outline-color のベースレイヤ保険を追加。`@import "ksk-design-system/preset"` するだけで有効。破壊変更なし — 明示色を持つ枠線は不変で、色未指定の枠線のフォールバックのみ `--border` / `--ring` に固定される（消費側で枠線が黒ずむ不具合を防止）
+
+何もしなくても既存コードはそのまま動く。
+
+### v1.15.x
+
+過去の minor / patch 履歴は GitHub Releases を参照。
+
+---
+
+## 移行作業の進め方
+
+### Step 1. Codemod を dry-run
+
+```bash
+npx ksk-design-system codemod vX-to-vY ./src --dry
+```
+
+書き換え対象ファイル一覧が表示される。
+
+### Step 2. 実際に適用
+
+```bash
+npx ksk-design-system codemod vX-to-vY ./src
+git diff
+```
+
+`git diff` で意図通りか確認。
+
+### Step 3. ESLint で残骸チェック
+
+`eslint.config.js` に:
+
+```js
+import kskDeprecated from "ksk-design-system/eslint/deprecated"
+
+export default [
+  {
+    plugins: { "ksk-deprecated": kskDeprecated },
+    rules: { "ksk-deprecated/no-deprecated": "error" },
+  },
+]
+```
+
+これで codemod が拾えなかった旧 API の使用を検出できる。
+
+### Step 4. 動作確認
+
+```bash
+npm run test
+npm run build
+```
+
+それから本番デプロイへ。

package/PUBLISHING.md

@@ -0,0 +1,160 @@
+# Publishing — `ksk-design-system`
+
+`ksk-design-system` のリリース・配布手順。
+
+> **配布方式**: このパッケージは npm レジストリには公開しない。
+> `npm pack` で生成した tgz を各消費リポジトリの `vendor/` に置き、
+> `package.json` から `file:vendor/ksk-design-system-X.Y.Z.tgz` で参照する **vendoring 方式**。
+> 消費リポ: belle-todo / trip_todo / ninshin-todo / yokoku-app / pawly（いずれも `~/LocalDev/` 直下）。
+
+## 前提
+
+- main ブランチが clean (`git status` で何もない)、リモートと一致
+- 消費リポが `~/LocalDev/<name>` に clone 済みで、`gh` CLI が使えること（PR 自動作成に使用）
+
+## 最短手順（推奨）
+
+```bash
+bash scripts/release.sh minor   # patch / minor / major / x.y.z
+```
+
+これだけ。中で以下を全部やる:
+
+1. `git diff --quiet` & main ブランチチェック（曜日チェック）
+2. `npm run check`
+3. `npm version <level>`（tag 切り）
+4. `npm pack`（新名 tgz 生成）
+5. `git push origin main --tags`
+6. `bash scripts/bump-consumers.sh <version>`（5 リポへ PR 自動作成）
+
+> v1.35.0 で旧名 `@ksk/design-system` 互換 tgz の生成は廃止。
+> 消費5リポ + todo-shared が新名 `ksk-design-system` に移行済。
+> 旧名復活が必要になった場合は git history で v1.35.0 期の release.sh を参照。
+
+個別に手作業したい場合は以下の手動フローを参照。
+
+## リリースフロー（手動）
+
+### 1. ローカルで動作確認
+
+```bash
+npm run check         # tsc + lint + deps + drift + lookup
+npm test              # vitest スイート
+npm run storybook     # 目視確認（特に新機能のストーリー）
+```
+
+すべて green であること。失敗があれば修正してコミット。
+
+### 2. バージョン更新
+
+```bash
+# patch (bug fix)        例: 1.15.2 → 1.15.3
+npm version patch
+
+# minor (feature add, 互換あり) 例: 1.15.2 → 1.16.0
+npm version minor
+
+# major (破壊変更)        例: 1.15.2 → 2.0.0
+npm version major
+```
+
+`npm version` が自動で `package.json` を更新し、`v1.16.0` タグを切る。
+`dist/` の再ビルド・コミットはこの version bump のタイミングでのみ行う。
+
+### 3. tgz 生成
+
+```bash
+npm pack
+```
+
+`prepack` フックで `npm run build:lib` が自動実行され、リポ直下に
+`ksk-design-system-X.Y.Z.tgz` が生成される。
+
+中身を確認したい場合:
+
+```bash
+npm pack --dry-run | tail -50
+```
+
+公開ファイル一覧を確認。`package.json#files` で許可した中身だけが入っているはず:
+- `dist/`
+- `bin/`
+- `templates/`
+- `contracts/`
+- `eslint/`
+- `scripts/codemod/`
+- `src/preset.css` / `src/styles/` / `src/themes/`
+- `tokens.json`
+- `AGENTS.md` / `CLAUDE.md` / `MIGRATION.md` / `PUBLISHING.md` / `RELEASE.md`
+- `src/components/COMPONENT_LOOKUP.md`
+
+### 4. push
+
+```bash
+git push origin main --tags
+```
+
+### 5. 消費リポへ配布
+
+```bash
+# 全リポ一括
+bash scripts/bump-consumers.sh 1.16.0
+
+# 特定リポのみ
+bash scripts/bump-consumers.sh 1.16.0 belle-todo pawly
+```
+
+各消費リポで `chore/bump-ds-<version>` ブランチを切り、tgz の `vendor/` 配置・
+`package.json` の参照書換・`npm install`・commit・push・PR 作成まで自動で行う。
+失敗したリポはスキップされ最後にまとめて報告されるので、個別にリトライする。
+
+過去版の tgz は `vendor/` に残す運用（ロールバックを git revert だけで済ませるため）。
+
+### 6. PR マージ
+
+各消費リポの PR で CI が green なことを確認してマージ。
+破壊変更を含む場合は、全リポ一括でなく 1〜2 リポで先に動作確認してから残りを配布する。
+
+## 緊急ホットフィックス
+
+本番障害時の応急対応:
+
+```bash
+# main から直接でも OK（hotfix ブランチを切る暇がない時）
+# 修正コミット
+git commit -m "fix: 重大なバグの説明"
+
+npm version patch
+npm pack
+git push origin main --tags
+bash scripts/bump-consumers.sh <version> <影響リポ...>
+```
+
+修正コミットの背景・影響範囲を `RELEASE.md` の「ホットフィックス履歴」セクションに必ず追記。
+
+## バージョニング規約
+
+`ksk-design-system` は [Semantic Versioning](https://semver.org/lang/ja/) に従う:
+
+| 種類 | 内容 | 例 |
+|---|---|---|
+| patch | バグ修正・内部最適化 | 1.15.2 → 1.15.3 |
+| minor | 新コンポーネント追加・新 prop 追加（既存壊さない） | 1.15.x → 1.16.0 |
+| major | 既存 prop 削除・コンポーネント rename・default 値変更 | 1.x → 2.0.0 |
+
+破壊変更時は `scripts/codemod/` に migration script を必ず添える。
+`MIGRATION.md` に rename テーブル / before-after を文書化。
+
+## 注意
+
+- 配布前に必ず `npm pack --dry-run` で中身確認
+- `package.json#exports` を変更したら必ず利用側プロジェクトでの import を試す
+- 金曜午後のリリースは厳禁（週末に障害対応できない）
+- メジャーリリースは月初の月曜が望ましい（フィードバック収集期間が取れる）
+
+## npm 公開について
+
+過去にタグ push で npm publish する GitHub Actions（`publish.yml`）が存在したが、
+実際の配布が vendoring 方式であり NPM_TOKEN も未設定で失敗し続けていたため削除した。
+将来 npm レジストリ公開に切り替える場合は、NPM_TOKEN の Secrets 登録と
+workflow の再作成をセットで行うこと。

package/README.md

@@ -0,0 +1,59 @@
+# KSK Design System
+
+複数クライアント案件を **1つのデザインシステム** で高速に回すために設計された、React 製のマルチテーマ対応 UI ライブラリ。BtoB / SaaS の信頼感と EC / BtoC の購買体験、2つのドメインの設計思想を統合しています。
+
+**🔗 ライブ Storybook → https://ksk-design-system.vercel.app**
+
+110 コンポーネントを実際に操作・確認できます。
+
+---
+
+## ✨ 特徴
+
+- **マルチテーマ** — Brand 色の 10 行を差し替えるだけで、全コンポーネントの見た目が自動で切り替わる（Primitive → Semantic → Bridge の 3 層トークン構造）
+- **アクセシブル** — shadcn/ui（Radix UI ベース）+ `@storybook/addon-a11y` で a11y を担保
+- **Tailwind CSS v4 ネイティブ** — `@theme` ベースのトークン設計
+- **型安全** — React 19 + TypeScript、CVA によるバリアント管理
+- **110 コンポーネント** — 汎用 UI 55 / EC 系 11 / 管理画面系 8 / レイアウトシェル 3 / 汎用パターン 33
+
+## 🎨 テーマ
+
+Brand 色を差し替えるだけで業種に合わせた配色に切り替わります。
+
+| テーマ | Brand-500 | 想定業種 |
+|--------|-----------|---------|
+| Default (Blue) | `#3B82F6` | 汎用・SaaS・BtoB |
+| Orange | `#F97316` | EC・フード・エンタメ |
+| Green | `#16A34A` | ヘルスケア・サステナ・金融 |
+| Violet | `#7C3AED` | プレミアム・クリエイティブ・教育 |
+
+## 🧱 技術スタック
+
+React 19 + TypeScript / Vite / **Tailwind CSS v4** / shadcn/ui（Radix UI）/ CVA / iconsax-reactjs / Storybook
+
+**Peer dependencies**: `react` 18 or 19, `react-dom`, `tailwindcss` ^4, `radix-ui`, `@radix-ui/react-slot`, `iconsax-reactjs`
+
+## 🚀 使い方
+
+```css
+/* プロジェクトの CSS */
+@import "ksk-design-system/preset";
+@import "./themes/my-client.css"; /* Brand 色を差し替えたテーマ */
+```
+
+```tsx
+import { Button, Card, Input, FormField } from "ksk-design-system"
+```
+
+新規クライアント案件では、テーマファイルで `--Primitive-Brand-500` などブランドカラーの 10 行を定義するだけで、全コンポーネントがそのブランドカラーで動作します。
+
+> **インストールについて**: 現在は npm 未公開です。まずは上のライブ Storybook でコンポーネントと挙動をご確認ください。npm パッケージとしての配布を準備中です。
+
+## 📖 ドキュメント
+
+- **ライブ Storybook**: https://ksk-design-system.vercel.app — 全コンポーネントのバリアント・テーマ切り替えを操作可能
+- 設計思想・トークン体系の詳細は `CLAUDE.md` / `DESIGN.md` を参照
+
+## 📄 ライセンス
+
+[MIT](./LICENSE) © 奥野圭祐 (Keisuke Okuno)

package/RELEASE.md

@@ -0,0 +1,82 @@
+# Release Cadence — `ksk-design-system`
+
+`ksk-design-system` のリリーススケジュール・運用ルール。
+
+## 通常リリースサイクル
+
+| 種類 | 頻度 | 曜日 |
+|---|---|---|
+| patch | 必要時 | 月〜木（金曜禁止） |
+| minor | 隔週 | 火曜 or 水曜 |
+| major | 四半期 | 月初の月曜 |
+
+**金曜午後・休前日のリリースは禁止**。週末に障害対応できる体制でない時間帯は patch も避ける。
+
+## メジャーリリースの段取り
+
+メジャー (`vX → vX+1`) は破壊変更を含むため、最低 4 週間前から計画する:
+
+```
+T-4w  破壊変更内容の確定 → MIGRATION.md 草案作成
+T-3w  scripts/codemod/vX-to-vY.mjs を実装、利用側で dry-run 検証
+T-2w  RC 版の tgz を 1〜2 の消費リポへ先行配布、動作確認
+T-1w  feedback 反映、ESLint 旧 API ルールを "error" に昇格
+T-0   全消費リポへ配布 (bump-consumers.sh)、リリースノート公開、社内告知
+T+1w  次の patch で旧 API を完全削除
+```
+
+## ホットフィックス手順
+
+本番障害が発生したら:
+
+1. main で直接修正（or hotfix ブランチ）
+2. `npm version patch`
+3. `npm pack` → `bash scripts/bump-consumers.sh <version> <影響リポ...>`
+4. 影響範囲・原因・修正内容を「ホットフィックス履歴」に記録
+5. ポストモーテムを Issue / wiki に書く
+
+## ホットフィックス履歴
+
+| 日付 | バージョン | 内容 | 影響 |
+|---|---|---|---|
+| 2026-05-30 | v1.21.2 | Sheet (`side="bottom"` / `swipeToClose` / `bottom-glass`) が仮想キーボード表示時にシート上端を画面外へ出さないよう `visualViewport` 監視で修正（PR #12） | モバイルの入力付きボトムシートでタイトル/ドラッグハンドルが隠れる不具合を解消 |
+| 2026-06-13 | v1.31.1 | `.glass-specular > *` が**絶対配置の子要素**の `position`/`z-index` を踏み潰す問題を `:not(.absolute):not(.fixed):not(.sticky)` 除外で修正 | glass 面に重ねた絶対配置オーバーレイ（閉じる × 等）が consumer 側の `absolute`/`z-*` を奪われ角からはみ出す不具合を解消 |
+
+新しいホットフィックスがあれば追記する。
+
+## リリースノート書き方
+
+GitHub Releases にコピペできるテンプレ:
+
+```md
+## v1.16.0 (2026-MM-DD)
+
+### Features
+- Button: `inverse` / `ghost-inverse` バリアント追加（暗背景上の CTA 用）
+- Button: `hero` サイズ追加（hero / final-CTA 専用ピル型）
+- Checkbox: `label` / `description` / `count` props でポリモーフィック化
+
+### Fixes
+- ...
+
+### Docs
+- ...
+
+### Migration
+- 破壊変更なし。vendor tgz の差し替え PR（bump-consumers.sh が自動作成）をマージするだけで OK。
+```
+
+破壊変更がある場合は必ず:
+
+```md
+### Breaking Changes
+- `OldComponent` を削除。`NewComponent` を使ってください。
+  自動移行: `npx ksk-design-system codemod v1-to-v2 ./src`
+- 詳細: [MIGRATION.md](./MIGRATION.md)
+```
+
+## 関連
+
+- [PUBLISHING.md](./PUBLISHING.md) — 実際の手順
+- [MIGRATION.md](./MIGRATION.md) — メジャー毎の移行ガイド
+- [scripts/codemod/README.md](./scripts/codemod/README.md) — codemod 雛形と使い方

package/bin/init.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+
+// ksk-design-system init
+// Consumer プロジェクトに AI (Claude / Codex) 向けルールファイルを設置する。
+// AI エージェントは node_modules 配下のファイルを自動で読まないため、
+// プロジェクトルートに AGENTS.md / CLAUDE.md（node_modules 内の DS ルールを
+// 参照する薄いポインタ）を置く必要がある。
+//
+// Usage:
+//   npx ksk-ds init          # AGENTS.md + CLAUDE.md を設置
+//   npx ksk-ds init --force  # 既存ファイルを上書き
+//   npx ksk-ds postinstall   # npm postinstall から呼ばれる silent モード
+
+import { copyFileSync, existsSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const pkgRoot = resolve(__dirname, "..")
+
+const args = process.argv.slice(2)
+const cmd = args[0] || "init"
+const force = args.includes("--force")
+
+if (cmd === "help" || cmd === "--help" || cmd === "-h") {
+  console.log(`ksk-design-system CLI
+
+使い方:
+  npx ksk-ds init          AI ルールファイルを設置
+  npx ksk-ds init --force  既存ファイルを上書き
+`)
+  process.exit(0)
+}
+
+if (cmd !== "init" && cmd !== "postinstall") {
+  console.error(`未知のコマンド: ${cmd}`)
+  console.error(`npx ksk-ds help を参照してください`)
+  process.exit(1)
+}
+
+// ─── postinstall モードのガード ─────────────────────────────
+// INIT_CWD は npm install が実行されたディレクトリ（consumer のルート）。
+// 未設定、または pkgRoot と同じ場合は DS 自身のインストールコンテキストなのでスキップ。
+const isPostinstall = cmd === "postinstall"
+const consumerRoot = process.env.INIT_CWD || process.cwd()
+
+if (isPostinstall) {
+  // DS 自身を開発している場合（INIT_CWD が pkgRoot）はスキップ
+  if (!process.env.INIT_CWD || resolve(consumerRoot) === pkgRoot) {
+    process.exit(0)
+  }
+  // consumer のルートに package.json が無ければスキップ（安全のため）
+  if (!existsSync(join(consumerRoot, "package.json"))) {
+    process.exit(0)
+  }
+}
+
+const files = [
+  { src: "templates/AGENTS.md", dest: "AGENTS.md", label: "Codex 用" },
+  { src: "templates/CLAUDE.md", dest: "CLAUDE.md", label: "Claude Code 用" },
+]
+
+if (!isPostinstall) {
+  console.log("ksk-design-system init")
+  console.log("AI (Claude / Codex) 向けルールファイルを設置します。\n")
+}
+
+let created = 0
+let skipped = 0
+
+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}`)
+    }
+    process.exit(isPostinstall ? 0 : 1)
+  }
+
+  if (existsSync(destPath) && !force) {
+    if (!isPostinstall) {
+      console.log(`  ⏭  ${dest} は既に存在するためスキップ（--force で上書き）`)
+    }
+    skipped++
+    continue
+  }
+
+  copyFileSync(srcPath, destPath)
+  if (isPostinstall) {
+    console.log(`[ksk-design-system] ${dest} をプロジェクトルートに設置しました`)
+  } else {
+    console.log(`  ✓ ${dest} を設置しました（${label}）`)
+  }
+  created++
+}
+
+if (isPostinstall) {
+  process.exit(0)
+}
+
+console.log(`\n完了: ${created} 作成 / ${skipped} スキップ`)
+
+if (created > 0) {
+  console.log(`
+次のステップ:
+  1. AI (Claude Code / Codex) を再起動してルールを読み込ませる
+  2. UI を作る前に必ず node_modules/ksk-design-system/{AGENTS.md,CLAUDE.md,contracts/*,tokens.json} を AI に読ませる
+  3. スクラッチコード（ハードコードカラー・余白・角丸等）を書かない運用を徹底する
+`)
+}