重构刷新后，焦点状态为何总被破坏？一份键盘优先检查清单

视觉翻新往往以牺牲键盘体验为代价。页面看起来更干净了，配色更舒服了，但焦点轮廓线在某个版本里悄悄消失了。这不是偶然风险，而是每次重构后几乎必然发生的事。一位前端开发者总结了一份每次上线前必跑的六点检查清单，在自家网站上跑完大约只需二十分钟。

为什么重构总是先吃掉焦点状态

焦点在需要它之前是不可见的，这正是问题的核心。盯着浏览器里的新布局时，大多数人用鼠标点击，而鼠标从不显示焦点环。键盘用户依赖的那个唯一视觉提示，恰恰是开发者在重构中最不容易注意到已经丢失的东西。

罪魁祸首通常是 CSS 重置。设计师为了干掉浏览器默认的"丑陋"焦点环，随手写上 outline: none，然后忘了补回任何替代样式。结果每个按钮、链接和输入框对 Tab 键用户来说都成了死胡同。

第二个常见原因是组件库替换。从一个样式组件库换到另一个，新组件自带各自的焦点行为——也许存在，也许只是一条 1px 的灰线，在灰色背景上完全看不见。开发者继承了别人的决定，却从未验证过。

第三个原因是主题适配。加了深色模式后，焦点环颜色被硬编码为深色值，在深色画布上彻底隐形。浅色主题没问题，深色主题却成了一个字面意义上的黑箱。

这里有一个值得直说的点：键盘用户并非小众边缘群体。高级用户用 Tab 导航是因为更快，屏幕阅读器用户完全依赖它，因运动障碍而难以使用鼠标的人更是离不开它。当焦点环消失，这些人在页面上同时失去了自己的位置。

用 :focus-visible 替换 :focus

作者认为价值最高的单点改动，是把 :focus 换成 :focus-visible。

旧的焦点样式有个恼人的权衡：如果为了键盘用户把 :focus 样式做得很显眼，鼠标用户每次点击按钮都会看到一个巨大的焦点环，显得很别扭。于是人们干脆删掉它，结果两类用户都受损。

:focus-visible 解决了这个矛盾——由浏览器决定何时显示。鼠标点击按钮，没有焦点环；用键盘 Tab 到按钮，焦点环醒目出现。同一套 CSS，根据元素获得焦点的方式表现出不同行为。

作者的基线规则是：outline: 2px solid currentColor; outline-offset: 2px;，同时用 :focus:not(:focus-visible) { outline: none; } 消除鼠标点击时的轮廓。

outline-offset 的作用比多数人预期的更重要。紧贴元素边缘的轮廓读起来像边框而非焦点状态，两像素的间隙能让用户明确感知元素被选中，也避免轮廓在圆角处被裁切。

作者坚持使用 outline 而非 box-shadow 来做焦点环。outline 不触发布局偏移，也不会被父元素的 overflow: hidden 裁掉。box-shadow 焦点环在滚动容器里经常莫名消失，直到某次滚动才会被发现。

还有一个陷阱：永远不要在没有 :focus-visible 替代样式的情况下全局应用 outline: none。如果只写 *:focus { outline: none } 而没有其他补救，一行代码就删除了整个站点的键盘导航能力。作者说，他见过不止一次这样的代码上了生产环境。

验证方法很简单：把鼠标收起来，按 Tab 键。每个可交互元素都应该随着移动而亮起。如果某个元素没有，要么它实际上不可聚焦（一个伪装成按钮的 div），要么焦点环样式没有应用到位。

:focus-visible 是 CSS Selectors Level 4 引入的伪类，用来区分「元素获得焦点的原因」。传统的 :focus 对任何方式获得的焦点都生效——包括鼠标点击、触摸和键盘导航，这正是它难以兼顾美观与可见性的根源。:focus-visible 则由浏览器根据启发式规则判断：如果焦点是通过键盘（Tab、Shift+Tab、方向键）或等价输入获得的，就匹配；如果只是鼠标或触摸点击，通常不匹配。例外情况是文本输入框——即使用鼠标点击，输入框也保留光标提示，因此浏览器一般仍会匹配。它的浏览器支持已相当成熟，Chrome、Firefox、Safari 及主流移动端均可用；但老版本浏览器会忽略这条规则，所以保留一条 :focus 兜底样式更稳妥。实现时通常写成 :focus { outline: none } 加 :focus-visible { outline: ... }，或像作者那样用 :focus:not(:focus-visible) 精确关闭鼠标态的轮廓。

outline-offset 属性控制轮廓线相对元素边框外缘的偏移距离，正值让轮廓向外扩张（离开元素），负值则向内收缩。它只影响绘制位置，不参与盒模型计算，因此不会改变元素尺寸或触发布局重排。当元素带有 border-radius 时，轮廓默认会随圆角绘制，但紧贴边缘的轮廓与边框难以区分，加上 2px 左右的偏移能制造明确的视觉间隙，让焦点状态一眼可辨。与 box-shadow 相比，outline 不占据布局空间、不被 overflow: hidden 裁剪，这些特性在滚动容器和组件嵌套场景中尤为重要。

让焦点环在两种主题下都有足够对比度

一个存在但看不见的焦点环，等同于没有焦点环。作者坚持的数字是：轮廓颜色与紧邻背景之间至少达到 3:1 的对比度。

3:1 是无障碍指南中非文本 UI 元素的阈值，焦点指示器也算在内。需要检查焦点环与元素自身背景的对比，以及与页面背景的对比，因为偏移间隙意味着焦点环往往一半在元素上、一半在页面背景上。

主题问题是大多数失败藏身之处。需要在元素可能出现的每一种背景上检查：浅色主题、深色主题，以及任何彩色区域如 hero 区或反色页脚。单一轮廓颜色几乎不可能通过所有背景的对比度要求。

作者的解决方案是把焦点环颜色绑定到主题变量而非硬编码。根变量定义浅色主题的 --focus-ring，[data-theme="dark"] 下覆盖为浅色值，焦点样式引用该变量。

对于背景不可预测的元素，比如照片或视频上的按钮，作者会叠加第二层焦点环——白色轮廓加黑色光晕，无论背后是什么，总有一半可见。这种场景下才使用 box-shadow 作为双层的补充，并接受其裁切风险，因为兜底可见性更重要。

检查对比度可以用任何对比度工具。选定轮廓颜色和背景，读取数值。低于 3:1 就加粗轮廓到 2px 或更换颜色。不要为了让焦点环"低调"而把它变细——对需要它的人来说，低调和隐形是同一回事。

顺便检查强制颜色模式下的表现。Windows 高对比度模式会完全覆盖自定义颜色，而 outline 在这种覆盖下比 box-shadow 更可靠地保留下来。这是作者默认使用 outline 的另一个原因。

这里的 3:1 对比度阈值来自 WCAG 2.1 的 1.4.11 非文本对比度准则，要求界面组件和图形对象（包括焦点指示器）与其相邻颜色之间至少 3:1。它衡量的是颜色相对亮度之差，与字号大小无关，和正文要求的 4.5:1 是不同阈值。焦点环的复杂之处在于它往往同时接触两类背景：元素本身和其外部的页面背景。若轮廓带有偏移间隙，则间隙处显示的是页面背景色，轮廓线一半压在元素上、一半压在页面上，因此两个方向都要验证。实践中可以用任何对比度检查工具，输入轮廓色与背景色的十六进制值读取比值；低于 3:1 时增加轮廓宽度、加深颜色或改换色相都能改善。此外，「强制颜色」模式（forced-colors）是操作系统层面的设置，Windows 高对比度模式会强制替换页面上大部分颜色，此时自定义背景和边框可能失效，而 outline 通常能被系统映射保留，box-shadow 则常被忽略——这是作者优先使用 outline 的又一个原因。

全程用 Tab 走完整个页面，鼠标拔掉

这是能抓住所有 CSS 检查遗漏问题的测试。把鼠标放一边，像没有其他选择一样从头到尾 Tab 走完整个页面。

焦点顺序应该遵循视觉布局：从上到下，从左到右。如果焦点从页头跳到页脚又弹回中间，说明 DOM 顺序与视觉顺序不匹配，键盘用户正在没有地图的页面上被来回抛掷。

这种情况在重构后频繁出现，因为 CSS 允许在不改动 DOM 的情况下移动视觉位置。用 flexbox 的 order 或 grid 布局把一个位于 HTML 底部的侧边栏放到视觉左侧——看起来对，Tab 起来错。应该修 DOM 顺序，而不是 Tab 顺序。避免使用正数值的 tabindex，那是让下一个人更难维护的补丁。

遍历时重点观察：每一站都有可见焦点环，没有静默跳跃；没有不可见的可聚焦元素（移动端菜单关闭时，链接不应出现在 Tab 顺序中）；没有焦点陷阱（每个模态框、下拉菜单和日期选择器都能 Tab 出去，Escape 能关闭）；第一站是跳转链接，让键盘用户可以跳过导航直达主内容。

模态框陷阱是组件替换后最容易踩的坑。好的模态框在打开时有意限制焦点，关闭时把焦点还给触发它的按钮；坏的模态框永远困住焦点，或者把用户丢回页面顶部。打开每一个覆盖层，Tab 一圈，按 Escape，确认焦点落到了合理的位置。

窄屏宽度下也要走一遍，因为移动端布局会重排和隐藏元素。桌面端完美的 Tab 顺序，在移动端可能一团糟。

每个主要视图做一次这样的遍历只需要几分钟，是最接近"做五分钟键盘用户"的方式。如果清单上只跑一项，就跑这项。

Tab 顺序由 DOM 顺序决定，并受 tabindex 属性调制。默认情况下，浏览器按照元素在 HTML 中出现的先后顺序遍历，只包含原生可聚焦元素（链接、按钮、输入框、select、textarea 以及带 tabindex 的元素）。CSS 的视觉重排（flexbox 的 order、grid 的显式行列定位、绝对定位）可以在不改动 DOM 的情况下改变元素在屏幕上的位置，从而导致焦点移动方向与视觉阅读方向脱节。修复方法是调整 HTML 结构，而不是用正数值 tabindex 强行校准——后者会让后续维护者在增删元素时不断调整数值，极易出错，并可能破坏屏幕阅读器的阅读顺序。

「跳转链接」（skip link）通常是一个放在页面最前方、默认视觉隐藏、获得焦点时显现的锚点，点击或回车后把焦点直接送到主内容容器，让键盘用户不必逐站穿过整个导航。焦点管理还涉及「焦点陷阱」与「焦点归还」两个概念：模态框打开时应把焦点约束在对话框内，关闭时把焦点还给触发它的控件；组件库往往在这一点上各有各的实现，切换库后需要逐一手动验证。移动端菜单、折叠面板等隐藏内容若未使用 display: none、hidden 属性或 inert，其中的链接仍可能出现在 Tab 顺序里，造成焦点跳到看不见的地方。

常见问题

焦点状态在重构中最容易被什么破坏？ CSS 重置里的全局 outline: none、组件库替换后新组件自带的不同焦点行为、以及深色主题下硬编码的深色焦点环，是三类最高频的破坏来源。

为什么推荐 :focus-visible 而不是 :focus？ 浏览器能根据元素获得焦点的方式自动判断：鼠标点击不显示焦点环，键盘 Tab 显示。这消除了一直以来"键盘可见性"与"鼠标美观度"之间的取舍困境。

焦点环对比度应该达到多少？ 轮廓颜色与紧邻背景之间至少 3:1。并且需要在浅色、深色及所有彩色区块上分别验证，单一颜色往往无法通过全部场景。

底线

四项检查按顺序跑一遍，几乎能抓住重构引入的所有焦点回归：换用 :focus-visible，给焦点环 2px 偏移，保持对所有背景（包括深色模式）3:1 的对比度，然后收起鼠标 Tab 走完全页。

如果只能保留一项，就是 Tab 遍历。样式表里的 CSS 看起来可以完美无缺，在实际流程中仍然失败，唯一知道答案的方式就是像键盘用户那样使用页面。

把这项检查加入上线前例行流程，它会成为肌肉记忆。需要记住的检查，就是忙碌那天会被跳过的检查。