webflow-mcp:accessibility-audit

Name: webflow-mcp:accessibility-audit
Author: webflow

github.com/webflow测试与质量133900 次安装今天更新

代码仓库

关于 webflow-mcp:accessibility-audit

这是面向 Webflow 页面的 WCAG 2.1 无障碍审计技能，可检查交互元素、表单和键盘访问问题，并按严重程度提供修复建议。它还可在批准后通过属性修改应用部分修复。

主要功能

01检查按钮、表单与链接
02分析键盘访问和焦点可见性
03检查标题层级及 ARIA 属性
04按严重程度分类并计分
05经批准后修改元素属性

适用场景

01审查页面的 WCAG 无障碍问题
02定位缺少标签的表单控件
03检查交互元素的键盘访问
04修复已确认的属性问题

MCP 相关

该技能要求通过 Webflow MCP 工具读取站点、页面和元素，并可使用元素工具设置属性以应用获准的修复。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/webflow/webflow-skills --skill webflow-mcp:accessibility-audit

安装后在 Claude Code 中输入/webflow-mcp:accessibility-audit确认已加载。

详细介绍

无障碍审计

针对 Webflow 页面进行全面的 WCAG 2.1 无障碍审计，详细检测问题并提供可执行的修复方案。

重要说明

所有操作都必须使用 Webflow MCP 工具：

开始前，使用 Webflow MCP 的 webflow_guide_tool 获取最佳实践
使用 Webflow MCP 的 data_sites_tool，并将 action 设为 list_sites，识别可用站点
使用 Webflow MCP 的 data_sites_tool，并将 action 设为 get_site，获取站点详情
使用 Webflow MCP 的 data_pages_tool，并将 action 设为 list_pages，获取所有页面及其页面 ID
使用 Webflow MCP 的 data_element_tool，并将 action 设为 get_all_elements（直接传入页面 ID），获取详细的元素信息
使用 Webflow MCP 的 data_element_tool，并将 action 设为 set_attributes，修复无障碍问题
使用 Webflow MCP 的 element_snapshot_tool 获取元素的视觉预览——这是一个 Designer 工具，如需使用则必须连接 Designer
Webflow 操作不得使用任何其他工具或方法
所有工具调用都必须包含必需的 context 参数（15–25 个单词，使用第三人称视角）
审计或修复无需连接 Designer。 data_element_tool 可直接对 list_pages 中任意页面 ID 进行无头操作。只有在选择使用 element_snapshot_tool 获取可选的视觉预览时，才需要 Designer。

说明

阶段 1：站点和页面选择

获取站点信息：使用 Webflow MCP 的 data_sites_tool，并将 action 设为 list_sites，识别目标站点
询问页面选择：
- 如果用户提供了页面 ID，直接使用
- 否则，使用 data_pages_tool，并将 action 设为 list_pages，展示可用页面
- 让用户选择要审计的页面
确认审计范围：询问用户要检查哪些内容：
- 全面审计（所有无障碍检查）
- 仅检查关键问题（WCAG A 级）
- 指定类别（表单、按钮、导航等）

阶段 2：元素提取与分析

提取所有元素：使用 data_element_tool，并将 action 设为 get_all_elements，传入阶段 1 中目标页面的 ID，以便进行详细分析——无需连接 Designer
- 设置 include_style_properties: true，检查焦点样式
- 设置 include_all_breakpoint_styles: false，尽量减少数据量
解析元素数据：识别交互元素和内容元素：
- 按钮（Button、具有 button 角色的 LinkBlock）
- 链接（TextLink、Link、LinkBlock）
- 表单输入项（Input、Select、Textarea）
- 标题（带级别的 Heading 元素）
- 交互式 div/span（检查是否有 onClick 或交互角色）
- 图片（Image 元素）——本次审计跳过
提取每个元素的属性：
- ARIA 属性（aria-label、aria-describedby、role、tabIndex）
- DOM 属性（id、domId、href、type、placeholder）
- 文本内容
- 样式属性（焦点状态下的 outline、border）
- 元素元数据（canHaveAttributes、标签名称）

阶段 3：无障碍检查

严重问题（必须修复 - WCAG A 级）

仅含图标且没有标签的按钮（WCAG 4.1.2）
- 查找：没有文本内容的按钮元素
- 检查：是否缺少 aria-label 或 aria-labelledby
- 影响：屏幕阅读器无法识别按钮的用途
- 修复：添加包含描述性文本的 aria-label 属性
没有标签的表单输入项（WCAG 1.3.1）
- 查找：Input、Select、Textarea 元素
- 检查：是否缺少关联的标签或 aria-label
- 影响：用户不知道输入项的用途
- 修复：添加 aria-label，或使用 id 将输入项与 <label> 关联
非语义化的点击处理程序（WCAG 2.1.1）
- 查找：Div 或 Span 元素（根据元素类型识别）
- 检查：是否存在交互行为，但缺少正确的角色或键盘支持
- 影响：无法通过键盘访问，屏幕阅读器无法识别其交互性
- 修复：添加 role="button"、tabIndex="0"，建议改用真正的 <button>
没有目标地址的链接（WCAG 2.1.1）
- 查找：没有 href 属性的 Link 元素
- 检查：是否存在只使用 onClick、不含 href 的链接
- 影响：无法通过键盘访问，且会破坏浏览器功能
- 修复：添加正确的 href，或将其转换为按钮

严重问题（应修复 - WCAG AA 级）

移除焦点轮廓但没有替代样式（WCAG 2.4.7）
- 查找：带有 outline: none 样式的元素
- 检查：是否没有可见的替代焦点指示器
- 影响：键盘用户无法看到焦点位置
- 修复：添加可见的焦点样式（边框、box-shadow、背景变化）
缺少键盘事件处理程序（WCAG 2.1.1）
- 查找：带有 onClick 处理程序的元素
- 检查：是否缺少用于 Enter/Space 按键的 onKeyDown
- 影响：无法仅使用键盘操作
- 修复：添加键盘事件处理程序
触控目标过小（WCAG 2.5.5）
- 查找：可点击元素（按钮、链接）
- 检查：宽度或高度是否 < 44px
- 影响：在移动设备上难以点击
- 修复：增加内边距，或将 min-width/min-height 增至 44px

中等问题（可考虑修复）

标题层级问题（WCAG 1.3.1）
- 查找：标题元素（h1-h6）
- 检查：是否跳过层级（h1 → h3，跳过 h2）
- 影响：文档结构令人困惑
- 修复：按顺序使用正确的标题层级
正数 tabIndex（WCAG 2.4.3）
- 查找：tabIndex > 0 的元素
- 检查：是否扰乱了自然的 Tab 顺序
- 影响：键盘导航令人困惑
- 修复：仅使用 tabIndex="0" 或 "-1"，让 DOM 的自然顺序发挥作用
角色缺少必需属性（WCAG 4.1.2）
- 查找：带有 ARIA 角色的元素
- 检查：是否缺少必需的 ARIA 属性（例如，role="button" 却没有 tabIndex）
- 影响：无障碍语义不完整
- 修复：为角色添加必需属性

阶段 4：问题分类与评分

对所有发现的问题进行分类：
- 严重：必须修复（阻碍访问）
- 高：应修复（严重影响可用性）
- 中等：可考虑修复（改善体验）
计算无障碍评分（0-100）：
- 从 100 分开始
- 每个严重问题：扣 10 分
- 每个高优先级问题：扣 5 分
- 每个中等问题：扣 2 分
- 最低分：0
生成严重性摘要：
- 发现的问题总数
- 按严重性分类统计
- 最常见的问题类型
- 受影响最严重的页面/版块

阶段 5：生成报告

创建详细报告，采用以下具体格式：

═══════════════════════════════════════════════════
无障碍审查：[页面名称]
═══════════════════════════════════════════════════

严重（X 个问题）
───────────────────
[A11Y] 元素：按钮“提交”
  问题：按钮缺少可访问名称
  位置：表单区域，元素 ID：{component: "abc", element: "xyz"}
  当前：<button><CloseIcon /></button>
  修复：添加 aria-label="Close"
  WCAG：4.1.2 名称、角色、值

[A11Y] 元素：输入框
  问题：表单输入框没有标签
  位置：联系表单，元素 ID：{component: "def", element: "uvw"}
  当前：<input type="email" />
  修复：添加 aria-label="Email address" 或与 <label> 关联
  WCAG：1.3.1 信息和关系

较严重（X 个问题）
──────────────────
[A11Y] 元素：链接“阅读更多”
  问题：焦点轮廓被移除，且没有可见的替代样式
  位置：博客区域
  当前：outline: none
  修复：添加可见的焦点样式（例如：border: 2px solid blue）
  WCAG：2.4.7 焦点可见

中等（X 个问题）
───────────────────
[A11Y] 元素：标题
  问题：标题层级跳级（h1 → h3）
  位置：文章区域
  当前：<h1>Title</h1> 后接 <h3>Subsection</h3>
  修复：改为 <h2>，或添加中间层级的 h2
  WCAG：1.3.1 信息和关系

═══════════════════════════════════════════════════
摘要
───────────────────────────────────────────────────
问题总数：X
- 严重：X 个问题
- 较严重：X 个问题
- 中等：X 个问题

无障碍评分：XX/100

最常见的问题：
1. [问题类型] - X 次
2. [问题类型] - X 次
3. [问题类型] - X 次
═══════════════════════════════════════════════════

提供可执行的建议：
- 按优先级排列的修复清单（先处理严重问题）
- 快速见效项（易于修复且影响显著）
- 设计模式建议
- 深入学习的资源

阶段 6：修复建议与审批（可选）

主动提出自动修复问题：修复不需要 Designer，因此可以直接提供自动修复

显示修复预览：

你想修复哪些问题？

[1] ✓ 为提交按钮添加 aria-label
    元素：联系表单中的按钮
    修复：添加 aria-label="Submit contact form"
    安全：是（仅添加属性）

[2] ✓ 为电子邮件输入框添加 aria-label
    元素：联系表单中的输入框
    修复：添加 aria-label="Email address"
    安全：是

[3] ⚠️ 修复标题层级
    元素：文章区域中的 h3
    修复：将标题级别从 h3 改为 h2
    安全：可能影响视觉样式

输入要跳过的问题编号（例如“3”），“all”表示全部，“none”表示取消

应用已批准的修复：使用 data_element_tool，操作为 set_attributes
- 分批处理
- 对大量修复显示进度
- 报告每项修复的成功或失败
生成修复后的报告：
- 已修复的问题：X
- 剩余问题：Y
- 新的无障碍评分：XX/100（较 YY/100 有所提高）

阶段 7：导出与资源（可选）

提供导出格式：
- Markdown（易读的文档）
- JSON（便于机器读取和跟踪）
- CSV（供团队审查的电子表格）
提供资源：
- WCAG 2.1 速查链接
- Webflow 无障碍最佳实践
- 推荐的测试工具（浏览器扩展、屏幕阅读器）

重要注意事项

此技能检查的内容

✅ 按钮的无障碍性（标签、角色） ✅ 表单输入框的标签及其关联关系 ✅ 链接语义和键盘访问 ✅ 焦点可见性和键盘导航 ✅ 标题层级和结构 ✅ ARIA 角色和属性 ✅ 触控目标尺寸 ✅ 交互元素语义

此技能不会检查的内容

❌ 图片替代文本（请改用 asset-audit 技能） ❌ 颜色对比度（需要进行视觉分析） ❌ 动画／动态效果偏好 ❌ 屏幕阅读器测试（需要手动验证） ❌ 内容可读性（语言难度、清晰度）

局限性

无法检测仅凭视觉才能发现的问题（颜色对比度、小字号文本）
无法测试屏幕阅读器的实际行为
无法验证内容的质量或清晰度
仅依赖元素属性和结构

示例

示例 1：完整页面审核

用户提示词：

Run an accessibility audit on my homepage

步骤 1：选择站点和页面

🔍 Accessibility Audit: Page Selection

I'll help you audit your homepage for accessibility issues.

First, let me get your site information...

Available sites:
1. Company Website
2. Portfolio Site

Which site? (1/2)

用户回复： 1

步骤 2：选择页面

Available pages in Company Website:
1. Home (/)
2. About (/about)
3. Contact (/contact)
4. Blog (/blog)

Which page would you like to audit? (1 for Home)

用户回复： 1

步骤 3：选择审核范围

What level of audit would you like?

1. Full audit (all WCAG checks) - Recommended
2. Critical issues only (Level A compliance)
3. Specific categories (buttons, forms, navigation)

Your choice: (1/2/3)

用户回复： 1

步骤 4：审核进度

🔄 Running Accessibility Audit...

Progress:
✅ Extracted page content (45 elements)
✅ Analyzing buttons and interactive elements
✅ Checking form inputs and labels
✅ Validating heading hierarchy
✅ Checking keyboard navigation
🔄 Analyzing focus states...

Analysis complete!

步骤 5：报告

═══════════════════════════════════════════════════
ACCESSIBILITY AUDIT: Home
═══════════════════════════════════════════════════

CRITICAL (3 issues)
───────────────────
[A11Y] Element: Button (navigation toggle)
  Issue: Icon-only button missing accessible name
  Location: Header navigation
  Element ID: {component: "nav-01", element: "btn-menu"}
  Current: <button><MenuIcon /></button>
  Fix: Add aria-label="Open navigation menu"
  WCAG: 4.1.2 Name, Role, Value

[A11Y] Element: Input (email subscription)
  Issue: Form input without label
  Location: Footer, newsletter signup
  Element ID: {component: "footer-01", element: "email-input"}
  Current: <input type="email" placeholder="Enter email" />
  Fix: Add aria-label="Email address for newsletter"
  WCAG: 1.3.1 Info and Relationships

[A11Y] Element: Div (clickable card)
  Issue: Non-semantic interactive element
  Location: Services section, card 2
  Element ID: {component: "services-01", element: "card-02"}
  Current: <div onClick={...}>Service card</div>
  Fix: Convert to <button> or add role="button" + tabIndex="0"
  WCAG: 2.1.1 Keyboard

SERIOUS (5 issues)
──────────────────
[A11Y] Element: Link "Learn more"
  Issue: Focus outline removed without visible alternative
  Location: Hero section
  Element ID: {component: "hero-01", element: "cta-link"}
  Current: outline: none
  Fix: Add focus style - border: 2px solid #0066cc or box-shadow
  WCAG: 2.4.7 Focus Visible

[A11Y] Element: Button "Subscribe"
  Issue: Touch target too small (30px × 36px)
  Location: Footer newsletter form
  Element ID: {component: "footer-01", element: "submit-btn"}
  Current: Small button
  Fix: Increase padding or set min-height: 44px
  WCAG: 2.5.5 Target Size

[continues with 3 more serious issues...]

MODERATE (4 issues)
───────────────────
[A11Y] Element: Heading "Our Services"
  Issue: Heading hierarchy skipped (h1 → h3)
  Location: Services section
  Element ID: {component: "services-01", element: "heading"}
  Current: <h3>Our Services</h3> follows <h1>Welcome</h1>
  Fix: Change to <h2> to maintain proper hierarchy
  WCAG: 1.3.1 Info and Relationships

[continues with 3 more moderate issues...]

═══════════════════════════════════════════════════
SUMMARY
───────────────────────────────────────────────────
Total Issues: 12
- Critical: 3 issues (must fix)
- Serious: 5 issues (should fix)
- Moderate: 4 issues (consider fixing)

Accessibility Score: 64/100

Most Common Issues:
1. Missing button labels - 2 occurrences
2. Focus styles removed - 3 occurrences
3. Heading hierarchy problems - 2 occurrences

Quick Wins (Easy + High Impact):
✨ Add aria-label to icon buttons (2 min, +20 score points)
✨ Add input labels (5 min, +10 score points)
✨ Add focus styles (10 min, +15 score points)

═══════════════════════════════════════════════════

💡 Next Steps:
1. Fix critical issues first (blocks access for some users)
2. Add visible focus styles for keyboard users
3. Test with keyboard navigation (Tab, Enter, Space keys)
4. Consider testing with screen reader (NVDA/JAWS/VoiceOver)

Would you like me to help fix these issues?

示例 2：多页面审核

用户提示词：

Audit accessibility across my entire site

Agent 回复：

🔍 Multi-Page Accessibility Audit

I'll audit all pages on your site for accessibility issues.

Found 8 pages:
1. Home
2. About
3. Services
4. Team
5. Blog
6. Blog Post Template (CMS)
7. Contact
8. Privacy Policy

This will take approximately 2-3 minutes.

Proceed with full site audit? (yes/no)

用户： yes

进度：

🔄 Auditing Site Accessibility...

Progress: ████████████░░░░░░░░ 60% (5/8 pages)

✅ Home - Score: 64/100 (12 issues)
✅ About - Score: 78/100 (6 issues)
✅ Services - Score: 71/100 (9 issues)
✅ Team - Score: 85/100 (4 issues)
✅ Blog - Score: 82/100 (5 issues)
🔄 Analyzing Blog Post Template...

最终报告：

═══════════════════════════════════════════════════
SITE-WIDE ACCESSIBILITY AUDIT
═══════════════════════════════════════════════════

OVERALL SCORE: 73/100

Pages Audited: 8
Total Issues: 48
- Critical: 11 issues
- Serious: 21 issues
- Moderate: 16 issues

═══════════════════════════════════════════════════
ISSUES BY PAGE
═══════════════════════════════════════════════════

🔴 Lowest Scores (Need Attention):
1. Home - 64/100 (12 issues: 3 critical, 5 serious, 4 moderate)
2. Services - 71/100 (9 issues: 2 critical, 5 serious, 2 moderate)
3. About - 78/100 (6 issues: 1 critical, 3 serious, 2 moderate)

🟢 Highest Scores:
1. Team - 85/100 (4 issues: 0 critical, 2 serious, 2 moderate)
2. Blog - 82/100 (5 issues: 1 critical, 2 serious, 2 moderate)

═══════════════════════════════════════════════════
SITE-WIDE PATTERNS
═══════════════════════════════════════════════════

Most Common Issues Across Site:
1. Missing button labels (icon buttons) - 8 occurrences
   Pages affected: Home, Services, Blog, Contact

2. Focus outline removed - 12 occurrences
   Pages affected: All pages (site-wide CSS issue)

3. Form inputs without labels - 5 occurrences
   Pages affected: Home, Contact

4. Small touch targets (<44px) - 9 occurrences
   Pages affected: Home, About, Services, Contact

═══════════════════════════════════════════════════
RECOMMENDATIONS
═══════════════════════════════════════════════════

🎯 Site-Wide Fixes (Fix Once, Helps Everywhere):
1. Add focus styles to global CSS (affects 12 issues across all pages)
2. Update button component to require aria-label (affects 8 issues)
3. Increase minimum touch target size in design system (affects 9 issues)

📋 Page-Specific Priorities:
1. Home page: Fix navigation menu button and newsletter form
2. Services page: Add labels to service card interactions
3. Contact page: Add proper labels to all form inputs

💡 Design System Improvements:
- Create accessible button component with required aria-label
- Add focus state variants to all interactive components
- Set minimum touch target size standard (44px)

Would you like:
1. Detailed report for specific page
2. Export findings to file (Markdown/JSON/CSV)
3. Help fixing site-wide issues

示例 3：仅查看严重问题

用户提示词：

Check my contact page for critical accessibility issues only

Agent 回复：

🔍 Critical Issues Audit: Contact Page

Running quick scan for blocking accessibility issues...

✅ Page analyzed

═══════════════════════════════════════════════════
CRITICAL ISSUES: Contact Page
═══════════════════════════════════════════════════

Found: 4 critical issues

[1] Form Input Missing Label
    Element: Email input field
    Location: Contact form, top
    Issue: No accessible name for screen readers
    Fix: Add aria-label="Your email address"
    WCAG: 1.3.1 (Level A)

[2] Form Input Missing Label
    Element: Message textarea
    Location: Contact form, bottom
    Issue: No accessible name for screen readers
    Fix: Add aria-label="Your message"
    WCAG: 1.3.1 (Level A)

[3] Button Missing Label
    Element: Submit button
    Location: Contact form, bottom
    Issue: Icon-only button with no text
    Fix: Add aria-label="Submit contact form"
    WCAG: 4.1.2 (Level A)

[4] Non-Semantic Interactive Element
    Element: Social media link (Instagram)
    Location: Footer
    Issue: Div with onClick instead of proper link
    Fix: Convert to <a href="..."> with aria-label="Instagram"
    WCAG: 2.1.1 (Level A)

═══════════════════════════════════════════════════

⚠️ Impact: These issues prevent screen reader users from using your contact form.

🔧 Estimated fix time: 5 minutes

Would you like me to:
1. Run full audit (includes serious and moderate issues)
2. Fix these 4 critical issues now
3. Export this report (Markdown/JSON/CSV)

安全规则

预览和确认

建议修复前，务必显示详细的问题列表
明确标注严重程度（严重／较严重／中等）
用通俗易懂的语言解释每个问题的影响
为每项发现提供具体的 WCAG 参考

按项审批修复

允许用户选择要修复的问题
提醒用户可能影响视觉设计的修复
分批处理修复，并显示进度
报告每次修复尝试的成功或失败情况

错误处理

如果无法访问页面，请清楚说明
如果无法修改元素，请建议手动修复
将自动修复项与需手动审核的项目分开

验证

提出修复建议前，先验证元素类型
添加属性前，检查元素是否支持该属性
测试建议的修复是否适用于该元素类型
如果修复可能破坏现有功能，请发出警告

输出标准

图标和格式

🔍 发现／分析
🔄 处理中
✅ 通过／成功
❌ 失败／严重问题
⚠️ 警告／较严重问题
💡 建议／中等问题
📊 报告／摘要
🎯 优先级／行动事项
🔴 最高优先级
🟡 中优先级
🟢 低优先级

报告结构

清晰的严重程度分类
指明具体元素及其 ID
当前状态与建议修复方案的对比
每个问题对应的 WCAG 参考
包含可执行优先事项的摘要
用于衡量进度的评分

沟通

使用清晰易懂、无术语的语言
解释问题的原因及其对用户的影响
提供具体、可执行的修复方法
鼓励使用真实的辅助技术进行测试
强调自动化检查只是第一步

应包含的资源

WCAG 2.1 快速参考

https://www.w3.org/WAI/WCAG21/quickref/

Webflow 无障碍资源

Webflow University：无障碍最佳实践
在 Webflow 中使用语义化 HTML
在 Webflow 中添加 ARIA 属性

测试工具

键盘：Tab、Shift+Tab、Enter、Space
屏幕阅读器：NVDA（Windows）、JAWS、VoiceOver（Mac/iOS）
浏览器扩展：axe DevTools、WAVE、Lighthouse

常见修复

按钮标签：始终包含可见文本或 aria-label
表单标签：使用 Webflow 的 label 元素或 aria-label
焦点样式：使用 :focus-visible 伪类
语义化 HTML：使用恰当的元素（button、a、label）

支持 Markdown

登录后评论

基本信息

作者: webflow
仓库: webflow/webflow-skills
分类: 测试与质量
安装次数: 900
GitHub Stars: 133

报告问题