opquast-digital-quality

Opquast 数字质量最佳实践

权威来源：mgifford/ACCESSIBILITY.md 中的 examples/OPQUAST_DIGITAL_QUALITY_BEST_PRACTICES.md 此技能源自该文件。如有疑问，请以示例为准。

构建或审查 Web 项目时，请应用 Opquast 数字质量检查清单 （第 5 版，2025-2030）。该框架包含 245 条规则，分为 14 个类别，涵盖内容、隐私、电子商务、 表单、无障碍、安全、性能等方面。

规则采用 Creative Commons BY-SA 4.0 许可发布。 Agent 可以引用规则文本；请注明 Opquast，并遵守相同方式共享许可——衍生作品必须使用相同许可。 权威来源请参阅 opquast.com。

---

严重程度等级（本技能）

等级	含义
严重	完全阻碍某一用户群体访问、购买或完成任务
较严重	显著影响访问或可用性；不应要求用户采用不合理的变通方式
中等	造成使用障碍；虽然有变通方式，但较为繁琐
轻微	未达到最佳实践；影响较小

各类别的严重程度参考：

• 安全问题（HTTPS、标头、密码）：严重至较严重
• 表单问题（标签、错误处理）：严重至较严重
• 导航问题（键盘、焦点）：严重至较严重
• 图像/媒体缺少替代文本/字幕：严重
• 隐私政策缺失：较严重
• 呈现对比度：较严重；缩放受阻：较严重
• 内容、链接、身份识别：多数情况下为中等至轻微
• 服务器/性能、新闻简报、国际化：多数情况下为轻微

---

何时使用此技能

• 构建新网站或 Web 应用程序
• 审查或审核现有网站的质量
• 实现无障碍、安全或隐私功能
• 创建电子商务流程、表单或导航系统
• 生成必须符合质量标准的 HTML/CSS 代码

---

按类别快速参考（14 个类别，共 245 条规则）

类别	规则	关键要求
内容	1–14	元数据（描述和 OG 标签）、明确的日期、缩略语使用 <abbr>、图表使用数据表格、广告明确标注、内容审核／滥用举报机制
个人数据／隐私	15–29	页脚提供隐私链接、记录数据访问／修改流程、不能只提供第三方登录、使用通用的身份验证失败提示、Referrer-Policy、敏感数据使用 HTTPS、URL 中不得包含敏感数据
电子商务	30–68	不预先勾选加入选项、结账前提供库存情况／配送时间／费用、明确标价并包含税费、提供两种或以上支付方式、发送订单确认邮件、可在线获取发票
表单	69–98	使用 <label for="...">、提示格式／大小写敏感要求、在文本中标明必填项、提供密码强度提示及显示／隐藏功能、aria-invalid、aria-describedby、出错时保留数据、正确设置 input type／autocomplete、不阻止粘贴、禁用按钮不得设置 aria-hidden
身份标识	99–115	页面标题唯一（页面 | 网站）、lang 属性、网站图标、页脚提供地址／电话、提供两种或以上联系方式、注明响应时间／服务时间
图像／媒体	116–127	提供有意义的 alt、装饰性图像使用空 alt=""、图像链接的 alt 描述目标位置、提供文字稿和同步字幕、不自动播放、媒体可暂停
国际化	128–135	提供国际拨号代码、地址中包含国家／地区、使用 hreflang／显示语言标识、在 <html> 上以及语言变更的行内元素上设置 lang、翻译语言链接标签
链接	136–152	锚文本应有描述性（不使用“点击这里”）、使用 tel: 协议、提示将在新标签页打开、下载项标明文件类型和大小、不含失效的站内链接
导航	153–172	无需强制登录即可访问公开内容、不弹出导航窗口、提供首页链接、面包屑导航、导航位置一致、图标旁显示标签、提供跳过链接、:focus-visible 清晰可见、Tab 顺序合理、站内搜索、网站地图
新闻简报	173–179	确认订阅、提供取消订阅链接、支持一键取消订阅、在线提供往期内容、注明发送频率
呈现	180–196	视觉标识一致、不仅依赖颜色传递信息、对比度：普通文本为 4.5:1／大号文本为 3:1、关闭样式后含义仍清晰、触控目标至少为 24×24px、不得阻止缩放、响应式布局、打印样式
安全	197–217	全站使用 HTTPS 并启用 HSTS、无混合内容、支持自助重置密码、不以明文存储密码、X-Content-Type-Options、X-Frame-Options／frame-ancestors、CSP、第三方脚本使用 SRI、不暴露服务器版本、SPF/DKIM/DMARC
服务器／性能	218–230	robots.txt、sitemap.xml、返回正确的 404 状态码（而非 200）、带导航的自定义错误页、gzip/Brotli、缓存控制标头、压缩 CSS/JS
结构／代码	231–244	使用机器可读的日期（<time datetime>）、UTF-8、ID 唯一、不使用 meta refresh、标题层级为 h1>h2>h3、PDF 添加标签（而非扫描件）、数据表格使用 <caption>／<th scope>

---

工作流

1. 确定适用类别

并非所有 14 个类别都适用于每个项目：

• 所有 Web 项目：内容、表单、身份标识、图像／媒体、链接、 导航、呈现、安全、服务器／性能、结构／代码
• 按需添加：电子商务（在线销售）、新闻简报（电子邮件营销）、 国际化（多语言）、个人数据／隐私（用户账户／数据收集）

2. 查阅完整规则文本

如需查看完整规则文本、代码示例和规则编号，请直接查阅 Opquast 权威指南 或官方检查清单； 此技能概述了各类别和最重要的模式，而非逐字复述全部 245 条规则。

3. 在开发过程中应用

生成或审查代码时，将规则作为实现要求：

• HTML 生成：包含元数据、语义化结构、无障碍表单和恰当的替代文本
• CSS 生成：确保对比度、焦点样式、响应式布局和打印样式
• 服务端配置：设置安全标头、启用压缩、配置缓存
• 内容审查：检查日期格式、链接文本和缩写展开

4. 验证

实现后，根据适用规则进行验证。常见的自动化检查包括：

• HTML 验证和标题层级
• 颜色对比度（普通文本为 4.5:1，大号文本为 3:1）
• 是否缺少 alt 属性
• 是否缺少表单标签
• 是否存在安全标头
• 是否存在失效的内部链接

---

必要的代码模式

页面模板最低要求

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <meta name="description" content="Page description here." />
  <meta property="og:title" content="Page Title | Site Name" />
  <meta property="og:description" content="Page description for sharing." />
  <title>Page Title | Site Name</title>
  <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
</head>
<body>
  <a href="#main" class="skip-link">Skip to main content</a>
  <nav aria-label="Main navigation"></nav>
  <main id="main"></main>
  <footer>
    <a href="/privacy">Privacy Policy</a>
    <a href="/terms">Terms of Use</a>
  </footer>
</body>
</html>

无障碍表单字段

在原生输入元素上使用原生的 required。如果已存在 required，aria-required 就是冗余的，应予以省略，以免无障碍树产生多余信息（规则 98 的原则：不要添加与原生语义重复的 ARIA 状态）。 仅在自定义控件（如 role="combobox"）上使用 aria-required。同时，应在可见文本中说明必填状态——仅用星号是不够的，除非已解释其含义（规则 71）。

<label for="email">
  Email address <span aria-hidden="true">*</span> <span class="hint">(required)</span>
  <span class="hint" id="email-hint">Example: [email protected]</span>
</label>
<input id="email" type="email" autocomplete="email"
  required aria-describedby="email-hint" />

密码字段（规则 75–76、202–205）

<label for="password">Password</label>
<div class="password-wrapper">
  <input id="password" type="password" aria-describedby="password-hint" />
  <button type="button" aria-controls="password" aria-pressed="false">
    Show password
  </button>
</div>

安全标头（服务端配置）

Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
X-Content-Type-Options: nosniff
X-Frame-Options: SAMEORIGIN
Content-Security-Policy: default-src 'self';
Referrer-Policy: strict-origin-when-cross-origin

不要在响应标头中暴露服务端软件版本（规则 213）——移除或混淆 Server 和 X-Powered-By。对第三方脚本和样式表应用子资源完整性（规则 214）：

<script src="https://cdn.example.com/library.min.js"
  integrity="sha384-<hash>" crossorigin="anonymous"></script>

焦点和对比度样式

:focus-visible {
  outline: 3px solid #005fcc;
  outline-offset: 2px;
}
body {
  color: #1a1a1a; /* ~16:1 contrast on white */
  background: #ffffff;
}

打印样式

@media print {
  nav, header, footer, .sidebar, .no-print { display: none; }
  body { font-size: 12pt; color: #000; }
  a[href]::after { content: " (" attr(href) ")"; }
}

无障碍数据表格（规则 242–243）

<table>
  <caption>Quarterly revenue by region (USD thousands)</caption>
  <thead>
    <tr><th scope="col">Region</th><th scope="col">Q1</th></tr>
  </thead>
  <tbody>
    <tr><th scope="row">North America</th><td>1,200</td></tr>
  </tbody>
</table>

---

与 WCAG 的关系

Opquast 是对 WCAG 2.2 的补充，而非替代。主要对应关系如下：

Opquast 规则	WCAG 标准
116（装饰性图像 alt=""）	1.1.1 非文本内容（A）
117-118（有意义的替代文本）	1.1.1 非文本内容（A）
121-122（文字稿、字幕）	1.2.2、1.2.3、1.2.5
124-127（不自动播放、可暂停）	1.4.2、2.2.2
131-132（lang 属性）	3.1.1、3.1.2
164（跳过链接）	2.4.1 绕过区块（A）
165（焦点可见）	2.4.7、2.4.11 焦点可见/外观
166（可通过键盘操作）	2.1.1 键盘（A）
167（逻辑合理的 Tab 顺序）	2.4.3 焦点顺序（A）
181（不只依赖颜色）	1.4.1 颜色的使用（A）
182（对比度）	1.4.3、1.4.6、1.4.11 对比度
186（触控目标最小为 24×24px）	2.5.8 目标尺寸最小值（AA，WCAG 2.2）
193（不禁止缩放）	1.4.4 调整文本大小（AA）
69-70（标签、说明）	1.3.1、3.3.2
79-80（错误识别）	3.3.1、3.3.3

将 Opquast 用作整体质量基准，并结合 WCAG 测试，以全面符合无障碍要求。

---

与可持续性的关联

Opquast 的多个类别与 SUSTAINABILITY.md 以及 Web Sustainability Guidelines 直接相关：

• 服务端/性能（规则 226-230）：压缩、缓存、缩小文件——直接减少每次页面浏览的数据传输量和能耗
• 呈现（规则 193）：不禁止缩放；（规则 194）：响应式布局——减少创建独立移动网站的需求
• 结构/代码（规则 239）：不使用 meta refresh——避免不必要的页面重新加载

应用 Opquast 服务端/性能规则时，请参考 SUSTAINABILITY.md，了解有关碳感知交付和资源优化的更多指导。

完成标准检查清单

适用于每个项目；不适用的类别可跳过：

内容与标识

• 每个页面都包含 <meta name="description"> 和 OG 标签
• 标题唯一，格式为 Page | Site
• 存在且正确设置 <html lang="...">
• 存在 <link rel="icon">
• 页脚包含隐私政策链接
• 至少提供两种联系方式

表单

• 每个字段都有通过程序关联的 <label>
• 使用原生 required；原生输入框不使用 aria-required
• 通过可见文本标明必填状态，而非仅用星号或颜色表示
• 对无效字段设置 aria-invalid="true"
• 通过 aria-describedby 关联错误消息；出错时保留之前填写的数据
• input type 和 autocomplete 的值正确
• 不阻止粘贴；不通过 aria-hidden 隐藏禁用按钮

图像与媒体

• 装饰性图像使用 alt=""
• 信息性图像使用描述性 alt；图像链接应描述目标位置
• 所有视频都配有同步字幕
• 所有音频都提供文字稿
• 不自动播放音频或视频；所有媒体均可暂停

导航与键盘

• 提供有效的跳转链接
• 定义 :focus-visible 样式；除非提供替代样式，否则不使用 outline: none
• 所有内容均可通过键盘操作；Tab 顺序符合逻辑
• 提供面包屑或等效的位置指示

呈现

• 普通文本的对比度 ≥ 4.5:1；大号文本和 UI 组件的对比度 ≥ 3:1
• 不单独依靠颜色传达信息
• 不使用 user-scalable=no 和 maximum-scale
• 触控目标 ≥ 24×24px（建议 44×44）
• 打印样式应隐藏导航，并显示链接 URL

安全

• 所有页面均使用 HTTPS；HTTP 请求重定向到 HTTPS；没有混合内容
• 存在 HSTS 标头
• 存在 X-Content-Type-Options: nosniff
• 存在 X-Frame-Options 或 CSP frame-ancestors
• 存在 CSP 标头
• 所有第三方脚本和样式表均使用 SRI
• 不公开服务器或框架版本标头

服务器/性能

• 存在 robots.txt 和 sitemap.xml
• 缺失页面返回正确的 404 状态（而非 200）
• 启用压缩（gzip 或 Brotli）
• 静态资源设置缓存控制标头
• CSS 和 JS 已压缩

结构/代码

• 每个 <head> 中都包含 <meta charset="UTF-8">
• 页面内没有重复的 id 属性
• 不使用 <meta http-equiv="refresh">
• 标题层级正确（h1 > h2 > h3，不跳级）
• 数据表格包含 <caption> 和 <th scope="...">
• 内部 PDF 已添加标签（文本可选中），而非扫描图像

---

WCAG 关键标准

请参阅上方的 WCAG 关系表。Opquast 涵盖了 WCAG 2.2 AA 的全部要求，并进一步扩展至安全、隐私、电子商务和性能领域。

---

参考资料

• 最佳实践完整指南
• Opquast 数字质量检查清单 — CC-BY-SA 4.0；引用规则文本时可注明出处
• opquast.com — 权威来源、培训与认证
• TRUSTED_SOURCES.yaml — id: opquast、id: opquast-checklist
• SUSTAINABILITY.md — 服务器/性能规则与 WSG 一致

标准规划周期： 这些规则以 WCAG 2.2 AA 和 Opquast v5 （2025-2030）为目标。WCAG 3.0 正在制定中。 请关注：https://www.w3.org/TR/wcag-3.0/