design-systems-frontend-architecture

设计系统前端架构

目的

帮助 Agent 将 UI、UX、产品和品牌决策转化为持久的前端系统：可复用组件、设计令牌、布局规则、状态行为、文档、治理和实现指南，使其能够跨屏幕、团队、设备和时间进行扩展。

以实际产品工作为优化目标。不要只描述设计系统。应提供用户可以直接采用的决策、默认方案、组件契约、实现指南、评审意见和后续步骤。

适用场景

当用户提出以下任一需求时，使用此技能：

• 设计系统策略、组件库、模式库、样式指南、设计令牌、UI 套件、组件审计、界面清单或治理。
• UI 评审、重新设计、前端实现计划、组件拆分、响应式布局指南、CSS 架构或前端可维护性。
• 将模型、截图、UX 流程或产品需求转化为可扩展的前端组件。
• 组件、令牌、无障碍状态、使用指南或设计到代码交接相关文档。
• 解决不同 UI 界面之间的不一致、模式重复、临时样式或组件偏移问题。

不适用场景

当任务主要涉及以下内容时，不要将此技能作为主要视角：

• 尚未关联到 UI 或系统决策的广泛 UX 研究规划、民族志研究、探索性访谈、市场调研或产品策略。
• 视觉艺术指导、插画风格、营销创意或品牌形象创建，但用户正将其转化为系统规则的情况除外。
• 纯后端架构、API 设计、数据建模或基础设施。
• 无需考虑复用、无障碍或前端实现的一次性静态图形设计。

核心原则

1. 设计系统，而不是页面。 按组件、模板、内容类型、状态、集成和行为来规划工作范围，而不是按页面数量。
2. 同时考虑局部与整体。 综合评估令牌、原子、组件、区块、模板和真实页面。设计组件时，务必检查它在真实的组合与内容中如何运作。
3. 区分功能与感知。 将功能模式视为行为和界面模块；将感知模式视为塑造产品特征的样式、语气、动效、间距、颜色和字体处理。
4. 先明确目的，再做抽象。 组件旨在解决用户或产品问题。不要仅凭视觉相似性创建抽象。
5. 将共享语言作为基础设施。 名称、定义、使用规则和示例都是系统的一部分，而非点缀。
6. 优先使用可复用的基础构件，同时保留产品特色。 一致性应减少用户的操作成本和团队的浪费，而不应抹去有价值的品牌表达或标志性体验。
7. 让系统成为事实来源。 对已发布 UI 的更改应在适当时同步更新对应组件、令牌或指南；避免孤立的热修复。
8. 将无障碍视为组件契约的一部分。 必须在模式规范中明确语义、键盘行为、焦点、对比度、点击区域、错误处理和减少动态效果的行为。
9. 尽早确定前端架构以避免技术债，同时保持灵活。 在实现扩散之前确立约定，并随着产品演进有意识地修订。
10. 文档应便于使用，而非仅供存档。 文档必须说明何时使用某种模式、何时不使用、其行为方式、实现方式以及负责人。

参阅 references/principle-cards.md，了解每项原则对应的可复用卡片。

默认建议

除非用户提供的上下文明确要求采用不同方案，否则使用以下默认建议。

产品与范围默认值

• 默认范围： 定义最小而实用的系统切片：令牌 + 3-5 个核心组件 + 1-2 个代表性模板 + 文档。这样可以避免打造臃肿的“大爆炸式”系统。
• 默认优先级： 优先处理高频、高风险的模式：按钮、链接、表单、警告、导航、卡片/列表、布局基元、字体比例、间距、颜色语义、加载/空状态/错误状态。
• 默认迁移方式： 逐步改进。优先按组件逐一替换并弃用旧方案，而不是全面重新设计；除非产品处于早期阶段，或正在进行重大平台迁移。

设计系统结构默认值

• 默认模型： 采用分层系统：基础/令牌 → 基元 → 组件 → 组合/模板 → 产品示例/页面。
• 默认命名： 按用途而非外观命名模式。优先使用 Primary action、Course card、Filter panel、Inline validation 或 Promotion banner，而非 blue button、big box 或 right rail thing。
• 默认文档： 每个可复用模式都应说明用途、结构、变体、状态、无障碍要求、内容指南、响应式行为、实现说明、示例和反例。
• 默认治理： 采用轻量管理。允许贡献，但新增令牌/组件须经审核，新增变体须有依据。

令牌默认值

• 默认令牌类别： 颜色、排版、间距、圆角、边框、层级/阴影、动效、不透明度、z-index/层级、尺寸、断点/容器，以及语义状态令牌。
• 默认令牌结构： 将原始值与语义令牌分开。例如：原始令牌 color.blue.600；语义令牌 color.action.primary.bg；仅当需要组件专属映射时，才使用组件令牌 button.primary.bg。
• 默认命名： 使用角色和状态，而非原始外观。优先使用 text.muted、surface.raised、border.focus、status.error.fg，而非 gray-500-for-labels。
• 默认覆盖规则： 不要为单个例外新增令牌。先确认现有语义令牌、组件变体或局部产品需求是否已能涵盖该情况。

布局与响应式默认值

• 默认布局策略： 以内容为先，设计内在响应式布局，使用灵活容器、网格/弹性布局基元、流式间距和感知容器的规则。避免将桌面、平板和移动端设计成彼此无关的产物。
• 默认断点： 只使用足以保障可读性、导航和任务完成的断点。优先采用组件/容器行为，而非全局视口编排。
• 默认密度： 从适中的密度和宽裕的可浏览性开始。只有在专家工作流、数据密集型任务或屏幕空间受限时，才提高密度。
• 默认内容测试： 使用真实或贴近实际的内容进行测试，包括较长标签、缺失图片、空数据、错误状态、加载状态、密集数据，以及适用时的翻译字符串。

CSS 和前端默认规范

• 默认标记语言： 优先使用语义化 HTML。仅在语义不足时添加 ARIA，而非用它替代原生语义。
• 默认 CSS： 使用组件作用域、低特异性、由设计令牌驱动的 CSS。避免通过深层页面位置选择器设置样式。
• 默认方法： 选择或调整清晰的命名和分层约定。只要规则明确且一致，类似 BEM 的命名、工具类层、CSS modules 或框架作用域样式都可以。
• 默认 JS： 对 CSS 能可靠处理的效果，不要使用 JavaScript。只有在行为、状态、数据或无障碍需求要求时才使用 JS。
• 默认自定义控件： 从原生控件开始。如果需要自定义样式，应保留原生语义、标签、键盘行为、焦点可见性和表单行为。
• 默认构建/流程： 自动执行 lint、格式化、适用情况下的类型检查、无障碍检查、重要组件的视觉回归，以及预览/文档构建。

无障碍默认规范

• 默认目标： 满足 WCAG 2.2 AA 要求，除非用户有更严格的内部标准。
• 默认对比度： 文本和有意义的 UI 指示必须满足对比度要求；状态不能只依赖颜色来区分。
• 默认焦点： 所有交互控件都需要有清晰可见的焦点状态，并支持键盘操作。
• 默认目标区域： 小型控件需要有足够易用的点击区域，尤其要考虑触控和运动障碍用户。
• 默认动效： 动效应有明确目的、时长简短，并尽可能可中断，同时遵循减少动态效果偏好设置。

必须向用户确认的问题

仅当答案会实质性影响系统时才提问。不要让用户决定常规最佳实践。

当以下事项尚不明确且与需求相关时，请提出有针对性的问题：

• 产品目标、用户任务或目标受众不明确。
• 用户要求构建新系统，但品牌/产品个性或现有系统成熟度不明确。
• 工作必须集成到现有前端技术栈、CMS、组件框架或令牌格式中。
• 产品有特殊的无障碍、法规、性能、设备、本地化或数据密度限制。
• 用户要求的建议取决于治理方式、团队规模、发布流程或贡献模式。
• 用户要求覆盖会影响无障碍、实施成本、品牌一致性或可维护性的默认规范。

提问时，提供推荐默认选项和其他选项。可用时，使用 question 工具或等效模式。

使用 references/decision-prompts.md 中可直接用于 question 工具的提示词。

工作流：评审现有成果

评审现有 UI、设计系统、组件库或前端实现时，请按以下顺序检查：

1. 任务契合度与产品用途 — UI 要解决什么用户目标？主要操作和结果是否清晰？
2. 系统覆盖范围 — 已有哪些设计令牌、组件、模板和状态？哪些内容重复或缺失？
3. 信息层级 — 无需过度装饰，是否也能区分主要、次要和第三级元素？
4. 功能模式 — 模块是否命名清晰、目的明确、可复用，且行为清楚？
5. 感知模式 — 颜色、字体、间距、动效、图像和语气是否与预期的产品个性一致？
6. 布局与响应式设计 — 布局是否根据内容和容器需求进行适配，而非依赖随意设定的断点？
7. 交互清晰度 — 是否明确说明可操作性、状态、验证、加载、错误、空状态和边缘情况？
8. 无障碍性 — 检查语义、键盘操作流程、焦点、对比度、标签、目标尺寸、阅读顺序、动效和辅助文本。
9. 前端可行性 — 检查标记复杂度、CSS 优先级、令牌映射、依赖项、性能风险和可测试性。
10. 文档与治理 — 是否有单一事实来源、负责人、贡献途径和弃用流程？

按以下格式输出评审意见：风险最高的问题 → 重要性 → 建议的修复方案 → 对系统的影响 → 实施说明。避免列出冗长且无序的视觉意见。

工作流：创建或改进系统

提出新建议时，请按以下顺序进行：

1. 明确功能或用户问题。 确定主要任务、目标受众、平台、现有约束和成功标准。
2. 选择最小且有用的系统范围。 不要一开始就构建详尽的组件目录。
3. 盘点现有模式。 查找重复的功能、样式、重复代码、不一致的名称和反复出现的状态。
4. 定义功能模式。 按用途和行为对 UI 进行分组，再根据组件的功能为其命名。
5. 定义感知模式。 提取产品的标志性风格：字体、颜色、间距、形状、动效、图像、语气和状态呈现。
6. 建立设计令牌。 在适用时，将反复出现的感知设计决策转化为基础级、语义级和组件级令牌。
7. 明确组件契约。 为每个组件记录其结构、变体、状态、内容规则、无障碍行为、响应式行为和实施指南。
8. 使用真实内容组合模板。 在实际流程和页面级组合中验证组件。
9. 规划实施架构。 选择语义化标记、CSS 策略、组件边界、构建与测试流程、分发方式和迁移路径。
10. 编写文档并制定治理规则。 明确负责人、贡献、评审、发布、弃用和采用流程。
11. 验证。 定稿前进行质量、无障碍、响应式、性能和可维护性检查。
12. 解释决策。 将建议与用户目标、系统一致性、无障碍性、可维护性和实施成本联系起来。

决策框架

在推荐模式或架构前，请按以下顺序进行判断：

1. 目的： 这能解决什么问题或用户任务？
2. 复用： 这一需求会在不同功能、产品或状态中反复出现吗？
3. 差异： 真正需要哪些变体？哪些变体只是偶发的一次性需求？
4. 内容： 此模式必须适应哪些内容类型、长度、状态和本地化情况？
5. 无障碍： 需要哪些语义、焦点行为、键盘交互、标签、对比度、目标尺寸和动效规则？
6. 实现： 能否通过语义化标记、低优先级 CSS、令牌和最少量的 JS 来实现？
7. 系统契合度： 是否与现有令牌、组件、名称和文档保持一致？
8. 治理： 由谁负责？如何变更？用户如何知道该使用哪个版本？

推荐能够满足这些约束且复杂度最低的方案。只有产品场景确有需要时，才增加复杂度。

实用规则

组件规则

• 组件必须有明确用途，而不只是视觉形状。
• 不要仅凭截图创建组件。首先确定用户任务、内容模型、状态和响应式行为。
• 优先选择变体定义清晰的少量组件，而不是许多相似的组件。
• 变体必须体现用途、显著程度、状态或场景上的实质差异。
• 组件应提供稳定的 API 或 props，以映射系统决策，而不是提供任意的样式逃生口。
• 每个组件都需要包含真实内容示例，以及至少一个边界情况。

令牌规则

• 令牌应表达决策，而不只是存储值。
• 使用语义令牌表达含义，使用原始令牌管理调色板和比例。
• 有语义决策可用时，不要让产品团队直接使用原始令牌。
• 在确认需求是否会重复出现之前，不要为解决一次性需求而扩充令牌集。
• 在适用的情况下，包含悬停、激活、焦点、禁用、选中、成功、警告、错误和加载状态的令牌。

文档规则

• 先记录使用规则，再记录实现细节。
• 为每个主要模式注明“适用场景”和“不适用场景”。
• 如果视觉示例和反例能避免误用，就应将其纳入文档。
• 文档应与代码或设计事实来源保持足够紧密，避免内容过时。
• 将名称和词汇表条目视为产品架构的一部分。

治理规则

• 新模式必须说明原因：用户需求缺失、反复出现的产品需求、无障碍要求或实现简化。
• 新增视觉样式、组件变体或令牌前必须经过评审。
• 允许在核心系统之外进行实验，但必须明确实验何时转正、变更或终止。
• 跟踪已弃用的组件，并提供迁移指南。
• 通过采用率、重复项减少情况、无障碍质量、交付速度和面向用户的一致性来衡量系统健康状况。

无障碍与包容性要求

针对每项组件或 UI 建议，请说明：

• 语义元素的选择和无障碍名称。
• 键盘交互和 Tab 顺序。
• 焦点、悬停、激活、选中、禁用、无效、加载、成功和错误状态。
• 对比度以及不依赖颜色的状态指示方式。
• 触控／运动目标尺寸和控件间距。
• 相关的屏幕阅读器行为、实时区域和错误播报。
• 针对装饰性或大量使用过渡效果的行为提供减少动态效果的替代方案。
• 对文本缩放和页面缩放的适应能力。
• 相关的本地化和内容扩展风险。
• 在阅读顺序、语言清晰度和非惩罚性错误文案方面采用包容性默认设置。

除非同时说明如何保留原生语义和交互，否则切勿推荐自定义控件。

前端实现指南

语义化 HTML

• 优先使用已具备所需行为的原生元素：button、a、input、select、textarea、details、dialog、列表元素、标题、地标以及适用的表格元素。
• 使用标题和地标保留有意义的页面结构。
• 仅在原生语义不足时使用 ARIA，并确保 ARIA 状态与实际 UI 状态同步。

组件结构

• 让组件职责精简明确。
• 在有助于复用和测试时，将容器／数据编排与展示基础组件分离。
• 复杂的组合组件和模板应使用组合方式；避免构建庞大的单体组件。
• 根据角色、状态和内容定义输入／属性，而非直接使用原始 CSS。
• 在组件契约中涵盖空、加载中、错误、成功、禁用、已选中和溢出等情况。

CSS 和布局

• 为重复使用的值定义令牌。
• 保持低特异性；避免深层嵌套选择器和依赖页面位置的规则。
• 优先使用布局基础组件和组件内部的响应式规则，而非散布在页面级的覆盖样式。
• 在项目约束允许时，使用 flex 和 grid 等现代布局工具。
• 当 CSS 能以无障碍且可靠的方式处理行为时，使用 CSS 实现呈现、过渡和状态样式。
• 除有意设置的工具层或已知覆盖边界外，避免使用 !important。

响应式行为

• 明确内容如何重排、截断、换行、堆叠或折叠。
• 独立测试组件，并在有代表性的模板中测试。
• 除非内容和平台确实要求，否则不要假设尺寸固定。
• 将窄视口、高缩放比例和大号文本视为首要场景。

性能和可维护性

• 避免发布重复的组件实现。
• 避免为简单的展示问题引入大型依赖。
• 使用构建工具自动化可重复的任务，但不要只为求新而选择工具。
• 为 UI 偏移代价较高的重要组件和模板添加视觉回归测试。
• 更改组件 API、令牌名称或标记结构时，附上迁移说明。

质量检查清单

完成工作前，请确认：

• 建议针对组件、状态和内容，而不只是页面。
• 主要用户任务和成功标准清晰明确。
• 功能模式和感知模式均已涵盖。
• 令牌能区分基础值与语义决策。
• 组件具备明确用途、结构、变体、状态、无障碍支持、响应式行为和实现说明。
• 布局能够适应内容变化以及视口／容器变化。
• 无障碍是必要要求，而非事后补充。
• CSS 策略能避免特异性不断升级和一次性覆盖。
• 文档说明何时以及为何使用这些模式。
• 治理机制说明系统如何演进，同时避免臃肿或过时。
• 从产品、用户和实现角度解释权衡。

请参阅 references/checklists.md 中的完整检查清单。

应避免的常见错误

• 按页面数量估算或规划，而不是按组件／功能复杂度。
• 创建仅包含截图集或彼此割裂模块的“组件库”。
• 按外观而非用途命名组件。
• 创建仅照搬原始 CSS 值、没有语义含义的令牌。
• 将颜色、字体、动效、间距和语气视为表面装饰，而非感知模式。
• 过分追求完美一致，以至于产品特性和有益的尝试空间消失。
• 放任变体和一次性覆盖无限增加，直到系统变得杂乱无章。
• 构建自定义控件时，没有保留原生行为和无障碍能力。
• 使用脆弱的固定尺寸和针对特定断点的变通方案来解决布局问题。
• 使用 JavaScript 实现 CSS 可以更简单解决的样式效果。
• 任由文档与代码和设计源文件脱节。
• 对常规最佳实践询问用户，而不是采用可靠的默认方案。

完整的反模式列表请参阅 references/anti-patterns.md。

如何向用户解释建议

按以下顺序解释选择：

1. 用户影响： 说明该建议如何改善任务完成度、清晰度、无障碍体验或信心。
2. 系统影响： 说明该建议如何提升一致性、复用性、治理能力或命名质量。
3. 前端影响： 说明该建议如何降低复杂度、特异性、偏差、回归问题或维护成本。
4. 权衡： 说明会失去或受到限制的内容，以及何时更适合采用其他选择。
5. 下一步行动： 说明接下来要实现、记录、测试或询问什么。

使用具体措辞。优先说“使用一个具有成功、警告和错误变体的 Inline validation 组件”，而不是“让验证保持一致”。