reviewing-design-system

reviewing-design-system — SKILL.md

バリアント： 標準 · 使用するタイミング： 完成したデザインシステム文書（または変更差分）を受け入れ判定の基準として評価し、デザイナー／エンジニアが一貫性とアクセシビリティを備えた UI を構築できるか確認したうえで、対応可能な指摘事項とともに VERDICT: approve|revise を出力します。

概要

このスキルは、デザインシステムの作成／評価を行う一組のスキルのうち、レビューを担います。完成したデザインシステム文書（または以前のバージョンに対する変更差分）を手元に持つレビュアーが読み込み、次の問いに照らして評価します。デザイナーは一貫性のある UI を構築でき、エンジニアは著者に確認せずにこの文書から実装できるか。また、カタログはプロダクトの画面で必要となるコンポーネントを網羅しているか。 固定されたユーザビリティ＋一貫性＋アクセシビリティのチェックリストを適用します。これは著者が作成時に用いる基準（authoring-design-system）と同じものなので、作成基準とレビュー基準が食い違いません。その後、機械で解析可能な単一の判定と、著者が一度の改訂で対応できる指摘事項を出力します。評価対象はレンダリングされたデザインファイルではなく、テキスト形式の Markdown 成果物（値としてのトークン＋DTCG 形式＋仕様テーブル）です。これは受け入れ判定のゲートであり、文書の作成、修正、書き換えは行いません。

有効化するタイミング

• ワイヤーフレーム／高精細デザイン／UI エンジニアリングで利用する前に、完成したデザインシステム文書について承認／修正の判定が必要な場合。
• 変更（既存システムに対するバージョン管理された差分）について、変更範囲に絞った承認／修正の判定が必要な場合。
• 以前の判定が revise だったデザインシステムの改訂版を再評価する場合。

次の場合は有効化しないでください：

• デザインシステムを作成または修正する場合 → authoring-design-system を使用します。
• ワイヤーフレーム／画面ごとのレイアウト文書をレビューする場合 → ワイヤーフレームレビュー用スキルを使用します（このスキルは、ひとつ上のレイヤーにある再利用可能な語彙を評価します）。
• ユーザーフロー文書をレビューする場合 → ユーザーフローレビュー用スキルを使用します。
• エンジニアリング設計文書（アーキテクチャ／ADR／RFC）をレビューする場合 → デザインレビュー用スキルを使用します。
• テンプレート／セクションへの準拠を確認する場合 → それはテンプレートに関する事項です。このスキルは基準に対する品質を評価します。
• コード化されたコンポーネントライブラリを評価する場合 → このスキルが評価するのは文書です。

ワークフロー

ステップ 1：文書全体を先入観なく読む

著者による説明に頼らず、最初から最後まで読みます。次の工程（ワイヤーフレーム＋高精細デザイン＋UI エンジニアリング）へのゲートキーパーとして、指摘に重みがあるのは、記述どおりではデザイナー／エンジニアが一貫性とアクセシビリティを備えた UI を構築できないことを示せる場合に限られます。プロダクトの類型（軽量な CLI／ユーティリティ、コンテンツアプリ、フル UI プロダクト）を特定し、利用できる場合はフロー／画面一覧も確認します。網羅性と比例性に関する条件は、それに応じて調整します。成果物が変更差分の場合は、以前のバージョンと変更範囲も読みます（ステップ 2b）。

ステップ 2：チェックリストを実施する — 各条件を評価する

それぞれについて、合格または不備ありを判断します。条件が不合格となるのは、実際に特定できる不備がある場合に限られます。「別のカラーパレットを選んでいた」は不備ではありません。不備ごとに正確な箇所を記録します。これらの条件が単一の基準（著者が作成時に用いる、レビューと作成の両方の観点）です。独自の条件を追加してはいけません。各条件には、正当に適用されない場合、つまり比例性によって適用対象から外れる場合も示されています。

1. 原則が明示されている。 実行可能な原則を3～6個示します（ありきたりな標語は不可）。記載がない場合や、ありきたりな標語しかない場合は 不足 とします。
2. トークンが定義され、DTCGに準拠し、意図を示す名前が付けられ、一貫して適用されている。 カラー（セマンティックロールトークンを含む）、タイポグラフィスケール、スペーシング、エレベーション、モーションを、具体的な値を持つ名前付きトークンとして定義します。W3C DTCG形式（型付きの$value＋エイリアス）で表現すること。規模を問わず必須であり、値の表を例外として認めません。コンポーネントはセマンティックトークンを参照し、生の値（#1A73E8、16px）を直接使用しません。トークンファミリーが欠けている、値がない、DTCG構造のないフラットな16進カラーコードの一覧になっている、またはコンポーネント仕様が生の値を参照している場合は 不足 とします。対象外： DTCGに関する例外はありません（すべてに適用）。モダンなカラー空間（Oklch/P3）は規模に応じて判断し、sRGBのみでも不足とはしません。
3. 基盤の網羅性。 アーキタイプで必要な場合、グリッド／レイアウト＋密度、アイコノグラフィ（グリッド／ストローク／サイズ／スタイル）、エレベーション／モーションが含まれています。UI製品が、明らかに使用しているグリッドやアイコンの基盤を省略している場合は 不足 とします。対象外： アイコンや複雑なレイアウトのない小規模な製品／ユーティリティ製品では、これらを正当に省略できます。
4. エイリアスの切り替えによるテーマ設定。 ライト／ダーク、および該当する場合はマルチブランドで、コンポーネントを分岐させず、固定された1つの階層の上でセマンティックエイリアスを付け替えます。テーマをコンポーネントの複製／分岐によって実装している場合は 不足 とします。対象外： 単一ブランド・単一テーマの場合、これを詳述する必要はありません。
5. コンポーネントの完全性（コンポーネントごと）。 カタログに掲載されるすべてのコンポーネントに、解剖図、状態、バリアント、使用上の推奨事項／禁止事項、アクセシビリティの5項目すべてが含まれています。いずれかのコンポーネントで1項目でも欠けている場合（例：バリアントはあるが状態やアクセシビリティの記載がない）は 不足 とします。
6. コンポーネントAPIの一貫性。 カタログ全体で、プロパティ／オプション／デフォルトの用語が統一されています（同じバリエーション軸には同じ名前を付けます。ある場所ではtype、別の場所ではmodeとしません）。共通の値を組み合わせて使用できます。コンポーネント間でAPIにずれがある場合は 不足 とします。対象外： 小規模なカタログでは、自然に一貫性を保てます。
7. カタログの網羅性 — 2つの最低基準。 製品のフロー／画面で使用するすべてのコンポーネント（完全な仕様を備えた必須下限）と、アーキタイプの規模に応じた標準セットを網羅します。実際の画面に必要なコンポーネントがカタログにない、または仕様が不十分な場合は 不足 とします。対象外： 標準セットはアーキタイプに応じた規模とします（過剰に網羅しません）。
8. パターンが含まれている。 フローで必要となる、複数コンポーネントを組み合わせた反復的なシナリオ（フォームの検証、空の状態、破壊的操作の確認など）を含みます。必要なパターンがない場合は 不足 とします。
9. レイアウト＋国際化。 ブレークポイント／グリッド／フォーカス順序を明記します。ローカライズされた製品では、i18n／RTL（テキストの拡張、論理プロパティ、RTL／双方向テキスト、ロケール別フォント）にも対応します。ローカライズされた製品でi18nが考慮されていない場合や、リフローする画面について何も記載されていない場合は 不足 とします。対象外： 単一ロケールのツールであると明記されている場合は、i18nを明示的に対象外にできます（明示的な対象外は不足ではありません。記載のない省略は不足です）。
10. 数値基準を伴うアクセシビリティ、WCAG 2.2 AA。 WCAG 2.2 AAへの適合を目標として明記し、検証可能な基準を設けます。テキストのコントラスト比は4.5:1以上（大きな文字／UIは3:1以上）。視認でき、遮られないフォーカスインジケーター（SC 2.4.7＋2.4.11、AA）に加え、AAAのFocus Appearance基準である、フォーカスなしの状態および隣接色とのコントラスト比3:1以上、太さ2px以上（SC 2.4.13）を社内ルールとして採用します。ターゲットサイズは24×24（間隔に関する例外あり）。キーボード操作、モーション低減、色だけに依存しない表現、コンポーネントごとのロール／名前／状態にも対応します。アクセシビリティが努力目標にとどまり、数値基準がない場合や、2.2固有の基準を満たしていない場合は 不足 とします。対象外： 例外はありません。アクセシビリティは必須です（ただし、静的な情報画面では、存在しない状態について詳述する必要はありません）。
11. ボイス／コンテンツが含まれている。 ボイスとトーンの指針（重要な場面ではブランドボイスより明確さを優先）、用語（概念ごとに用語を1つに統一）、コンポーネントの文言ルール（ボタンは動詞から始める、エラーは原因＋解決策、空の状態は次の行動を案内）を定めます。ユーザー向けの文言がある製品で記載がない場合、またはエラー／空の状態のルールに原因＋解決策／行動への案内がない場合は 不足 とします。対象外： ユーザー向けの文言がない製品では、簡素な記載で構いません。
12. ライフサイクルとガバナンス（基準を超える場合）。 複数の利用者／チームがあるシステム、またはバージョン管理された外部リリースでは、バージョン管理＋変更履歴、非推奨化／移行ポリシー、コントリビューションモデル、所有者、導入方法、および意思決定事項として記録された対象読者（想定ペルソナに依存しない）を定めます。基準を超えているにもかかわらず、ガバナンス／バージョン管理がない場合や、想定された対象読者が用語を左右している場合は 不足 とします。対象外： 基準未満（メンテナーが1人、利用者が1つ、バージョン管理された外部リリースがない）の場合は全面的に省略可能です。この場合にガバナンス上の不足を無理に作り出すのは、誤った修正判断です。
13. 定型文ではなく実態に即し、後続工程で利用できる。 トークン／コンポーネントがこの製品（アーキタイプの規模に応じたもの）を反映しています。不足事項は捏造せず、前提／未解決の質問として明らかにします。ワイヤーフレーム／高精細デザインで実在するコンポーネント／トークンを参照でき、エンジニアが作成者に問い合わせずに実装できます。汎用的な記載、捏造されたブランド／コントラストの回答、または参照先の欠落がある場合は 不足 とします。 比例性。 「これを基に一貫性のある UI を構築する」ために必要な要件は、製品の規模に応じて変わります。小規模な製品のシステムでは、上記の条件が適切に簡略化されることがあります。ただし、最低限の基準（条件 7a）、DTCG（条件 2）、数値で示すアクセシビリティ要件（条件 10）は、どの規模でも満たす必要があります。判断基準は、行数ではなく、判断事項が網羅されているかどうかです。簡潔さを理由に、実際には存在しない不足を指摘しないでください。

Step 2b: 成果物が改訂版（差分）の場合 — 文書全体ではなく差分をレビューする

バージョン管理された差分を以前のバージョンと比較して評価する場合、基準の対象は差分に限定されます。

• 対象範囲の限定 — 変更されているのは指定されたトークン／コンポーネントのみであり、無関係な名称変更、パレットの大幅な変更、階層の再構成がないこと。対象範囲外の変更はスコープクリープにあたるため、revise（または変更を分割）とします。
• 波及／リグレッション — すべてのコンポーネントが実在するセマンティックトークンを引き続き参照していること（名称変更／削除によって孤立したものがないこと）。エイリアスレイヤーが解決できること。テーマバリアントの整合性が保たれていること（ダークモード／ブランドに気づかれない破損がないこと）。
• バージョニングと変更履歴の正確性 — SemVer の更新が変更クラスに適合していること（名称変更／削除／型変更 ⇒ MAJOR、追加 ⇒ MINOR、修正 ⇒ PATCH）。変更履歴が差分と一致していること。
• 非推奨化への対応 — 破壊的変更には非推奨化と移行手順を含めること。告知なしに削除しないこと。
• 一貫性 — 変更が既存の階層／意図を示す命名／カタログ API に適合していること。また、差分が該当する Step 2 の条件を局所的に満たしていること。
• 再レビューの比例性 — 評価するのは差分です。確定済みで変更のないトークン／コンポーネントを再び問題にしないでください。

Step 3: 判定を決める

• approve — 適用される条件（差分の場合は、差分に限定されたすべての確認事項）に合格しており、デザイナー／エンジニアが記載どおりに構築できること。スタイル上の改善案が思い浮かんでも承認してください。基準は使いやすさ、一貫性、アクセシビリティであり、完璧さや最大限の網羅性ではありません。
• revise — 構築を妨げる、具体的に指摘できる不足が 1 つ以上あること（未定義／不整合／DTCG 非準拠のトークン、仕様内の生の値、部品が欠けているコンポーネント、API の不整合、数値で示されていない、または 2.2 に準拠しないアクセシビリティ要件、カバレッジの抜け、ローカライズ製品での i18n の見落とし、基準値を超える場合のガバナンスの欠如、対象範囲外またはバージョン管理されていない差分、捏造された内容）。

努力を評価するため、または「あればよい」項目を求めるために revise にしないでください。

Step 4: 判定と、実行可能な指摘事項を出力する

判定は、単独の行にリテラルな VERDICT: approve または VERDICT: revise のいずれかを出力します。コードフェンスや引用符、余分な語句は付けません。

VERDICT: approve

続けて指摘事項を列挙します。revise の場合、それぞれの指摘事項には、該当する不合格条件＋正確な場所＋修正方法を含め、作成者が一度の作業で解決できるようにします。approve の場合、指摘事項は任意で、ブロッキングではない注記に限ります。

良い指摘事項：

revise — トークン（条件 2）、「Button」仕様：background: #1A73E8 は生の HEX 値です。修正方法：セマンティックトークン color.action.primary を参照し（色のセクションで定義してください）、DTCG 形式で表現します。

悪い指摘事項：「トークンを改善できるはずです。」 (どのトークンですか？ なぜですか？ どう修正すればよいですか？)

ルール

必須ルール（決して違反しないこと）：

• 判定行は必ず1行だけ出力してください。VERDICT: approve または VERDICT: revise — この文字列を単独の行に記載します。
• 評価に徹し、執筆はしないでください。 指摘事項を返し、文書を書き換えたり修正したりしないでください。
• 単一の基準に従ってください。 Step 2 の条件（差分の場合は Step 2b も）に照らして評価します。これは執筆者が従う基準と同じです。独自の追加条件を設けないでください。
• 誤った revise 判定をしないでください。 適用されるすべての条件を満たすシステムは、内容が簡素でも approve します。対象範囲をカバーした適切な規模の設計は欠陥ではありません。
• 誤った approve 判定をしないでください。 実際に不足があれば revise とします。
• 生の値、または DTCG に準拠しないトークンは、一貫性の欠如にあたります（条件 2）。5つの要素のうち1つでも欠けているコンポーネントは不足にあたります（条件 5）。API の乖離は不足にあたります（条件 6）。
• アクセシビリティは WCAG 2.2 AA に準拠した数値で示す必要があります（条件 10）— 可視で隠されていないフォーカス（AA）、AAA のフォーカス表示に関する 2px／3:1 以上という独自ルール、ターゲットサイズ 24px を含みます。
• 対象範囲の最低基準、DTCG、数値で示すアクセシビリティは、どのような規模でも維持してください — 省略できません。
• ガバナンスは、しきい値未満なら省略可能で、しきい値以上なら必須です（条件 12）— 規模の小さい内部システムに、存在しないガバナンス不足を指摘しないでください。
• 差分の場合は変更箇所を確認してください（Step 2b）— スコープの限定、波及影響、セマンティックバージョニング、非推奨化を確認し、変更されていない部分を再評価しないでください。
• 捏造は、根拠ではなく不足です（条件 13）。
• 文書に与えられた上流資料に照らして評価してください。 提供されていない上流資料を根拠に revise としてはなりません。参照すべき提供済みの上流資料を文書が無視している場合は、妥当な指摘です。
• revise の指摘はすべて、実行可能な内容にしてください — 不合格となった条件、該当箇所、具体的な修正方法を示します。

優先事項（状況に応じて変更可能）：

• 指摘は重大度順に並べてください — まずブロッキングとなる不足を示します。
• 各指摘で、条件番号または条件名に触れてください。
• approve に添える注記は少数にとどめ、ブロッキングではないことが明確に伝わるようにしてください。

注意点

• 実装可能性ではなく、網羅性を理由に approve する。 すべてのセクションが揃っていても、実装できない場合があります（仕様書に生の値がある、コンポーネントに状態やアクセシビリティの記載がない、コントラストが数値化されていないなど）。テンプレートを埋めているかではなく、実装可能かを評価してください。
• 仕様書に隠れている生の値／DTCG 非準拠のトークン。 トークンのセクションが適切に見えても、「Button」に #1A73E8 がハードコードされていたり、トークンが DTCG 構造を持たない単なる 16 進カラー値の一覧だったりすれば、いずれも条件 2 に不合格です。
• 仕様が不完全なコンポーネント。 構造、バリエーション、使用方法があっても、状態やアクセシビリティがなければ、完成しているように見えるだけで不十分です（条件 5）。
• 2.2 固有のアクセシビリティ要件を見落とさないこと。 「フォーカスのコントラスト比 ≥3:1」のような一般的な記述だけで、隠されていないこと（AA、SC 2.4.11）、フォーカス表示に関する 2px 以上という独自ルール（SC 2.4.13）、ターゲットサイズ 24px がなければ、基準を満たしません（条件 10）。
• 規模の小さいシステムを誤って revise にしないこと。 小規模な製品のシステムは、適切に小規模であるべきです。不要なセクションの省略、対象外とされた i18n、しきい値未満でのガバナンスの省略は、仕様不足ではなく適切な規模への調整です。
• しきい値未満でガバナンス不足を捏造しないこと — 保守担当者が1人で利用者も1人のシステムでは、ライフサイクル／ガバナンスのセクションを完全に省略しても問題ありません（条件 12）。
• 差分レビューで文書全体を再評価しないこと — Step 2b に従い変更箇所を確認します。変更されていない確定済みトークンを再び問題にするのは、差分レビューでの誤った revise 判定です。
• 非推奨化なしで破壊的変更を含む差分を MINOR として通さないこと — Step 2b のバージョニングと非推奨化の確認事項です。
• 判定トークンを変えないこと。 「Approved」、「LGTM」、文中に埋め込まれた判定では解析できません。VERDICT: approve|revise の文字列を単独の行に出力してください。

アンチパターン

• 形式だけの approve。 revise の繰り返しを避けるため、ざっと見ただけで approve すること。
• 細部へのこだわりによる revise。 配色の好みやあると望ましいだけの要素を、不足と見なしてブロッキングにすること。
• 黙って書き換えること。 レビュー中に文書を執筆すること。
• 条件を勝手に追加すること（Figma のリンク、不要なダークモードなど）— 生成基準から評価基準がずれてしまいます。
• 過度な要求。 規模の小さい製品に、幅広い標準一式や完全なガバナンスを求めること。
• 差分レビューで再生成扱いにすること。 差分を、まったく新しい文書であるかのように評価すること。
• 曖昧な判定。 「ほぼ approve ですが……」や、判定行を2行出すこと。

出力

単一のレビュー結果：

• 判定を1行で記載 — VERDICT: approve または VERDICT: revise を、そのまま単独の行に記載します。
• 指摘事項 — revise の場合、ブロック要因となる不備ごとに、実施可能な指摘を1件ずつ記載します（未達条件＋場所＋修正方法）。approve の場合、ブロック要因とならない注記は任意です。

抽象的なコンシューマーとは、生成→レビューのループをオーケストレーションするものを指します。approve はシステムを次のフェーズ（ワイヤーフレーム／ハイファイ／UI エンジニアリング）へ進めることを承認します。revise は、範囲を限定した修正パスに向けて指摘事項を返します。

関連項目

• authoring-design-system — 生成を担います。このレビューが評価する基準に沿って作成します。組み合わせることで、基準の単一の情報源を共有できます。
• wireframe-review スキル — 画面ごとのレイアウトを審査するゲート（1つ下のレイヤー）です。
• user-flow-review スキル — ナビゲーションパスを審査するゲートです。
• design-review スキル — エンジニアリング設計ドキュメントを審査するゲートです。
• design-system template / content-template ツール — セクションの構造を担います。こちらは基準に照らした品質を評価します。

段階的な開示

• references/buildability-bar.md — 条件ごとの合格／不備のシグナル、指摘事項の作成例、差分レビューのチェック項目を含む詳細な条件です。
• references/sources.md — この手法と、authoring-design-system の関連スキルと共有する単一の情報源となる基準の、調査の出典です。

本文の上限

• description は1,024文字以下（agentskills.io の上限）。
• 本文は約500行／5,000トークン以下。
• 参照ファイルごとに、10,000トークンを超えたら警告、25,000トークンを超えたらエラー。参照ファイル全体では、25,000トークンを超えたら警告、50,000トークンを超えたらエラー。