Front-End Checklist 仓库工程规范全解规则编写、质量门槛与 MCP 服务开发【免费下载链接】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 开源 monorepo 的工程协作指南面向两类读者为仓库贡献 385 条前端最佳实践规则的作者以及希望在 AI Agent / MCP 客户端中接入规则语料进行代码审查的开发者。读完本文你将掌握规则 MDX 的完整 frontmatter 契约与正文骨架、10012 分的质量评分体系与 50 分门槛、11 个 MCP 工具的开发与注册流程以及整个 monorepo 的架构约定能够直接写出可过审、可被 MCP 消费的高质量规则。项目定位为人类与 AI Agent 准备的现代 Web 开发清单Front-End Checklist 是一个开源的 pnpm monorepoworkspaces Turborepo提供385 条质量门控quality-gated的前端最佳实践规则并内置一个 MCPModel Context Protocol服务器用于结构化审查工作流。核心组件如下组件位置说明MCP Server远程端点https://mcp.frontendchecklist.io对外暴露 11 个只读工具规则语料packages/content/rules/en/category/slug.mdx格式385 条规则Web 应用apps/web/Next.js App Router 实现的清单站点MCP 包packages/mcp/TypeScript 实现的 MCP 服务器包管理器pnpm根目录 package.json pnpm-workspace.yaml需要说明的是MCP 工具与规则语料之间是强绑定关系——评分低于质量门槛的规则会被排除在 MCP 工具响应与 Web UI 之外见后文质量评分章节这正是质量门控的含义。Monorepo 结构总览AGENTS.md 给出了顶层目录的官方划分apps/ web/ # Next.js app (App Router) packages/ mcp/ # MCP server implementation content/ # Rules MDX content content-collections config auth/ # Better-Auth Prisma Supabase design-system/ # Shared UI components types/ # Shared TypeScript types >interface ReviewCodeInput { code: string focus?: Category[] // 可选指定审查类别默认从代码自动检测 minPriority?: Priority // 可选报告的最低优先级默认 medium }实现上有几个值得注意的设计阈值常量所有启发式阈值都以命名常量声明例如INLINE_STYLE_THRESHOLD 3超过 3 个内联样式判定为系统性滥用、DIV_SOUP_THRESHOLD 5超过 5 个 div 且无语义元素、HEX_COLOR_THRESHOLD 5、LAZY_LOAD_THRESHOLD 3等代码类型自动检测detectCategories()会通过html、meta、CSS 属性、JS 结构模式const、function、document.等自动判断代码类型并派生相关类别框架感知的误报抑制shouldSuppressIssueForSourceContext()对 JSX/TSX 组件源码、Next.js metadata 驱动源码export const metadata、generateMetadata、异步 React 组件做了特殊处理——例如组件片段不判 heading-hierarchy、metadata 驱动源码不判 canonical/OG/CSRF 等头部管理类规则避免对框架代码产生误报诚实的结论当review_code未发现问题时返回的 suggestions 会明确提示这是保守的静态启发式结果不是健康证明并建议继续用search_rules或get_rule检索相关清单。规则 MDX Frontmatter 规范规则存放在packages/content/rules/en/category/slug.mdx。frontmatter 分必填字段与推荐字段两级前者缺失会导致构建失败。必填字段7 个--- title: Human-readable rule title (string, use quotes) description: One-sentence description of what to do categories: [html] # Array; first item primaryCategory priority: high # critical | high | medium | low difficulty: beginner # beginner | intermediate | advanced | expert estimatedTime: 15 # Minutes as integer prompts: check: Prompt for checking whether the implementation follows this rule fix: Prompt for fixing the issue explain: Prompt for explaining why this rule matters ---注意prompts的三种 prompt 各有职责check用于检查实现是否遵循规则fix用于修复问题explain用于解释规则为何重要。这是 MCP 工具check_rule、fix_rule、explain_rule直接消费的字段因此必须可执行而非空泛。推荐字段不影响解析但实质性提升质量subcategory: keyboard # Sub-grouping within category tldr: # Array of bullet points (used in llms.txt) - Key point one - Key point two whyItMatters: Paragraph explaining the business/user impact sources: - title: MDN or spec page title url: https://... type: mdn|spec|guide|wcag|google id: stable-source-id role: standard|reference|implementation|compatibility|regulation|search|research authority: primary|secondary resources: - name: Supplementary tool or article url: https://... type: tool|article|reference relatedRules: - slug: other-rule-slug reason: Why these rules relate tools: - name: Tool Name url: https://... # or null tags: [wcag, performance] prompts: codeReview: Recommended prompt for systematic code review context aiContext: Additional context for automated review about when this rule applies以仓库中真实的 alt-text.mdx 为例可以看到完整实践categories: [images]subcategory: accessibility、priority: critical、relatedRules关联了figure-figcaption、error-images、dimensions并各自给出原因tools列出了 axe DevTools、WAVE、Lighthousesources提供了 MDN 与 web.dev 两个 primary 权威引用aiContext说明自动化审查的适用时机tldr提炼了 4 条要点llms.txt 消费。写作放置规则权威引用放在sources不要写在正文散文里如Reference: ...sources是证据元数据而非泛读列表——每条规则至少 2 个 sources、2 种 source roles、1 个authority: primaryresources仅用于延伸阅读或工具不要把证据主张映射到resources系统可能在构建时推断或规范化id、role、authority作者应聚焦于强相关来源而不是维护逐条声明的证明对象跨规则导航放在relatedRules不要在正文写See also ...引言段落聚焦规则本身元数据应由 frontmatter 驱动的 UI 渲染。内联链接契约正文中的自然内联链接允许存在但必须支持具体的论断、对比或实现建议且遵循轻触控密度每条规则通常2–5 个内联链接引言 0–1 个主体指导区 1–3 个优先外链内部规则链接通常保持 0–1 个仅对异常互联的规则允许 2 个正文不保留独立的元数据行不要添加以See also ...或Reference: ...开头的段落常青证据放sources内联外链仅在补充主来源缺乏的实操/时效上下文时使用文中首次提到具名工具如Screaming Frog、Google Search Console时若该工具已存在于resources或tools且有助读者应链接首次提及受批准的二阶内联链接平台应精选如CSS-Tricks、Smashing Magazine、Nielsen Norman Group、WebAIM、Screaming Frog、Sitebulb、Moz、Yoast锚文本要描述性与句子主张绑定不要用 read more 这类泛标签。另外需要注意impact、standards、automation目前刻意不属于活跃规则编写契约的一部分——现有语料与工具链对它们的消费尚不一致不足以将其作为标准编写字段。规则正文的规范骨架Canonical Rule Shape新建或刷新规则时应遵循以下结构除非有充分理由偏离简短引言用平实语言解释规则## Code Example或## Code Examples## Why It Matters可选的实现或指导章节## VerificationH2 排序是强制的且会被校验器检查## Code Example(s)必须出现在## Why It Matters之前## Why It Matters必须出现在## Verification之前## Verification必须是规则正文的最后一个 H2可选 H2 位于## Why It Matters与## Verification之间。推荐的可选 H2 分类taxonomy## Best Practices、## Common Mistakes、## Framework Examples、## Tools Validation、## Thresholds、## Exceptions、## Browser Support、## Support Notes、## Standards、## Implementation Notes校验器会报告超出该分类的标题使章节蔓延section sprawl长期可见。Rule Contract V2 的三个条件概念## Exceptions用于有细微差别、容易误报或有合理例外的规则## Verification内的### Automated Checks与### Manual Checks当自动化与人工检查都重要时可见的 standards/support 说明对兼容性或合规性敏感的规则。这些应按条件应用而非一刀切。阈值与浏览器支持浏览器支持建议应来自仓库的.browserslistrc策略 基于包的兼容性数据如mdn/browser-compat-data不能凭记忆编写只要规则可度量就必须使用显式阈值Web Vitals 与性能指标LCP 2.5s、CLS 0.1、bundle 或图片大小预算可访问性度量对比度、目标尺寸、缩放或 reflow 阈值SEO 与抓取状态可索引性、状态码、canonical-url 行为安全头与传输要求优先如何验证的指导而非泛泛建议——一条强规则应确切告诉工程师如何确认规则通过。以 alt-text.mdx 为例其正文依次为引言 →## Code Example含 HTML 正反例→## Why It Matters→## Decorative Images→## Images Used as Links→## Images of Text→## Complex Images→## Framework ExamplesReact / Next.js 的 CodeTabs→## Standards→## Verification含### Automated Checks与### Manual Checks完整呈现了规范骨架与 V2 条件概念的组合。常见错误清单Common Mistakes to AvoidYAML 中冒号未加引号含:的字符串必须加引号例如title: Use rel: new-tab而非title: Use rel: noopener占位式 promptsprompt 必须可执行。反面Check this rule正面Find all img elements missing an alt attribute in this HTML缺少 sources规则完成前至少加一个权威引用MDN、W3C/WCAG、规范、web.dev或产品文档没有验证路径必须包含收尾的## Verification章节使修复可测试Verification 不是最后不要在## Verification之后放置任何 H2缺少 caveats规则存在重要误报或合理例外时加## Exceptions缺少支持说明兼容性或合规性会影响实现决策时加## Browser Support、## Support Notes或可见的标准说明优先级错误critical 破坏站点 / 安全 / 法律high 显著降低 UXmedium 最佳实践low 锦上添花缺少必填字段7 个必填字段必须齐全否则构建失败标题带 emoji标题应为纯文本。分类分类法Category Taxonomycategories数组的合法取值Slug描述html文档结构、语义、表单css布局、排版、动画、响应式javascript客户端脚本、异步、安全performance加载速度、渲染、Core Web VitalsaccessibilityWCAG、ARIA、键盘、屏幕阅读器seoMeta 标签、结构化数据、可抓取性securityHTTPS、CSP、XSS 防护、安全头images优化、格式、响应式图片testing单元、集成、e2e、可访问性测试privacy同意、数据最小化、数据权利i18n本地化、复数化、双向文本、区域格式化general跨领域最佳实践注意categories数组的第一项即 primaryCategory。质量评分体系100 12 分制与 50 分门槛规则由pnpm score:rules自动评分实现见 scripts/rule-structure/score-rules.ts100 分基础分 最多 12 条件加分最低 50 分才能通过当前质量门控。维度分值检查内容Promptscheck/fix/explain243 个 prompt 均具体且非泛泛TLDR 要点43 条以上可执行的要点Why it matters4解释用户、业务或运营影响AI context6捕获自动化审查中规则的适用场景与时机Related rules6链接相邻规则并说明清晰原因Sources10包含权威引用Resources / tools6包含有用的支撑文档或工具Code review prompt6提供系统性审查策略Code examples10包含真实示例而非只有散文Body depth10提供实质性的实现细节Verification section8包含Verification、Testing、Audit Checklist或等价章节Thresholds / pass-fail criteria6可度量处使用显式数字或条件Exceptions条件加分4规则易误报或微妙时加Exceptions章节Verification split条件加分4自动化与人工检查均适用时拆分验证Standards/support visibility条件加分4规则类型需要时添加可见阈值、标准说明或支持说明评分 50 的规则会被排除在 MCP 工具响应和 Web UI 之外。从 score-rules.ts 源码可以看到实现细节它会用gray-matter解析 frontmatter通过STUB_PATTERNS正则如^verify if the project adheres to、^check if . follows best practices识别占位式 prompt统计正文代码块数量与词数作为 body depth 的输入并按 85%/70%/55%/40% 比例映射 A/B/C/D/F 评级。添加或更新一条规则完整 8 步工作流创建packages/content/rules/en/category/slug.mdx填满所有必填 frontmatter 字段添加推荐元数据sources、resources、aiContext、relatedRules、prompts.codeReview适用时使用规范骨架写作intro、examples、why it matters、verification、类别特定指导运行pnpm score:rules—— 当前必须 ≥ 50新工作目标 60运行pnpm validate:rule-structure—— 校验规则章节顺序与最后的Verification标题运行pnpm report:rule-links—— 审查内联链接密度建议安全的内部/外部候选运行pnpm validate:sources—— 校验外部 URL运行pnpm generate:skills—— 从规则重新生成 skills 索引对应脚本的实际命令映射见根目录 package.jsonscore:rules对应tsx scripts/rule-structure/score-rules.tsvalidate:rule-structure对应tsx scripts/rule-structure/validate-rule-structure.tsreport:rule-links对应tsx scripts/rule-structure/report-rule-links.tsvalidate:sources对应tsx scripts/validate/validate-sources.tsgenerate:skills对应tsx scripts/generate/generate-skills.ts。脚本速查表AGENTS.md 提供的完整脚本参考均已映射到 package.json 的 scriptspnpm score:rules # 为所有规则评分标记 50 质量门控失败 pnpm validate:rule-structure # 校验规则标题结构并报告漂移 pnpm report:v2-gaps # 按类别和迁移批次报告条件 V2 差距 pnpm report:rule-links # 审查内联链接密度与候选内/外链 pnpm generate:exceptions-hints # 对缺失 Exceptions 章节给出干跑建议 pnpm generate:support-notes # 从浏览器数据干跑支持说明建议 pnpm generate:verification-split # 干跑 Verification 拆分建议 pnpm validate:sources # 校验规则 frontmatter 中的外部 URL pnpm validate:packages # 检查包依赖一致性 pnpm generate:skills # 从规则重新生成 skills/ 目录 pnpm build # 全量 monorepo 构建经 Turborepo pnpm typecheck # 跨所有包执行 TypeScript 检查 pnpm lint # Biome lint pnpm lint:fix # Biome lint 自动修复此外pnpm ci:check串联了 lint、typecheck、validate:rule-structure、validate:guide-structure、validate:guides、validate:evidence与test:ci是 CI 的完整校验链。MCP 工具开发三步注册流程新 MCP 工具位于packages/mcp/src/tools/tool-name.ts必须完成三步从 packages/mcp/src/tools/index.ts 导出加入 server-tools.ts 的BASE_TOOL_DEFINITIONS或按 checklists 条件挂载的getToolDefinitions在 server.ts 的handleToolsCallswitch实际为executeTool中添加case分支。工具定义形状export const myToolDefinition { name: my_tool, description: ..., // 对工具可发现性至关重要——要具体 inputSchema: { type: object as const, properties: { ... }, required: [fieldName], }, }以review_code为例review-code.ts其定义包含title、面向 Agent 的详细description说明何时优先调用、工作流是什么、annotations: READ_ONLY_TOOL_ANNOTATIONS以及完整的inputSchema/outputSchema如focus枚举 8 个类别、minPriority枚举 critical/high/medium/low。注册侧server-tools.ts 的registerTools通过jsonSchemaToZod将 JSON Schema 转换为 Zod 校验工具执行结果经capResponseText按maxResponseChars截断后同时返回文本内容与结构化内容。远程 HTTP 场景由 server.ts 的handleMcpHttpRequest通过WebStandardStreamableHTTPServerTransportenableJsonResponse: true处理每次请求创建无状态传输并在 finally 中关闭。工作区架构约定AGENTS.md 记录的架构决策对在仓库内开发功能有直接约束AuthBetter-Auth Prisma Supabase Postgres位于 packages/auth/ValidationZod v4 ——ZodError上使用.issues而非.errorsFormstanstack/react-form 提交时手动 Zod 校验EmailResend SDK v6发送域名mail.frontendchecklist.ioRate limitingupstash/ratelimitupstash/redis位于 apps/web/lib/rate-limit.tsQueryTanStack Query v5使用getQueryClient()工厂非单例Dev serverportless run next dev已沉淀的协作偏好Learned User Preferences共享关注点字体、排版放 design system 并从那里导入apps 用 design system 的配置接线具体实现如 next/font不使用suppressHydrationWarning修复服务端/客户端不一致如把仅客户端状态延迟到 mount 之后复用既有组件而非为页面创建特化变体如共享FAQAccordion、.code-block/.code-inline、ChecklistActionBar给一种页面类型加功能时要加到所有相关页面类型如 ShareButton 同时加在 category、rule detail、all-rules 页面组件优先用 Tailwind 工具类而非在 globals.css 写自定义 CSS 类特殊标签用可扩展的 overrides map如 subcategoryaria→ARIA不用硬编码条件不要用git commit --no-verify修复所有 pre-commit 违规JSDoc、as-casts、barrel files、复杂度、相对导入代码与 JSDoc 同时写卡片式链接用 stretched-link 模式a/Link只包裹标题文本并用after:absolute after:inset-0 after:content-[]让::after伪元素撑满卡片容器容器position: relative次级交互元素需要relative z-10图标集中在repo/design-system品牌图标在brand-icons.tsxpackages/design-system/src/brand-icons.tsxLucide 从icons.ts再导出品牌服务用官方品牌图标icons-pack/react-simple-icons消费者不得直接import自lucide-react不要对语义主题文本色使用 Tailwind 透明度修饰符/50、/60、/70——会压垮浅色模式对比度改用完整不透明度的text-foreground-muted、text-foreground-subtletoken社交平台一律称 X 而非 TwitterSchema 字段用xUrl非twitterUrlUI 标签写 XURL 指向x.comAbout 页链接只放页脚不放主导航栏。已沉淀的工作区事实Learned Workspace Facts流式排版 token 在theme inline中对text-base及以上使用clamp()text-xs、text-sm保持固定以适配紧凑 UI 控件next/font将各字体的.className应用到 document 元素而非.variableNext.js 要求字面量 option 对象因此 app 必须内联字体选项design system 只记录它们不要对 MCP 等程序化 API 端点应用客户端机器人防护如 Vercel BotID仅用于浏览器发起的表单与变更端点Next.js 启动时读取 next.config.js修改后需重启 dev serverwithContentCollections返回 Promiseasync config必须是最外层包装export default withContentCollections(withBotId(nextConfig))withBotId不处理 async config会静默丢弃包括images在内的所有属性Tailwind preflight 重置了ul/ol的list-style.prose样式必须显式设置list-style-type: discul、decimalol及嵌套变体circle、lower-alphaCSS 自定义属性使用 OKLCH 颜色格式浅色模式 token 需要在所有屏幕上有可见对比度--border至少oklch(0.885)--foreground-subtle为oklch(0.64)阴影 0.06 透明度主题感知透明色用color-mix(in oklch, var(--token) N%, transparent)而非硬编码rgba()预提交钩子lefthook配置见 lefthook.yml强制执行biome check、JSDoc、no-as-casts、no-barrel-files、file-complexityReact 300 行 / 其他 500 行、no-deep-relative-imports、no-console-logs、测试覆盖率Button 默认 variant 使用bg-accent text-accent-foreground hover:bg-accent-hover项目 accent token而非 shadcn 的bg-primary即使存在 shadcn 别名也要在组件 variant 中保留项目专属语义 token脚本按子文件夹组织scripts/{validation,generate,rule-structure,validate,audit}/scripts/README.md 记录每个脚本与子文件夹Biome 的useSortedClasses只排序 class顺序不能重命名废弃类用tailwindcss/upgrade安装在 apps/web做全项目类名规范化monorepo 使用 pnpm catalogscatalog:in pnpm-workspace.yaml集中管理依赖版本出现在 2 包的共享依赖使用catalog:而非硬编码版本字符串品牌图标ChatGPT、Claude、X、LinkedIn、Reddit、Cursor、VSCode位于 packages/design-system/src/brand-icons.tsx并从 design-system barrel 再导出。结语让每一条规则可评分、可检索、可修复Front-End Checklist 的工程体系本质上是一套可度量的前端知识治理流程frontmatter 契约保证规则被 MCP 工具结构化消费规范骨架保证正文可读且顺序可校验评分体系保证只有质量达标的规则≥ 50 分进入 MCP 响应与 Web UI而review_code等启发式工具把规则语料变成了 Agent 可执行的静态审查能力。对贡献者而言从新建一条规则到发布始终围绕同一闭环写全 frontmatter → 遵循骨架 → 跑分过门 → 校验结构 → 生成 skills。这份指南与仓库中的 AGENTS.md、packages/mcp/SPEC.md 及 scripts/rule-structure/score-rules.ts 等源码互为印证可作为后续所有前端实现与审查工作的统一基准。【免费下载链接】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），仅供参考