企业官网建设流程全解析

Front-End-Checklist 规则实战：为图片提供有意义的 alt 文本（alt-text 规则全解）

【免费下载链接】Front-End-Checklist🗂 The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist

本文基于 Front-End-Checklist 仓库中的 alt-text 规则参考文档，系统讲解图片可访问性的核心机制：为什么每个<img>都必须有alt属性、不同角色（信息性、装饰性、链接、纯文字、复杂图表）的图片应如何取值、如何在 React/Next.js 中落地，以及如何用 axe、Lighthouse 和屏幕阅读器完成验证。读完后，你既能手动修复图片 alt 问题，也能理解该规则在仓库中从 MDX 源文件到 Agent 可安装 skill 的完整生成链路。

规则定位与元信息

alt属性是图片可访问性的首要机制。规则文档给出的定位是：每个<img>都必须有alt属性，其取值取决于图片在页面中所扮演的角色（见 rules 正文）。

该规则的元信息（定义在源 MDX 的 frontmatter 中，见 alt-text.mdx）：

为什么是 critical 优先级？文档给出了三层依据：

1. 规模：全球约有 22 亿人存在视力障碍，屏幕阅读器会逐字朗读alt属性——没有有意义的 alt，视障用户对图片内容一无所知；
2. 合规：缺失 alt 直接违反 WCAG 2.1 Success Criterion 1.1.1（非文本内容），这是 Level A（最低级）要求，合规基线的第一道门槛；
3. SEO：搜索引擎同样依赖 alt 文本来索引图片内容。

核心原则：alt 描述"图片传达了什么"，而不是"图片长什么样"

文档用一个营收图表的例子完整展示了四种典型错误与正确写法：

<!-- ❌ Bad: Missing alt --> <img src="revenue-chart.png"> <!-- ❌ Bad: Filename as alt --> <img src="revenue-chart.png" alt="revenue-chart.png"> <!-- ❌ Bad: Generic alt --> <img src="revenue-chart.png" alt="chart"> <!-- ✅ Good: Describes what the image conveys --> <img src="revenue-chart.png" alt="Bar chart showing Q3 2024 revenue increased 40% year-over-year, reaching $2.4M" >

四个反例覆盖了真实代码库中最常见的失误模式：完全缺失、文件名当 alt、泛化 alt（alt="image"、alt="photo"）。规则文档明确指出，糟糕的 alt（如alt="image"）与没有 alt 没有本质区别——它占用了属性位却不传递任何信息。判断某张图该取什么值时，文档建议参照 W3C 官方的 alt 决策树（该决策树也列在源 MDX 的 resources 字段 中）。

四类特殊场景的取值策略

规则文档把图片按角色分为四类特殊场景，每类有独立的取值策略，这也是修复工作的核心决策树。

装饰性图片：alt=""显式隐藏

纯粹用于视觉装饰的图片不承载信息，应让辅助技术完全跳过。关键点在于alt=""（空字符串）与省略alt行为完全不同：

<!-- ❌ Bad: No alt attribute—screen reader may announce the filename --> <img src="decorative-swirl.png"> <!-- ✅ Good: Empty alt hides image from screen readers --> <img src="decorative-swirl.png" alt=""> <!-- ✅ Good: Or use CSS background images for decoration --> <div class="decorative-swirl" aria-hidden="true"></div>

省略alt时，部分屏幕阅读器会朗读文件名（如 "decorative-swirl.png"），反而制造噪声。文档还给出第三条路线：纯装饰效果直接用 CSS 背景图 +aria-hidden="true"容器。仓库中生成的全局审计 skill 也印证了这一立场——generate-skills.ts 中明确要求审计时"不要把alt=""默认当问题"，把<img ... alt="" aria-hidden="true">视为零问题安全模式（Zero-issue pattern）。

作为链接的图片：alt 描述链接目的地

当<img>被包在<a>里时，图片承担的是"链接"角色，屏幕阅读器朗读的是alt+ "链接"，因此 alt 应描述跳转目标而非视觉外观：

<!-- ❌ Bad: Describes appearance, not destination --> <a href="https://twitter.com/example"> <img src="twitter-logo.svg" alt="Blue bird logo"> </a> <!-- ✅ Good: Describes the link destination --> <a href="https://twitter.com/example"> <img src="twitter-logo.svg" alt="Follow us on Twitter"> </a>

文字图片：alt 逐字复刻图中文字

图片本身承载文字（logo、横幅、截图）时，alt 应逐字（verbatim）复刻其中的文字，让屏幕阅读器用户获得与视觉用户一致的内容：

<!-- ✅ Good: Alt reproduces the text shown in the image --> <img src="sale-banner.png" alt="Summer Sale — 50% off all items"> <!-- ✅ Good: Logo with company name --> <img src="logo.svg" alt="Acme Corp">

复杂图片（图表、示意图）：短 alt + 长描述

复杂视觉内容无法在一行 alt 内说清，策略是"简短 alt + 对所有用户可见的长描述"。文档给出的实现是用aria-describedby关联一个可见的figcaption：

<!-- Using aria-describedby to link to a visible description --> <figure> <img src="org-chart.png" alt="Company organisational chart" aria-describedby="org-chart-desc" > <figcaption id="org-chart-desc"> The chart shows three departments reporting to the CEO: Engineering (12 staff), Marketing (8 staff), and Operations (5 staff). </figcaption> </figure>

这种"可见描述 +aria-describedby"的组合是刻意设计：长描述放在<figcaption>里让所有用户都能读到（而非仅屏幕阅读器），aria-describedby则保证朗读顺序自然衔接。这也解释了源 MDX 中 relatedRules 字段 为何把figure-figcaption列为第一条关联规则——两条规则在复杂图片场景下天然成对出现。

框架落地：React 与 Next.js 示例

规则文档提供了两套框架级写法，核心思想是把"装饰性 → 空字符串"的决策固化进组件 API，从类型层面杜绝忘记传 alt。

React 组件封装（装饰性走decorative布尔开关）：

interface ImageProps { src: string alt: string decorative?: boolean } function AccessibleImage({ src, alt, decorative = false }: ImageProps) { return ( <img src={src} // Decorative images use empty string; informative images use descriptive text alt={decorative ? '' : alt} /> ) } // Usage <AccessibleImage src="hero.jpg" alt="Team members collaborating in a modern office" /> <AccessibleImage src="divider.png" decorative />

Next.js 版本（next/image强制要求alt，装饰图传""）：

import Image from 'next/image' // Next.js Image requires alt; use "" for decorative function HeroBanner() { return ( <> {/* Informative */} <Image src="/hero.jpg" alt="Product team celebrating a successful launch" width={1200} height={600} priority /> {/* Decorative */} <Image src="/wave-divider.svg" alt="" width={1200} height={60} aria-hidden="true" /> </> ) }

注意装饰图的alt=""与aria-hidden="true"同时出现——前者处理<img>语义，后者进一步抑制辅助树，两者并不冲突而是双保险（对应文档 Verification 一节中"SVG 图标 + 相邻文字标签时用aria-hidden"的原则在位图场景的延伸）。

Agent 视角：Check / Fix / Explain 三步提示

除了给人读的正文，该规则在 skills/alt-text/SKILL.md 中还以"Agent 可执行的指令"形式存在，包含四段机器可读提示。这是本仓库"规则同时服务人类和 AI Agent"设计的一部分。

Check（检查步骤）——扫描代码库中所有<img>元素，逐项验证：

1. 每个<img>都有alt属性（缺失即错误）；
2. 装饰性图片使用alt=""；
3. 信息性图片的描述传达图片含义，而非仅文件名；
4. 链接图片描述目的地；
5. 文字图片在 alt 中复刻文字。

命中以下任一项即应标记：无alt、alt与文件名相同（如alt="photo1.jpg"）、泛化值（alt="image"/alt="photo"）。

Fix（修复步骤）——对每张问题图片按角色执行：信息性图片描述其传达内容（alt="Bar chart showing 40% increase in sales Q3 2024"而非alt="chart"）；装饰性图片补alt=""；链接图片描述目的地；文字图片逐字复制图中文字；复杂图片用短alt+aria-describedby或可见说明。

Explain（解释话术）——面向用户解释 WCAG 2.1 SC 1.1.1 时强调：屏幕阅读器朗读 alt；alt="image"这类差值等于没有；装饰图必须显式alt=""，因为省略alt会导致部分屏幕阅读器朗读文件名。

这四段提示并非手工维护——它们正是源 MDX frontmatter 中prompts.check/prompts.fix/prompts.explain/prompts.codeReview字段（见 alt-text.mdx frontmatter）逐字落地的结果。

验证方法：自动化工具 + 手动检查

规则文档将验证拆为两条线。

自动化检查

• axe DevTools / WAVE：两者都会标记"缺失 alt"以及"非装饰性图片使用了空 alt"——注意它们能区分装饰图（空 alt 合法）与信息图（空 alt 违规）；
• Lighthouse 可访问性审计：Images do not have alternate text是计分项（scored item），意味着它会直接影响总分。

这三个工具的名称与链接同时登记在源 MDX 的tools字段 中，说明验证手段是规则定义的一部分，而非事后补充。

手动检查

• 启用屏幕阅读器（VoiceOver / NVDA / JAWS），用G键在图片间导航，逐一确认朗读内容；
• 在 Network 面板中任选一个图片 URL，回到 DOM 核对对应<img>是否有有意义的alt；
• CAPTCHA 图片：alt 应描述目的而非字符（如alt="CAPTCHA: type the characters shown"），并按 WCAG 1.1.1 提供语音替代方案；
• 带相邻文字标签的 SVG 图标：图标的含义已被可见文字表达时，对 SVG 使用aria-hidden="true"而不是 alt。

最后两条是规则文档中最容易被遗漏的边界案例：CAPTCHA 的"字符"本身不应被朗读（也不应被 alt 预先剧透），而"图标 + 文字"组合属于语义冗余，此时 alt 反而是多余的。

仓库中的生成链路：从 MDX 到 skills/alt-text

理解skills/alt-text/references/rule.md从何而来，能帮你判断该文档的可信边界：它不是手写副本，而是生成产物。

1. 唯一事实源是 packages/content/rules/en/images/alt-text.mdx——frontmatter 承载元数据（priority、tools、resources、prompts、tldr），正文承载上述全部技术内容；
2. 生成脚本scripts/generate/generate-skills.ts 读取该 MDX：buildSkillMd()（约 L88-L160）把tldr展开为 Quick Reference、把prompts四字段展开为 Check/Fix/Explain/Code Review 小节，产出 SKILL.md；buildReferencesMd()（约 L165-L186）把正文中的 MDX 组件（<Tip>、<CodeTabs>、<Tab>等 JSX）经stripMdxToMarkdown()剥离为纯 Markdown，产出references/rule.md——这解释了你在 rule.md 中看到的 Framework Examples 章节为何有连续空行（Tab 组件被剥离、代码块保留）；
3. 触发方式：根 package.json 中generate:skills脚本运行tsx scripts/generate/generate-skills.ts，支持全量生成和传入具体.mdx路径的增量模式，后者被 lefthook 在规则 MDX 变更时自动调用（见 scripts/README.md）；
4. 运行时消费：Web 端通过 apps/web/lib/rule-content.ts 的getRuleRawContent直接从磁盘读取 MDX 正文并剥离 frontmatter（带unstable_cache缓存），供规则详情页与/api/fix-suggestion?slug=alt-text这类接口使用。

由于references/rule.md由 MDX 正文转换而来，若发现两者表述差异，以 MDX 源文件为准，并按仓库文档（见 AGENTS.md）通过pnpm generate:skills重新生成。

关联规则与标准依据

源 MDX 的relatedRules字段声明了三条需要协同审查的规则：

• figure-figcaption：可见说明与 alt 在复杂图片上互补；
• error-images：图片加载失败的降级图同样需要 alt 才能保持可访问；
• dimensions：与 alt 一样作用于图片，常在同一次审查中一并处理。

文档 "Standards" 一节还要求：在认定规则满足之前，实现必须对照 MDN 的 Responsive images 与 web.dev 的 Image performance 两份权威参考核验——这两个 source 亦登记在 frontmatter sources 字段 中。

适用前提：本文所有结论以当前仓库的 alt-text 规则版本为准（priority=critical，Level A 合规项）；WCAG 2.1 SC 1.1.1 的判定语义（如"等效文本必须随图片缩放同步可用"）以 W3C 原文为最终依据，规则文档未覆盖的边界（如 SVG 内部<title>与 alt 的取舍）建议在具体项目中单独核实。

【免费下载链接】Front-End-Checklist🗂 The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist