design-review

Name: design-review
Author: shiplightai

github.com/shiplightaiデザイン・UI2418 回インストール16 週間前に更新

リポジトリ

design-review について

design-reviewは、デザインとアクセシビリティの基準に沿ってアプリの視覚品質と使いやすさを評価するスキルです。ブラウザー検証、根拠付きレポート、修正テストの作成を案内します。

主な機能

01ブレークポイントごとのレスポンシブ確認
02WCAGアクセシビリティ検査
03視覚的一貫性とタイポグラフィのレビュー
04国際化への対応状況の確認
05根拠と信頼度を含むレポート
06修正案とYAML回帰テスト

活用シーン

01リリースやデモ前のUIレビュー
02WCAG 2.1 AAに基づくアクセシビリティ確認
03デザイン刷新後のレスポンシブ評価

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/shiplightai/agent-skills --skill design-review

インストール後、Claude Code で/design-reviewを入力して読み込まれたか確認します。

詳細

デザインレビュー

確立されたデザイン基準に照らして、アプリケーションの視覚的な品質と使いやすさを評価します。このレビューでは、レスポンシブのブレークポイント、アクセシビリティへの準拠、視覚的な階層、余白の一貫性、国際化への対応状況など、通常は経験豊富なデザイナーの目が必要となる問題を見つけます。

使用するタイミング

次の場合に /design-review を使用します。

デザイナーのレビューを受けずに UI をリリースするとき
リリースやデモの前
大幅な UI の変更や再設計の後
アクセシビリティへの準拠状況を確認するとき（WCAG 2.1 AA）
デバイスごとのレスポンシブ動作を検証するとき

参照する基準

WCAG 2.1 Level AA — ウェブコンテンツ・アクセシビリティ・ガイドライン
Material Design / Human Interface Guidelines — 余白、タッチターゲット、タイポグラフィの尺度
ISO 9241-110 — インタラクションの原則（適合性、自己記述性、規約への適合）
APCA — 高度知覚コントラストアルゴリズム（次世代のコントラスト評価）

フェーズの概要

Phase 1: EDUCATE   → Brief context on what we check and why
Phase 2: SCOPE     → Identify pages, breakpoints, and focus areas
Phase 3: ANALYZE   → Browser-based checks with evidence capture
Phase 4: REPORT    → Findings with screenshots, scores, confidence
Phase 5: REMEDIATE → Fix guidance + YAML regression tests

フェーズ 1：基礎知識の共有

重要な理由： 第一印象の 94% はデザインに関係しています。視覚的な品質が低いと、機能が正しくても信頼が損なわれます。アクセシビリティの問題はユーザーの 15～20% に影響し、法的リスクも伴います（ADA 訴訟は 2018 年以降 300% 増加しています）。

このレビューでは、主観的な好みではなく、客観的で測定可能なデザイン基準に照らしてアプリを確認します。検出した問題には、いずれも具体的な基準を示します。

フェーズ 2：対象範囲

コンテキストを収集する

自動検出 — プロジェクトをスキャンして、以下を確認します。
- フレームワーク（React、Vue、Next.js など）
- CSS の手法（Tailwind、CSS modules、styled-components など）
- 使用中のデザインシステム（あれば）
- ルート構成 → ページの一覧
- 既存の a11y ツール（eslint-plugin-jsx-a11y、axe-core など）
ユーザーに質問する（自動検出したデフォルト値を使い、一度に 1 つずつ質問します）。
- 対象 URL：アプリはどこで動作していますか？（開発サーバーを自動検出）
- 主要なページ：どのページが最も重要ですか？（ルートから上位 3～5 件を推奨）
- 対象デバイス：デスクトップのみですか？モバイルファーストですか？両方ですか？（デフォルト：両方）
- ブランドガイドライン：特定の色、フォント、デザインシステムはありますか？（デフォルト：一般的なベストプラクティスに照らして評価）
- 重点項目：把握している懸念事項はありますか？（任意）
テストするブレークポイントを定義します。
- モバイル：375px（iPhone SE）、390px（iPhone 14）
- タブレット：768px（iPad）
- デスクトップ：1280px、1920px
- （ユーザーの対象者に応じて調整）

フェーズ 3：分析

record_evidence: true を指定して new_session でブラウザーセッションを開始します。対象範囲内の各ページで、次のチェック項目を実行します。

カテゴリ A：レスポンシブデザイン（RES）

チェック ID	チェック項目	基準	方法
RES-01	Viewport の meta タグがある	モバイルのベストプラクティス	`<meta name="viewport">` を確認する
RES-02	いずれのブレークポイントでも横方向にはみ出さない	レスポンシブデザイン	ビューポートのサイズを変更し、横スクロールバーがないか確認する
RES-03	モバイルでのタッチターゲットが 48x48px 以上	WCAG 2.5.8 / Material Design	モバイルのブレークポイントでインタラクティブ要素のサイズを測定する
RES-04	375px で拡大しなくてもテキストを読める	WCAG 1.4.4	モバイルで本文のフォントサイズが 16px 以上か確認する
RES-05	すべてのブレークポイントでナビゲーションを利用できる	使いやすさ	ナビゲーションが折りたたまれる、またはレイアウトに適応すること、ハンバーガーメニューが動作することを確認する
RES-06	画像が適切に拡大・縮小される	レスポンシブ画像	`srcset`/`sizes` または CSS によるコンテインメントを確認する
RES-07	明示なくコンテンツが切り詰められない	使いやすさ	テキストのオーバーフローや、ツールチップまたは展開機能のある省略表示を確認する
RES-08	モバイルでフォーム入力を使用できる	使いやすさ	入力欄のサイズと適切な入力タイプ（tel、email）を確認する

ブラウザーでの検証： 各ブレークポイントで act を使ってビューポートのサイズを変更し、inspect_page で DOM とスクリーンショットを取得します。オーバーフローしている要素がないか確認し、JavaScript でサイズを測定します。

カテゴリ B：アクセシビリティ（A11Y）

チェック ID	チェック項目	標準	方法
A11Y-01	色のコントラスト比が 4.5:1 以上（通常のテキスト）	WCAG 1.4.3 AA	計算済みの色を抽出し、比率を計算
A11Y-02	色のコントラスト比が 3:1 以上（大きなテキスト ≥ 18pt）	WCAG 1.4.3 AA	大きなテキストについて上記と同様に確認
A11Y-03	すべての画像に代替テキストがある	WCAG 1.1.1	`<img>` 要素に `alt` 属性があるか確認
A11Y-04	フォーム入力に対応するラベルがある	WCAG 1.3.1	`<label for="">` または `aria-label` を確認
A11Y-05	見出しの階層が論理的である（h1→h2→h3）	WCAG 1.3.1	見出しレベルを抽出し、順序を確認
A11Y-06	すべてのインタラクティブ要素でフォーカスが見える	WCAG 2.4.7	要素を Tab キーで移動し、フォーカスリングが見えるか確認
A11Y-07	キーボード操作が機能する（Tab、Enter、Escape）	WCAG 2.1.1	キーボードのみでページ全体を移動
A11Y-08	ナビゲーションをスキップするリンクがある	WCAG 2.4.1	コンテンツへのスキップリンクがあるか確認
A11Y-09	ARIA ロールが正しく使用されている	WCAG 4.1.2	ARIA の誤用や冗長な使用がないか確認
A11Y-10	ページに lang 属性がある	WCAG 3.1.1	`<html lang="">` を確認
A11Y-11	モーダルのフォーカストラップが機能する	WCAG 2.4.3	モーダルを開き、Tab キーの移動がモーダル内にとどまることを確認
A11Y-12	エラーメッセージが入力欄に関連付けられている	WCAG 3.3.1	`aria-describedby` または `aria-errormessage` を確認
A11Y-13	動きを減らす設定が尊重される	WCAG 2.3.3	`prefers-reduced-motion` メディアクエリーを確認
A11Y-14	発作を誘発するコンテンツがない（1 秒あたり 3 回を超える点滅）	WCAG 2.3.1	アニメーションを目視で確認

ブラウザー検証： inspect_page を使って DOM を抽出します。act 経由で JavaScript を実行し、コントラスト比の計算、ARIA 属性の確認、見出し階層の抽出を行います。キーボード操作（Tab、Enter、Escape）でフォーカス管理をテストします。

カテゴリ C：視覚的一貫性（VIS）

チェック ID	チェック項目	標準	方法
VIS-01	余白のスケールが一貫している	デザインシステム	マージンとパディングを抽出し、一貫したスケール（4px／8px グリッド）か確認
VIS-02	タイポグラフィのスケールが一貫している	タイポグラフィの階層	フォントサイズを抽出し、一貫した比率／スケールか確認
VIS-03	カラーパレットが限定され、意図的に選ばれている	デザインのベストプラクティス	使用されている色をすべて抽出し、グレー以外の色が 10 色を超える場合に警告
VIS-04	インタラクティブ要素のスタイルが一貫している	一貫性	ページ間でボタンとリンクのスタイルを比較
VIS-05	配置グリッドが一貫している	レイアウト	視覚的なグリッドを崩す位置ずれした要素がないか確認
VIS-06	非同期操作にローディング状態がある	UX のベストプラクティス	非同期アクションを実行し、ローディングインジケーターを確認
VIS-07	空の状態が適切に処理されている	UX のベストプラクティス	データのないページに移動し、意味のある空の状態が表示されるか確認
VIS-08	エラー状態のスタイルが一貫している	UX のベストプラクティス	検証エラーを発生させ、スタイルを確認
VIS-09	ダークモードの一貫性（該当する場合）	デザインシステム	ダークモードに切り替え、テーマが適用されていない要素がないか確認

ブラウザー検証： JavaScript を使って計算済みスタイルを抽出し、要素間およびページ間で比較します。ページ間のスクリーンショットを比較し、視覚的一貫性を確認します。

カテゴリ D：タイポグラフィと読みやすさ（TYP）

チェック ID	チェック項目	標準	方法
TYP-01	本文テキストが 16～20px	可読性に関する研究	計算済みの font-size を抽出
TYP-02	本文テキストの行の高さが 1.4～1.6	可読性	計算済みの line-height を抽出
TYP-03	1 行の長さが 45～75 文字	可読性（Bringhurst）	1 行あたりの文字数を計測
TYP-04	フォントの読み込み戦略（FOUT／FOIT の防止）	ウェブパフォーマンス	font-display CSS とプリロードヒントを確認
TYP-05	十分な階層レベルがある（異なるサイズが 3 種類以上）	タイポグラフィ	異なる見出しサイズを抽出して数える
TYP-06	本文テキストが左揃えである（両端揃えではない）	可読性	本文の段落の text-align を確認

カテゴリ E：国際化への対応（I18N）

チェック ID	チェック項目	標準	方法
I18N-01	コンポーネントにハードコードされた文字列がない	i18n のベストプラクティス	ソースコードをスキャンし、JSX／テンプレート内の文字列リテラルを確認する
I18N-02	レイアウトがテキストの拡張（+30%）に対応している	i18n の設計	より長いテキスト文字列を挿入し、はみ出しがないか確認する
I18N-03	RTL レイアウトに対応している（該当する場合）	i18n	`dir="rtl"` に切り替え、レイアウトの適応を確認する
I18N-04	日付／数値の書式設定でロケールを使用している	i18n	日付／数値の書式がハードコードされていないか確認する
I18N-05	フォントスタックに CJK／Unicode のフォールバックが含まれている	i18n のタイポグラフィ	font-family の宣言を確認する
I18N-06	アイコン／画像にテキストが含まれていない	i18n	画像の内容を目視で確認する

ブラウザーでの検証： JavaScript を使用して dir 属性を変更し、より長いテキストを挿入して、ロケール設定を変更します。各状態でスクリーンショットを撮影します。

フェーズ 4：レポート

構造化されたレポートを shiplight/reports/design-review-{date}.md に保存します。

# Design Review Report
**Date:** {date}
**URL:** {url}
**Pages reviewed:** {list}
**Breakpoints tested:** {list}

## Overall Score: {X}/10 | Confidence: {X}%

## Score Breakdown
| Category | Score | Findings |
|----------|-------|----------|
| Responsive (RES) | 7/10 | 2 high, 1 medium |
| Accessibility (A11Y) | 5/10 | 1 critical, 3 high |
| Visual Consistency (VIS) | 8/10 | 1 medium |
| Typography (TYP) | 9/10 | 1 low |
| i18n Readiness (I18N) | 6/10 | 2 medium |

## Findings

### CRITICAL

#### A11Y-01: Insufficient color contrast on primary buttons
- **Standard:** WCAG 1.4.3 AA (minimum 4.5:1)
- **Finding:** Primary button (#4A90D2 on #FFFFFF) has contrast ratio 3.1:1
- **Evidence:** [screenshot with annotation]
- **Pages affected:** All pages with primary CTA
- **Confidence:** 97%

### HIGH
...

### MEDIUM
...

### LOW / INFO
...

信頼度スコア

90-100%：ブラウザーで検証済みで、プログラムによる測定済み（コントラスト比を計算し、要素のサイズを測定）
70-89%：DOM の検査で強い根拠があり、スクリーンショットが指摘事項を裏付けている
50-69%：ヒューリスティックに基づいており、状況によって異なる可能性がある（例：「間隔に一貫性がないように見える」）
50% 未満：報告しない

フェーズ 5：修正

各指摘事項について、以下を提示します。

1. 修正の指針

#### A11Y-01: Insufficient color contrast
**File:** src/components/Button.tsx:23
**Current:** `background: #4A90D2` (contrast 3.1:1 against white)
**Fix:** `background: #2563EB` (contrast 4.8:1 against white) — maintains blue hue, meets AA
**Alternative:** `background: #1D4ED8` (contrast 7.1:1) — meets AAA

2. YAML 回帰テスト

- name: a11y-01-button-contrast
  description: Verify primary button meets WCAG AA contrast ratio
  severity: critical
  standard: WCAG-1.4.3-AA
  steps:
    - URL: /
    - VERIFY: Primary action buttons have sufficient color contrast (minimum 4.5:1 ratio for normal text)
      timeout_seconds: 15

すべての YAML テストを shiplight/tests/design-review.test.yaml に保存します。

ヒント

まず inspect_page を使って DOM を読み取ります。スクリーンショットより低コストで、act に使える要素インデックスも確認できます。
コントラストを確認するには、act 経由で JavaScript の window.getComputedStyle() を使用し、実際にレンダリングされた色を抽出します。
act でキーボード操作（Tab、Enter、Escape、矢印キー）を行い、キーボードナビゲーションをテストします。
このレビューは複数のブレークポイントで実施します。特定のビューポートサイズでしか現れない問題も多くあります。
i18n のテキスト拡張をテストするには、act で JavaScript を使用し、textContent をより長い文字列に変更します。
close_session でセッションを閉じ、generate_html_report を使って共有可能なエビデンスレポートを作成します。

Markdown 対応

ログインしてコメント

基本情報

作者: shiplightai
リポジトリ: shiplightai/agent-skills
カテゴリ: デザイン・UI
インストール数: 418
GitHub スター: 2

問題を報告