170 lines
10 KiB
Markdown
170 lines
10 KiB
Markdown
# workspace-ui-kit
|
||
|
||
「自分の思想を画面にする」月のひな形です。
|
||
画面にはサンプルとして**採用管理**の4ペイン（候補者リスト・候補者の詳細・スコアカード・サイドバー）が出ますが、これを自分の仕事用に作り変えるところから月3の課題が始まります。
|
||
|
||
## 起動する
|
||
|
||
```bash
|
||
git clone <このリポジトリのURL>
|
||
cd workspace-ui-kit
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
ブラウザで `http://localhost:3000` を開くと、採用管理のサンプル画面が表示されます。
|
||
|
||
|
||
|
||
## 構成
|
||
|
||
### 技術スタック
|
||
|
||
- **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に貼り付けて聞いてください。
|
||
ほとんどのつまずきはそれで解決します。
|