展开本页目录
开始前准备什么
- Node.js与npm已可运行；练习只需本地文本文件和官方@google/design.md CLI，不需要Stitch账号或付费生成。
- 固定当前CLI版本并保留版本号；DESIGN.md仍为alpha格式，升级前先在练习副本复核。
- 本课给出作者自制规则文件和预期，不把预期JSON冒充已执行的官方CLI返回。
- 建立两个可比较按钮
- 保存基线渲染
- 读取contrast finding
- 辨认零退出的边界
- 改语义色的前景组合
- 写明确的检查条件
- 复查焦点与禁用显示
1. 建立两个可比较按钮
准备浅灰字/白底按钮与深色字/白底按钮，尺寸和文案完全相同。
先把两组前景背景写入组件token，不用图片压缩后的取色代替源色值。
2. 保存基线渲染
用作者HTML页同时显示两组样式，记录文字字号和正常阅读距离。
截图只证明外观，不能替代颜色计算或键盘焦点测试。
3. 读取contrast finding
运行lint并筛出contrast-ratio的warning，查看它对应的组件。
官方规则针对组件前景背景低于4.5:1给警告，不要把warning解释为解析失败。
官方界面与功能位置
以下为官方文档配图，具体版本与账号入口以当前产品为准。本课练习输入与验收对照见相邻步骤。
4. 辨认零退出的边界
记录该文件退出码，并查看summary中的warnings。
若exitCode为0但仍有对比度警告，说明本课需要的可读性门槛尚未满足。
5. 改语义色的前景组合
将低对比按钮文字改为已有的深色on-surface，保留按钮背景。
别同时改文案、尺寸和颜色，否则无法判断改善来自哪一项。
6. 写明确的检查条件
在作者检查清单里约定contrast-ratio warning不得出现，再重复运行。
这条是项目自己的交付要求，不把它说成CLI默认会以1退出的行为。
7. 复查焦点与禁用显示
在预览页用Tab查看焦点环，切换禁用状态确认仍能辨认。
保存色值、finding和截图三类证据，未执行的辅助技术检查保持未测。
下载本课材料并开始操作
练习包包含本课的具体输入、可编辑数据、正反样例与七步说明。index.html 可离线查看原件和验收参考，actual-results.csv 用于记录你实际操作后的结果。
怎样确认已经完成
- 正常按钮不再出现对应contrast-ratio warning。
- 报告明确区分exitCode=0与warnings=0。
- 焦点和禁用样式另有实际查看记录。
常见问题
DESIGN.md lint退出0，为什么还说按钮不合格？
用同文同尺寸的两组按钮保存视觉基线，再运行 lint 读取 contrast-ratio warning 和退出码。修正前景/背景色后重新测可读性；零退出只能说明该 CLI 状态，不能自动作为无障碍验收结论。
字号大一点就不用改对比度了吗？
不要借此规避本课规则。这里按CLI使用的4.5:1门槛检查，并保持两个样例字号一致；大字号、图形与交互状态还需结合真实界面另查。