@cakejp/design-system 0.3.0

package/MIGRATION.md

@@ -0,0 +1,228 @@
+# Migration Guide
+
+@cakejp/design-system のバージョン間移行ガイド。
+
+---
+
+## v0.2.x → v0.3.0
+
+### 概要
+
+v0.3.0 では **3-tier 構造への再編成** と **業界標準命名への揃え** を実施しました。
+
+| 変更カテゴリ | 内容 |
+|---|---|
+| **フォルダ構造** | `ui/` `cake/` → `foundations/` `primitives/` `ec/` |
+| **コンポーネント rename** | 7 個（Material 固有用語・冗長命名・非標準用語の整理） |
+| **API 変更** | `MypageSidebar` → `SideNav + mypageMenuGroups` |
+
+### 後方互換性
+
+**v0.2.x のコードは v0.3.0 でもそのまま動きます。** 旧名はすべて `@deprecated` alias として残してあります。
+
+ただし開発環境（`NODE_ENV !== 'production'`）では console に警告が出ます：
+
+```
+[@cakejp/design-system] 'TopAppBar' is deprecated and will be removed in v1.0.
+  → Use 'Header' instead.
+  → Run 'npx @cakejp/design-system codemod v0.2-to-v0.3' to auto-migrate.
+  → See https://github.com/flashpark/cake-design-system/blob/main/MIGRATION.md
+```
+
+**production ビルドには影響しません**（dead code elimination で警告は削除されます）。
+
+### 自動移行
+
+```bash
+# 利用側プロジェクトで実行
+npx @cakejp/design-system codemod v0.2-to-v0.3 ./src
+```
+
+このコマンドが自動で：
+- `import { TopAppBar }` → `import { Header }` に置換
+- JSX タグ `<TopAppBar>` → `<Header>` に置換
+- 型 `TopAppBarProps` → `HeaderProps` に置換
+- 7 コンポーネント全部一括対応
+
+### 手動移行リファレンス
+
+#### 1. シンプル rename（同一シグネチャ）
+
+| v0.2.x | v0.3.0+ | 理由 |
+|---|---|---|
+| `Banner` | `Alert` (bordered variant + prop-based API) | Alert と機能重複していたため統合 |
+| `TopAppBar` | `Header` | Material 固有用語 → HTML semantic に統一 |
+| `BottomNavigation` | `BottomTabBar` | Material 固有 → iOS / Bootstrap 標準 |
+| `BottomAction` | `StickyActionBar` | 用途不明 → Web 慣習 (Bootstrap fixed-bottom) |
+| `Balloon` | `CoachMark` | 日本語圏特有 → Atlassian / Pendo 標準 |
+| `NavigationRibbon` | `SubNav` | 「Ribbon」は MS Office 固有 → GitHub Primer 標準 |
+| `CategoryIconStrip` | `CategoryShortcuts` | 「Strip」は曖昧 → Shopify / Ant Design 慣習 |
+| `mypageSidebarDefaultGroups` | `mypageMenuGroups` | 命名整理 |
+
+### Banner → Alert (bordered variant + prop-based API)
+
+v0.3.0 で Alert の bordered variant に **prop-based API** を追加。
+`children` を渡さない場合は title / description / action prop で構築できる。
+見た目は Alert の bordered スタイル（白bg + 色枠 + 5px outer ring）で統一。
+
+```tsx
+// Before (v0.2.x)
+import { Banner } from '@cakejp/design-system'
+
+<Banner
+  variant="caution"
+  title="銀行口座が未登録です"
+  description="売上の振込を受け取るには、銀行口座の登録が必要です。"
+  action={<Button>登録する</Button>}
+/>
+
+// After (v0.3+)
+import { Alert } from '@cakejp/design-system'
+
+<Alert
+  variant="warning"
+  title="銀行口座が未登録です"
+  description="売上の振込を受け取るには、銀行口座の登録が必要です。"
+  action={<Button>登録する</Button>}
+/>
+```
+
+variant 対応表:
+
+| Banner variant | Alert variant |
+|---|---|
+| `caution` | `warning` または `error`（赤色寄りなら `error`） |
+| `warning` | `warning` |
+| `info` | `info` |
+| `success` | `success` |
+
+prop API は同じ（title / description / action / icon）。
+アイコンは variant に応じて自動選択（Warning2 / InfoCircle / TickCircle / CloseCircle）、
+`icon` prop でカスタムアイコンも指定可能。
+
+---
+
+これらは **import 文・型名・JSX タグの単純置換** で対応可能：
+
+```tsx
+// Before
+import { TopAppBar, BottomNavigation, Balloon } from '@cakejp/design-system'
+import type { TopAppBarProps } from '@cakejp/design-system'
+
+<TopAppBar variant="logo" />
+<BottomNavigation items={[...]} />
+<Balloon direction="top">ヒント</Balloon>
+
+// After
+import { Header, BottomTabBar, CoachMark } from '@cakejp/design-system'
+import type { HeaderProps } from '@cakejp/design-system'
+
+<Header variant="logo" />
+<BottomTabBar items={[...]} />
+<CoachMark direction="top">ヒント</CoachMark>
+```
+
+#### 2. API 変更を伴う移行: `MypageSidebar`
+
+汎用サイドナビ + Cake.jp 専用データに分離されました。
+
+```tsx
+// Before (v0.2.x)
+import { MypageSidebar } from '@cakejp/design-system'
+
+<MypageSidebar activeMenu="news" />
+// ↑ デフォルトで Cake.jp マイページの 17 項目メニューを表示
+
+// After (v0.3+) — 推奨
+import { SideNav, mypageMenuGroups } from '@cakejp/design-system'
+
+<SideNav
+  groups={mypageMenuGroups}
+  activeMenu="news"
+  ariaLabel="マイページメニュー"
+/>
+```
+
+`SideNav` は汎用なので、jobboard など他事業の独自メニューでも使えます：
+
+```tsx
+import { SideNav } from '@cakejp/design-system'
+import { Briefcase, FileText } from 'iconsax-reactjs'
+
+const jobboardMenu = [
+  {
+    items: [
+      { icon: <Briefcase size={16} />, label: "求人検索", href: "/jobs", key: "jobs" },
+      { icon: <FileText size={16} />, label: "応募履歴", href: "/applications", key: "apps" },
+    ]
+  }
+]
+
+<SideNav groups={jobboardMenu} activeMenu="jobs" ariaLabel="求人メニュー" />
+```
+
+#### 3. ディレクトリ構造（社内開発のみ影響）
+
+外部 npm 利用側は影響なし（バレル export 経由）。社内コード内の個別 import を使っている場合：
+
+```tsx
+// Before
+import { Button } from '@/components/ui/button'
+import { ProductCard } from '@/components/cake/product-card'
+
+// After
+import { Button } from '@/components/foundations/button'
+import { ProductCard } from '@/components/ec/product-card'
+```
+
+新構造：
+
+```
+src/components/
+├── foundations/   shadcn ベース汎用 UI（46個）
+├── primitives/    業界汎用パターン（35個・jobboard 等他事業でも再利用可）
+└── ec/            Cake.jp / EC 事業特化（23個）
+```
+
+### 段階的削除スケジュール
+
+| バージョン | リリース予定 | deprecated alias の状態 |
+|---|---|---|
+| **v0.3.0** | 2026-05 | ✅ 動作（dev mode で console.warn） |
+| **v0.4.0** | 2026-07 予定 | ⚠️ 動作（production でも警告 / runtime warn 強化） |
+| **v0.5.0** | 2026-09 予定 | 🚨 動作（npm install 時 peer warning） |
+| **v1.0.0** | 2026-11 予定 | ❌ 完全削除 |
+
+利用側は **v0.4 までに移行完了** が推奨。Codemod を使えば数分で対応可能です。
+
+### 移行進捗の自己診断
+
+利用側プロジェクトで残作業を可視化：
+
+```bash
+npx @cakejp/design-system check-migration ./src
+# → 旧 API 利用箇所をリストアップ
+# → 残工数（n 件中 m 件移行済み）を報告
+```
+
+### ESLint plugin（v0.4 で導入予定）
+
+```json
+// .eslintrc.json
+{
+  "extends": ["@cakejp/design-system/eslint"]
+}
+```
+
+旧名 import がエディタで赤線エラー、`--fix` で自動修正。
+
+### サポート
+
+質問・問題報告は GitHub Issue: https://github.com/flashpark/cake-design-system/issues
+
+---
+
+## 過去のリリース
+
+- v0.2.0 → v0.2.2: 後方互換あり（patch リリース）
+- v0.1.x → v0.2.0: shadcn 構造の整理（社内のみ、利用側影響なし）

package/README.md

@@ -0,0 +1,79 @@
+# @cakejp/design-system
+
+Cake.jp デザインシステム — 104 個の React コンポーネント・カラートークン・タイポグラフィ。
+
+## インストール
+
+```bash
+npm install @cakejp/design-system
+```
+
+## 使い方
+
+```tsx
+import { Button, ProductCard, Header } from "@cakejp/design-system"
+import "@cakejp/design-system/dist/index.css"
+
+<Header logo={<MyLogo />} variant="logo" />
+<ProductCard ... />
+<Button>カートに入れる</Button>
+```
+
+## 構造
+
+3-tier アーキテクチャ:
+
+| レイヤー | 内容 | コンポーネント数 |
+|---|---|---|
+| `foundations/` | shadcn ベース汎用 UI（Button, Input, Dialog 等） | 46 |
+| `primitives/` | 業界汎用パターン（Header, SideNav, PriceDisplay 等） | 35 |
+| `ec/` | Cake.jp / EC 事業特化（ProductCard, CouponCard 等） | 23 |
+
+依存方向: `ec/` → `primitives/` → `foundations/`（逆方向 import 禁止、CI で検証）
+
+## ドキュメント
+
+- [Storybook](https://flashpark.github.io/cake-design-system/) — 全コンポーネントのカタログ
+- [CHANGELOG.md](./CHANGELOG.md) — リリース履歴
+- [MIGRATION.md](./MIGRATION.md) — バージョン間移行ガイド
+- [RELEASE.md](./RELEASE.md) — リリース運用ルール（週1手動）
+- [CLAUDE.md](./CLAUDE.md) — AI エージェント向け使用ルール
+
+## バージョン移行
+
+### v0.2.x → v0.3.0
+
+```bash
+# 自動移行（推奨）
+npx @cakejp/design-system codemod v0.2-to-v0.3 ./src
+
+# 移行進捗の確認
+npx @cakejp/design-system check-migration ./src
+```
+
+旧 API（`TopAppBar`, `BottomNavigation`, `Balloon` 等）は v0.3.0 でも動作しますが、開発時に console 警告が出ます。v1.0 で完全削除予定。
+
+詳細は [MIGRATION.md](./MIGRATION.md) を参照。
+
+#### 段階的削除スケジュール
+
+| バージョン | リリース予定 | 旧 API（deprecated）の状態 |
+|---|---|---|
+| v0.3.0 | 2026-05 | ✅ 動作 + dev mode 警告 |
+| v0.4.0 | 2026-07 | ⚠️ 動作 + production でも警告 |
+| v0.5.0 | 2026-09 | 🚨 動作 + npm install 時警告 |
+| v1.0.0 | 2026-11 | ❌ 完全削除 |
+
+## 開発
+
+```bash
+npm install
+npm run storybook       # Storybook を起動
+npm run build:lib       # ライブラリビルド
+npm run check           # 全品質ゲート
+npm run test:compat     # 後方互換テスト
+```
+
+## ライセンス
+
+UNLICENSED（社内利用）

package/RELEASE.md

@@ -0,0 +1,205 @@
+# Release Process
+
+@cakejp/design-system のリリース運用ルール。
+
+---
+
+## 🗓 基本方針
+
+- **週 1 回・手動リリース** を原則とする
+- 自動 publish は無効化済み（タグ push しても何も起きない）
+- **金曜は publish しない**（万一トラブった時に対応できる人がいないため）
+- 緊急パッチは個別に手動実行
+
+### 標準スケジュール
+
+| 曜日 | 内容 |
+|---|---|
+| 月〜木 | 開発・PR レビュー・main マージ |
+| **金曜** | リリース確認・取りまとめ・version bump（コミットまで）<br>**publish はしない** |
+| 土・日 | お休み |
+| **月曜** | npm publish 実行 → 利用側で動作確認 |
+| 火〜木 | 問題があれば patch リリース対応 |
+
+### この運用にする理由
+
+- **Read-Only Friday**: 金曜は本番 publish しない（業界慣習）
+- 障害発生時に **対応できるエンジニアが翌営業日まで動ける** 状態でリリース
+- 利用側 (cake-api/frontend 等) も **週初めから安心して install** できる
+- 金曜時点で「意味ある単位にまとまっているか」を確認できれば、月曜の publish はスムーズ
+
+---
+
+## 📦 リリース手順
+
+### 金曜 (確認のみ・publish はしない)
+
+1. main の差分を確認
+2. CHANGELOG.md を整理（minor/patch 判断）
+3. 必要なら version bump コミットだけ作る → main に push
+4. **ここで publish はせず、月曜の作業に残す**
+
+### 月曜 (publish 実行)
+
+1. main 最新を pull
+2. dry-run で事前確認
+3. 本番 publish
+4. cake-api/frontend で動作確認
+5. Slack で告知
+
+---
+
+### 詳細手順
+
+### 1. リリース対象の取りまとめ
+
+```bash
+# main にマージ済みの差分を確認
+git log v$(npm view @cakejp/design-system version)..main --oneline
+```
+
+「意味ある単位」になっているか確認:
+- 機能追加・破壊的変更が複数ある → minor bump (`0.3.0` → `0.4.0`)
+- バグ修正のみ → patch bump (`0.3.0` → `0.3.1`)
+- 互換性ある内部改善のみ → patch bump
+
+### 2. version bump
+
+```bash
+# patch リリース
+npm version patch -m "chore(release): v%s"
+
+# minor リリース
+npm version minor -m "chore(release): v%s"
+
+# major リリース（注意）
+npm version major -m "chore(release): v%s"
+```
+
+`npm version` は package.json と package-lock.json を更新し、
+コミット作成までやってくれる。タグ作成は workflow 側でやるので
+`--no-git-tag-version` を付けたい場合は手動コミット。
+
+### 3. CHANGELOG.md / MIGRATION.md 更新
+
+破壊的変更・新機能・バグ修正の概要を CHANGELOG に追記。
+
+### 4. main に push
+
+```bash
+git push origin main
+```
+
+### 5. dry-run で事前検証
+
+```bash
+gh workflow run publish.yml -f dry_run=true
+```
+
+または GitHub UI で **Actions > Publish to npm > Run workflow** から実行。
+失敗ログを確認し、問題なければ次へ。
+
+### 6. 本番 publish
+
+```bash
+gh workflow run publish.yml -f dry_run=false -f tag_after_publish=true
+```
+
+または GitHub UI で実行。
+Workflow が npm publish + `v{version}` タグ作成を自動でやる。
+
+### 7. リリース後の確認
+
+```bash
+# npm に反映確認
+npm view @cakejp/design-system@$(node -p "require('./package.json').version")
+
+# 利用側で install 確認
+cd ../cake-api/frontend
+npm install @cakejp/design-system@latest
+```
+
+---
+
+## 🚨 緊急パッチ
+
+平日でもセキュリティ脆弱性・本番障害対応のパッチは即時リリース可能:
+
+```bash
+# 1. fix ブランチ
+git checkout -b fix/critical-issue main
+# ... 修正
+
+# 2. PR → 緊急マージ
+gh pr create --base main --title "fix: critical security issue"
+gh pr merge --squash
+
+# 3. patch bump
+git checkout main && git pull
+npm version patch -m "chore(release): v%s (hotfix)"
+git push origin main
+
+# 4. publish
+gh workflow run publish.yml -f dry_run=false
+```
+
+---
+
+## 🎯 ブランチ運用
+
+| 接頭辞 | 用途 | リリースに含める? |
+|---|---|---|
+| `feat/...` | 機能追加 | minor bump |
+| `fix/...` | バグ修正 | patch bump |
+| `refactor/...` | 内部整理 | minor or patch |
+| `docs/...` | ドキュメント | patch (またはスキップ) |
+| `chore/...` | 雑務（依存更新等） | リリース対象外（マージはする） |
+
+---
+
+## 🔒 publish 権限
+
+publish 操作は **NPM_TOKEN を持つ GitHub Actions のみ** が実行可能。
+ローカルから `npm publish` を直接叩く運用は禁止。
+
+token 管理:
+- npmjs.com で Access Token を発行
+- リポジトリの Settings > Secrets and variables > Actions > `NPM_TOKEN`
+- token は **少なくとも 1 年に 1 度** rotate
+
+---
+
+## 📋 リリース前チェックリスト
+
+```
+[ ] main 最新を pull
+[ ] 全 CI 通過確認
+[ ] npm run check で品質ゲート OK
+[ ] CHANGELOG.md 更新
+[ ] package.json version bump
+[ ] dry_run で事前検証
+[ ] publish 実行
+[ ] npm view で反映確認
+[ ] cake-api/frontend で動作確認
+[ ] Slack #design-system チャンネルに告知
+```
+
+---
+
+## ⚠️ よくある失敗パターン
+
+| 失敗 | 原因 | 対策 |
+|---|---|---|
+| publish が走らない | NPM_TOKEN 未設定 / 期限切れ | secrets を再登録 |
+| `npm version` が main 以外で走る | 別ブランチで実行 | main で実行する |
+| dist が古い | build:lib スキップ | workflow が自動で実行するので問題なし |
+| 同じバージョンを 2 回 publish | npm が拒否 | バージョンを bump し直す（1 度発行された version は永久に上書き不可） |
+| `prepack` で本番ビルド失敗 | peer dep 不足 | npm ci で全部入る、ローカルで再現できないなら CI ログを確認 |
+
+---
+
+## 🔗 関連ドキュメント
+
+- [CHANGELOG.md](./CHANGELOG.md) — 過去のリリース履歴
+- [MIGRATION.md](./MIGRATION.md) — バージョン間の移行ガイド
+- [.github/workflows/publish.yml](./.github/workflows/publish.yml) — publish workflow 定義

package/bin/init.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+
+// @cakejp/design-system init
+// Consumer プロジェクトに AI (Claude / Codex) 向けルールファイルを設置する。
+// AI エージェントは node_modules 配下のファイルを自動で読まないため、
+// プロジェクトルートに AGENTS.md / CLAUDE.md（node_modules 内の DS ルールを
+// 参照する薄いポインタ）を置く必要がある。
+//
+// Usage:
+//   npx cakejp-ds init          # AGENTS.md + CLAUDE.md を設置
+//   npx cakejp-ds init --force  # 既存ファイルを上書き
+//   npx cakejp-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(`@cakejp/design-system CLI
+
+使い方:
+  npx cakejp-ds init                          AI ルールファイルを設置
+  npx cakejp-ds init --force                  既存ファイルを上書き
+  npx cakejp-ds codemod v0.2-to-v0.3 [DIR]    旧 API を新 API に自動移行
+  npx cakejp-ds check-migration [DIR]         旧 API 利用箇所を検出
+`)
+  process.exit(0)
+}
+
+// codemod / check-migration は別 script に委譲
+if (cmd === "codemod") {
+  const subcmd = args[1]
+  if (subcmd !== "v0.2-to-v0.3") {
+    console.error(`未知の codemod: ${subcmd}`)
+    console.error(`使えるもの: v0.2-to-v0.3`)
+    process.exit(1)
+  }
+  await import(join(pkgRoot, "scripts/codemod/v0.2-to-v0.3.mjs"))
+  process.exit(0)
+}
+
+if (cmd === "check-migration") {
+  // process.argv の調整（codemod スクリプト側は process.argv[2] を見る）
+  process.argv = [process.argv[0], process.argv[1], ...args.slice(1)]
+  await import(join(pkgRoot, "scripts/codemod/check-migration.mjs"))
+  process.exit(0)
+}
+
+if (cmd !== "init" && cmd !== "postinstall") {
+  console.error(`未知のコマンド: ${cmd}`)
+  console.error(`npx cakejp-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("@cakejp/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(`[@cakejp/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/@cakejp/design-system/{AGENTS.md,CLAUDE.md,contracts/*,tokens.json} を AI に読ませる
+  3. スクラッチコード（ハードコードカラー・余白・角丸等）を書かない運用を徹底する
+`)
+}