qc-uiux

スキル：qc-uiux

内容

目的とコンテキスト

• 目的： 既存のルート／画面について、シニアレベルの評価を提示します。4項目（アクセシビリティ・視覚的階層・一貫性・アンチパターン）それぞれについて、10点満点のスコア、最も重大な問題、修正方法を示します。測定可能な項目は決定論的エンジンで測定し、目視が必要な項目はLLMが監査します。
• トリガー（使用するタイミング）：
  • UIを新規作成または変更した直後（モックアップ /br、新しいページ、コンポーネントなど）に、確定前にシニアの視点で確認したいとき。
  • UIに大きな変更を加えるコミットの前。verify-before-commit の前に /orca-workflow へ任意のステップとして組み込み、UIを含む各 /br run フレームの後に自動実行します。
  • ユーザーが「qc uiux」「audit ui」「soi giao diện」「dẹp antipattern ui」「/qc-uiux」と言ったとき。
• 対象外： 次の場合は使用しません。全体的なデザインの刷新（それには /redesign-existing-projects を使用）、またはピクセル比較だけを目的とした撮影（それには /visual-qa を使用します。qc-uiux は測定エンジンとしてこれを呼び出します）。コードのレビュー（それには /qc-code を使用）。評価結果はコミットをブロックしません。

メンタルモデル

route/画面 → 決定論的エンジン（DESIGN_AUDIT が実際の rect を測定）＝事実 → 4項目 ×（10点満点のスコア・最も重大な問題・修正方法）＝数値を根拠とする意見 → 評価結果 PASS | 要修正（最も弱い項目／ルートに基づく）→ 修正 → エンジンを再実行（赤→緑）。コストの高い処理（LLM、手動実行）と低い処理（エンジン、自動フック）を分離します。

入力と出力の契約

	Field	Required?	意味
In	route/画面	いいえ（デフォルト＝既存のモックアップ／ルート）	ユーザーが指定した場合は、それを確認します
In	実行可能な <base-url>	測定には必須	headless エンジンにはサーバーが必要です。起動できない場合は fail-open になります
In	ルートの種類（list/table?）	自動判定	該当する場合は references/list-control-checklist.md を読み込みます
Out	4項目 × 10点満点のスコア・最も重大な問題・修正方法	必須	項目3には drift の表を付けます。測定可能な問題がある項目には、エンジンの数値を根拠として示します
Out	評価結果	必須	PASS または CẦN SỬA ＋修正必須項目の一覧 — ADVISORY
Out	下書き llmwiki/wiki/sources/draft/DDMMYY-qc-uiux-<route>.md ＋ index ＋ log	必須（エンジンのみの実行を除く）	Output Report 項目を参照

ルールと機能

• RULE-01（必須）：高コスト／低コストを分離： LLM監査（4項目）は手動呼び出し、または任意のワークフローステップで実行します。決定論的測定は visual-qa エンジンを介して自動実行します。フック内でLLMを呼び出してはいけません（hook-0-token 原則）。
• RULE-02（必須）：評価結果は助言、エンジン測定はハードゲート — LLMの評価結果でコミットをブロックしてはいけません。測定値（contrast/tap-target/geometry）を事実として扱います。
• RULE-03（必須）：CSSを読むだけでは幾何情報は分からない — レイアウト／サイズ／コントラストに関する判断はすべて、静的なCSSから推測せず、エンジンを介して実際の rect を測定します。
• RULE-04（必須）：役割を重複させない： /redesign-existing-projects ＝デザイン刷新、/visual-qa ＝撮影＋ピクセル差分によるゲート、/qc-code ＝コードレビュー。/qc-uiux ＝UI/UXの4項目に対するシニア評価＋測定エンジンの再利用。
• RULE-05（必須）：見た目より機能を優先し、スコアを平均しない（browser-use の qa スキルから学習、09/2026）： 確認対象のルート／フローにユーザー操作（送信、チェックアウト、ログインなど）があり、その操作を完了できない場合、4項目のスコアが高くても評価結果は CẦN SỬA とします。見た目が良くても、壊れたフローは救えません。 全体の評価結果は最も弱い項目／ルートに基づいて判断し、平均点は取りません。
• RULE-06（必須）：きれいなスクリーンショットは何も証明しない — エンジンを headless で実行するときは、隠れた問題も調べます。console の error、pageerror、>= 400 の response、requestfailed（/playwright-verify の Rules を参照）。 ページの見た目が良くても、クリックするたびにエラーが発生する場合は、項目4に記録し、PASS にしてはいけません。
• RULE-07（必須）：a11yは好みではなくルール — CLAUDE.md の例外規定により、contrast/tap-target/label の確認を怠ってはいけません。WCAGの自動検査で確認できるのは約30%にすぎません。残りは「人の目による確認が必要／負債 [[150726-unknown-ledger]]」と明記します。
• 機能：headless ブラウザーでページを実行し、DOM/rect/contrast を測定（0-token）します。CSS/DOM を読み取り、wiki の下書きを記録します。監査中にUIを変更してはいけません。

失敗境界

• サーバー／ヘッドレスを起動できない → エンジンはフェイルオープン（ブロックしない）で動作します。LLM 監査は引き続き実行しますが、測定できる項目には数値がないことを記録する必要があります。
• ルート上のユーザータスクを完了できない → 4項目のスコアにかかわらず、判定は CẦN SỬA です。
• Console の error／pageerror／response >= 400／requestfailed → 4項目に記録し、PASS にしません。
• WCAG の自動化できない基準 → 「人の目による確認が必要／負債 [[150726-unknown-ledger]]」と明記し、PASS にしません。

方法

メインワークフロー

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W00	判断	route	route はリスト／テーブルか？ → references/list-control-checklist.md を読み込む	追加チェックリスト	いいえ → スキップ
W01	決定論的	route, <base-url>	対象範囲を特定し、最初にエンジン route-shots.mjs --audit を実行	route ごとの issues	起動できない → フェイルオープン、注記
W02	判断	issues + DOM	4項目を採点：スコア/10 · 最も重大な問題 · 修正方法	4項目すべてに3要素	—
W03	決定論的	issues engine	測定可能な問題がある項目にエンジンのデータを付与	出典付き測定値	—
W04	判断	4項目	PASS / CẦN SỬA を判定（項目／route の最も低い評価に基づく）	判定 + 要修正項目	—
W05	決定論的	修正済み UI	エンジンを再実行し、測定可能な問題がすべて解消したことを証明（赤→緑）	エンジンが緑	赤が残る → 依然として CẦN SỬA
W06	効果	結果	Output Report のドラフト + index + log を記録	ドラフト	エンジン実行のみ → スキップ

各ステップの詳細（W00～W06 の信頼できる情報源）：

監査範囲（デフォルト = 既存のモックアップ／route）

デフォルトでは既存の UI、つまり直近で作成したモックアップの route／ページを確認します。ユーザーが route／画面を指定した場合は、そこを確認します。エンジンで DOM を読み取り、実際の rect（getBoundingClientRect）を測定します。静的な CSS から推測してはいけません（CSS を読むだけではレンダリングの不具合を見落とします。15/07/26 の教訓）。

手順

0. route はリスト／テーブルか？（queue、admin grid、ticket/request list、dashboard summary strip）→ references/list-control-checklist.md も読み込みます。リスト／テーブル特有のよくある問題が11項目あります（row 上の配色の重なり、sort bucket、popover の overflow-clip、mobile filter の折りたたみなど）。各問題には、以下の4項目のどれに該当するかがあらかじめ紐づけられています。
1. 対象範囲を特定 — どの route／画面か。まず決定論的エンジンを実行して、測定可能なデータを取得します（下記「エンジン」項目）。
2. 4項目を採点（下記の項目）。各項目：スコア/10 · 最も重大な問題 · 修正方法。→ 4項目すべてに3要素が揃ったら完了です。
3. 測定可能な問題がある項目：エンジンのデータを付与（コントラストの不合格箇所、24px 未満のコントロール、重なっている要素の組み合わせなど）。→ 測定値はデータ、判定は意見です。
4. 結論 — PASS（次のステップへ）か CẦN SỬA（修正が必要な項目を列挙）を判定します。→ 判定が明確で、CẦN SỬA の場合は要修正項目の一覧ができたら完了です。
5. 修正後にエンジンを再実行して、測定可能な問題が解消したこと（赤→緑）を証明します。qc-code の再現テストと同様です。

4項目

1. アクセシビリティ（a11y）— スコア/10 · 最も重大な問題 · 修正方法

確認項目（大部分は測定可能 — エンジンで検出可能）：コントラスト（通常テキスト ≥4.5:1、大きな文字 ≥3:1、コントロール／枠線／アイコン ≥3:1 — WCAG 2.2 AA） · タップターゲット（インタラクティブなコントロール ≥24×24px CSS は AA 2.5.8 の最低基準。mobile では 44/48px を推奨） · フォーカス表示（明確なフォーカスリングがあり、コントラスト ≥3:1） · ラベル不足（スクリーンリーダーで読み上げると空になるボタン／アイコン／リンク — aria-label/text が不足）。これはアクセシビリティの境界です。手を抜いてはいけません（a11y は好みではなく、法律です）。注意：WCAG の基準のうち自動化できるのは約30%にすぎません → 残り（キーボードトラップ、フォーカス順序、意味のある alt）は人の目による確認が必要です。

2. 視覚的階層 — 点数/10 · 最も重大な問題 · 修正方法

測定可能なルール（engine fdk/tools/html-visual-gate.mjs、PLAN 220926 — user 22/09/2026）。この項目をLLMが採点する前に実行します：

• heading-scale（FAIL）：存在する見出しレベルは大きい順（h1 > h2 > h3 > h4）で、本文より小さくしてはいけません。
• title-scale（FAIL）：ページ名（ブランド／ロゴ／h1）は、ナビゲーション項目とコンテンツ選択タブの最大文字サイズの1.2倍以上にします。
• sentence-case（FAIL）：見出し、ラベル、ボタン、タブ、ナビゲーション項目は、先頭文字を大文字にします（数字／-_./:@を含む識別子、固有名詞、コード内の文字は除外します。data-case="keep"で意図的に小文字にする指定は維持します）。
• eye-rest（WARN）：目を休める余白が必要です。最初の画面は文字／ブロックが55%以下で、余白が24px以上ない520pxを超える密な帯があってはいけません。これはフレームワークのヒューリスティックなしきい値です。一つの画面に同等の要素を詰め込みすぎる（ステータス表示6個＋チップ3個＋ボタン3個を一つのバーに並べるなど）のは、個々の要素が正しくても問題です。まとめて、詳細はクリックしたときに表示します（NN/g progressive disclosure）。
• kanban-uniform（FAIL）：カンバンボード（2列以上のlane|kanban|[data-kanban-lane]）では、すべてのカードの幅と高さ（±2px）、スタイル（背景・枠線・角丸・パディング・フォント）を統一します。カードのサイズを固定し、クリックすると詳細を表示します。
• ボタンの調和（専用エンジンfdk/tools/button-harmony.mjs、user 24/09/2026 — 1440と390の両方で実行し、rc 0の場合のみPASSとして採点します）：lone-action（FAIL）一行に単独で配置されたボタンが行末のボタンではなく、行幅の50%を超えて離れている場合。補助ボタンは、それが機能する見出し／入力欄と同じ行に配置します。edge-gap（FAIL）右端に揃えた行で、最後の要素が端から8pxを超えて離れている場合。empty-occupant（FAIL）横並びの行で、48pxを超える不可視の空要素がスペースを占めている場合（flex:1のスペーサー要素は除外します）。mixed-edge（WARN）同じブロック内のボタン行の終端位置が揃っていない場合。右下を優先するaction-leftのルールは引き続き有効です。調和は追加の条件であり、このルールに取って代わるものではありません。ログインが必要なページでは、描画済みDOMをファイルに保存し、アプリケーションスクリプトを削除してから、そのファイルに対して実行します。
• **比較基準：**監査対象の各UI要素には、サンプルページskills/hallmark/references/design-showcase.html（クライアント：~/.claude/skills/hallmark/references/design-showcase.html）に同種のブロックがあります。python3 fdk/tools/build-design-showcase.py --get <id>（クライアント：python3 ~/.claude/harness/fdk/tools/build-design-showcase.py --get <id>。--listはインデックスを出力します）でブロックを取得し、各項目（サイズ、状態、色トークン、モーション）を比較します。差異についてページに免除の記載がなければ問題とし、「修正方法」に基準ブロックのidを明記します。
• 特別な要件は、ページ側で明示します：<meta name="overstack-exempt" content="heading-scale,…" data-reason="…"> — 監査では理由を確認し、自動的に免除してはいけません。

確認項目（LLMの目視）：ボタンはボタンらしく、リンクはリンクらしく、見出しはサイズで明確に階層化されていること（ユーザーにインターフェースを「解読」させる必要がある場合はfail） · CTAが明確であること（主なアクションが目立ち、曖昧でないこと） · コンテンツ密度（一つの画面に詰め込みすぎていないこと。過密だと階層が失われます）。最初に視線が止まる場所と、それが本当に主なアクションなのかを指摘します。

3. 一貫性（design-system）— 点数/10 · 最も重大な問題 · 差異の表

確認項目（LLMの目視、一部は測定可能）：トークンに沿ったスペーシング（4/8pxのスケール — gapが不規則だとリズムが崩れます） · 一貫した色使い（衝突・混在するカラーパレットがないこと） · シャドウ（過剰な使用や深さの誤りがないこと — エンジンがshadow-clipped／monochrome-surfaceを検出します） · タイポグラフィ（フォントとサイズの組み合わせが一貫していること） · ページ間の統一性（同じものはすべての画面で同じスタイルにすること）。差異の表を出します：

箇所	基準との差異	修正後
card padding	14px / 20px / 17pxが混在	token --sp-4（16px）

4. アンチパターンとインタラクション — 点数/10 · 最も重大な問題 · 測定値による証拠

確認項目：ダークモードでの読みやすさ（文字が白っぽすぎる／暗すぎる — ダークモードでよくある問題。エンジンは暗色テーマでcontrast-aaにより検出します） · 崩れたレイアウト（4px以上の重なり、row-misalign — コントロールが重なっている／高さが揃っていない状態。エンジンがrectを測定します） · フィードバック不足（操作に対するシステムの応答がない） · レスポンシブ表示の崩れ（狭い画面での横方向へのはみ出しや重なり） · ダークパターン（強制、選択肢への誘導、離脱の困難さ）。測定可能な問題ごとに、エンジンの数値を示します（route、要素のペア、重なりのpx数）。

結論（判定）

次のいずれかを、理由とともに示します。

• PASS — 重大な問題はなく、測定可能な a11y 項目も問題ありません。次のステップに進めます。
• 要修正 — 修正すべき内容を具体的に列挙します（測定可能な a11y と崩れたレイアウトを、階層や一貫性より優先します）。

判定はあくまで参考情報です。最終判断は人が行い、コミットをブロックしません。 厳格にブロックするのは、決定論的エンジン（コントラスト／タップターゲット／重なり／位置ずれが赤から緑になること）です。「qc-uiux PASS = UI が完璧」とユーザーに思わせないでください。これはシニアの目によるレビューであり、証明ではありません。

決定論的エンジン（0トークン、LLM 不使用）— visual-qa を再利用

測定可能な部分では /visual-qa のエンジン（skills/visual-qa/assets/route-shots.mjs、headless playwright）を共用します。DESIGN_AUDIT 関数がページ内の実際の矩形を測定し、次のルールを検出します：contrast-aa · tap-target · missing-label · overlap · row-misalign · shadow-clipped · monochrome-surface · rogue-slab。実行方法：

node skills/visual-qa/assets/route-shots.mjs <base-url> --audit    # in issues theo route; exit ≠0 nếu a11y/hình học fail

これは「UI が変更されたときの自動フック」にあたる部分です。フックするのは低コストで決定論的な部分だけです。LLM による監査（このスキル、4 項目）は手動で呼び出します。サーバー／headless を起動できない場合は fail-open（ブロックしない）になります。qc-code の qc-regression.py --run と同様に、verify-before-commit のステップ 3b から呼び出します。UI の変更後に、測定可能なアンチパターンがいつの間にか再発することを防ぎます。

分岐

ID	種類	条件	動作	スキップ／失敗	合流先
B01	conditional_required	route が list/table（queue、admin grid、ticket/request list、dashboard summary strip）の場合	references/list-control-checklist.md を読み込み、11 個の問題を 4 項目にあらかじめ割り当てます	該当しない route → スキップ	W01
B02	recovery	server/headless を起動できない場合	エンジンは fail-open（ブロックしない）。LLM による監査を続行し、測定可能な項目は数値を取得できなかったと記録します	—	W02
B03	conditional_required	ユーザーの操作（submit、checkout、ログイン）がある route で、それを完了できない場合	4 項目のスコアにかかわらず、判定は 要修正	—	W04

検証と停止条件

測定可能な部分（contrast、tap-target、overlap、misalign、missing-label など）は決定論的エンジンが判定し、失敗時は exit ≠0 になります。階層／ドリフト／ダークパターンは LLM によるレビューで、判定はあくまで参考情報です。4 項目それぞれに 3 つのパートが揃い、判定が明確になったら終了します。修正後は、エンジンが成功する必要があります（W05）。

例

• 成功例： /br run の後に /qc-uiux でサインアップフォームのフレームを確認 → エンジンに問題なし、4 項目は 8〜9/10、項目 3 の最も重大な問題は card の padding が 14/20/17px → ドリフト表を --sp-4 に統一 → 判定は PASS、draft は DDMMYY-qc-uiux-signup.md。
• 境界例／失敗例： ダークモードで補助テキストのコントラストが 2.8:1、アイコンボタンが 20×20px → エンジンの contrast-aa と tap-target が数値付きで失敗 → 項目 1 に最も重大な問題と修正方法を記載 → 要修正。修正後にエンジンを再実行し、成功する必要があります。
• 境界例： ページの見た目はよく、4 項目のスコアも高いが、submit ボタンで pageerror が発生 → 項目 4 にエラーを記載し、判定は 要修正。

参考 — 関連項目

• references/list-control-checklist.md — list/table 固有の 11 個の問題（Steps のステップ 0 で確認）。
• skills/visual-qa/assets/route-shots.mjs — このスキルが再利用する決定論的測定エンジン（DESIGN_AUDIT）。
• llmwiki/skills/dev-loop/qc-code.md — 関連スキル。CODE を対象に、LLM を使う高コストな処理と決定論的な低コスト処理を同じパターンで扱います。
• harness/scripts/qc-regression.py — verify-before-commit で実行される、決定論的な qc-* テスト（qc-code）の runner。
• llmwiki/skills/dev-loop/build-now-adapt-later.md — 高コスト／低コストを分離するパターンを通じて、quarantine を扱う方法。

成果物 — 出力レポート

監査後、draft llmwiki/wiki/sources/draft/DDMMYY-qc-uiux-<route>.md（OKF frontmatter の type: draft、## Origin）を作成し、確認した route、4 項目のスコア、エンジンで検出した測定可能な問題、判定と修正事項をまとめます。index.md と log.md に行を追加します。測定エンジンのみを実行し、新たな判断がない場合は省略します。