frontend-ui-standards

前端 UI 标准

目的

使用此技能，将 UI 工作转化为系统化的前端实现。目标不是逐像素微调，而是在代码中保留设计系统，让后续变更更可预测、更易复用，并在视觉上保持一致。

此技能与框架无关。请根据当前技术栈应用以下规则：

• SwiftUI：将设计令牌定义为枚举或静态常量，使用可复用的 View 和语义化度量值。
• React/Web：使用 CSS 变量、设计令牌模块、组件属性和变体。
• React Native/Flutter：使用主题对象、共享组件和语义化尺寸。

适用场景

如果任务涉及以下内容，请在修改 UI 前使用此技能：

• 构建或修改可见屏幕、组件、布局或交互。
• 将 Figma、SVG、屏幕截图或视觉规范转化为代码。
• 修复视觉问题：对齐错误、文本截断、间距不一致、字体错误、按钮尺寸不当、安全区域问题。
• 创建或修改按钮、卡片、标签、选项卡、导航栏、底部面板、对话框、列表、进度指示器、输入框或阅读界面。
• 检查前端代码是否达到生产就绪标准或符合设计规范。
• 重构重复的 UI 或分散的硬编码值。

如果工作纯粹涉及后端、数据模型、提示词或基础设施，且变更不会影响面向用户的 UI，则不要使用此技能。

核心原则

UI 代码分为三个层次：

1. 设计令牌：全局基础值和语义化值，例如颜色、字体、间距、圆角、阴影、安全区域偏移、内容宽度。
2. 组件度量值：组件专属结构，例如标签高度、图标尺寸、内部边距、卡片标题间距、按钮变体。
3. 屏幕布局度量值：页面专属布局，例如主视觉卡片位置、区块间距、重复行的对齐方式、装饰资源的位置。

视图代码应描述结构和状态，不应在主体中隐藏原始设计计算。

实现工作流

1. 检查现有模式

   • 添加新 UI 前，先查找最相近的现有组件和屏幕。
   • 找出本地的设计令牌文件、主题文件、组件库和布局辅助工具。
   • 检查其他位置是否已存在相同的视觉元素。

2. 为每个视觉值分类

   • 全局且可复用：放入设计令牌。
   • 组件专属：放入组件度量值对象或枚举。
   • 屏幕专属但在该屏幕内重复使用：放入屏幕布局度量值。
   • 一次性装饰定位：将其单独放入命名明确的屏幕度量值中，不要写在视图主体内。

3. 基于复用进行构建

   • 优先扩展现有组件变体，而不是创建新组件。
   • 如果两个位置使用相同的视觉角色，应共用相同的组件或度量值。
   • 如果新组件很快会被重复使用，应立即将其提取出来。

4. 编码布局关系

   • 优先使用推导值，而不是重复写入数字。
   • 示例：authorChipWidth = rowWidth - sourceChipWidth - rowGap，而不是使用三个互不相关的宽度值。
   • 通过共用容器、网格、布局参考线或命名明确的度量值来对齐相关元素。
   • 除非偏移是命名明确的装饰性例外，否则不要通过局部移动单个元素来修正对齐。

5. 验证相似界面

   • 修复按钮、卡片或标题栏后，搜索相同的标签、组件、资源或模式。
   • 尽可能更新共享组件。
   • 如果仍有一次性实现，请通过清晰的度量值名称或简短注释说明原因。

6. 构建并检查视觉效果

   • 运行相关的构建或类型检查。
   • 对于移动 UI，如果用户正在主动验证视觉效果，请在模拟器或设备上安装或运行。
   • 检查文本截断、安全区域、触控目标、动态文本风险和导航或返回行为。

令牌与度量规则

优先使用语义化名称，而不是视觉坐标：

• 好：primaryActionWidth、screenHorizontalInset、cardVerticalSpacing、metadataRowWidth、sourceChipWidth。
• 不好：width: 271、padding(.leading, 12)、在视图主体中反复使用 offset(y: 37)。

允许的数值：

• 令牌或度量定义中可以使用数值。
• 单次使用的资源几何属性可以使用数值，但应将其归入有名称的度量区段。
• 使用要求提供字面值的平台 API 时可以使用数值，前提是该数值不属于视觉设计的一部分。

避免：

• 分散的原始十六进制颜色值。
• 已存在字号比例时仍内联指定字体大小。
• 本应来自间距比例的内联间距值。
• 多个局部版本的同类按钮、标签、顶部栏、卡片或底部 CTA。
• 只在一个调用位置修复共享组件的问题。

组件复用规则

创建 UI 前，先思考：

• 这是新的视觉角色，还是现有角色的变体？
• 现有组件是否已经定义了交互方式、尺寸、阴影、圆角或字体样式？
• 这个组件还会出现在其他屏幕上吗？
• 是否应将其设为组件属性或变体，而不是创建新文件？

以下情况应创建组件变体：

• 结构相同，但颜色或状态不同。
• 按钮形状相同，但文本或图标不同。
• 卡片外壳相同，但内容不同。
• 标签相同，但文字或图标不同。

仅在以下情况创建新组件：

• 结构、行为或布局角色存在明显差异。
• 扩展旧组件会使其难以理解或变得脆弱。

Figma 转代码规则

使用 Figma、SVG、截图或视觉规范时：

• 将 Figma 中的数值视为输入依据，而不是最终代码结构。
• 首先识别重复出现的基本元素：颜色、字体样式、圆角、阴影、间距和内容宽度。
• 将重复的基本元素映射到现有令牌，或添加新的语义化令牌。
• 将重复的 UI 元素映射到现有组件或组件变体。
• 仅当设计确实具有插画或装饰性质，或平台布局模型要求使用时，才使用绝对定位。
• 保留层级和元素关系，不要盲目照搬坐标。

如果 Figma 中两个元素对齐，应在代码中通过共同的容器、网格、宽度或派生度量来实现对齐关系。

字体样式规则

• 优先使用项目的字号比例或平台文本样式。
• 应通过字号、字重、颜色和间距体现文本层级。
• 移动端正文应保持易读；有意义的内容不要使用过小的标签。
• 对用户需要阅读的内容，优先使用换行。
• 仅对元数据、标签、用户名、作者或有意限制空间的固定宽度标签使用截断。
• 截断文本时，应将文本限制在正确的组件内。不要让文本调整大小或挤压周围布局。

布局与间距规则

• 使用统一的页面内边距和内容最大宽度。
• 遵循安全区域、刘海屏、主屏幕指示条和键盘行为要求。
• 产品中的主要底部操作应采用统一的宽度和垂直位置。
• 返回、关闭、通知或收藏等顶部控件应采用统一的定位方式。
• 同一系列的卡片应采用统一的外观度量：宽度、圆角、阴影、内容内边距和间距节奏。
• 除非设计明确使用内嵌子卡片，否则避免嵌套卡片。

交互规则

• iOS 上的触控目标至少应为 44 pt，其他平台则采用相应标准。
• 仅包含图标的按钮需要提供无障碍标签。
• 破坏性操作需要明确的确认或撤销方式。
• 加载、重试、禁用、空状态和错误状态都必须明确呈现。
• 在可行的情况下，返回行为应符合用户的进入路径。
• 可点击区域应符合用户预期；如果整行或整张卡片都表示可操作区域，不要只将点击限制在很小的图标上。

审查清单

完成 UI 工作前，请检查：

• 添加新组件前，我是否搜索过现有组件？
• 颜色、字体排印、间距、圆角和阴影是否都已令牌化？
• 组件内部的尺寸参数是否放在组件指标中，而不是内联写在视图主体里？
• 特定屏幕的布局值是否集中分组并命名？
• 相关的宽度和位置是否都基于同一个事实来源推导？
• 我是否更新了同一系列的所有组件，或说明了未更新的原因？
• 文本是否能完整显示，没有不必要的截断？
• 是否遵循了触控目标和安全区域的要求？
• 我是否运行了相关的构建和类型检查？
• 如果是在优化视觉效果，在可行的情况下，我是否安装并运行了应用，或截取了屏幕截图？

常见反模式

• 没有检查共享容器，就说“把这里往下移 8px”。
• 仅仅因为这个屏幕“稍有不同”，就重复实现一个按钮。
• 将 Figma 坐标直接复制到视图主体中。
• 仅仅因为某个标签看起来不对，就添加一个局部字号。
• 只在一个屏幕上修复宽度，却让同一组件在其他地方继续出问题。
• 在生产 UI 中使用仅适用于模拟数据的布局假设。
• 让生成内容或后端文本决定 UI 布局，却不设置长度限制或截断策略。

可以接受局部例外的情况

如果例外是经过刻意设计且范围受控的，就可以接受：

• 仅用于某个屏幕的装饰资源。
• 具有独特艺术指导的一次性营销或编辑类布局。
• 过渡期重构：在当前变更中，完整提取组件的风险过高。
• 需要局部适配的平台特定约束。

即便如此，也要将值放在有名称的指标对象中，并将例外控制在较小范围内。