Front-End-Checklist 实战指南构建符合 WCAG 2.2 SC 3.3.8 的无障碍认证流程autocomplete、OTP 自动填充与 Passkey 路径【免费下载链接】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 仓库中的无障碍认证规则rule.md系统讲解如何设计登录、MFA 与账户恢复流程使其兼容密码管理器、粘贴、OTP 自动填充与 Passkey而不依赖用户的记忆或誊写能力。读完后你将掌握autocomplete令牌username webauthn、current-password、one-time-code的正确用法、可直接复制的 HTML 与 React 代码示例、自动化与手动验证清单以及 WCAG 2.2 SC 3.3.8 对非记忆依赖路径的具体要求。规则定位与元信息在本仓库的规则体系中Provide accessible authentication methods 是一条高优先级、进阶难度的认证可访问性规则核心断言只有一句话认证流程应避免不必要的认知测试并支持密码管理器、粘贴、OTP 自动填充和 Passkey 等辅助机制。规则元数据优先级 high / 难度 advanced / 预计耗时 25 分钟在两个文件中保持一致技能入口 SKILL.md 的 frontmatter以及规则正文 rule.md 的头部声明。技能文件还声明了它的适用边界用于审查登录、注册、MFA、CAPTCHA、恢复与重新认证re-auth流程且要求评估完整的认证路径含错误处理与备用方式而不只是主登录表单。仓库中对应的完整规则定义位于 accessible-authentication.mdx其 frontmatter 标注了三个分类维度accessibility / security / html、表单子分类以及三条权威资料来源资料来源类型角色WCAG 2.2 SC 3.3.8 Accessible Authentication (Minimum)wcagstandard标准依据W3C Understanding SC 3.3.8wcagimplementation实现指导MDN HTML autocomplete attributemdnreference属性参考从 frontmatter 的relatedRules结构看这条规则与四条相邻规则显式关联构成一个认证可访问性审查簇paste-inputs.mdx阻止粘贴是认证流程中最常见的直接违规点password-field-security.mdx密码字段语义、显示切换与密码管理器支持form-captcha.mdx反滥用控制往往是合规替代路径断裂之处session-timeout-recovery.mdx会话过期后的重新认证与恢复仍需可用。核心原理为什么反认知测试会同时提升安全原文档给出的论点是当存在可行的辅助路径时认证不应依赖用户记忆、誊写或手工复现信息的能力。好的无障碍认证通常同时提升安全性——因为它与密码管理器、基于设备的验证和 Passkey 协作而不是与它们对抗。原文档列出了典型的不必要的摩擦模式阻止粘贴blocked paste自研 OTP 输入组件破坏了标准自动填充要求誊写的 CAPTCHA用备份问题式的记忆证明替代基于持有物possession-based的验证。这些摩擦的实际代价包括认知障碍在用户做任何事情之前就先阻断了账户访问对密码管理器不友好会诱发更弱、被复用的密码语音输入、切换设备、纯键盘用户在被禁用复制/粘贴和自动填充时付出更多操作成本恢复流程和 MFA 步骤经常失败——哪怕主登录表单本身看起来没问题。代码示例密码管理器与 OTP 友好的字段下面完整继承原文档的三段示例代码。第一段是登录 OTP 场景的标准字段写法!-- Better: password-manager and OTP-friendly fields -- label foremailEmail/label input idemail nameemail typeemail autocompleteusername webauthn label forpasswordPassword/label input idpassword namepassword typepassword autocompletecurrent-password label forotpVerification code/label input idotp nameotp inputmodenumeric autocompleteone-time-code三个字段各对应一个关键的autocomplete令牌autocompleteusername webauthn用户名字段。webauthn令牌多令牌空格分隔是合法写法提示浏览器此用户标识可用于 Passkey/WebAuthn 注册与登录让支持 WebAuthn 的浏览器把该用户与 Passkey 凭据关联起来这是非记忆依赖路径的前置语义autocompletecurrent-password登录密码字段。密码管理器据此识别这是要取回已存密码的场景与注册场景的new-password区分后者在 password-field-security.mdx 中有进一步说明autocompleteone-time-code配合inputmodenumeric一次性验证码字段。one-time-code令牌是现代浏览器/OS 对 SMS 验证码与邮件代码自动填充的识别依据inputmodenumeric则让移动端直接弹出数字键盘减少误输入。第二段是 React 组件写法注意autoComplete、inputMode是 React 的驼峰属性名且保留了单输入框而非拆分为六个格子function VerifyCodeField({ onSubmit, }: { onSubmit: (code: string) void }) { return ( form onSubmit{(event) { event.preventDefault() const formData new FormData(event.currentTarget) onSubmit(String(formData.get(otp) ?? )) }} label htmlForotpEnter the verification code/label input autoCompleteone-time-code idotp inputModenumeric nameotp typetext / button typesubmitContinue/button /form ) }从源码结构看这个示例刻意用FormData从整个表单取值意味着提交逻辑不依赖具体的输入控件结构——即使未来浏览器改变 OTP 自动填充的注入方式例如写入隐藏字段或触发input事件new FormData(event.currentTarget)仍能以标准方式拿到值。typetext而非typetel也是有意为之文本类型对自动填充兼容面更广数字键盘由inputMode单独控制。第三段是非记忆依赖替代路径的最小呈现——两个并列按钮!-- Better: offer a non-memory-dependent alternative -- button typebuttonContinue with a passkey/button button typebuttonEmail me a sign-in link/buttonPasskey基于 WebAuthn 的凭据与 magic link邮件签到链接分别对应基于设备的证明与发送到可信邮箱两种路径二者都不要求用户记忆或誊写任何信息。最佳实践一支持辅助输入assisted entry原文档要求认证流程必须与以下机制协同工作密码管理器password managers粘贴的凭据与验证码pasted credentials and codes操作系统/浏览器 OTP 自动填充OS/browser OTP autofill可用时的 Passkey 或设备审批device approval。并给出一条硬约束不要把一个一次性验证码拆进会破坏标准自动填充的自定义组件中除非你已在真实浏览器中验证过行为。这条约束在仓库的相邻规则中有直接佐证。paste-inputs.mdx 明确列出了三类阻止粘贴的反模式并给出对应的正面写法!-- Incorrect: Prevents pasting -- input typepassword onpastereturn false; placeholderConfirm Password !-- Correct: Default behavior allows pasting -- label forconfirm-passwordConfirm Password/label input typepassword idconfirm-password nameconfirm-password !-- Incorrect JavaScript -- script document.querySelector(#email).addEventListener(paste, (e) { e.preventDefault(); // Dont do this }); /script该规则同样以 WCAG 2.2 SC 3.3.8 为第一来源其给出的理由链与本篇一致阻止粘贴会劝退使用长而唯一的密码管理器生成密码精细运动控制受限的用户难以准确敲入长字符串粘贴还降低了 IBAN、订单号等关键字段的键入错误率。因此支持粘贴与支持自动填充应视为同一项认证可访问性要求的两个侧面。最佳实践二至少一条不依赖记忆的路径原文档要求在登录、MFA、恢复三个环节中至少有一条可行路径不依赖认知功能测试cognitive function test。被点名的合格路径有四类路径机制用户依赖PasskeyWebAuthn 凭据 设备生物识别/PIN持有可信设备可信设备审批推送审批device approval持有第二设备Magic link一次性链接发送到邮箱/手机持有可信邮箱密码管理器辅助正确autocomplete语义下的自动填充已配置的密码管理器注意这条要求覆盖的是整条认证链路即使主登录表单完全合规如果 MFA 第二步只有一条记住我 12 年前的安全答案的路径整条流程仍不满足规则。这也是技能文件中评估完整认证路径包括错误处理和备用方式这一边界声明的落地含义。最佳实践三反滥用控制的相称性proportionality原文档的表述是如果在认证流程中使用 CAPTCHA 或其他滥用缓解手段必须提供一条不强制记忆或誊写的替代路径。可访问性与防滥用不是相互竞争的目标而是需要共同设计。仓库将这一交叉点显式编码在规则关联关系中form-captcha.mdx 被列为本规则的相关规则关联理由引自 accessible-authentication.mdx 的 frontmatter是反滥用控制往往正是合规替代认证路径断裂的地方。实操含义是审查 CAPTCHA 组件时除检查组件本身的可达性外还要回答如果用户无法通过该 CAPTCHA是否存在另一条完成认证的合规路径标准映射WCAG 2.2 SC 3.3.8 与例外本规则映射到WCAG 2.2 Success Criterion 3.3.8 Accessible Authentication (Minimum)。原文档特别澄清了一个常见误解实际目标不是更少的安全而是至少一条不依赖认知功能测试的可行路径。原文档给出三条例外边界Exceptions审查时不应误报重复输入新密码当系统不会把用户刚输入的密码回显给其本人时确认密码式的重新输入是有效的安全例外SC 3.3.8 的 c 条款精神即不能简单重做/重输新输入的内容MFA 与本规则兼容但用户仍需至少一条不依赖记忆或誊写的实用路径无障碍不要求移除安全控制而是要求选择用户实际能完成的安全控制。验证清单自动化检查 手动检查自动化检查Automated Checks原文档给出的两条静态/自动化检查方向在认证流程代码中搜索阻止粘贴的事件处理器onpastereturn false、paste事件的preventDefault()、自定义 OTP 拆分组件、缺失autocomplete属性的认证字段校验username、current-password、new-password、one-time-code四类字段是否使用了恰当的自动填充语义。用 ripgrep 风格的模式表达第一条检查可以落地为# 在认证相关目录中搜索阻止粘贴的处理器 rg -n onpaste\s*|paste|\\paste\\ auth/ # 搜索缺失 autocomplete 的认证输入 rg -n type\(password|email|tel)\ -g !*.test.* auth/以上为本仓库文档给出的检查思路的代码化表达具体目录按项目结构调整。手动检查Manual Checks原文档列出的四条人工验证步骤构成一条完整的验收清单用密码管理器测试签到——自动填充应命中用户名和密码两个字段粘贴一个 OTP或在浏览器支持时让它自动填充——单输入框 one-time-code语义下这一步应当零成本完成演练恢复流程和 MFA 流程而不只是主登录表单——这是最常被漏测的部分判定失败的判据如果唯一可用路径要求用户记忆、誊写或解答认知测试且不存在辅助替代路径则检查不通过。仓库中的配套工件与延伸阅读围绕这条规则仓库维护了三类配套工件可用于持续工程化上述清单技能Skill工件SKILL.md 定义了面向 Agent 的 Quick Reference / Check / Fix / Explain / Code Review 五段式工作流把人工清单转化为可重复执行的审查提示rule.md 则是其中完整实现细节、代码示例与框架级指导的引用文件即本文的主体来源规则源文档Source of Truthaccessible-authentication.mdx 包含规则的完整元数据、资料来源sources与相关规则图relatedRules是规则站点化与工具化消费的入口关联规则paste-inputs.mdx、password-field-security.mdx、form-captcha.mdx、session-timeout-recovery.mdx 分别覆盖粘贴权限、密码字段安全、CAPTCHA 相称性与会话恢复四者与本篇规则共同构成认证流程的完整可访问性审查面。小结无障碍认证的工程化落点可以压缩为四件事——为每个认证字段写对autocomplete语义、保持 OTP 单输入框可粘贴可自动填充、在登录/MFA/恢复链路上各保留一条 Passkey 或 magic link 式的非记忆路径、把 CAPTCHA 的替代路径纳入与主流程同等强度的验证。满足这四点后流程在 WCAG 2.2 SC 3.3.8 意义上的合规性与在真实用户群体的完成率应当同步提升——这正是原文档无障碍与防滥用共同设计论断的实践含义。【免费下载链接】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），仅供参考