slide-design-review

完成した Slidev のページを、画像として見て直すための Skill。 1ページずつ「レンダリング → レビュー → 直す問題を決める → 直す → 再レンダリング → 再レビュー」を回し、重大な問題が無くなるか、良くならなくなるか、上限の回数に達したら止める。

• 入力: Slidev のプロジェクト（package.json に @slidev/cli）と、対象のページ番号（または「全ページ」）
• 出力: 直したソース、プロジェクト直下の design-review/（ページごとのレビュー・変更記録・差分・比較・経過表、ページをまたいだ症状の記録）
• 扱わないこと: 内容・主張・構成の見直し、ページの分割や並べ替え、デッキ全体のテーマ作り、画像の生成
• 完成例: assets/example/（1ページを3回直した実際の記録。レビュー・変更・差分・比較・前後の画像）

原則

1. 見るのはレンダリングされた画像

評価の対象はソースではなく、ブラウザで描かれた PNG。Slidev 公式の slidev export --format png を同梱の scripts/render.mjs で包み、キャンバス等倍（1920×1080 なら 1920×1080）で書き出す。

2. 直す役と評価する役を分ける

主セッションは進行役で、スライドを直さず、デザインの良し悪しも判定しない。次の3つの役を、毎回新しい subagent として呼ぶ。

レビュー役は毎回新しく呼ぶので、前に自分が何を指摘したかに引きずられない。「前より良くなったか」はレビューの件数ではなく、比較役が2枚を並べて判定する。

3. 一度に全部を直さない

1回の修正で直すのは、レビューの最優先の問題1件（同じ場所の関連する問題なら2件まで）。大きな問題から順に直す。

4. ほかのページを理由なく変えない

修正のたびに全ページを書き出し、前後を画素で比べる（同じソースからの書き出しはバイト単位で一致するので、差は本当の変化）。対象外のページが変わっていたら、比較役で後退していないかを確かめ、後退していれば戻す。

5. 後退した変更は戻し、経過は全部残す

修正の前にソースを退避し、比較で後退・差なしと判定された変更は戻す。反復ごとのレビュー・変更記録・差分・比較・判断を design-review/ に残し、何を問題と見て何を変えたかを後から追えるようにする。

ワークフロー

以下、<skill> はこの SKILL.md のあるフォルダ、<root> は Slidev プロジェクトのルート、<log> は <root>/design-review/ を指す。

Step 0: 対象と環境の点検

1. デッキのファイルを決める（既定は <root>/slides.md）。ページの一覧を取る

   node <skill>/scripts/render.mjs --deck <root>/slides.md --list

   終了コード 2 なら Slidev のプロジェクトでないか、依存が入っていない。メッセージのとおりに伝えて止まる。

2. 対象のページを確定する。「Page 3」は Slidev の表示上のページ番号（非表示のスライドを除いた順番）。一覧の title・layout と、依頼者の言うページが食い違いそうなら、一覧を見せて確かめる
3. playwright-chromium があるかは、Step 1 の書き出しで分かる（無ければ終了コード 3）。無いときは選択式の質問で導入先を聞く
   • プロジェクトの devDependencies に入れる（推奨。Slidev 公式の手順で、PDF の書き出しにも使える。package.json と lockfile が変わる）
   • グローバルに入れる（プロジェクトのファイルは変わらない）
   • やめる
4. 規約メモを作る。実装役が守る決まりを、プロジェクトから集めて数行にまとめる
   • CLAUDE.md、README、docs/ のデザイン規則、slide-plan.md
   • layouts/md-standard.vue などの md- で始まる layout があれば、md-to-slidev で作ったデッキ。その決まり（slides.md に <style>・色・文字サイズ・UnoCSS のクラスを書かない、18px 未満の文字を使わない、色やサイズは style.css の変数、図は同梱の component）を規約メモに入れる
   • 何も無ければ「規約の文書なし。既存のページの書き方に合わせる」と書く
5. ソースの状態を記録する。git で管理されていれば、今のコミットと未コミットの変更の有無を控える（経過表の「開始時点のソース」）
6. 修正の上限を決める。既定は 3回（レビューは最大4回）。依頼者が回数を言えば従う

Step 1: 準備と最初の書き出し

1. <log> が無ければ作り、assets/gitignore を <log>/.gitignore として置く（画像と退避は追跡しない。Markdown の記録は残る）。<log>/patterns.md が無ければ assets/patterns.template.md から作る
2. <log>/page-NN/（NN はページ番号、2桁）を作り、assets/log.template.md から log.md を作る。{{...}} は Step 0 で分かった値で埋める。同じページの記録が既にあれば、新しいフォルダ page-NN-2/ を作る（前回の記録を消さない）

3. 全ページを書き出す

   node <skill>/scripts/render.mjs --deck <root>/slides.md --out <log>/.renders/current

4. 対象ページの画像を <log>/page-NN/r0.png にコピーする

回数を k（1から）とし、Step 2〜6 を繰り返す。r(k-1).png が今の画像。

Step 2: レビュー

レビュー役の subagent を呼ぶ（Claude Code の Agent ツール、general-purpose）。渡すのは次だけ。

あなたはスライドのデザインレビュー役。<skill>/references/reviewer.md を読んで、その指示に従う。
- 画像: <log>/page-NN/r(k-1).png
- ページ: NN（layout: <layout 名>）
- キャンバス: 1920×1080

前回のレビュー、変更記録、ソースの場所は渡さない。返ってきた本文を、手を加えずに <log>/page-NN/review-k.md に保存する。 形が崩れていたら（見出しが無い、Priority に改善案が無い）、同じ入力で1回だけ呼び直す。

Step 3: 終了の判定と、直す問題の選択

次のどれかに当たれば Step 7 へ。

• Critical と Major が両方「なし」 → 終了（重大な問題なし）
• 修正が上限の回数に達している（k-1 = 上限） → 終了（上限）。このレビューが最後の評価になる
• Priority 1 が、同じ箇所の同じ性質を、これまでの修正と逆向きに動かす指摘で、その性質の向きが入れ替わるのが2回目になる（大きく → 小さく → また大きく） → 終了（指摘が往復）。独立したレビューのぶれで、改善が収束したとみなす。1回だけの逆向き（修正の行き過ぎを戻す量の調整）は往復に数えない

当たらなければ、今回直す問題を選ぶ。Priority 1 は必ず。Priority 2 は、Priority 1 と同じ場所・同じ原因で、一緒に直す方が自然なときだけ足す。選んだ問題と理由を log.md に書く。

Step 4: 修正

1. ソースを退避する

   node <skill>/scripts/snapshot.mjs save <root> <log>/.snapshots/page-NN-k

2. 実装役の subagent を呼ぶ（general-purpose）

   あなたはスライドの実装役。<skill>/references/implementer.md を読んで、その指示に従う。
   - プロジェクト: <root>、デッキ: slides.md
   - 対象: ページ NN（slides.md の L<start>-<end>、layout: <layout 名>）
   - 今回直す問題: （review-k.md の Priority をそのまま貼る）
   - 壊してはいけない良い点: （review-k.md の Positive aspects をそのまま貼る）
   - 規約メモ: （Step 0 のもの）
   - 変更記録: <log>/page-NN/changes-k.md に書く

   やり直しのとき（Step 5・6 で戻した場合）は、前回の changes と、採られなかった理由を足す。

3. 差分を残す

   node <skill>/scripts/snapshot.mjs diff <root> <log>/.snapshots/page-NN-k > <log>/page-NN/diff-k.patch

   差分が「no changes」なら、実装役が直さずに提案だけを返したということ。提案を log.md に書き、Step 7 へ（終了: 実装役が提案のみ）。

Step 5: 再書き出しと影響の範囲

node <skill>/scripts/render.mjs --deck <root>/slides.md --out <log>/.renders/next
node <skill>/scripts/compare-renders.mjs <log>/.renders/current <log>/.renders/next

• 書き出しが失敗したら、エラーを実装役に渡して直させる（同じ回のうち。2回失敗したら、退避から戻して Step 7 へ。終了: 書き出し失敗）
• ページが増えた・減った（added・removed）なら、実装役が規約に反してページを動かした。戻して Step 7 へ
• 対象ページが changed に無いなら、修正が見た目に効いていない。1回だけ、そのことを伝えて実装役に直させる。それでも変わらなければ戻して Step 7 へ（終了: 変化なし）
• 対象ページの新しい画像を <log>/page-NN/rk.png にコピーする

Step 6: 比較と採否

1. 対象ページについて、比較役の subagent を呼ぶ。A と B のどちらを新しい画像にするかは、偏らないよう毎回ランダムに決める（node -e "console.log(Math.random()<0.5?'new=A':'new=B')"）。どちらが新しいかは比較役に伝えない

   あなたはスライドの比較役。<skill>/references/comparator.md を読んで、その指示に従う。
   - 画像 A: <パス>
   - 画像 B: <パス>
   - ページの種類の手がかり: layout: <layout 名>、キャンバス 1920×1080

   比較役の画像は、r(k-1).png と rk.png を、A・B という名前だけが分かるようにコピーしたものを渡す（例: <log>/.renders/compare/A.png）。ファイル名から新旧が分からないようにするため。

2. ほかのページで changed になったものがあれば、それぞれを同じ方法で比較役にかける（current と next の同じページ）
3. 結果と、A・B のどちらが新しかったかを <log>/page-NN/compare-k.md に書く。判定は次のとおり

戻したときは、.renders/next を消す（current は戻したソースと一致している）。判断を log.md の経過表に1行足す。

Step 7: ページの締め

1. log.md の「終了」を埋める。最後のレビュー、残った指摘、提案だけにしたこと、共通のファイルへの変更と、それで変化したほかのページ
2. <log>/patterns.md の表に、このページで直した（または戻した）症状を1行ずつ足す。同じ症状が3ページ以上に出ていれば「共通化の候補」を更新する。原因が共通の部品（layout の既定の文字組み、CSS の変数）にある症状は、同じ構造を持つページすべてに出るので、1ページでも候補に挙げる
3. <log>/.renders/next と <log>/.renders/compare を消す。.snapshots/ は残す（あとで戻したくなったときのため。追跡はされない）

Step 8: 報告

• 終了の理由と、最後のレビューの重大度の件数
• 反復ごとの「問題 → 変更 → 比較の結果 → 判断」（log.md の経過表から）
• 最初と最後の画像のパス（r0.png と最後の rk.png）。依頼者が並べて見られるように
• 共通のファイルに触ったか。触ったなら、見た目が変わったほかのページと、後退していないと判定されたこと
• 残った指摘、実装役の提案（ページの分割など）、共通化の候補
• 比較役の判定も LLM の判断であり、最終的な良し悪しは依頼者が画像で確かめること

全ページを対象にするとき

「全ページ」「3〜8ページ」のように複数を頼まれたら、Step 0 は1回だけ行い、対象のページを先頭から順に、1ページずつ Step 1〜7 で処理する。並列にはしない（修正が同じファイルに触るため）。

• 始める前に、対象のページ数と、1ページあたり最大でレビュー4回・修正3回・比較3回の subagent 呼び出しになることを伝える。依頼がそのとおりなら確認を待たずに始める
• 最初のレビューで Critical・Major が無いページは、そこで終わる。直すのは問題のあるページだけになる
• 前のページの修正で共通のファイルが変わり、後ろのページの見た目が変わっていても、その比較は Step 6 で済んでいる。後ろのページは、その時点の画像から始める
• 最後に、ページごとの終了理由と残った指摘の一覧、patterns.md の共通化の候補を報告する

避けるパターン

前提と制約

• Claude Code 専用。役を分けるために subagent（Agent ツール）を使う
• Slidev（@slidev/cli）が入ったプロジェクトと、その Slidev が求める版の Node.js（Slidev 53 は 22.12 以上）、playwright-chromium（プロジェクトかグローバル）
• 書き出しは Slidev の公式機能に任せているので、Slidev が描けるものなら描ける。クリックで出る要素は、すべて出た最後の状態で書き出される
• 書き出しの詳細と、うまくいかないときの対処は references/rendering.md