frontend-quality-guardrails-cn

前端质量守门规则

Overview

将本技能作为前端实现和审查的质量守门规则，覆盖超长文本、溢出、换行、截断、对齐、间距、响应式、组件状态、可访问性、国际化、视觉细节、项目代码审查、浏览器截图验证和常见 UI 样式踩坑点。

把所有 UI 都当成会遇到不完美内容来处理。默认假设标签、姓名、URL、ID、价格、翻译文本、用户输入、错误信息、表格单元格、徽章、面包屑、Tab 和按钮文案都可能比设计稿更长。

优先做小而局部的 CSS/布局修复，不要为了局部问题重写整体结构。除非用户明确要求重设计，否则保留现有设计系统、组件 API、设计 token、间距尺度和框架约定。

何时使用

在构建、修改或审查前端 UI 且布局质量重要时使用本技能，尤其是：

• 超长文本、URL、ID、翻译文案、表单错误、标签、表格单元格、卡片、Tab、面包屑或徽章可能溢出。
• 任务涉及 HTML、CSS、React、Vue、Svelte、Next.js、Tailwind、shadcn/ui、Ant Design、表单、表格、仪表盘、弹窗、抽屉、导航或响应式布局。
• 用户要求打磨 UI、修复溢出、改进对齐、审查前端代码、验证浏览器截图或规避前端样式踩坑点。

不要使用

以下场景不要把本技能作为主要指南：

• 后端、CLI、数据库或基础设施等没有可见 UI 的任务。
• 完整品牌设计、插画、Logo 设计或图片生成。
• 基于截图做像素级还原，且已有更专门的 image-to-code 或设计还原技能。
• 需要正式 WCAG 评分或合规报告的无障碍专项审计。

使用说明

把下面的流程作为项目现有前端规范之上的质量守门层。简单修改只使用核心清单；更深入的开发、审查或验收，按需读取“深度参考”里的文件。

工作流程

1. 先检查现有 UI 约定：

   • 识别框架、样式系统、组件库、断点、字体尺度、间距 token 和图标库。
   • 复用现有组件和工具类。
   • 不要为了局部修复引入新设计系统。

2. 找出文本风险面：

   • 用户名、组织名、文件名、路径、slug、UUID、hash、token、URL、邮箱、手机号。
   • 标题、卡片标题、表格单元格、导航项、Tab、面包屑、筛选器、chip、badge、tooltip、toast、dialog。
   • 表单标签、占位符、帮助文本、校验错误、空状态、加载文案。
   • 翻译文案和中英文混排内容。

3. 明确每个文本容器的预期行为：

   • 换行：内容可以多行显示且不破坏布局。
   • 限行：内容视觉上限制行数，但完整值在其他地方可访问。
   • 截断：紧凑重复 UI 中使用省略号缩短。
   • 滚动：代码、日志、表格或面板等内容刻意滚动。
   • 自适应：布局随内容变化，但有稳定的最小/最大约束。

4. 实现最小且稳健的修复：

   • 在 flex/grid 文本子项上补 min-width: 0 或 min-height: 0。
   • 在必要位置添加明确的 max-width、overflow-wrap、text-overflow、line-clamp 或滚动行为。
   • 只有父容器才是溢出源时，才调整父级布局。

5. 用极端内容和视口验证：

   • 测试窄屏手机、平板、桌面和宽屏桌面。
   • 测试超长无空格字符串、长自然语言、中英文混排、URL、空值和密集列表。
   • 可行时使用浏览器截图或 DOM 检查验证视觉变化。

深度参考

需要更完整覆盖时读取这些参考文件：

• code-review-checklist.md：编辑或审查 React、Vue、Svelte、HTML/CSS、组件库、状态型 UI、表单、表格或现有项目代码前使用。
• visual-standards.md：创建、重设计、打磨或评审视觉风格、密度、层级、色彩、圆角、阴影、字体和交互状态时使用。
• browser-verification.md：完成可见 UI 修改后，或调试布局、溢出、响应式问题时，用于浏览器自动化、截图、控制台和视口检查。

文本溢出规则

用户必须直接阅读的内容优先换行：

.wrap-text {
  overflow-wrap: anywhere;
  word-break: normal;
  hyphens: auto;
}