Front-End-Checklist 焦点样式规范实战用 :focus-visible 构建可见的自定义焦点指示器【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist键盘用户完全依赖焦点指示器判断自己在页面中的位置一旦 CSS 中无差别移除outline且没有提供替代方案整个站点对键盘导航用户运动障碍人士、重度快捷键用户、辅助技术使用场景来说将寸步难行。本指南以 Front-End-Checklist 仓库中的focus-styles规则Skill 定义 与 完整规则参考、规则源文件为主体结合仓库 Web 应用的真实样式实现系统讲解焦点指示器的设计原理、可复制的 CSS 方案与 WCAG 2.2 合规验证方法。读完你将能够识别并修复所有outline: none隐患、正确区分:focus与:focus-visible、设计出符合对比度与面积要求的高质量焦点环并在多视口下完成验证。为什么焦点指示器不可或缺Front-End-Checklist 将本规则定位为high 优先级、beginner 难度、约 15 分钟的检查项见 rule.md 的元信息。它的核心主张非常明确永远不要在没有更好替代方案的情况下移除默认焦点轮廓。键盘用户运动障碍人士、快捷键重度用户、依赖辅助技术的场景完全依靠焦点指示器来获知当前交互位置。移除轮廓且不提供替代会让整个站点对键盘用户彻底不可用。规则源文件明确指出两套标准要求focus-styles.mdxWCAG 2.4.7Focus VisibleAA要求可见的焦点指示器WCAG 2.4.13Focus Appearance为自定义指示器定义了更强的面积与对比度目标。在 WCAG 2.2 中该要求被进一步细化为 Success Criterion2.4.11Focus AppearanceAA三个量化指标将在下文“合规要求”中逐一拆解。最常见的反模式无差别移除 outline规则参考文档给出的反例非常典型值得逐条对照检查自己的样式表rule.md/* ❌ 移除焦点指示器——键盘用户看不见自己在哪里 */ * { outline: none; } *:focus { outline: none; } button:focus { outline: 0; }*通配符重置、*:focus全局隐藏、button:focus定向隐藏三种写法在真实项目中出现频率极高尤其是搭配 CSS Reset 或第三方 UI 库的全局样式时。Skill 定义的Check 步骤给出了对应的排查命令式指令SKILL.md找出该 CSS 中所有outline: none、outline: 0或:focus { outline: none }的实例检查它们是否提供了可替代的可见焦点指示器。如果替代方案使用伪元素绘制还要验证焦点环不会被overflow裁切或因缺少定位上下文而错位。即排查不只要“找到移除点”还要确认“替代方案是否真的渲染正确”。正确姿势用 :focus-visible 区分键盘与鼠标:focus-visible只在键盘导航期间显示焦点指示器鼠标点击时不显示。这一机制同时满足了“美观”点击不出环与“无障碍”键盘有环两个诉求是规则文档明确推荐的现代方案rule.md/* ❌ 旧方案鼠标点击时也显示焦点环 */ button:focus { outline: 2px solid blue; } /* ✅ 现代方案仅键盘导航时显示 */ button:focus { outline: none; } /* 鼠标点击时隐藏默认环 */ button:focus-visible { outline: 2px solid var(--color-primary); outline-offset: 2px; }这段代码同时示范了本规则最重要的两条 Quick Reference 要点SKILL.md绝不可以在没有可见的:focus-visible替代方案时使用outline: none或outline: 0用:focus-visible而非:focus来仅在键盘导航期间显示指示器。浏览器兼容性提示:focus-visible是现代浏览器Chrome 86、Firefox 85、Safari 15.4的稳定特性。规则元数据中列出了 WICG/focus-visible polyfill见 focus-styles.mdx 的 tools 字段旧浏览器场景下可借助它平滑回退。设计一个高质量的全局焦点环规则文档提供了一个可直接落地的“基础重置 键盘焦点”组合rule.md/* 所有浏览器的基础重置 */ *:focus { outline: none; } /* 仅键盘导航时显示可见焦点 */ *:focus-visible { outline: 2px solid var(--color-primary); outline-offset: 3px; border-radius: 3px; /* 可选与元素 border-radius 保持一致 */ }关键设计参数来自 Skill 的 Quick ReferenceSKILL.md焦点指示器与相邻颜色之间须有3:1 对比度WCAG 2.2高质量焦点环至少提供2px 实线 outline 并带偏移量outline-offset避免环与元素本身粘连而难以分辨若用伪元素绘制焦点环务必确认它锚定在正确的定位元素上且不被overflow: hidden裁切若组件使用 stretched-link拉伸链接模式验证可见焦点环跟随真实的交互元素而不是意外落在父级容器上。组件级焦点环的三种实战形态统一全局环之外真实组件通常需要因地制宜。规则文档给出了三种典型场景rule.md1. 普通按钮——外置偏移环.button { position: relative; } .button:focus-visible { outline: 2px solid var(--color-primary); outline-offset: 2px; }2. 暗色表面——反白焦点环.dark-nav .nav-link:focus-visible { outline-color: white; }3. 输入框——用边框变化替代 outline.input:focus-visible { outline: none; border-color: var(--color-primary); box-shadow: 0 0 0 3px rgb(37 99 235 / 0.25); }输入框场景是“移除 outline 但提供替代”的合法范例焦点可见性由border-color变化与 3px 扩散的box-shadow承担outline: none因此不再构成违规。键盘用户的跳转链接Skip Link焦点样式不止作用于“环”还关系到键盘用户能否快速跳过重复导航。规则文档给出了隐藏但聚焦时出现的.skip-link方案rule.md/* 视觉隐藏但获得焦点时可见 */ .skip-link { position: absolute; top: -100%; left: 1rem; padding: 0.5rem 1rem; background: var(--color-primary); color: white; text-decoration: none; border-radius: 0 0 0.5rem 0.5rem; z-index: 1000; } .skip-link:focus { top: 0; }注意这里的:focus用法是合理的——跳过链接的触发者必然是键盘用户无需区分输入方式。本仓库另有 skip-link 与 skip-navigation 两个独立规则可配合查阅。WCAG 2.2 的量化合规要求规则文档对 WCAG 2.2 Success Criterion 2.4.11Focus AppearanceAA给出了三条硬性指标rule.md焦点指示器面积至少为未聚焦组件周长的2 CSS 像素倍数聚焦态与非聚焦态之间的对比度至少为3:1与相邻颜色的对比度至少为3:1。规则的 tldr 摘要 也明确要求焦点指示器与相邻颜色达到 3:1 对比度WCAG 2.2并提供了 WCAG 2.4.13 Focus Appearance 理解文档 作为权威依据。仓库真实实现globals.css 中的焦点样式Front-End-Checklist 的 Web 应用本身就是这套规范的落地案例。在 apps/web/app/globals.css 的全局基础层中仓库用 CSS 变量实现了“WCAG AAA 合规”的全局焦点环/* Focus styles - WCAG AAA compliant */ *:focus-visible { outline: 2px solid var(--ring); outline-offset: 2px; border-radius: var(--radius-sm); }这正对应规则文档的“高质量焦点环”范式2px 实线、2px 偏移、圆角匹配设计系统。而组件级覆盖同样存在——代码标签页触发器 .code-tabs-trigger:focus-visible 使用了负偏移的内置环.code-tabs-trigger:focus-visible { outline: 2px solid var(--accent); outline-offset: -2px; border-radius: var(--radius-sm); }outline-offset: -2px正是规则文档中“Inset ring内嵌环”的实战体现——当外置偏移会与周围内容重叠时将环内收进元素边界内。这种“全局兜底 组件微调”的分层策略是把焦点样式写进设计系统的推荐做法。作为 Skill 使用Agent 视角的检查与修复工作流focus-stylesSkill 不仅面向人类开发者其结构本身就是为 AI Agent 设计的元数据含category: css、priority: high、difficulty: beginner、estimatedTime: 15来源标注为 frontendchecklist.io见 SKILL.md。它在执行阶段提供四个明确的指令槽位Check找出所有outline: none/outline: 0/:focus { outline: none }确认是否提供替代指示器伪元素替代方案需额外验证裁切与定位Fix将:focus上的outline: none替换为带清晰可见、对比度适当的自定义焦点环的:focus-visible样式Explain解释:focus与:focus-visible的差异、焦点样式对无障碍的意义以及如何设计可访问的焦点环Code Review审查样式表、组件样式与响应式状态在渲染后的 UI 中标记违反本规则的具体选择器、声明或断点。规则源文件同时通过relatedRules字段声明了两条关联规则focus-styles.mdxtouch-targets可见焦点与足够的点击目标尺寸对键盘与触屏用户同样关键keyboard-navigation与 focus-styles 同属css/keyboard子类常一起审查。在实际审核中建议将三者视为一组配套检查先确认键盘可达keyboard-navigation再确认焦点可见focus-styles最后确认触屏可用touch-targets。验证清单发布前必须完成的四步规则文档的 Verification 步骤要求结合真实渲染结果而非只看源码rule.md在受规则影响的断点与交互状态下检查渲染后的 UI在 DevTools 中确认计算样式与预期修复一致发布前至少测试一个移动端视口和一个桌面端视口若规则影响动效、对比度或布局稳定性直接验证这些面向用户的结果。其中第 3 条呼应了 Skill 描述中“跨断点与交互状态检查渲染布局”的要求SKILL.md——焦点环在窄屏上可能被截断、在缩放后可能偏移仅靠桌面端验证远远不够。小结可见焦点指示器是无障碍底线的组成部分不是可选的“加分项”。遵循 Front-End-Checklist 的focus-styles规则你可以用三行 CSS 保住整个站点的键盘可用性全局*:focus-visible提供 2px 实线、带偏移、3:1 对比度的焦点环组件级按需覆盖任何outline: none都必须先问一句“替代方案在哪里”。从本仓库的 globals.css 可以看到这套规范与设计系统变量结合后既统一又可维护——这正是把它从“一条规则”升级为“工程实践”的路径。【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考