CSS 生成内容的无障碍实践:modern-web-guidance 中 `content` 替换文本完全指南

原创2026-11-12 12:16:111,634 阅读
文章标签:前端文档AI 技能AI 评测Agent 评测人工智能RAGCLI提示工程

CSS 生成内容的无障碍实践:modern-web-guidance 中 content 替换文本完全指南

在 modern-web-guidance 仓库中,accessible-generated-content 指南 专门解决一个容易被忽视的问题:用 ::before / ::after 插入的 CSS 生成内容,究竟什么时候会被屏幕阅读器朗读,又应该如何用 content 的替换文本(alt text)语法把语义控制权交还给 DOM。本文以该指南为骨架,结合仓库中的评分器、练习目标应用与 Baseline 宏实现,把"能看"和"能被读出"这两件事讲透,读完后你可以为任意界面添加装饰性图标、箭头、分隔符,而不会让屏幕阅读器用户听到多余的噪音,也不会让真正重要的标签只存在于样式表里。

一、核心矛盾:生成内容既"不在 DOM 里",又可能"被读出来"

CSS 生成内容由样式表产生,不进入文档对象模型,因此它不参与正常的可访问名称计算路径;但浏览器与辅助技术的实现会把它作为伪元素暴露在无障碍树中,纯文本型生成内容往往会被朗读。

这就形成了一个陷阱:

  • 开发者以为"CSS 里的东西是装饰,屏幕阅读器不会管";
  • 于是把标签、状态、操作提示写进 content,视觉上完美,语义上彻底丢失;
  • 或者反过来,把本该读出的内容也当成装饰,用户完全不知道按钮是干什么的。

指南给出的立场非常明确(见 guide.md):content 的替换文本参数是减害手段(harm reduction),用于兜住"装饰意外承载了含义"的情况,不是把语义放进 CSS 的许可证。

二、五条必须记住的规则

指南用五条祈使句划定了边界,这里逐条展开:

规则 正确做法 说明
不要用 content 传达有意义的文本 标签、状态、指令保留在 DOM 中 对应 WCAG F87(用 CSS 生成内容插入信息导致的失败案例)
用替换文本参数为图片提供替代文本 content: url(cloud.svg) / "Save"; 屏幕阅读器读取 / 之后的字符串
用空替换文本让纯装饰文本静音 content: "text" / ""; 视觉保留、朗读抑制
不要给图片使用空替换文本 反例:content: url(cloud.svg) / ""; 图片型生成内容默认就是呈现性的,空 alt 属多余且易误导
不要给 emoji 添加"官方名称"式的描述 反例:content: "🎉" / "celebration"; 正确:content: "🎉" / "Yay!"; 只有当描述不同于 emoji 官方名称时才有价值

2.1 为什么标签必须留在 DOM

把 <button> 的文字写在 content 里,会造成链式问题:

  • 按钮的可访问名称来自生成内容,DOM 中却是空的;
  • 复制粘贴、页内查找、翻译工具、阅读模式全部失效;
  • 一旦样式表加载失败或被用户样式覆盖,功能描述直接消失。

所以指南的第一条是"禁止项",后四条才是"补救项"。

2.2 什么时候空的替换文本才是对的

content: " →" / ""; 是典型的良性用法:箭头只是视觉提示,宿主元素(如"查看详情"链接)本身已有完整文本。此时抑制朗读不损失任何信息。

而 content: url(cloud.svg) / ""; 是错误写法。图片型生成内容本就默认不被朗读为文本,多写一个空 alt 只会让代码读者误以为"这里本来需要 alt"。

2.3 emoji 的特殊判断

屏幕阅读器对 emoji 通常已有内置名称(如"庆祝"、"派对爆竹")。因此 content: "🎉" / "celebration"; 相当于把同一信息说两遍。只有当你的语义与官方名称不同——例如"Yay!"表达的是语气而非图形名称——替换文本才有存在意义。

三、边界条件:只在"文本不同且 DOM 中没有"时使用替换文本

这是最容易被忽略的一条,也是指南里唯一给出完整反例的地方(guide.md)。

错误示范:

HTML:

<button class="save">Save</button>

CSS:

button.save::before {
  content: url(cloud.svg) / "Save";
}

宿主按钮的 DOM 文本已经是 "Save",生成内容又提供了 "Save",屏幕阅读器会读成 "Save save"。

判定标准可以归纳为两个条件,必须同时满足才写替换文本:

  1. 替换文本与 content 的主值不同(图片 URL ≠ "Save",成立;纯文本 "Save" = "Save",不成立);
  2. 该文本没有已经出现在宿主元素的 DOM 文本或 ARIA 名称中。

如果装饰图确实需要被读出,正确做法是把标签放进按钮的 DOM(可见文本、视觉隐藏的 <span>、或 aria-label),而不是靠 CSS。

四、这份指南在仓库中的位置与关联

4.1 元数据:两个 web-feature ID

指南 frontmatter 声明了两个特性标识(guide.md):

name: accessible-generated-content
description: Use CSS generated content (`::before`/`::after`) in ways that stay accessible, including alternative text for decorative content.
web-feature-ids:
  - content
  - alt-text-generated-content

content 覆盖 content 属性本身,alt-text-generated-content 覆盖 / 替换文本语法。在构建期的特性分组映射里,两者都归入 css 组(feature-to-groups.gen.json),因此该指南在检索与分类上属于 CSS 范畴,尽管其内容完全是无障碍规则。

4.2 与其他指南的交叉引用

仓库中有两处显式指向本指南:

  • 无障碍总纲在"CSS generated content"小节要求:"Use the alternative text argument of content … and keep meaningful text in the DOM",并标注 WCAG 1.1.1 Non-text Content (Level A)(accessibility/guide.md);
  • CSS 指南在讨论装饰性内容时,把"不破坏屏幕阅读器与复制粘贴"的细节委托给本指南(css/guide.md)。

这种"总纲给原则、专题给细节"的结构,说明本文讨论的不是冷门技巧,而是仓库无障碍体系中的一个强制节点。

4.3 它在静态分析中被特殊对待

值得注意的是,src/analyzing/schema.ts 的注释把 accessible-generated-content 与 passkey-registration 并列,作为 'no-legacy-pattern' 类规则的例子——原因是这类指南的适用性"取决于人的视觉与语义判断",不存在可自动匹配的旧代码模式(schema.ts)。这从侧面印证:/ 替换文本用得好不好,本质上是一个需要人审的设计决策。

五、实战:为 Daily Grind 首页添加无障碍装饰图标

5.1 目标应用结构

练习目标应用是仓库内置的 daily-grind 基础应用(index.html)。它的相关结构包括:

<header class="hero">
  <h1>Wake Up Your Senses</h1>
  <p>Ethically sourced, locally roasted, delivered to your cup.</p>
  <a href="/order-online" class="btn">Order Now</a>
</header>

<main class="container">
  <section>
    <h2 style="text-align: center;">Seasonal Favorites</h2>
    <div class="grid">
      <div class="card">
        <h3>Maple Oat Latte</h3>
        <p>Creamy oat milk with a hint of Vermont maple syrup.</p>
        <a href="/menu/seasonal" class="btn">View Details</a>
      </div>
      <!-- Dark Roast Espresso / Cold Brew 结构相同 -->
    </div>
  </section>
</main>

样式侧已经有 .card h3(标题配色)与 .btn(主色按钮、transition: background 0.3s)(index.html)。任务要求很具体:为"Seasonal Favorites"饮品标题以及"Order Now" / "View Details"按钮添加装饰性图标与视觉点缀,同时保证屏幕阅读器体验不受影响(task.md)。

5.2 最小可行实现

参考仓库中评分通过的解法补丁(claude-solution.patch):

/* 装饰性字形:通过空替换文本对屏幕阅读器静音 */
.btn::after {
  content: " →" / "";
}

.card h3::before {
  content: "☕ " / "";
}

两点关键:

  • 箭头与咖啡杯都是装饰,宿主链接/标题已有完整文本,因此用 / "" 抑制朗读;
  • 两处都没有使用 url(...),所以不存在"给图片写空 alt"的问题。

另一个通过的方案还处理了页脚分隔符与品牌标志(antigravity-solution.patch):.logo::before、.logout-link::before 同样使用 / "";同时把 HTML 里裸写的 | 字符从页脚移除,改由 .footer-links a:not(:last-child)::after { content: " |" / ""; } 生成。这一步很重要——原来那些 | 是 DOM 中的真实文本,屏幕阅读器会把它们当作内容读出;改成生成内容并静音后,视觉不变,朗读噪音消失。

5.3 如果装饰图需要被读出

假设要为一个图标链接补充说明,而该说明在 DOM 中并不存在:

.download-link::before {
  content: url(icons/download.svg) / "下载报告";
}

前提是宿主元素没有同名文本。若链接文字本来就是"下载报告",请删掉替换文本,或改为纯 content: url(icons/download.svg);。

六、降级策略:不支持 / 语法的浏览器怎么办

指南在这一节嵌入了 Baseline 状态宏(guide.md):

{{ BASELINE_STATUS("alt-text-generated-content") }}

6.1 宏背后的解析链

这个占位符不是装饰性文档标记,构建时会被真实解析。宏处理器在 src/core/macros.ts 中注册 BASELINE_STATUS,取值来自 getStatusMessage(featureId, bcdKey)(macros.ts);后者通过 web-features 包与 BCD 数据解析特性状态,最终由 formatStatusMessage 输出形如"Baseline status for … : Widely. It's been Baseline since …"或"Limited availability"的句子(baseline.ts)。当构建目标为 devsite 且未指定 BCD 键时,宏会改写成 {{ macros.BaselineStatus('...') }},交由站点模板渲染。

这也解释了为什么指南本身不写死"某年某月起可用"——版本结论只能通过宏获取,避免文档与数据脱节。

6.2 双声明降级模式

如果支持目标包含不认识 / 语法的浏览器,必须把单值声明放在前面:

.more-link::after {
  /* 降级:在不支持 `/` 的浏览器中渲染字形
     (那里的屏幕阅读器仍会朗读它) */
  content: " →";
  content: " →" / "";
}

原理是 CSS 的"无效声明丢弃"行为:不支持该语法的解析器会把第二条声明视为无效并忽略,第一条继续生效。视觉不退化,代价只是这些旧浏览器里装饰文本仍会被朗读。

6.3 非空替换文本的取舍

对于 content: url(...) / "..." 这类非空 alt,单值降级 content: url(...) 能保住图片可见,但会丢掉替代文本。指南给出的决策是(guide.md):

如果该标签在旧浏览器中是必需的,就把它放进 DOM(例如视觉隐藏的 <span> 或 aria-label),并改用不带 / 的 content: url(...)。

换句话说:可访问性不能靠新语法兜底时,语义就必须回到 DOM。这与第二节第一条规则形成了闭环。

七、评分器如何判定"写对了"

练习目标自带自动化评分器(grader.ts),它的实现几乎就是这份指南的可执行版本。

7.1 上下文准备

评分器通过 getTargetFiles() 定位待测文件:优先读取 PATCH_FILE 环境变量所指补丁中出现的文件,再并入基础应用默认文件(daily-grind 对应 index.html)(test-fixture.ts)。这意味着一份补丁改了哪些文件,就评哪些文件。

7.2 解析 content 值:不能简单 split('/')

parseContentValue 手写了一个状态机(grader.ts),逐字符跟踪:

  • 双引号内(inDoubleQuote)、单引号内(inSingleQuote)的 / 不算分隔符;
  • url( 到 ) 之间的 / 也不算(例如 url(a/b.svg));
  • 其余第一个 / 作为主值与替换文本的分界;
  • 随后剥离替换文本外层引号。

如果没有这层处理,content: url(icons/a/b.svg) / "下载" 会被错误切分。这段代码本身就是一个值得复用的解析范式。

7.3 三条断言

评分器包含三个测试(grader.ts),与 expectations.md 的三条可观测要求一一对应:

  1. 必须存在静音型装饰规则:至少有一条 ::before/::after 规则使用 / "",且主值不含 url(。这保证了"装饰要静音"不是空谈。
  2. 宿主元素必须有可访问名称:收集所有使用替换文本的规则,去掉伪元素与 :hover/:focus 等交互伪类得到宿主选择器,再在 HTML 中匹配元素;每个匹配元素的 textContent、aria-label、aria-labelledby、title、alt 至少有一项非空(hasAccessibleLabel)。这直接封杀了"把标签写进 CSS、DOM 留空"的写法。
  3. 每条替换文本都必须合法:由 isValidAltSyntax 判定(grader.ts)。

7.4 isValidAltSyntax 的两条硬规则

  • 若替换文本为空:主值不得是图片(正则 /url\s*\(/i)。即 url(...) / "" 直接判负。
  • 若非空:先去引号比对主值,相等则判负(对应 "Save save" 问题);再把替换文本与所有宿主元素的 textContent 归一化比较,重复则判负(对应"DOM 中已存在"问题)。

注意它只做结构性与重复性检查,不判断文案质量——这正是 schema.ts 所说"依赖人的语义判断"的部分,需要作者自己把关。

八、落地检查清单

在提交任何含 ::before / ::after 的改动前,可以按下面顺序自检:

  1. 这段文字/图标是信息还是装饰?是信息 → 移回 DOM。
  2. 如果是装饰文本(箭头、分隔符、装饰符号)→ 加 / ""。
  3. 如果是装饰图片 → 直接用 content: url(...),不要加 / ""。
  4. 如果替换文本非空 → 确认它不等于主值,也不等于宿主元素已有文本。
  5. 如果描述的是 emoji → 只在含义与 emoji 官方名称不同时才写。
  6. 如果支持目标包含旧浏览器 → 先写单值声明,再写带 / 的声明;必要时把关键标签放回 DOM。
  7. 用仓库的评分器或等价检查跑一遍:静音规则存在、宿主有可访问名称、每条 alt 合法。

九、常见错误速查

症状 根因 修复
屏幕阅读器读出 "Save save" 替换文本与 DOM 文本重复 删除替换文本,或把标签移入 DOM
按钮在无障碍树中无名称 标签只写在 content 里 用真实文本 / aria-label / 视觉隐藏 <span>
装饰箭头被逐字朗读 缺少 / "" 补上空替换文本
代码审阅者误以为图片缺 alt 写了 url(...) / "" 去掉 / "",图片默认即呈现性
emoji 被读两遍 替换文本复述了 emoji 官方名称 仅在语义不同时保留
旧浏览器里整条声明失效、图标消失 只有带 / 的单条声明 前置单值 content 降级声明

CSS 生成内容本身没有问题,问题在于它是一条"绕过 DOM 的捷径"。modern-web-guidance 的这份指南用五条规则、一个反例和一套降级模式把这条捷径约束在装饰用途内;而仓库中的评分器则把这些约束变成了可执行断言——先有宿主元素的可访问名称,才轮到替换文本来锦上添花。

登录后查看全文
modern-web-guidance-src