From 05dfda4faa070fba3b1fdbbd83ebd8c44128af01 Mon Sep 17 00:00:00 2001 From: tkc310 Date: Wed, 21 Oct 2026 05:11:02 +0000 Subject: [PATCH] =?UTF-8?q?docs(skills):=20=E3=82=B9=E3=82=AD=E3=83=AB?= =?UTF-8?q?=E3=81=AE=E4=B8=80=E8=A6=A7=E3=82=92=E8=BF=BD=E5=8A=A0=E3=81=97?= =?UTF-8?q?=E3=80=81=E6=96=87=E6=9B=B8=E3=82=92=E5=BF=85=E8=A6=81=E3=81=AA?= =?UTF-8?q?=E3=81=A8=E3=81=8D=E3=81=A0=E3=81=91=E8=AA=AD=E3=81=BF=E8=BE=BC?= =?UTF-8?q?=E3=82=80=E6=A7=8B=E6=88=90=E3=81=AB=E3=81=99=E3=82=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - スキルの一覧 docs/skills.md を追加し、README・AGENTS.md・CONTRIBUTING・ai-agents.md からリンク（重複していた表は一覧へのリンクに置き換え） - 大きいスキルを本体（手順の骨組み）と段階ごとの文書に分割: design-principles（mode-1〜3・feedback）、ds-factory（hearing・finish）、ds-slides（authoring・verify）、ds-storybook-preview（pr-body・setup） - design-init / adjust / review は design-principles のモードの文書を指すだけにし、内容の重複をなくした - ds-build-ui は DESIGN.md の全文ではなく必要な節だけを読む手順に変更 - AGENTS.md に「読み込みの方針」を追加 - scripts/check-skills.ts（name・description・一覧の網羅・本体 2,000 字以内・リンク切れ・参照されない文書）を make check に追加 - ADR-0018、改善ログ Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Yb44feYKDNj2ukQeT2j8Ks --- .claude/skills/design-adjust/SKILL.md | 22 +- .claude/skills/design-init/SKILL.md | 26 +-- .claude/skills/design-principles/SKILL.md | 202 +++--------------- .claude/skills/design-principles/feedback.md | 18 ++ .../skills/design-principles/mode-1-init.md | 29 +++ .../skills/design-principles/mode-2-adjust.md | 21 ++ .../skills/design-principles/mode-3-review.md | 47 ++++ .claude/skills/design-review/SKILL.md | 59 +---- .claude/skills/ds-build-ui/SKILL.md | 12 +- .claude/skills/ds-factory/SKILL.md | 91 ++------ .claude/skills/ds-factory/finish.md | 15 ++ .claude/skills/ds-factory/hearing.md | 40 ++++ .claude/skills/ds-slides/SKILL.md | 127 ++--------- .claude/skills/ds-slides/authoring.md | 63 ++++++ .claude/skills/ds-slides/verify.md | 35 +++ .claude/skills/ds-storybook-preview/SKILL.md | 83 +------ .../skills/ds-storybook-preview/pr-body.md | 45 ++++ .claude/skills/ds-storybook-preview/setup.md | 22 ++ AGENTS.md | 13 +- CONTRIBUTING.md | 9 +- Makefile | 2 +- README.md | 5 +- docs/ai-agents.md | 14 +- docs/decisions/0018-progressive-disclosure.md | 26 +++ docs/decisions/README.md | 1 + docs/factory.md | 2 +- docs/improvement/log.md | 1 + docs/rulebook/01-principles.md | 2 +- docs/skills.md | 59 +++++ package.json | 2 +- scripts/check-skills.ts | 112 ++++++++++ 31 files changed, 649 insertions(+), 556 deletions(-) create mode 100644 .claude/skills/design-principles/feedback.md create mode 100644 .claude/skills/design-principles/mode-1-init.md create mode 100644 .claude/skills/design-principles/mode-2-adjust.md create mode 100644 .claude/skills/design-principles/mode-3-review.md create mode 100644 .claude/skills/ds-factory/finish.md create mode 100644 .claude/skills/ds-factory/hearing.md create mode 100644 .claude/skills/ds-slides/authoring.md create mode 100644 .claude/skills/ds-slides/verify.md create mode 100644 .claude/skills/ds-storybook-preview/pr-body.md create mode 100644 .claude/skills/ds-storybook-preview/setup.md create mode 100644 docs/decisions/0018-progressive-disclosure.md create mode 100644 docs/skills.md create mode 100644 scripts/check-skills.ts diff --git a/.claude/skills/design-adjust/SKILL.md b/.claude/skills/design-adjust/SKILL.md index 2218a465d..f1a3c3492 100644 --- a/.claude/skills/design-adjust/SKILL.md +++ b/.claude/skills/design-adjust/SKILL.md @@ -5,22 +5,10 @@ description: 既存のデザインシステムまたは DESIGN.md を調整・ # 既存デザインシステム調整 -`design-principles` スキルの「モード 2: 既存の調整」を実行する。 +`design-principles` スキルの「モード 2: 既存の調整」を直接呼ぶ入口。 -## 実行内容 +1. `../design-principles/SKILL.md` を読み、「ルールの優先順位」と手順 1（前提条件のヒアリング。既存の DESIGN.md から分かることは聞かない）を行う +2. `../design-principles/mode-2-adjust.md` を読み、調整する領域に関係する `references/` だけを読む +3. トークンやコンポーネントを追加・変更し、DESIGN.md を更新する（成果物は mode-2-adjust.md） -1. design-principles スキルを読み込む -2. **前提条件のヒアリング**: 既存の DESIGN.md とリポジトリ内の情報を確認し、変更点や追加の制約をユーザーに質問する -3. UI の方向性が適切か確認する（ドメインと対象ユーザーが変わった場合は見直す） -4. 調整が必要な領域に関係するルールを参照する -5. トークンやコンポーネントの追加・変更を行う -6. DESIGN.md を更新する - -**ルールへのフィードバック**: 対話中にルールの改善点が見つかった場合、ユーザーに伝え、`docs/design-principles/` への編集を提案する。正本は `docs/design-principles/`（スキルの `references/` はそこへのシンボリックリンク）。 - -## 成果物 - -- UI の方向性の確認結果（変更がある場合は新しい方向性と理由） -- 追加・変更したトークンとコンポーネントの定義 -- 必須ルールを外した場合の理由の追記 -- 既存ルールとの整合性確認結果 +ルールのギャップに気づいたら `../design-principles/feedback.md` の手順でユーザーに伝える。 diff --git a/.claude/skills/design-init/SKILL.md b/.claude/skills/design-init/SKILL.md index 090c0c9f9..b7d503315 100644 --- a/.claude/skills/design-init/SKILL.md +++ b/.claude/skills/design-init/SKILL.md @@ -5,26 +5,10 @@ description: 新しいデザインシステムまたは DESIGN.md を作成す # 新規デザインシステム作成 -`design-principles` スキルの「モード 1: 新規作成」を実行する。 +`design-principles` スキルの「モード 1: 新規作成」を直接呼ぶ入口。 -## 実行内容 +1. `../design-principles/SKILL.md` を読み、「ルールの優先順位」と手順 1（前提条件のヒアリング）を行う +2. `../design-principles/mode-1-init.md` を読み、その「読む順序」で必要な `references/` だけを読む +3. UI の方向性 → 特化ルール → 原則 → WCAG の順でルールを適用し、DESIGN.md を作る（成果物は mode-1-init.md） -1. design-principles スキルを読み込む -2. **前提条件のヒアリング**: リポジトリ内の既存情報を確認し、推測できない項目をユーザーに質問する -3. UI の方向性を決める（オブジェクト指向 UI かタスク指向 UI か） -4. 該当するサービス種別を選ぶ（管理画面、社内向けツール、SaaS、toC） -5. UI の方向性 → 特化ルール → 原則 → WCAG の順でルールを適用する -6. DESIGN.md を作成する - -**ルールへのフィードバック**: 対話中にルールの改善点が見つかった場合、ユーザーに伝え、`docs/design-principles/` への編集を提案する。正本は `docs/design-principles/`（スキルの `references/` はそこへのシンボリックリンク）。 - -## 成果物 - -次を含む DESIGN.md： - -- プロダクトの UI の方向性（オブジェクト指向 UI かタスク指向 UI か）と選択理由 -- 画面領域ごとの UI の方向性（一つのプロダクトに両方の画面があるときは領域ごとに書く） -- 画面領域ごとのサービス種別（管理画面、社内向けツール、SaaS、toC） -- 採用したルール（優先順位順） -- トークン名とコンポーネント名の対応 -- 必須ルールを外した項目がある場合、その理由 +ルールのギャップに気づいたら `../design-principles/feedback.md` の手順でユーザーに伝える。 diff --git a/.claude/skills/design-principles/SKILL.md b/.claude/skills/design-principles/SKILL.md index 9d45b25e0..c1133643f 100644 --- a/.claude/skills/design-principles/SKILL.md +++ b/.claude/skills/design-principles/SKILL.md @@ -5,30 +5,17 @@ description: ウェブの画面設計ルール。新規デザインシステム # デザイン原則スキル -このスキルは、ウェブの画面を設計するときのルールを提供する。設計作業、DESIGN.md の作成・更新、デザインレビュー時に使う。 - -## いつ使うか - -次のいずれかの作業を行うときに、このスキルを読み込む： - -- 新しいデザインシステムを作成する -- プロジェクトの DESIGN.md を書く -- 既存のデザインシステムや DESIGN.md を調整する -- 画面デザインをレビューする -- デザイン段階でアクセシビリティを評価する +ウェブの画面を設計するときのルールを提供する。設計作業、DESIGN.md の作成・更新、デザインレビューのときに使う。 +ルールの本文は `references/`（このリポジトリの `docs/design-principles/` へのシンボリックリンク）にある。**この本体には手順の骨組みだけを置き、詳細は作業モードを決めてから読む。** ## ルールの優先順位 -画面を設計するときは、次の順でルールを適用する。後のルールは、前のルールが書いていない判断にだけ使う。 +次の順で適用する。後のルールは、前のルールが書いていない判断にだけ使う。 -1. **UI の方向性** - 画面をオブジェクト指向 UI にするかタスク指向 UI にするかを、ドメインと対象ユーザーから決める +1. **UI の方向性** - オブジェクト指向 UI かタスク指向 UI かを、ドメインと対象ユーザーから決める 2. **サービス別の特化ルール** - 管理画面、社内向けツール、SaaS、toC のいずれかに当たる画面では、特化ルールを満たす -3. **ウェブデザインの原則** - UI の方向性と特化ルールが書いていない判断に使う -4. **WCAG 2.2 の達成基準** - この必須は、UI の方向性、特化ルール、原則のいずれからも緩めない - -### ルールの強さ - -各ルールには「必須」と「推奨」がある。DESIGN.md での扱いは次のとおり： +3. **ウェブデザインの原則** - 1 と 2 が書いていない判断に使う +4. **WCAG 2.2 の達成基準** - この必須は、1〜3 のいずれからも緩めない | ルール | DESIGN.md での扱い | | --- | --- | @@ -36,163 +23,44 @@ description: ウェブの画面設計ルール。新規デザインシステム | 特化ルールと原則の必須 | 原則として採る。外すときは、外す理由を DESIGN.md に書く | | 推奨 | プロダクトごとに採るかどうかを決める | -## 前提条件のヒアリング - -**すべての作業モードで、アウトプットを作る前に前提条件をヒアリングする。** - -`references/hearing.md` に従い、次の手順で進める： - -1. リポジトリ内の既存情報を確認する（DESIGN.md、コード、既存のトークンやコンポーネント） -2. 推測できない項目だけをユーザーに質問する（短いリストにまとめる） -3. ユーザーの回答を要約し、理解が正しいか確認する -4. 確認した前提条件を DESIGN.md に記録する - -## 作業モード - -作業の目的に応じて、次のいずれかのモードを選ぶ。 - -### モード 1: 新規作成（新しいデザインシステム / DESIGN.md） - -**目的**: これから作るプロジェクトの DESIGN.md を書く、または新しいデザインシステムを定義する。 - -**読み込む順序**: - -1. `references/README.md` - 全体の構造と読み順を確認する -2. `references/ui-orientation.md` - 画面の方向性（オブジェクト指向 UI かタスク指向 UI か）を、ドメインと対象ユーザーから決める -3. `references/services/README.md` - 画面の目的に合う特化ルールを選ぶ -4. 選んだ特化ルール（`references/services/admin.md`、`internal.md`、`saas.md`、`consumer.md` のいずれか） -5. `references/principles.md` - UI の方向性と特化ルールが書いていない判断を補う -6. `references/wcag-for-designers.md` - 必須の達成基準を確認する - -**成果物**: - -DESIGN.md に次を含める： - -- プロダクトの UI の方向性（オブジェクト指向 UI かタスク指向 UI か）と選択理由 -- 画面領域ごとの UI の方向性（一つのプロダクトに両方の画面があるときは領域ごとに書く） -- 画面領域ごとのサービス種別（管理画面、社内向けツール、SaaS、toC） -- 採用したルール（UI の方向性 → 特化ルール → 原則 → WCAG の順） -- トークン名とコンポーネント名の対応 -- 必須ルールを外した項目がある場合、その理由 - -**複数のプロダクトで共有する基盤のデザインシステムの場合**: UI の方向性とサービス種別は基盤では決めず、各プロダクトの DESIGN.md で決める。基盤の DESIGN.md には、原則の各ルールとトークン・コンポーネントの対応表、テーマごとの WCAG の確認結果、プロダクト側の DESIGN.md の雛形を含める。手順は `references/README.md` の「複数のプロダクトで共有する基盤のデザインシステムを作る」に従う。 - -### モード 2: 既存の調整（既存 DS / DESIGN.md の調整） - -**目的**: 既にあるデザインシステムや DESIGN.md を見直す。トークンやコンポーネントを追加・変更する。 - -**読み込む順序**: - -1. 既存の DESIGN.md または設計資料を確認する -2. `references/README.md` - 読み順を確認する -3. `references/ui-orientation.md` - 画面の方向性が適切か確認する（ドメインと対象ユーザーが変わった場合は見直す） -4. 調整が必要な領域に関係する特化ルール（`references/services/` から該当するもの） -5. `references/principles.md` の該当箇所 -6. `references/wcag-for-designers.md` の該当箇所 - -**成果物**: - -- UI の方向性の確認結果（変更がある場合は新しい方向性と理由） -- 追加・変更したトークンとコンポーネントの定義 -- 必須ルールを外した場合の理由の追記 -- 既存ルールとの整合性確認 +## 手順 -### モード 3: 評価・レビュー（画面/デザインの評価） +1. **前提条件をヒアリングする**（すべてのモードで、アウトプットを作る前に）。`references/hearing.md` に従い、リポジトリから分かることは聞かず、推測できない項目だけを短いリストで聞く。回答を要約して確認し、DESIGN.md に記録する +2. **作業モードを選び、そのモードの文書だけを読む** -**目的**: 既存の画面デザインやモックアップをレビューする。ルール違反を見つけ、改善提案をする。 + | 目的 | モード | 読む文書 | + | --- | --- | --- | + | これから作るプロダクトの DESIGN.md を書く・新しいデザインシステムを定義する | 1. 新規作成 | [mode-1-init.md](./mode-1-init.md) | + | 既存のデザインシステムや DESIGN.md を見直す・トークンやコンポーネントを足す | 2. 既存の調整 | [mode-2-adjust.md](./mode-2-adjust.md) | + | 画面やモックアップを評価し、違反と改善案を出す | 3. 評価・レビュー | [mode-3-review.md](./mode-3-review.md) | -**読み込む順序**: +3. **モードの文書が指す `references/` のファイルを、必要な範囲だけ読む**（下の「読む範囲を絞る」） +4. ルールにギャップや曖昧さを見つけたら、[feedback.md](./feedback.md) の手順でユーザーに伝える -1. レビュー対象の画面を確認する -2. `references/README.md` - 評価基準の優先順位を確認する -3. `references/ui-orientation.md` - 画面の方向性（オブジェクト指向 UI かタスク指向 UI か）が適切か、チェックリストを使って確認する -4. 画面の目的に合う特化ルール（`references/services/` から） -5. `references/principles.md` の適用ルール -6. `references/wcag-for-designers.md` の必須項目 +## 読む範囲を絞る -**成果物**: +すべてのルールを一度に読まない。 -評価レポートを、次の構造で作成する： - -#### 0. UI の方向性の適合性 - -画面の方向性が適切か確認する。 - -- **現在の方向性**: オブジェクト指向 UI かタスク指向 UI か -- **判断**: ドメインと対象ユーザーに照らして、現在の方向性が適切か -- **チェックリスト結果**: `ui-orientation.md` のチェックリストに沿った確認結果 -- **提案**: 方向性の変更が必要な場合、理由とともに提案する - -#### 1. WCAG 必須違反 - -達成基準を満たさない項目。必ず修正が必要。 - -- **項目**: 該当する達成基準（例: 1.4.3 コントラスト（最低限）） -- **問題**: 何がどう基準を満たしていないか -- **修正方法**: 具体的な改善案 - -#### 2. 必須ルール違反 - -UI の方向性、特化ルール、または原則の必須を満たさない項目。修正が必要（外す場合は理由を明記）。 - -- **項目**: 該当するルール（例: 原則「操作の幾何」） -- **問題**: どのルールに反しているか -- **修正方法**: 具体的な改善案 - -#### 3. 推奨からの提案 - -推奨ルールに沿った改善提案。プロダクトの方針に応じて採用を検討する。 - -- **項目**: 該当するルール -- **提案**: より良くするための提案 -- **根拠**: なぜその提案が有効か - -## プログレッシブディスクロージャー - -すべてのルールを一度に読まない。作業モードと画面の種類に応じて、必要なファイルだけを読む。 - -- **画面の方向性の決定**: ui-orientation.md だけを読む（特化ルールや原則は読まない） -- **画面の種類が決まっている**: その特化ルールだけを読む（他の特化ルールは読まない） -- **レビュー対象が部分的**: 該当する適用ルールだけを読む（principles.md の全体は読まない） -- **WCAG の確認だけ**: wcag-for-designers.md だけを読む - -## ルールへのフィードバック - -対話中にルールの改善点が見つかった場合、ユーザーに伝え、このリポジトリの `docs/design-principles/` への具体的な編集を提案する（`references/` は `docs/design-principles/` へのシンボリックリンクなので、正本は `docs/design-principles/` である）。 - -**改善が必要な場合**: -- ルールにギャップがある（判断基準が書かれていない） -- ルールが曖昧で解釈に迷う -- ルールが特定の状況に適合しない -- 同じ例外を繰り返し認める必要がある - -**提案の手順**: -1. 問題を具体的に説明する -2. `docs/design-principles/` のどのファイルの、どの箇所を、どう変更するか提案する -3. ユーザーの承認を得てから、PR を通じて変更する - -**プロダクト固有の例外**: 共有ルールではなく、そのプロダクトの DESIGN.md に記録する。 +- **画面の方向性を決めるだけ**: `references/ui-orientation.md` だけ（特化ルールや原則は読まない） +- **画面の種類が決まっている**: その特化ルール（`references/services/` の 1 ファイル）だけ +- **レビュー対象が部分的**: `references/principles.md` の該当する適用ルールの節だけ（見出しで探して読む） +- **WCAG の確認だけ**: `references/wcag-for-designers.md` の該当する達成基準だけ ## 注意事項 -- `references/` 以下のファイルが、実際のルールの置き場所である -- WCAG の必須は、どの場合も緩めない - UI の方向性と特化ルールが原則と食い違うときは、UI の方向性と特化ルールを採る - 特化ルールが WCAG より厳しいときは、特化ルールを採る - 必須ルールを外すときは、外す理由を必ず DESIGN.md に書く -- UI の方向性とサービス種別は別の概念である（UI の方向性は OOUI かタスク指向か、サービス種別は管理画面か SaaS かなど） - -## ファイル参照パス - -`references/` は、このリポジトリの `docs/design-principles/` へのシンボリックリンクである。Claude Code（`.claude/skills/`）、Codex と Cursor（`.agents/skills/` → `.claude/skills/`）のどれから読んでも同じファイルを指す。 - -- `references/README.md` - ルール全体の構造 -- `references/hearing.md` - 前提条件のヒアリング項目 -- `references/ui-orientation.md` - UI の方向性の選択 -- `references/services/README.md` - サービス別特化ルールの選び方 -- `references/services/admin.md` - 管理画面 -- `references/services/internal.md` - 社内向けツール -- `references/services/saas.md` - SaaS -- `references/services/consumer.md` - toC サービス -- `references/principles.md` - ウェブデザインの原則 -- `references/wcag-for-designers.md` - WCAG 2.2 の達成基準 +- UI の方向性とサービス種別は別の概念である（方向性は OOUI かタスク指向か、サービス種別は管理画面か SaaS かなど） +- 複数のプロダクトで共有する基盤のデザインシステムでは、UI の方向性とサービス種別を決めない（[mode-1-init.md](./mode-1-init.md) の「共有の基盤の場合」） + +## `references/` の中身 + +| ファイル | 内容 | +| --- | --- | +| `README.md` | ルール全体の構造と読み順 | +| `hearing.md` | 前提条件のヒアリング項目 | +| `ui-orientation.md` | UI の方向性の選択とチェックリスト | +| `services/README.md` | 特化ルールの選び方（`admin.md`・`internal.md`・`saas.md`・`consumer.md`） | +| `principles.md` | ウェブデザインの原則（15 の適用ルール） | +| `wcag-for-designers.md` | WCAG 2.2 の達成基準 | diff --git a/.claude/skills/design-principles/feedback.md b/.claude/skills/design-principles/feedback.md new file mode 100644 index 000000000..8f928a1dd --- /dev/null +++ b/.claude/skills/design-principles/feedback.md @@ -0,0 +1,18 @@ +# ルールへのフィードバック + +対話中にルールの改善点が見つかったときに読む。ルールの正本は `docs/design-principles/`（スキルの `references/` はそこへのシンボリックリンク）。 + +## 改善が必要な場合 + +- ルールにギャップがある（判断基準が書かれていない） +- ルールが曖昧で解釈に迷う +- ルールが特定の状況に適合しない +- 同じ例外を繰り返し認める必要がある + +## 提案の手順 + +1. 問題を具体的に説明する +2. `docs/design-principles/` のどのファイルの、どの箇所を、どう変更するか提案する +3. ユーザーの承認を得てから、PR を通じて変更する + +**プロダクト固有の例外**: 共有ルールではなく、そのプロダクトの DESIGN.md に記録する。 diff --git a/.claude/skills/design-principles/mode-1-init.md b/.claude/skills/design-principles/mode-1-init.md new file mode 100644 index 000000000..e7f73b8dc --- /dev/null +++ b/.claude/skills/design-principles/mode-1-init.md @@ -0,0 +1,29 @@ +# モード 1: 新規作成（新しいデザインシステム / DESIGN.md） + +`design-principles` スキルの本体（[SKILL.md](./SKILL.md)）でヒアリングを終え、このモードを選んだときに読む。 + +**目的**: これから作るプロジェクトの DESIGN.md を書く、または新しいデザインシステムを定義する。 + +## 読む順序 + +1. `references/README.md` - 全体の構造と読み順 +2. `references/ui-orientation.md` - 画面の方向性（オブジェクト指向 UI かタスク指向 UI か）を、ドメインと対象ユーザーから決める +3. `references/services/README.md` - 画面の目的に合う特化ルールを選ぶ +4. 選んだ特化ルールだけ（`references/services/admin.md`・`internal.md`・`saas.md`・`consumer.md` のどれか） +5. `references/principles.md` - 1〜4 が書いていない判断を補う +6. `references/wcag-for-designers.md` - 必須の達成基準を確認する + +## 成果物 + +DESIGN.md に次を含める。 + +- プロダクトの UI の方向性（オブジェクト指向 UI かタスク指向 UI か）と選択理由 +- 画面領域ごとの UI の方向性（一つのプロダクトに両方の画面があるときは領域ごとに書く） +- 画面領域ごとのサービス種別（管理画面、社内向けツール、SaaS、toC） +- 採用したルール（UI の方向性 → 特化ルール → 原則 → WCAG の順） +- トークン名とコンポーネント名の対応 +- 必須ルールを外した項目がある場合、その理由 + +## 共有の基盤の場合 + +複数のプロダクトで共有する基盤のデザインシステムでは、UI の方向性とサービス種別は基盤では決めず、各プロダクトの DESIGN.md で決める。基盤の DESIGN.md には、原則の各ルールとトークン・コンポーネントの対応表、テーマごとの WCAG の確認結果、プロダクト側の DESIGN.md の雛形を含める。手順は `references/README.md` の「複数のプロダクトで共有する基盤のデザインシステムを作る」に従う。 diff --git a/.claude/skills/design-principles/mode-2-adjust.md b/.claude/skills/design-principles/mode-2-adjust.md new file mode 100644 index 000000000..904c52c1f --- /dev/null +++ b/.claude/skills/design-principles/mode-2-adjust.md @@ -0,0 +1,21 @@ +# モード 2: 既存の調整（既存 DS / DESIGN.md の調整） + +`design-principles` スキルの本体（[SKILL.md](./SKILL.md)）でヒアリングを終え、このモードを選んだときに読む。 + +**目的**: 既にあるデザインシステムや DESIGN.md を見直す。トークンやコンポーネントを追加・変更する。 + +## 読む順序 + +1. 既存の DESIGN.md または設計資料（調整する領域に関係する節から） +2. `references/README.md` - 読み順の確認 +3. `references/ui-orientation.md` - 画面の方向性が適切か確認する（ドメインと対象ユーザーが変わった場合は見直す） +4. 調整が必要な領域に関係する特化ルールだけ（`references/services/` から該当するもの） +5. `references/principles.md` の該当する節だけ +6. `references/wcag-for-designers.md` の該当する達成基準だけ + +## 成果物 + +- UI の方向性の確認結果（変更がある場合は新しい方向性と理由） +- 追加・変更したトークンとコンポーネントの定義 +- 必須ルールを外した場合の理由の追記 +- 既存ルールとの整合性の確認結果 diff --git a/.claude/skills/design-principles/mode-3-review.md b/.claude/skills/design-principles/mode-3-review.md new file mode 100644 index 000000000..93754112a --- /dev/null +++ b/.claude/skills/design-principles/mode-3-review.md @@ -0,0 +1,47 @@ +# モード 3: 評価・レビュー（画面 / デザインの評価） + +`design-principles` スキルの本体（[SKILL.md](./SKILL.md)）でヒアリングを終え、このモードを選んだときに読む。 + +**目的**: 既存の画面デザインやモックアップをレビューする。ルール違反を見つけ、改善提案をする。 + +## 読む順序 + +1. レビュー対象の画面 +2. `references/README.md` - 評価基準の優先順位 +3. `references/ui-orientation.md` - チェックリストで方向性が適切か確認する +4. 画面の目的に合う特化ルールだけ（`references/services/` から） +5. `references/principles.md` の、対象に当てはまる適用ルールの節だけ +6. `references/wcag-for-designers.md` の必須項目 + +## レポートの構成 + +### 0. UI の方向性の適合性 + +- **現在の方向性**: オブジェクト指向 UI かタスク指向 UI か +- **判断**: ドメインと対象ユーザーに照らして適切か +- **チェックリスト結果**: `ui-orientation.md` のチェックリストに沿った確認結果 +- **提案**: 方向性の変更が必要な場合、理由とともに + +### 1. WCAG 必須違反 + +達成基準を満たさない項目。必ず修正が必要。 + +- **項目**: 該当する達成基準（例: 1.4.3 コントラスト（最低限）） +- **問題**: 何がどう基準を満たしていないか +- **修正方法**: 具体的な改善案 + +### 2. 必須ルール違反 + +UI の方向性、特化ルール、または原則の必須を満たさない項目。修正が必要（外す場合は理由を明記）。 + +- **項目**: 該当するルール（例: 原則「操作の幾何」） +- **問題**: どのルールに反しているか +- **修正方法**: 具体的な改善案 + +### 3. 推奨からの提案 + +推奨ルールに沿った改善提案。プロダクトの方針に応じて採用を検討する。 + +- **項目**: 該当するルール +- **提案**: より良くするための提案 +- **根拠**: なぜその提案が有効か diff --git a/.claude/skills/design-review/SKILL.md b/.claude/skills/design-review/SKILL.md index 988f801f4..c7530626b 100644 --- a/.claude/skills/design-review/SKILL.md +++ b/.claude/skills/design-review/SKILL.md @@ -5,66 +5,25 @@ description: 画面デザインやモックアップをレビューする。UI # デザインレビュー -`design-principles` スキルの「モード 3: 評価・レビュー」を実行する。 +`design-principles` スキルの「モード 3: 評価・レビュー」を直接呼ぶ入口。 -## 実行内容 +1. `../design-principles/SKILL.md` を読み、手順 1（前提条件のヒアリング）でレビュー対象（範囲・懸念点）、既存の DESIGN.md、期待するアウトプットを確認する +2. レビュー対象の画面を確認する（Figma URL、スクリーンショット、コードなど） +3. `../design-principles/mode-3-review.md` を読み、対象に当てはまる `references/` だけを読む +4. ルール違反と改善提案を抽出し、mode-3-review.md の「レポートの構成」で報告する -1. design-principles スキルを読み込む -2. **前提条件のヒアリング**: レビュー対象（範囲、懸念点）、既存の DESIGN.md、期待するアウトプットをユーザーに確認する -3. レビュー対象の画面を確認する（Figma URL、スクリーンショット、コードなど） -4. UI の方向性が適切か確認する（オブジェクト指向 UI かタスク指向 UI か） -5. 画面の目的に合うルールを参照する（UI の方向性 → 特化ルール → 原則 → WCAG） -6. ルール違反と改善提案を抽出する -7. レビューレポートを作成する - -**ルールへのフィードバック**: 対話中にルールの改善点が見つかった場合、ユーザーに伝え、`docs/design-principles/` への編集を提案する。正本は `docs/design-principles/`（スキルの `references/` はそこへのシンボリックリンク）。 - -## レポート構成 - -### 0. UI の方向性の適合性 - -画面の方向性が適切か確認する。 - -- 現在の方向性: オブジェクト指向 UI かタスク指向 UI か -- 判断: ドメインと対象ユーザーに照らして、現在の方向性が適切か -- チェックリスト結果: ui-orientation.md のチェックリストに沿った確認結果 -- 提案: 方向性の変更が必要な場合、理由とともに提案する - -### 1. WCAG 必須違反 - -達成基準を満たさない項目。必ず修正が必要。 - -- 項目: 該当する達成基準 -- 問題: 何がどう基準を満たしていないか -- 修正方法: 具体的な改善案 - -### 2. 必須ルール違反 - -UI の方向性、特化ルール、または原則の必須を満たさない項目。 - -- 項目: 該当するルール -- 問題: どのルールに反しているか -- 修正方法: 具体的な改善案 - -### 3. 推奨からの提案 - -推奨ルールに沿った改善提案。 - -- 項目: 該当するルール -- 提案: より良くするための提案 -- 根拠: なぜその提案が有効か +ルールのギャップに気づいたら `../design-principles/feedback.md` の手順でユーザーに伝える。 ## レビュー時の追加確認 -レビュー時には次の観点も確認する： - - コメントが日本語かどうか - 不具合になりそうな部分はないか - リファクタできそうな部分がないか（変更差分の範囲内のみ） - 修正が必要な場合は提案のみ行い、修正は実行しないこと -- インラインコメントやPRコメントで補足した方が良い箇所がないか +- インラインコメントや PR コメントで補足した方が良い箇所がないか （フロントエンドの場合） -- 不必要なメモ化（useMemo/useCallback）がないか + +- 不必要なメモ化（useMemo / useCallback）がないか - 過剰な抽象化によって可読性が低下していないか - リンクは next/link を利用しているか diff --git a/.claude/skills/ds-build-ui/SKILL.md b/.claude/skills/ds-build-ui/SKILL.md index 49810c8f7..c17e30b07 100644 --- a/.claude/skills/ds-build-ui/SKILL.md +++ b/.claude/skills/ds-build-ui/SKILL.md @@ -7,11 +7,13 @@ description: このデザインシステムを使って画面やフォームを ## 作る前に読む -0. プロダクトの DESIGN.md。無ければ `templates/PRODUCT-DESIGN.md` から作り、UI の方向性とサービス種別を決める。`design-principles` スキル（このリポジトリの `.claude/skills/design-principles/`）の手順（ヒアリング → 方向性 → 特化ルール → 原則 → WCAG）に従う -1. `DESIGN.md`（トークン・コンポーネントの早見表と Do / Don't） -2. `docs/rulebook/02-accessibility.md`（必須ルール A1〜A15） -3. `docs/rulebook/05-writing.md`（ボタン・エラー文の書き方） -4. 使うコンポーネントのストーリー（`packages/ui/src/components/ui/*/index.stories.tsx`） +文書は大きいので、**全文ではなく必要な節だけ** を読む（見出しで探して、その節を読む）。 + +0. プロダクトの DESIGN.md。無ければ `templates/PRODUCT-DESIGN.md` から作り、UI の方向性とサービス種別を決める。`design-principles` スキルの手順（ヒアリング → 方向性 → 特化ルール → 原則 → WCAG）に従う +1. `DESIGN.md` は次の節だけ: 「9. Agent Prompt Guide」のクイックリファレンス、「7. Do's and Don'ts」、「4. Component Stylings」の一覧と、使うコンポーネントの節。色や余白を決めるときだけ「2. Color Palette & Roles」「5. Layout Principles」 +2. `docs/rulebook/02-accessibility.md` の「必須ルール」の表（A1〜A16） +3. フォームやボタンの文言を書くときだけ `docs/rulebook/05-writing.md` +4. 使うコンポーネントのストーリー（`packages/ui/src/components/ui//index.stories.tsx`） ## 作るときの決まり diff --git a/.claude/skills/ds-factory/SKILL.md b/.claude/skills/ds-factory/SKILL.md index 1deb2a8af..63ff104b5 100644 --- a/.claude/skills/ds-factory/SKILL.md +++ b/.claude/skills/ds-factory/SKILL.md @@ -6,95 +6,28 @@ description: 新しいデザインシステムを作るときに使う（デザ # デザインシステムファクトリー このリポジトリ（8341-ui）をひな形にして、**新しいデザインシステムのリポジトリ**を作る。 -画面設計の判断は `design-principles` スキル（`docs/design-principles/`）に従い、プロダクト固有の前提はユーザーへのヒアリングで決める。 -位置づけと全体像は `docs/factory.md`。 +画面設計の判断は `design-principles` スキルに従い、プロダクト固有の前提はユーザーへのヒアリングで決める。位置づけと全体像は `docs/factory.md`（必要になったときだけ読む）。 生成されるもの: 同じスタック（Base UI・Tailwind v4・DTCG トークン・Storybook・検査・改善ループ・design-principles）を持ち、名前・接頭辞・キーカラー・見た目の性格・DESIGN.md が新しいプロダクトに合わせて書き換わったリポジトリ。 ## 手順 -### 1. ルールを読む +各段階の詳しい文書は、その段階に入ったときに読む。 -- `design-principles` スキルを読み込み、「モード 1: 新規作成」に従う -- 共有の基盤にする場合は `docs/design-principles/README.md` の「複数のプロダクトで共有する基盤のデザインシステムを作る」も読む - -### 2. ヒアリングする - -`docs/design-principles/hearing.md` の項目に、次のファクトリー固有の項目を足して**一度にまとめて**聞く。 -Claude Code では AskUserQuestion を使う。使えないエージェント（Cursor・Codex など）では、番号付きの短い質問リストをテキストで出す。 -リポジトリや会話から分かることは聞かない。回答は要約して確認してから進む。 - -| # | 項目 | 選択肢・既定 | -| --- | --- | --- | -| 1 | 位置づけ | 複数プロダクトで共有する基盤 / 特定のプロダクト専用 | -| 2 | （専用のときのみ）サービス種別・対象ユーザー・ドメイン・UI の方向性・対象デバイス | hearing.md のとおり | -| 3 | 名前（パッケージ名の元） | 例: `acme-ui` → `acme-ui`、`acme-ui-tokens` | -| 4 | 接頭辞（CSS 変数・レジストリの名前空間） | 例: `acme` → `--acme-*`、`@acme/button` | -| 5 | キーカラー | ブランドカラーの hex、または OKLCH の色相。系統名（英小文字。例: `wakatake`）と表示名（例: 若竹 Wakatake） | -| 6 | フォント・その他のブランド制約 | 既定はひな形のまま（Noto Sans JP 系） | -| 7 | アクセシビリティ目標 | WCAG 2.2 AA（既定）/ AAA | -| 8 | テーマ | ライト＋ダーク（既定）/ ライトのみ | -| 9 | リポジトリ | GitHub の owner と リポジトリ名、ローカルの出力先ディレクトリ | -| 10 | 配布 | shadcn のレジストリのみ（既定）/ npm にも公開 | - -注意: -- キーカラーの色相が状態色（赤 25・橙 50・黄 90・緑 155）に近いと、状態色と区別しにくい。近いときはユーザーに伝え、キーカラーか状態色の色相をずらす案を出す -- 接頭辞と名前は英小文字・数字・ハイフンのみ - -### 3. 設定ファイルを書く - -ヒアリングの結果を JSON にする（置き場所は作業用の一時ディレクトリ。このリポジトリにはコミットしない）。 - -```json -{ - "name": "acme-ui", - "prefix": "acme", - "repository": { "owner": "acme-inc", "name": "acme-design-system" }, - "keyColor": { "hex": "#2f7d5b", "family": "wakatake", "label": "若竹 Wakatake — キーカラー" } -} -``` - -`keyColor` は `hex` の代わりに `hue`（0〜360）でもよい。 - -### 4. 生成する - -```bash -make factory CONFIG=<設定ファイル> OUT=<出力先> -``` - -- git で追跡しているファイルだけがコピーされる。未コミットの変更を含めたいときは先にコミットする -- 名前・接頭辞・系統名・リポジトリの URL が置き換わり、キーカラーの色相が `palette.config.json` に入る -- 最後に「ひな形の見た目の性格が残っている箇所」と「次の手順」が表示される - -### 5. 生成先で仕上げる - -以降は生成先のディレクトリで行う。 - -1. **依存とトークン**: `git init && make setup`（道具の版は `.tool-versions`） → `make palette` → `make tokens` → `design-md` → `tw-merge` → `make registry` -2. **コントラスト**: `make check`。不足があれば `semantic/light.tokens.json` / `dark.tokens.json` の段階番号を調整する。`contrast.rules.json` の基準は緩めない。AAA を選んだ場合は、文字の基準を 7:1 に上げる -3. **見た目の性格**: 4 で表示された箇所を、新しいキーカラーと性格で書き換える（DESIGN.md の冒頭、`docs/rulebook/01-principles.md` の「見た目の性格」、README の冒頭と特長、README のバナー `docs/assets/banner-*.svg` の色）。ロゴとアイコン（`docs/assets/logo*`・`icon-*`、`apps/storybook/public/` の favicon・アイコン・`logo.svg`）は 8341-ui 固有なので、新しいシステムのロゴに差し替えるか、削除して `.storybook/manager.ts` の `brandImage` と `manager-head.html` のリンクを外す（`docs/assets/README.md`）。ひな形の ADR（0002 など）は「引き継いだ判断」として残し、変えた判断は新しい ADR に書く -4. **プロダクトの前提**: - - 共有の基盤 → DESIGN.md の「UI の方向性とサービス種別は各プロダクトで決める」をそのまま使う - - 専用 → `templates/PRODUCT-DESIGN.md` を元に、ヒアリング結果（プロダクト概要・画面領域ごとの方向性とサービス種別・採用したルール・外した必須とその理由）を DESIGN.md の冒頭に書く。特化ルールの「トークン」節に挙がる値（表の行高、主操作のサイズなど）をトークンとコンポーネントに反映する -5. **作者とライセンス**: `package.json` の `author`、`LICENSE` の著作権者を、新しいデザインシステムの持ち主に書き換える。`packages/*/CHANGELOG.md` の初回リリースの説明も新しいシステムに合わせる -6. **フォント**: 指定があれば `packages/tokens/src/primitive/typography.tokens.json` の font-family を変える -7. **ライトのみ**を選んだ場合: ひな形はライト＋ダーク前提。ダークを外す変更は影響が大きいので、範囲（resolver の theme、dark.tokens.json、Storybook の切り替え）をユーザーに示して確認してから行い、ADR に残す -8. **npm にも公開**を選んだ場合: `docs/releasing.md` のとおり、アカウント保有者が `npm login` したうえで `make release-publish NPM=1` を実行すると伝える（トークンは発行しない） -9. **確認**: `make verify && make build-storybook`。Storybook をライト・ダークで開き、キーカラー・フォーカス表示・状態色を目で確かめる - -### 6. 公開する（ユーザーの承認を得てから） - -- コミットし、ユーザーが承認したら GitHub にリポジトリを作って push する（例: `gh repo create / --public --source . --push`） -- GitHub Pages（Settings > Pages を `gh-pages` ブランチに）と、main の保護（README の手順）をユーザーに案内する - -### 7. 報告する - -生成したリポジトリの場所、ヒアリングの要約、ひな形から変えた点、外した必須とその理由、残っている作業を短く伝える。 +1. **ルールを読む**: `design-principles` スキルを読み込み、`mode-1-init.md`（新規作成）に従う +2. **ヒアリングする**: [hearing.md](./hearing.md) の項目を一度にまとめて聞き、要約して確認する +3. **設定ファイルを書く**: 回答を JSON にする（形は [hearing.md](./hearing.md) の「設定ファイル」。作業用の一時ディレクトリに置き、このリポジトリにはコミットしない） +4. **生成する**: `make factory CONFIG=<設定ファイル> OUT=<出力先>` + - git で追跡しているファイルだけがコピーされる。未コミットの変更を含めたいときは先にコミットする + - 最後に「ひな形の見た目の性格が残っている箇所」と「次の手順」が表示される +5. **生成先で仕上げる**: [finish.md](./finish.md) の 1〜9 を順に行う +6. **公開する（ユーザーの承認を得てから）**: コミットし、承認されたら GitHub にリポジトリを作って push する（例: `gh repo create / --public --source . --push`）。GitHub Pages（`gh-pages` ブランチ）と main の保護をユーザーに案内する +7. **報告する**: 生成したリポジトリの場所、ヒアリングの要約、ひな形から変えた点、外した必須とその理由、残っている作業を短く伝える ## このリポジトリ側の改善 - 生成で困った点（置き換え漏れ、手作業が多い手順）は、`scripts/factory/create.mjs` かこのスキルを直す PR にする -- 画面設計のルールのギャップは `docs/design-principles/` を直す（`design-principles` スキルの「ルールへのフィードバック」） +- 画面設計のルールのギャップは `docs/design-principles/` を直す（`design-principles` スキルの `feedback.md`） ## やってはいけないこと diff --git a/.claude/skills/ds-factory/finish.md b/.claude/skills/ds-factory/finish.md new file mode 100644 index 000000000..5724e7d14 --- /dev/null +++ b/.claude/skills/ds-factory/finish.md @@ -0,0 +1,15 @@ +# 生成先での仕上げ（ds-factory の手順 5） + +以降は生成先のディレクトリで行う。 + +1. **依存とトークン**: `git init && make setup`（道具の版は `.tool-versions`） → `make palette` → `make tokens` → `design-md` → `tw-merge` → `make registry` +2. **コントラスト**: `make check`。不足があれば `semantic/light.tokens.json` / `dark.tokens.json` の段階番号を調整する。`contrast.rules.json` の基準は緩めない。AAA を選んだ場合は、文字の基準を 7:1 に上げる +3. **見た目の性格**: 生成時に表示された箇所を、新しいキーカラーと性格で書き換える（DESIGN.md の冒頭、`docs/rulebook/01-principles.md` の「見た目の性格」、README の冒頭と特長、README のバナー `docs/assets/banner-*.svg` の色）。ロゴとアイコン（`docs/assets/logo*`・`icon-*`、`apps/storybook/public/` の favicon・アイコン・`logo.svg`）は 8341-ui 固有なので、新しいシステムのロゴに差し替えるか、削除して `.storybook/manager.ts` の `brandImage` と `manager-head.html` のリンクを外す（`docs/assets/README.md`）。ひな形の ADR（0002 など）は「引き継いだ判断」として残し、変えた判断は新しい ADR に書く +4. **プロダクトの前提**: + - 共有の基盤 → DESIGN.md の「UI の方向性とサービス種別は各プロダクトで決める」をそのまま使う + - 専用 → `templates/PRODUCT-DESIGN.md` を元に、ヒアリング結果（プロダクト概要・画面領域ごとの方向性とサービス種別・採用したルール・外した必須とその理由）を DESIGN.md の冒頭に書く。特化ルールの「トークン」節に挙がる値（表の行高、主操作のサイズなど）をトークンとコンポーネントに反映する +5. **作者とライセンス**: `package.json` の `author`、`LICENSE` の著作権者を、新しいデザインシステムの持ち主に書き換える。`packages/*/CHANGELOG.md` の初回リリースの説明も新しいシステムに合わせる +6. **フォント**: 指定があれば `packages/tokens/src/primitive/typography.tokens.json` の font-family を変える +7. **ライトのみ**を選んだ場合: ひな形はライト＋ダーク前提。ダークを外す変更は影響が大きいので、範囲（resolver の theme、dark.tokens.json、Storybook の切り替え）をユーザーに示して確認してから行い、ADR に残す +8. **npm にも公開**を選んだ場合: `docs/releasing.md` のとおり、アカウント保有者が `npm login` したうえで `make release-publish NPM=1` を実行すると伝える（トークンは発行しない） +9. **確認**: `make verify && make build-storybook`。Storybook をライト・ダークで開き、キーカラー・フォーカス表示・状態色を目で確かめる diff --git a/.claude/skills/ds-factory/hearing.md b/.claude/skills/ds-factory/hearing.md new file mode 100644 index 000000000..e19214b8a --- /dev/null +++ b/.claude/skills/ds-factory/hearing.md @@ -0,0 +1,40 @@ +# ヒアリングと設定ファイル（ds-factory の手順 2・3） + +## ヒアリングの項目 + +`docs/design-principles/hearing.md` の項目に、次のファクトリー固有の項目を足して**一度にまとめて**聞く。 +Claude Code では AskUserQuestion を使う。使えないエージェント（Cursor・Codex など）では、番号付きの短い質問リストをテキストで出す。 +リポジトリや会話から分かることは聞かない。回答は要約して確認してから進む。 + +| # | 項目 | 選択肢・既定 | +| --- | --- | --- | +| 1 | 位置づけ | 複数プロダクトで共有する基盤 / 特定のプロダクト専用 | +| 2 | （専用のときのみ）サービス種別・対象ユーザー・ドメイン・UI の方向性・対象デバイス | hearing.md のとおり | +| 3 | 名前（パッケージ名の元） | 例: `acme-ui` → `acme-ui`、`acme-ui-tokens` | +| 4 | 接頭辞（CSS 変数・レジストリの名前空間） | 例: `acme` → `--acme-*`、`@acme/button` | +| 5 | キーカラー | ブランドカラーの hex、または OKLCH の色相。系統名（英小文字。例: `wakatake`）と表示名（例: 若竹 Wakatake） | +| 6 | フォント・その他のブランド制約 | 既定はひな形のまま（Noto Sans JP 系） | +| 7 | アクセシビリティ目標 | WCAG 2.2 AA（既定）/ AAA | +| 8 | テーマ | ライト＋ダーク（既定）/ ライトのみ | +| 9 | リポジトリ | GitHub の owner と リポジトリ名、ローカルの出力先ディレクトリ | +| 10 | 配布 | shadcn のレジストリのみ（既定）/ npm にも公開 | + +注意: + +- キーカラーの色相が状態色（赤 25・橙 50・黄 90・緑 155）に近いと、状態色と区別しにくい。近いときはユーザーに伝え、キーカラーか状態色の色相をずらす案を出す +- 接頭辞と名前は英小文字・数字・ハイフンのみ + +## 設定ファイル + +ヒアリングの結果を JSON にする（置き場所は作業用の一時ディレクトリ。このリポジトリにはコミットしない）。 + +```json +{ + "name": "acme-ui", + "prefix": "acme", + "repository": { "owner": "acme-inc", "name": "acme-design-system" }, + "keyColor": { "hex": "#2f7d5b", "family": "wakatake", "label": "若竹 Wakatake — キーカラー" } +} +``` + +`keyColor` は `hex` の代わりに `hue`（0〜360）でもよい。 diff --git a/.claude/skills/ds-slides/SKILL.md b/.claude/skills/ds-slides/SKILL.md index a8086f8b8..1428b8f18 100644 --- a/.claude/skills/ds-slides/SKILL.md +++ b/.claude/skills/ds-slides/SKILL.md @@ -7,124 +7,25 @@ description: 8341-ui のトークンとデザイン原則に沿って、発表 スライドの見た目（文字サイズ・色・余白・揃え）は `scripts/slides/deck.css` が 8341-ui の semantic トークンだけで決める。作者が決めるのは **構成・文言・レイアウトの選択** だけにする。ルールの正は `docs/rulebook/07-slides.md`（S1〜S20）で、その元は `docs/design-principles/principles.md` と WCAG 2.2 である。 -## 作る前に読む - -1. `docs/rulebook/07-slides.md`（ルール・レイアウト・使えるクラス） -2. `docs/rulebook/05-writing.md`（です・ます、数字、リンクの書き方） -3. `scripts/slides/examples/sample.html`（全レイアウトの見本） -4. 判断に迷ったら `docs/design-principles/principles.md` の該当ルールだけ（「読み順と優先度」「まとまり」「一度に出す数」「削る」「文言」） - ## 手順 -### 1. 前提を聞く - -推測できない項目だけを、短いリストで一度に聞く（Claude Code では AskUserQuestion、ほかのエージェントでは番号付きの質問リスト）。 - -- 目的: 聞き手に何を決めて・知ってもらいたいか（1 文で） -- 聞き手: 誰か、前提知識はどれくらいか -- 場: 発表時間（枚数の目安は 1 分 1 枚）、投影か配布か、会場が暗いか（暗いならダークを提案） -- 材料: 数字・図・出典として使ってよい資料 - -答えを 3〜5 行で要約して確認してから進む。 - -### 2. 構成を決める（書く前に） - -- まず **結論の 1 文** を決める。冒頭（表紙の次）に `statement` で置く（S7） -- 各スライドの見出し（`h2`）だけを並べた骨子を作る。見出しは **そのスライドの結論を文で**（S1）。見出しだけを順に読んで話が通じれば構成は良い -- 章が 3 つ以上なら `section`（章扉）で区切る。最後は `summary` で「持ち帰ってほしいこと」を 3 つまで -- 骨子をユーザーに見せて合意してから中身を書く（枚数が多い、または聞き手が重要な場合） - -### 3. レイアウトを選ぶ - -| 伝えたいこと | レイアウト | -| --- | --- | -| 1 文の主張・結論 | `statement` | -| 理由や事実を 3〜5 個 | `content`（箇条書き） | -| 2〜3 個の対比・並列 | `columns`（枠が要るなら `.col.card`） | -| 数字そのものが主役 | `stats`（2〜4 個） | -| 時間の流れ・手順 | `steps`（3〜5 段） | -| 推移・比較の傾向 | `figure`（SVG のグラフ） | -| 数値を正確に読ませる | `table`（6 行 × 5 列まで） | - -同じ種類の内容には、デッキの中で同じレイアウトを使う（一貫性）。 - -### 4. ソースを書く - -`slides/<名前>.html`（置き場所はユーザーの指定に従う）に、見本と同じ形で書く。 - -```html - - -デッキの題 - -
-

デッキの題

-

副題

-

2026年10月20日　発表者

-
-
-

このスライドの結論を文で書く

-
  • …
-

出典: …

- -
- - -``` - -決まり（違反は検査でエラーになる）: - -- `body` の直下は `section.slide` だけ。`style` 属性・`