antislop-human

antislop-human

アンチスロップ：AI コーディングエージェントのためのルール。人間向けスキル

antislop システムの一部です。コアである antislop.md と一緒に読んでください。このスキルでは、人間に関わる課題を掘り下げます。つまり、さまざまな見え方や手の動かし方、環境の人が使える UI を維持することです。コントラスト、キーボード、フォーカス、状態、そして人を排除するモバイル特有の細部を扱います。

このスキルの使い方

• UI を作成または編集するタスクでは、必ず antislop.md と一緒に読み込んでください。コアには仕組み（目的の検証、3 つのティア、デリバリーゲート）が記載されており、このスキルでは人間側の詳細、つまりさまざまな見え方や手の動かし方、環境の人を排除する UI の部分を扱います。
• 各項目は同じ構成です。Tell（パターン）、Why（誰を排除するのか、なぜ未完成に見えるのか）、Fix（代わりにすべきこと）。適用されるコアのルールを R-XX として示します。
• アクセシビリティは、最後に付け足す追加チェックリストではありません。「UI が十分に機能する」（C-4）というコアの約束の一部です。コアのデリバリーゲートが引き続き判定基準となり、このファイル末尾の「人間向けスキルチェックリスト」はそれと並行して実行する補足です。
• コントラストチェッカー（数式、参照表、スクリプト）はこのスキルに含まれています。目視で検証できない色の組み合わせには必ず使用してください。
• このスキルで扱うモバイル特有の詳細は、人を排除するものに限ります。ズームとオンスクリーンキーボードです。

色とコントラスト

コントラストの低いテキスト

• Tell： 白または白に近い背景に薄いグレーのテキスト、細い本文テキスト、見た目が「上品」という理由で選ばれているものの読みにくい控えめなラベル。
• Why： 弱視のユーザーや、明るい場所にいるすべての人を排除します。これは基準を確認せずに選ばれた視覚的な表現であり、まさにこのフィルターが見つけるためにある既定の選択です。
• Fix： WCAG AA の最低基準（R-25）を満たしてください。通常のテキストは 4.5:1、大きなテキスト（18px 以上）は 3:1 です。比率を計算し、目視で判断しないでください。

写真やグラデーション上のテキスト

• Tell： 一部が明るい画像やグラデーションの上に白いテキストを直接配置し、明るい箇所を 1 か所だけ確認している。
• Why： コントラストは場所によって異なります。画像が明るい箇所では、ヒーロー部分が「問題なさそう」に見えても、テキストのコントラストは 4.5:1 を下回ります。R-25 では、1 か所だけではなく、テキストが重なる領域全体をテストする必要があります。
• Fix： テキストの背後にスクリーンまたは単色のブロックを追加し、最もコントラストが低い箇所を確認してください。最も高い箇所ではありません。テキスト領域の一部でも基準を満たさなければ、その表現は不適切です。

グレー同士のコントラストに関する誤認

• Tell： 計算せずに「黒の上の濃いグレー」や「白の上の薄いグレー」が AA に適合すると主張する。
• Why： これは最もよくあるアクセシビリティに関する誤認です。グレー同士の組み合わせでは、目がコントラストを過大評価します。また、エージェントはもっともらしく聞こえるため、同じ主張を繰り返します。黒の上の #555555 は 2.8:1 であり、基準を満たしません。
• Fix： 組み合わせが基準を満たすと断言しないでください。コントラストチェッカー（以下）を実行するか、数式を適用してください。どちらもできない場合は、参照表を使用してください。

テキスト以外のコントラスト

• Tell： インタラクティブコンポーネント（ボタン、アイコン、入力欄の境界線、フォーカスインジケーター、チャートのセグメント）が、背景とのコントラスト 3:1 未満で区別されている。
• Why： テキスト以外の UI は、形状や境界線によって情報を伝えます。境界線の色合いがごくわずかだと、弱視のユーザーはコントロールを見つけられません。ホバーや選択などの状態にも同じ基準が適用されます。
• Fix： すべてのコンポーネントの境界線とステータスインジケーターについて、隣接する色との比率を 3:1 にしてください（WCAG 1.4.11）。アイコンには、4.5:1 を満たすテキストラベルを組み合わせてください。

コントラストチェッカー

コントラストチェッカーの説明です。最も手軽な方法から順に、3つの方法があります。

スクリプト。 スクリプトを実行できる環境があり、ファイルが存在する場合は、手動で計算せずに実行してください。スクリプトはこのスキルのフォルダー内にあります（この SKILL.md と同じ場所にある contrast-check.py）。macOS と Linux では python3、Windows では python で実行します。

python3 "${CLAUDE_SKILL_DIR}/contrast-check.py" "#FFFFFF" "#777777"
# normal text: FAIL (4.48 < 4.5)
# large text:  PASS (4.48 >= 3.0)

このエージェントで ${CLAUDE_SKILL_DIR} 変数を利用できない場合は、スクリプトのパスにこのスキルのフォルダーを直接指定してください。このスクリプトは、エージェントが AA 判定をでっち上げないようにするためのものです。2つの16進カラーコードを受け取り、比率と両方のテキストサイズに対する判定を出力します。ファイルが見つからない場合は、以下の計算式と表だけで十分です。スクリプトの実行を必須にしないでください。

計算式（WCAG 2.x）。

1. コントラスト比 = (L1 + 0.05) / (L2 + 0.05)。L1 は相対輝度が高い方、L2 は低い方です。
2. 1色の相対輝度 L：各チャンネルを0〜1に変換し（c = hex / 255）、次に線形化します。c <= 0.03928 の場合は c_lin = c / 12.92、それ以外の場合は c_lin = ((c + 0.055) / 1.055)^2.4 です。
3. L = 0.2126*R + 0.7152*G + 0.0722*B。
4. 丸める前の比率を比較します。通常のテキストは4.5:1、大きなテキスト（R-25に基づき18px以上）は3:1です。表示用にのみ丸めてください。たとえば、4.498:1の組み合わせは4.50と表示されても、4.5:1の基準には不合格です。最大比率は21.0（白地に黒）です。

参考表（一般的な組み合わせを計算式で算出）：

組み合わせ（背景上のテキスト）	比率	通常のテキスト（4.5）	大きなテキスト（3.0）
白地に黒	21.00	合格	合格
黒地に白	21.00	合格	合格
#333333地に白	12.63	合格	合格
#666666地に白	5.74	合格	合格
白地に#777777	4.48	不合格	合格
#070707地に#777777	4.50	不合格	合格
#888888地に白	3.54	不合格	合格
#999999地に白	2.85	不合格	不合格
黒地に#555555	2.82	不合格	不合格

#777777 on #070707 の行はしきい値に近いケースです。4.4983:1は表示用に丸めると4.50になりますが、4.5:1の基準には不合格です。

この表は妥当性を確認する目安として使い、代用にはしないでください。表にない組み合わせや、しきい値に近いものは、計算式またはスクリプトで確認してください。

キーボード

フォーカスアウトラインの削除

• 確認箇所： 置き換えのフォーカススタイルがない outline: none または outline: 0。
• 理由： キーボードユーザーは現在の位置を確認できません。マウスなしではUIを使えなくする最も手っ取り早い方法であり、R-32でも明確に禁止されています。
• 修正： アウトラインを維持するか、同等のコントラスト基準（周囲に対して3:1）を満たす、視認可能な :focus-visible スタイルに置き換えてください。置き換えなしで outline: none を設定しないでください。

マウス専用のパターン

• 確認箇所： ホバー時にしか開かないメニュー、クリックで開くもののキーボードでは開けないドロップダウン、キーボードでの代替操作がないドラッグアンドドロップ。
• 理由： それぞれがキーボードユーザーや支援技術の利用者を締め出します（R-32）。Tab、Enter、Spaceで到達して操作できないコントロールは、ある人々にとって存在しないのと同じです。
• 修正： すべてのインタラクティブ要素にキーボードで到達して操作できるようにします（R-32）。視覚的な順序に沿った論理的なタブ順、EnterまたはSpaceによる有効化、Escapeで閉じられるダイアログを実装してください（R-26）。

タブ順序の不具合

• 確認箇所： DOMの順序が視覚的な順序と一致しないために、フォーカスがページ内を飛び回る、コンテンツを飛ばす、非表示要素に移動する。
• 理由： 視覚的な順序ではなくコードの順序で読み進めるタブ順序では、予測どおりに操作できません（R-32）。ユーザーは現在位置を見失い、ページが壊れているように感じます。
• 修正： ソースの順序を視覚的な順序と一致させ、長いページにはスキップリンクを追加してください。ダイアログのような制御されたフォーカストラップの一部でない限り、実際のコンテンツに tabindex="-1" を指定しないでください。

フォーカスと状態

フォーカスインジケーターが弱い、または見えない

• 見分け方： 背景と同じ色のフォーカスリング、ホバー時にしか表示されないリング、または1pxの境界線より細いインジケーターです。
• 理由： フォーカスインジケーターは、キーボードユーザーが現在の位置を把握するためのものです。コントラスト基準を満たさない場合や、ホバー時にしか表示されない場合、キーボードだけでの操作ができなくなります（R-32、R-34）。
• 修正方法： すべてのテーマで、すべてのインタラクティブ要素に視認できるフォーカスインジケーターを表示し、隣接する色とのコントラスト比を3:1にします。ダークモードとライトモードの両方で確認してください。

色だけによるフィードバック

• 見分け方： 成功、エラー、ステータスが色だけで伝えられています。たとえば、エラーを赤いテキスト、成功を緑の境界線、色付きのチップだけで示し、アイコン、ラベル、テキストがありません。
• 理由： 色覚に障害のあるユーザーや弱視のユーザーを排除し、強制カラーモードでは情報が完全に消えてしまいます。色相を見分けることに依存するステータスは、ステータスとは言えません（C-4）。
• 修正方法： 色によるすべての表示に、テキスト、アイコン、またはパターンを組み合わせます。エラー状態は、まずテキストで伝えます。「赤い境界線」だけでなく、「パスワードは8文字以上である必要があります」と表示します。

UI 状態の不足

• 見分け方： データビューに空、読み込み、エラーの状態がないか、状態があっても見えません。たとえば、テキストのないスピナーや、説明のない空画面です。
• 理由： R-27では3つの状態すべてが求められています。アクセシビリティの観点では、それぞれが装飾ではなく、知覚できて情報を伝えるものでなければなりません。状況説明のない読み込みスピナーは、スクリーンリーダーのユーザーにはページがフリーズしたように感じられます。
• 修正方法： すべてのデータビューに3つの状態を用意し（R-27）、それぞれを読み上げ可能、または視認可能にします。具体的には、明示的な空状態のメッセージ、テキスト付きの読み込み状態、何が起きたのかと次にどうすればよいかを伝えるエラー状態を用意します。

ズームとモバイルでの利用

モバイル表示のレイアウトの仕組み（ブレークポイント、拡大縮小、グリッド、オーバーフロー、タップ対象）は、antislop-layoutmobile の対象です。このセクションでは、ユーザーを排除するモバイル関連の詳細である、ズームとオンスクリーンキーボードのみを扱います。

ズームできないテキスト

• 見分け方： 固定ピクセルのフォントサイズが使われているか、overflow: hidden が指定されたコンテナーによって、ズーム率200％でテキストが切り取られます。
• 理由： ユーザーはテキストのサイズを変更できなければなりません（WCAG 1.4.4）。ズーム率を200％にしたときにコンテンツが切り取られたり、横スクロールを強いられたりするなら、実際にはテキストのサイズを変更できていません。
• 修正方法： ズームに応じてリフローする可変サイズの文字を使い、テキストを含むコンテナーでのクリッピングを避けます。狭いビューポートでズーム率を200％にしてもレイアウトが維持されることを確認してください（R-35）。

モバイルキーボードがフォームを覆う

• 見分け方： ビューポートの下部にある入力欄がオンスクリーンキーボードの背後に隠れ、画面内にスクロールして表示する仕組みも、入力欄のための余白もありません。
• 理由： ユーザーが見たり操作したりできないフォームは、完了できないフォームです。これはモバイルに特有の排除です（R-03）。
• 修正方法： 入力欄にフォーカスが当たったとき、キーボードより上に表示されるよう画面をスクロールし、フォーカス中のフィールドが隠れないだけの下部余白を確保します。実機またはエミュレートしたキーボードでテストしてください。

人のスキルのチェックリスト

タスクにUIが含まれる場合、コアのDelivery Gateと併せて実施します。すべての回答がはいでなければなりません。

• 画像やグラデーション上のテキストも含め、すべてのテキストと背景の組み合わせを、コントラストチェッカー（計算式、表、またはスクリプト）で検証していますか？（R-25）
• すべてのインタラクティブコンポーネントの境界とステータスインジケーターは、背景とのコントラスト比が3:1以上ですか？（非テキストのコントラスト）
• すべてのテーマで、すべてのインタラクティブ要素に、視認性が高くコントラストの強いフォーカスインジケーターが表示されていますか？（R-32、R-34）
• すべてのインタラクティブ要素にキーボードで移動して操作でき、ダイアログをEscapeキーで閉じられ、代替手段なしに outline: none を指定していませんか？（R-32、R-26）
• すべてのデータビューに空、読み込み、エラーの状態があり、色だけに頼らず知覚できるようになっていますか？（R-27、C-4）
• テキストを切り取らずに200％まで拡大でき、モバイルキーボードがフォーカス中の入力欄を覆うことはありませんか？（R-35）