antislop-human

antislop-human

Anti Slop：AI 编码 Agent 规则。人类技能

属于 antislop 系统的一部分。请与 antislop.md（核心规则）一起阅读。本技能深入探讨与人有关的问题：UI 必须适用于视力、操作能力和使用环境各不相同的人。对比度、键盘、焦点、状态，以及那些会排斥用户的移动端细节。

如何使用本技能

• 每当任务涉及构建或编辑 UI 时，都要与 antislop.md 一起加载。核心规则涵盖机制（用途测试、三个层级、交付门槛）；本技能则深入探讨与人有关的部分：UI 中会排斥视力、操作能力和使用环境各不相同的人的细节。
• 每个条目都采用相同的结构：说明（模式）、原因（会排斥哪些人，以及为何显得未完成）、修复（应如何处理），并注明对应的核心规则 R-XX。
• 无障碍不是最后附加的一份额外检查清单，而是“UI 经得起检验”（C-4）这一核心承诺的一部分。核心规则中的交付门槛仍然是关卡；本文件末尾的“人类技能检查清单”是与其配套使用的补充内容。
• 对于无法凭肉眼确认的颜色搭配，请使用本技能中的对比度检查器（公式 + 参考表 + 脚本）。
• 本技能只保留会排斥用户的移动端细节：缩放和屏幕键盘。

颜色与对比度

低对比度文本

• 说明： 白色或近白色背景上的浅灰色文本、细小的正文文本，以及因看起来“优雅”而选用却难以阅读的柔和标签。
• 原因： 这会排斥低视力用户，也会影响所有处于明亮环境中的人。这种视觉选择未经标准检查，恰恰是过滤器要捕捉的默认做法。
• 修复： 达到 WCAG AA 最低要求（R-25）：普通文本为 4.5:1，大号文本（18px+）为 3:1。请计算比率，不要凭肉眼判断。

照片或渐变上的文本

• 说明： 白色文本直接叠加在部分区域较亮的图像或渐变上，却只检查了一个明亮点。
• 原因： 对比度取决于局部区域。图像较亮的地方，文本对比度会低于 4.5:1，即使首屏整体“看起来”没问题。R-25 要求检查文本覆盖的整个区域，而不是单个点。
• 修复： 在文本后方添加遮罩或纯色块，然后验证最差的位置，而不是最好的位置。文本区域的任何部分未达标，整个处理方案就不合格。

灰底灰的错觉

• 说明： 未经计算就声称“黑色上的深灰色”或“白色上的浅灰色”符合 AA 标准。
• 原因： 这是最常见的无障碍错觉。人眼会高估灰色搭配的对比度，而 Agent 会因为这种说法听起来合理而重复它。#555555 在黑色上的对比度为 2.8:1，不合格。
• 修复： 不要直接断言某种搭配符合标准。运行对比度检查器（见下文）或应用公式。两者都无法使用时，请参考参考表。

非文本对比度

• 说明： 交互组件（按钮、图标、输入框边框、焦点指示器、图表区段）与背景的对比度低于 3:1。
• 原因： 非文本 UI 通过形状和边缘传递信息。当边缘只比背景深一点点时，低视力用户就无法找到控件。悬停和选中等状态也适用相同标准。
• 修复： 确保每个组件边界和状态指示器与相邻颜色的对比度均达到 3:1（WCAG 1.4.11）。图标应搭配对比度达到 4.5:1 的文本标签。

对比度检查器

对比度检查器的主页。分为三个层级，按便捷程度从高到低排列：

脚本。 如果运行时可用且文件存在，请运行脚本，而不是手动计算。脚本位于此技能的文件夹中（与此 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)

如果此 Agent 中没有 ${CLAUDE_SKILL_DIR} 变量，请将脚本路径直接指向此技能的文件夹。提供此脚本是为了让 Agent 不再臆测 AA 结果。脚本接收两个十六进制颜色，并输出对比度以及两种文本尺寸各自的判定结果。如果文件缺失，下面的公式和表格本身就已足够。切勿因等待脚本而停滞。

公式（WCAG 2.x）。

1. 对比度 = (L1 + 0.05) / (L2 + 0.05)，其中 L1 是较亮颜色的相对亮度，L2 是较暗颜色的相对亮度。
2. 单种颜色的相对亮度 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，大号文本为 3:1（18px+，依据 R-25）。仅在显示时舍入，因此对比度为 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 明令禁止这样做。
• 修复： 保留轮廓，或使用可见的 :focus-visible 样式替代，并达到相同的对比度要求（与相邻区域的对比度为 3:1）。切勿在没有替代样式的情况下设置 outline: none。

仅支持鼠标的模式

• 判断依据： 仅在悬停时打开的菜单、点击可打开但无法通过键盘打开的下拉菜单、没有键盘替代操作的拖放功能。
• 原因： 这些模式都会排斥键盘用户和辅助技术用户（R-32）。如果某个控件无法通过 Tab、Enter 或 Space 键访问和操作，那么对一整类用户来说，它就形同虚设。
• 修复： 每个交互元素都应可通过键盘访问和操作（R-32）：Tab 键顺序应符合视觉顺序，使用 Enter 或 Space 键激活，使用 Escape 键关闭对话框（R-26）。

Tab 顺序错误

• 判断依据： 焦点在页面上跳来跳去、跳过内容，或因 DOM 顺序与视觉顺序不一致而落在隐藏元素上。
• 原因： Tab 顺序按代码顺序而非视觉顺序读取，会导致导航不可预测（R-32）。用户会迷失位置，页面也会显得无法正常工作。
• 修复： 保持源代码顺序与视觉顺序一致，为长页面添加跳转链接；除非真实内容属于对话框等受控焦点陷阱的一部分，否则切勿为其设置 tabindex="-1"。

焦点与状态

焦点指示器不明显或不可见

• **迹象：**焦点环与背景颜色相同、焦点环只在悬停时出现，或指示器比 1px 边框还细。
• **原因：**焦点指示器能让键盘用户知道当前焦点所在位置。如果它未达到对比度要求，或只在悬停时显示，纯键盘操作就会受阻（R-32、R-34）。
• **修复：**为每个交互元素提供可见的焦点指示器；在所有发布的主题中，指示器与相邻颜色的对比度都应达到 3:1。请在深色和浅色模式下检查。

仅通过颜色反馈

• **迹象：**仅通过颜色传达成功、错误和状态，例如红色错误文本、绿色成功边框或带色调的标签，没有图标、标签或文本。
• **原因：**这会排除色盲和低视力用户，而且在强制颜色模式下会完全消失。依赖辨别色相的状态就不算状态（C-4）。
• **修复：**每个颜色信号都应搭配文本、图标或图案。错误状态应以文本为主：“密码至少需要 8 个字符”，而不应只有红色边框。

缺少 UI 状态

• **迹象：**数据视图缺少空状态、加载状态或错误状态，或者这些状态虽存在却不可见：例如没有文本的微调指示器，或没有说明的空白屏幕。
• **原因：**R-27 要求提供这三种状态；从无障碍角度看，每种状态都必须可感知且能提供信息，而非仅作装饰。没有上下文的加载微调指示器会让屏幕阅读器用户以为页面卡住了。
• **修复：**每个数据视图都应包含这三种状态（R-27），且每种状态都应有语音提示或可见内容：明确的空状态消息、带文本的加载状态，以及说明发生了什么和如何继续操作的错误状态。

缩放与移动设备使用

antislop-layoutmobile 负责移动设备布局机制（断点、缩放、网格、溢出和点击目标）。本节只保留会排除部分用户的移动设备相关细节：缩放和屏幕键盘。

文本无法缩放

• **迹象：**字体大小固定为像素值，或容器设置了 overflow: hidden，导致文本在缩放至 200% 时被裁切。
• **原因：**用户必须能够调整文本大小（WCAG 1.4.4）。如果缩放至 200% 会裁切内容或导致水平滚动，文本实际上就无法调整大小。
• **修复：**使用能随缩放重新排版的流式字体，不要用容器裁切文本，并确认布局在窄视口缩放至 200% 时仍正常（R-35）。

移动设备键盘遮挡表单

• **迹象：**视口底部的输入框被屏幕键盘遮挡，且不会滚动至可见区域，或没有足够空间显示输入框。
• **原因：**用户看不到或无法触及的表单，就无法完成填写。这是仅影响移动设备的排除问题（R-03）。
• **修复：**输入框获得焦点时，应滚动至键盘上方的可见区域，并留出足够的底部内边距，确保焦点所在字段不会被遮挡。请使用真实设备或模拟键盘进行测试。

人工技能检查清单

任务涉及 UI 时，请与核心交付门禁一并执行这些检查。所有回答都必须为是：

• 是否使用对比度检查器（公式、表格或脚本）验证了每组文本与背景颜色的搭配，包括图片和渐变上的文本？（R-25）
• 每个交互组件边界和状态指示器与背景的对比度是否都达到 3:1？（非文本对比度）
• 每个主题中的每个交互元素是否都具有可见且对比度高的焦点指示器？（R-32、R-34）
• 每个交互元素是否都可通过键盘访问和操作，对话框是否可通过 Escape 关闭，并且没有未提供替代样式的 outline: none？（R-32、R-26）
• 每个数据视图是否都具备可感知的空状态、加载状态和错误状态，且不会仅通过颜色传达？（R-27、C-4）
• 文本能否放大至 200% 而不被裁切，移动设备键盘是否始终不会遮挡获得焦点的输入框？（R-35）