# workspace-ui-kit

「自分の思想を画面にする」月のひな形です。
画面にはサンプルとして**採用管理**の4ペイン（候補者リスト・候補者の詳細・スコアカード・サイドバー）が出ますが、これを自分の仕事用に作り変えるところから月3の課題が始まります。

## 起動する

```bash
git clone <このリポジトリのURL>
cd workspace-ui-kit
npm install
npm run dev
```

ブラウザで `http://localhost:3000` を開くと、採用管理のサンプル画面が表示されます。

![採用管理のサンプル画面：左から「部署/ポジション」「候補者リスト」「候補者ダッシュボード」「選考ステージ詳細」の4ペイン構造](docs/screenshot-workspace.png)

## 構成

### 技術スタック

- **Next.js 16** / **React 19** / **TypeScript**（strict）
- **Tailwind CSS v4**（`app/globals.css` の `@theme` で CSS 変数を一元管理）
- **shadcn/ui**（`base-nova` スタイル / `@base-ui/react` ベース）
- **lucide-react**（アイコン）/ **zod**（実行時の型検証）

### ディレクトリ構成

```
app/                Next.js App Router の画面エントリ
  page.tsx          トップページ（ここから Workspace を呼んでいる）
  globals.css       色・角丸・余白などのデザイントークン
components/
  ui/               shadcn の UI 部品（Button, Card, Dialog 等。編集 OK）
  primitives/       このプロジェクト独自の編集 UI 部品
  workspace/        4ペイン本体（Pane1〜4 と関連ダイアログ）
data/               サンプルの種データ（JSON）
hooks/              React のカスタムフック
lib/                型定義（zod スキーマ）・ユーティリティ
openspec/           設計の決定記録（ADR、参考資料）
__tests__/          テスト
```

> 道A（踏襲ルート）でよく触る場所は **`components/workspace/`**（画面の中身）と **`app/globals.css`**（色や角丸）です。

### 開発コマンド

| コマンド | 役割 |
|---|---|
| `npm run dev` | 開発サーバー起動 |
| `npm run build` | 本番ビルド |
| `npm run lint` | ESLint チェック |
| `npm run test` | スモークテスト（Vitest） |
| `npm run format` | Prettier で整形 |
| `npm run check:radius` | 角丸ドリフト検出（独自スクリプト） |

## 同梱されている "AI への操縦マニュアル"

このリポジトリには、UI を作る作業を AI が手伝ってくれるように、あらかじめ「お手本」と「ルール集」が同梱されています。これを **スキル**と呼びます。

スキルとは、AI が作業を始めるときに自動で読みに行く**指示書**のことです。たとえば「ボタンを変えて」と頼むと、該当するスキルを AI が見つけて、「このプロジェクトでの正しい書き方はこれ」「やってはいけないことはこれ」を読んだ上で作業します。AI が暴走しにくくなります。

このリポジトリに入っているスキルは2種類:

- **`shadcn` スキル（純正）**
  shadcn/ui（このリポジトリで使っている UI ライブラリ）を使うときの一般的なルール集。「新しい部品を入れる」「使い方を調べる」など、shadcn 操作全般に効きます。shadcn/ui の中身を覚えていなくても、AI が代わりに調べてくれます。
  なお、中身は英語のままです。これは shadcn の **公式が配布しているものをそのまま置いている**だけだからです（特別にカスタマイズはしていません。誰でも同じ手順で導入できます）。AI が読むので、人間が読む必要はありません。読みたくなったら AI に翻訳してもらえば OK です。

- **`designing-workspace-ui` スキル（このプロジェクト固有）**
  この採用管理サンプルの **4ペイン構造**を尊重するためのルール集。「ペインの責務」「色や角丸の階層」「インライン編集の保存規約」など、このサンプルが採っている思想を AI に守らせます。

両者は独立しており、AI が片方を起動しても、もう片方は自動では起動しません。**どちらを使うかは、あなたが進む "道" によって決まります**。

## 2つの道：踏襲ルート / 自由ルート

このサンプルを使った課題には、2つの進め方があります。正解はひとつではありません。**自分の業務と性格に合う方を選んでください**。

### 道A: 踏襲ルート（このリポジトリで改造）

採用管理のサンプル UI を**土台にして**、自分の業務（顧客管理 / 在庫管理 / プロジェクト管理など）に作り変える道です。

- 使うスキル: `designing-workspace-ui` がメイン。必要に応じて `shadcn` も併用
- 立ち上がり: 速い。Day1 から動くものがある状態でスタート
- 規律: 強い。スキルが「サンプルの思想」を守らせる
- 自由度: 中。**4ペイン構造**と既存の色・角丸ルールに沿う必要がある
- 向いている人:
  - 業務が「リスト + 詳細 + サブパネル」的な構造で表現できる
  - まず動かしてから考えたい
  - AI 開発に慣れていない

### 道B: 自由ルート（別リポジトリでゼロから）

このリポジトリは**参考資料**として残し、**別の空のリポジトリ**で shadcn/ui を使ってゼロから作る道です。

- 使うスキル: `shadcn`（純正）がメイン。自分でプロジェクトを初期化する
- 立ち上がり: 遅い。Next.js セットアップ、shadcn 初期化から自分でやる
- 規律: 弱い（=自由）。サンプルの規律はないので、**自分で決める**
- 自由度: 高。**4ペイン構造に縛られない**。3ペインでも単一ページでも可
- 向いている人:
  - 業務が4ペインで表現しきれない（チャット型・カレンダー型・ボード型など）
  - 自分の思想を最初から全部決めたい
  - shadcn の純正スキルで AI を操縦する練習もしたい

## どちらを選ぶか

迷ったら、以下の3問に答えてみてください。

1. **あなたの業務は「リスト → 詳細 → 操作パネル」的な構造ですか？**
   - YES → 道A（踏襲ルート）が楽
   - NO → 道B（自由ルート）を検討
2. **早く何か動くものを見たいですか？それとも遅くても自分の思想を貫きたいですか？**
   - 早く動かしたい → 道A
   - 遅くても自分の思想 → 道B
3. **AI と shadcn/ui に慣れていますか？**
   - 慣れていない → 道A（規律が守ってくれる）
   - ある程度慣れた → 道B（自由を活かせる）

### 途中で道を変えてもOK

最初は **道A** で立ち上げ、途中で「やっぱり構造が合わない」と感じたら **道B** に切り替える進め方も可能です。そのときは「サンプルから何を残すか」を自分で決めるので、**`designing-workspace-ui` スキルがむしろ足枷になります**。道Bへ移ったら、このスキルは無効化（=`.claude/skills/designing-workspace-ui/` を削除）し、shadcn 純正スキルだけで進めてください。

逆に、道Bから道Aに移るのは現実的ではないので、**最初の判断は慎重に**。迷ったら担当講師に相談してください。

## 自分の仕事に作り変える

選んだ道に応じて、Cursor または Claude Code で AI に作業させます。

### AI と一緒に UI を作るときの現実

最新の AI と shadcn/ui を使っても、「いい感じの UI を作って」という抽象的な指示で**完璧な UI が完成するわけではありません**。実際には、

- どの shadcn/ui 部品を**そのまま使う**か、**カスタマイズする**かを判断する
- 一つの変更ごとに **AI の出力を確認して微調整する**
- 言葉で表現できる粒度（例: 「Pane 3 のカードの間隔を1段詰めて」「Badge を success トークンの色に変えて」）まで噛み砕いて伝える

を**一つずつ丁寧に積み重ねる**作業になります。最初の数日は遠回りに感じるかもしれませんが、これが「自分の思想を画面にする」唯一の道です。

### 道A（踏襲ルート）の場合

AI に依頼するときは「`designing-workspace-ui` スキルを使って」と一言添えると、規律に沿った変更が返ってきます。
例: 「Pane 3 のカード並びを変えたい。designing-workspace-ui を使って」

### 道B（自由ルート）の場合

別のリポジトリで `npx shadcn@latest init` から始めてください。AI には「shadcn スキルで進めて」と頼むと、純正のレジストリ機能を使った部品検索 + 追加をやってくれます。

### 独自性を強めるなら、自分専用のデザインスキルも育てる

道B を選んだ場合、あるいは道A から始めても**採用管理のサンプル思想から離れていく**にしたがって、あなたの新しいデザイン思想を AI に教えるための **専用スキル**を作っていくのが本筋です。スキルが古いままだと、AI は「採用管理の世界観」のままコードを書き続けてしまい、せっかくの独自デザインと噛み合わなくなります。

ゼロから書く必要はありません。同梱の `.claude/skills/designing-workspace-ui/SKILL.md` を**参考雛形**として、自分のプロジェクトの言葉で書き直していくのがおすすめです。

- 「ペインの責務」 → あなたの画面構造の責務に
- 「採用管理」 → 自分の業務名に
- 角丸ルールや色のトークン規律も、自分の流派で書き換える

スキルを育てるほど、AI は**あなたの思想を理解した上で**動くようになり、独自デザインでも一貫性のある変更が積み上がります。**スキルを育てること自体が、デザインを言語化する訓練**にもなります。

課題の取り組み方の詳細は**受講生ポータル**を参照してください。

## 提出する

提出物・期限・中間発表のフォーマットは**受講生ポータル**を見てください。

## 詰まったら

エラーメッセージをそのままAIに貼り付けて聞いてください。
ほとんどのつまずきはそれで解決します。