name: web-interface-guidelines-review description: “根据可访问性、用户体验和性能规则审查UI文件，然后按文件分组输出简洁的发现。用于：(1) 审计前端代码质量，(2) 在PR中强制执行设计系统规则，或 (3) 生成可操作的文件:行合规报告。”

Web界面指南审查

审计前端文件的可访问性、交互质量、性能和内容规则。以文件:行格式返回按文件分组的简洁发现，无需前言。

使用时机

用例1：当需要在合并前对UI组件进行快速合规性检查时
用例2：当团队希望进行一致的可访问性和交互质量检查时
用例3：当审查者需要简洁、高信号量的发现，而不是长篇解释时

所需工具 / API

rg（ripgrep）— 跨源文件的快速代码搜索
node（可选）— 结构化扫描和报告生成
无需外部API

安装选项：

# Ubuntu/Debian
sudo apt-get install -y ripgrep nodejs npm

# macOS
brew install ripgrep node

技能

基本用法

运行基于模式的合规性扫描并输出分组发现。

# 1) 选择文件（示例）
FILES="src/**/*.{vue,js,jsx,html,css}"

# 2) 运行针对性检查（示例）
rg -n "<button[^>]*>\s*(<svg|<i)" $FILES
rg -n "<img(?![^>]*\balt=)" -P $FILES
rg -n "transition\s*:\s*all" -P $FILES
rg -n "outline-none|outline:\s*none" -P $FILES
rg -n "onPaste\s*=\s*\{[^}]*preventDefault" -P $FILES
rg -n "user-scalable\s*=\s*no|maximum-scale\s*=\s*1" -P $FILES

Node.js：

const { execSync } = require('node:child_process');

const checks = [
  { rule: '图标按钮缺少aria-label', cmd: "rg -n \"<button[^>]*>\\s*(<svg|<i)\" src" },
  { rule: '图像缺少alt属性', cmd: "rg -n -P \"<img(?![^>]*\\balt=)\" src" },
  { rule: '使用了transition: all', cmd: "rg -n -P \"transition\\s*:\\s*all\" src" },
  { rule: '移除了轮廓线但没有替代', cmd: "rg -n -P \"outline-none|outline:\\s*none\" src" }
];

function runCheck({ rule, cmd }) {
  try {
    const out = execSync(cmd, { encoding: 'utf8' }).trim();
    if (!out) return [];
    return out.split('
').map((line) => {
      const [file, lineNo] = line.split(':');
      return `${file}:${lineNo} - ${rule}`;
    });
  } catch {
    return [];
  }
}

const findings = checks.flatMap(runCheck);
if (!findings.length) {
  console.log('✓ 通过');
} else {
  console.log(findings.join('
'));
}

健壮用法

使用分组输出、反模式检查和严重性标签进行更广泛的审查。

# 以所需风格保存报告（按文件分组）
node scripts/review-ui-guidelines.js "src/**/*.{vue,js,jsx,html,css}" > ui-guidelines-report.txt
cat ui-guidelines-report.txt

Node.js：

const { execSync } = require('node:child_process');

const inputGlob = process.argv[2] || 'src/**/*.{vue,js,jsx,html,css}';

const checks = [
  { id: 'a11y-icon-label', label: '图标按钮缺少aria-label', pattern: '<button[^>]*>\\s*(<svg|<i)' },
  { id: 'a11y-input-label', label: '输入框缺少标签/aria-label', pattern: '<input(?![^>]*(aria-label|id=|name=))' },
  { id: 'a11y-img-alt', label: '图像缺少alt属性', pattern: '<img(?![^>]*\\balt=)' },
  { id: 'focus-outline', label: '移除了轮廓线但没有焦点替代', pattern: 'outline-none|outline:\\s*none' },
  { id: 'anim-all', label: 'transition: all → 列出属性', pattern: 'transition\\s*:\\s*all' },
  { id: 'paste-block', label: 'onPaste preventDefault 反模式', pattern: 'onPaste\\s*=\\s*\\{[^}]*preventDefault' },
  { id: 'zoom-block', label: '禁用缩放（user-scalable=no 或 maximum-scale=1）', pattern: 'user-scalable\\s*=\\s*no|maximum-scale\\s*=\\s*1' },
  { id: 'click-div', label: 'div/span上的点击处理器应该是按钮', pattern: '<(div|span)[^>]*onClick=' }
];

function grep(pattern) {
  try {
    const cmd = `rg -n -P "${pattern}" ${inputGlob}`;
    const out = execSync(cmd, { encoding: 'utf8' }).trim();
    return out ? out.split('
') : [];
  } catch {
    return [];
  }
}

const grouped = new Map();

for (const check of checks) {
  for (const hit of grep(check.pattern)) {
    const first = hit.indexOf(':');
    const second = hit.indexOf(':', first + 1);
    if (first === -1 || second === -1) continue;

    const file = hit.slice(0, first);
    const line = hit.slice(first + 1, second);
    const finding = `${file}:${line} - ${check.label}`;

    if (!grouped.has(file)) grouped.set(file, []);
    grouped.get(file).push(finding);
  }
}

if (!grouped.size) {
  console.log('✓ 通过');
  process.exit(0);
}

for (const [file, items] of grouped.entries()) {
  console.log(`## ${file}`);
  console.log('');
  for (const item of items) console.log(item);
  console.log('');
}

Vue + Tailwind 报告视图（可选）

当您希望在浏览器中获得可读的审查输出时，使用此轻量级UI。

<template>
  <a href="#main" class="sr-only focus:not-sr-only focus:absolute focus:left-4 focus:top-4 focus:z-50 focus:rounded focus:bg-white focus:px-3 focus:py-2 focus:ring-2 focus:ring-slate-500">跳转到主要内容</a>

  <main id="main" class="mx-auto max-w-4xl p-4 sm:p-6 text-slate-900">
    <h1 class="text-2xl font-semibold text-balance">Web界面指南报告</h1>

    <p aria-live="polite" class="mt-2 text-sm text-slate-600">
      {{ loading ? '加载中…' : `${groups.length} 个文件已检查` }}
    </p>

    <section v-if="!loading && groups.length === 0" class="mt-6 rounded border border-emerald-200 bg-emerald-50 p-4">
      <p class="font-medium">✓ 通过</p>
    </section>

    <section v-for="group in groups" :key="group.file" class="mt-6 rounded border border-slate-200 bg-white p-4 shadow-sm">
      <h2 class="text-lg font-semibold text-wrap-balance">{{ group.file }}</h2>
      <ul class="mt-3 space-y-2">
        <li v-for="item in group.items" :key="item" class="min-w-0 break-words rounded bg-slate-50 px-3 py-2 font-mono text-sm tabular-nums">
          {{ item }}
        </li>
      </ul>
    </section>
  </main>
</template>

<script setup>
import { ref, onMounted } from 'vue';

const loading = ref(true);
const groups = ref([]);

onMounted(async () => {
  try {
    const res = await fetch('/ui-guidelines-report.json');
    groups.value = await res.json();
  } finally {
    loading.value = false;
  }
});
</script>

输出格式

使用此确切形状。

## src/Button.vue

src/Button.vue:42 - 图标按钮缺少aria-label
src/Button.vue:18 - 输入框缺少标签
src/Button.vue:55 - 动画缺少prefers-reduced-motion
src/Button.vue:67 - transition: all → 列出属性

## src/Modal.vue

src/Modal.vue:12 - 缺少overscroll-behavior: contain
src/Modal.vue:34 - "..." → "…"

## src/Card.vue

✓ 通过

输出规则：

按文件分组
使用文件:行 - 问题格式
保持文本简洁，高信号量
除非修复不明显，否则跳过解释
无需前言

代理提示

您有一个Web界面指南审查技能。

当用户要求审查前端文件时，在提供的路径上运行基于规则的检查，并按文件分组返回发现。

要求：
1. 遵循可访问性、焦点、表单、动画、排版、内容处理、图像、性能、导航/状态、触摸、布局、主题、i18n、水合、悬停和复制规则。
2. 明确标记反模式。
3. 仅以以下格式输出：

## 路径/到/文件

路径/到/文件:行 - 简洁的问题

如果文件没有问题：

## 路径/到/文件

✓ 通过

不要强制使用框架或语言。当需要UI示例时，优先使用Vue + Tailwind示例。除非用户明确请求，否则避免TypeScript。

故障排除

没有发现但存在问题：

症状：报告意外显示✓ 通过
解决方案：扩展文件通配符，包括模板/样式文件，并添加缺失的正则表达式检查

太多误报：

症状：发现噪音大或重复
解决方案：缩小模式，添加上下文感知检查，并抑制已知安全路径

另请参阅

…/using-web-scraping/SKILL.md — 从网页提取源数据
…/city-tourism-website-builder/SKILL.md — 快速构建精美的静态页面

备注

推荐路径：skills/web-interface-guidelines-review/SKILL.md
保持示例在干净环境中可复制粘贴运行
优先使用语义HTML；使用ARIA补充语义