Imported from yangsonhung/awesome-agent-skills (skills/zh-cn/frontend-quality-guardrails-cn/SKILL.md). Install upstream with npx skills add yangsonhung/awesome-agent-skills --skill frontend-quality-guardrails-cn. Copyright stays with the author.

前端质量守门规则

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 评分或合规报告的无障碍专项审计。

使用说明

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

工作流程

先检查现有 UI 约定：
- 识别框架、样式系统、组件库、断点、字体尺度、间距 token 和图标库。
- 复用现有组件和工具类。
- 不要为了局部修复引入新设计系统。
找出文本风险面：
- 用户名、组织名、文件名、路径、slug、UUID、hash、token、URL、邮箱、手机号。
- 标题、卡片标题、表格单元格、导航项、Tab、面包屑、筛选器、chip、badge、tooltip、toast、dialog。
- 表单标签、占位符、帮助文本、校验错误、空状态、加载文案。
- 翻译文案和中英文混排内容。
明确每个文本容器的预期行为：
- 换行：内容可以多行显示且不破坏布局。
- 限行：内容视觉上限制行数，但完整值在其他地方可访问。
- 截断：紧凑重复 UI 中使用省略号缩短。
- 滚动：代码、日志、表格或面板等内容刻意滚动。
- 自适应：布局随内容变化，但有稳定的最小/最大约束。
实现最小且稳健的修复：
- 在 flex/grid 文本子项上补 min-width: 0 或 min-height: 0。
- 在必要位置添加明确的 max-width、overflow-wrap、text-overflow、line-clamp 或滚动行为。
- 只有父容器才是溢出源时，才调整父级布局。
用极端内容和视口验证：
- 测试窄屏手机、平板、桌面和宽屏桌面。
- 测试超长无空格字符串、长自然语言、中英文混排、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;
}

只有在空间刻意紧凑且完整值仍可访问时才截断：

.truncate-one-line {
  min-width: 0;
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}

对于重复 UI 里的紧凑名称或标题，优先使用单行省略号，并通过项目已有的 Tooltip/title 模式在鼠标悬停和键盘聚焦时展示完整文本。不要只靠裁剪来“保护布局”；用户仍然必须能查看完整值。

卡片摘要、搜索结果和说明文本可使用多行限行：

.clamp-2 {
  display: -webkit-box;
  -webkit-line-clamp: 2;
  -webkit-box-orient: vertical;
  overflow: hidden;
}

日志、代码、长表格和原始技术值适合滚动：

.scroll-panel {
  min-width: 0;
  min-height: 0;
  overflow: auto;
}

避免这些陷阱：

不要只靠 overflow: hidden 解决问题，它会隐藏 bug 并让内容不可访问。
不要把 white-space: nowrap 套在可能接收翻译文案的容器上。
不要默认对可读正文使用 word-break: break-all；长无空格 token 优先用 overflow-wrap: anywhere。
不要截断表单错误、关键警告、价格、日期或危险操作文案。
没有受约束宽度和块级/行内块/flex 行为时，不要指望省略号生效。
使用限行时，要考虑键盘焦点、屏幕阅读器和完整内容访问路径。

Flex 和 Grid 踩坑点

含文本的 flex/grid 子项通常要检查 min-width: 0：

.row {
  display: flex;
}

.row__content {
  min-width: 0;
  flex: 1;
}

CSS Grid 中含长内容的列优先使用 minmax(0, 1fr)：

.grid {
  display: grid;
  grid-template-columns: minmax(0, 1fr) auto;
}

防止布局抖动：

给头像、图标、按钮、表格列和缩略图稳定尺寸。
图标和固定控件使用 flex: none 或等价写法。
重复的横向/纵向节奏优先使用 gap。
避免百分比宽度叠加 padding 后导致溢出。
项目没有全局设置时，补 box-sizing: border-box。
需要内部滚动的嵌套 flex/grid 面板要检查 min-height: 0。

对齐和间距

按视觉角色对齐，不按偶然的 DOM 顺序对齐：

表单、详情面板、表格和卡片中的 label/value 要一致对齐。
图标和文本用 inline-flex、align-items: center 和稳定 gap。
纯图标按钮保持正方形并居中。
图标+文本控件要视觉上基线平衡，避免图标漂在文字上方。
使用项目已有间距尺度，不随意发明一次性 margin。
保持标题、正文、控件和区块边界之间的垂直节奏。
长段落、表格、表单标签和高密度业务界面不要居中对齐。
只有便于列间比较的数字才右对齐。
指标、价格、计时器和数字列优先使用等宽数字。

字体排版

保持字体可读且稳定：

不要用视口宽度直接缩放字号。
除非项目设计系统明确使用，否则避免负字间距。
中英文混排和 CJK 内容要有足够行高。
紧凑卡片、侧边栏、工具栏、表格和弹窗里避免过大的标题。
按钮文案要短，但不要难懂。
即使视觉尺寸不同，也保持语义化 heading 顺序。
不要滥用字重，层级也应来自字号、间距、颜色和布局。
测试翻译膨胀，德语、俄语、越南语、中文、日文、韩文会以不同方式挑战宽高。

建议起点：

正文行高约 1.45 到 1.7，按密度调整。
UI 标签行高约 1.2 到 1.4。
高密度表格先保证可读，再追求行数。

响应式布局

面向真实断点设计，不只看一个桌面宽度：

可行时检查 320px、375px、768px、1024px、1280px 和一个宽屏尺寸。
避免超过小屏的固定宽度。
媒体和文本容器使用 max-width: 100%。
确保 sticky header、侧边栏、底部栏和浮动控件不会遮挡内容。
只有大表格、时间线、代码或对比矩阵等天然需要时才横向滚动。
移动端点击目标尽量接近 44px 高/宽，除非项目明确采用高密度规范。
移动浏览器地址栏会影响视口高度，必要时使用 svh、dvh 或项目支持的 fallback。

移动端：

表单和筛选条在横向密度脆弱时应堆叠。
主要操作要可触达且不遮挡输入。
弹窗要适配视口高度，并让正文内部滚动。
不要依赖 hover-only 交互。

组件专项检查

按钮和控件

灵活按钮内的文本 span 要能处理溢出。
loading 状态和 idle 状态保持同尺寸。
危险、禁用、焦点、悬停、按下和选中状态要可区分。
不要移除 focus outline，除非替换成可访问的焦点样式。
有图标库时，熟悉工具操作优先用图标，并提供可访问标签或 tooltip。

表单

尽量保留可见 label，占位符不是 label。
校验错误要能换行并靠近字段。
错误出现时避免布局大跳动。
select、radio、checkbox、combobox 中的长选项要明确换行或截断。
覆盖 autofill、disabled、readonly、required、invalid、loading、success 状态。
输入文本不要小到影响阅读。

表格和数据网格

每列明确策略：固定宽、弹性宽、换行、截断或横向滚动。
重要标识符要可读；若截断，应提供复制或完整值访问路径。
数字右对齐，文本左对齐。
sticky 表头/列不能制造裁剪或 z-index 问题。
测试空、单行、多行、加载、错误和筛选后状态。
除非产品模式已有，不要在每个表格单元格里塞复杂卡片。

卡片和列表

重复项结构稳定，操作位置一致。
可以限行摘要，但不要随意限行关键标题，除非 hover/focus/detail 能看到完整标题。
badge 不应把主要内容挤出视野。
hover/focus 样式不要改变卡片尺寸。
除非设计系统明确使用，否则避免卡片套卡片。

导航、Tab 和面包屑

测试长路由名和翻译标签。
按需使用溢出菜单、可滚动 Tab、可换行面包屑或有意截断。
标签截断时仍要看得出 active 状态。
保持键盘导航可用。

弹窗、抽屉、浮层、Tooltip

header/footer 稳定，body 内容滚动。
popover 不应被视口边缘裁剪。
不要把关键信息只放在 hover tooltip 里。
dialog 要能处理长标题、长错误和复杂表单。
escape、外部点击、焦点陷阱、关闭后焦点回归遵循组件库模式。

图片、头像和媒体

设置明确宽高或 aspect-ratio，避免布局位移。
有意使用 object-fit。
有意义图片提供 alt，装饰图使用空 alt。
测试缺失、加载慢、损坏和超大图片。
不要过度裁剪产品、人物或内容图片，影响用户辨认。

CSS 和样式踩坑点

避免脆弱 CSS：

不要用随机 z-index、position: absolute 或负 margin 修溢出。
app shell 不要无脑使用 height: 100vh，要考虑移动端视口。
高层布局容器不要随意 overflow: hidden。
不要用全局选择器影响无关组件。
没有理由时不要引入 token 之外的颜色、圆角、阴影或间距值。
不要让 placeholder、muted、disabled 或 secondary 颜色低对比到不可读。
不要把重要内容放在透明遮罩或装饰层后面。
hover 边框不要改变元素尺寸。
能用 transform/opacity 的动画，不要动画布局属性。

稳健基础属性：

box-sizing: border-box
min-width: 0
min-height: 0
max-width: 100%
overflow-wrap: anywhere
text-wrap: balance 只用于标题增强，不作为正确性依赖
contain、content-visibility 或虚拟列表只在确有性能需求时使用

Tailwind 注意点

flex/grid 文本子项补 min-w-0。
truncate 必须配合受约束宽度。
可读文本优先 break-words，只有技术 token 可接受时才用 break-all。
支持时用 line-clamp-* 处理摘要。
大表格外层使用 overflow-x-auto，不要让整页横向滚动。
图标/头像用 shrink-0，文本用 flex-1 min-w-0。
有 token 或现有组件类时，避免堆很长的 arbitrary value。

常见写法：

<div className="flex min-w-0 items-center gap-2">
  <Icon className="size-4 shrink-0" aria-hidden="true" />
  <span className="min-w-0 truncate">Very long label</span>
</div>

<div className="grid grid-cols-[minmax(0,1fr)_auto] items-center gap-3">
  <p className="min-w-0 break-words">Long readable content</p>
  <button className="shrink-0">Action</button>
</div>

组件库注意点

修改前先读项目里的 wrapper 组件。
优先使用组件库公开 props 控制尺寸、状态、禁用、位置、溢出和可访问性。
除非没有公开 API，不要用脆弱选择器覆盖内部实现。
Ant Design 重点检查 Table 列宽、ellipsis、scroll.x、Tooltip、Form.Item help、Select option 渲染、Typography.Text ellipsis。
shadcn/ui 要保留 Radix 的可访问行为和组合方式，优先通过 wrapper class 修布局。
MUI/Chakra/Headless UI 优先用文档化的 slot props、style props 或组合点。

可访问性和语义

保留可见焦点和合理 tab 顺序。
按钮、链接、标题、列表、表格、表单和 landmark 使用语义元素。
纯图标控件提供可访问名称。
错误、警告、active 状态和 status 不只靠颜色表达。
重要内容被截断时要有完整值访问路径。
tooltip 要可触达或不承载关键信息。
大范围或重复动画尊重 reduced motion。
normal、muted、disabled、hover、selected、error 文本都要有足够对比。

国际化和内容变化

可能翻译的文本容器避免硬编码像素高度。
不要拼接翻译片段，语法顺序可能不同。
检查复数和变量插值。
不要假设英文单词边界。
确保 CJK、RTL、变音符、emoji 和长数字不破坏布局。
支持 RTL 时使用 dir、逻辑 CSS 属性或组件库 RTL 能力。

视觉细节检查

完成 UI 修改前扫描：

文本是否覆盖图标、badge、图片、输入框或相邻区块。
内容是否被圆角、sticky bar、抽屉或 hidden overflow 裁剪。
卡片或行 hover 时是否改变尺寸。
图标尺寸和描边是否不一致。
同一组件组内圆角是否混乱。
阴影或边框是否让嵌套层级显得偶然。
重复项间距是否不均匀。
空状态是否像加载坏了。
skeleton 是否匹配最终布局尺寸。
disabled 状态是否对比不足或含义不清。
toast、dropdown、menu、popover 是否被 header 或 modal 遮挡。

必测内容

可行时使用这些字符串验证：

This is a normal sentence that should wrap naturally without breaking the layout.
SuperLongUnbrokenOrganizationNameWithNoSpacesAndManyCharacters1234567890
https://example.com/a/very/long/path/with/query?search=frontend-layout-overflow-and-wrapping
张三李四王五赵六前端页面超长文本混排ABCDEFGHIJKLMN1234567890
aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

同时测试：

空字符串
单字符
超长翻译标签
长数字或货币值
长校验错误
多个 badge/tag
缺失图片/头像
加载和错误状态

验收清单

不要在这些条件满足前标记完成：

除非有意设计，否则页面没有横向溢出。
文本不会覆盖相邻 UI。
长文本按预期换行、限行、截断或滚动。
关键完整内容仍可访问。
含文本的 flex/grid 子项有合适的 min-width: 0 或 min-height: 0。
移动端和桌面端布局可用。
相关时覆盖 loading、empty、error、disabled、hover、focus、selected 和密集数据状态。
修改遵循现有设计 token 和组件模式。
可用浏览器或截图流程时，完成视觉验证。

回复格式

使用本技能完成任务时：

说明处理了哪些具体溢出/布局风险。
说明做过哪些验证。
说明仍未检查的 UI 风险、视口或状态。

frontend-quality-guardrails-cn

About