evolving-design-system-components

演进设计系统组件

此技能依据 Bitwarden 的两个治理页面开展组件库工作： 创建新的设计模式 和 修改现有设计系统组件。 在推进实际提案前，请通过 get_confluence_page 阅读规范页面——这些页面的更新速度 比此技能快，并且链接到下文提及的模板 Figma 文件和工程流程。Figma 规范（属性排序、命名）见 references/figma-conventions.md。

两种路径

共有两种治理流程。它们从相同的起点出发，但之后会分开。

• 创建新模式。 创建尚不存在的模式。根据使用场景和复杂程度，在“这是 核心组件，还是 Recipe/Snowflake？”处选择分支。
• 修改现有组件。 修改已存在的模式。由于会影响整个产品中的组件实例，因此始终需要 UI Foundation 团队参与。

此技能会逐一介绍这两种路径。推荐步骤前，请先确认适用哪一种——它们的评审关卡不同。

步骤 1：先搜索，再提议

对于任一路径，都应先检查该模式是否已经存在。“我们需要一个新组件”最常见的误判是： “组件库里已经有这个组件，只是设计师没找到。”

使用 using-figma 中的 search_design_system 和 get_libraries。如果找到相似项， 问题就变成了：是直接使用、修改它（路径 B），还是在其下提议一个新变体。如果没有找到匹配项，则继续。

步骤 2：与团队确认需求

对于两种路径，都应先由设计团队达成一致，再让工程团队参与。根据 Confluence 页面：

• 设计师识别需求，并在功能文件中创建新模式或修改后模式的草稿。
• 设计师与设计团队分享——根据时间安排，可以进行团队迭代，也可以先独立起草，再由团队评议。
• 设计团队会根据所选路径，围绕三到四个问题进行评审：

新模式：

• 考虑过哪些现有模式？为什么不适用？
• 新模式能带来什么价值？
• 是否符合现有设计／品牌指南？
• 还有哪些使用场景？是否可以在多个地方使用？

修改模式：

• 是否提升了视觉吸引力？
• 是否扩展了组件的使用场景？
• 是否符合其他 UI 模式？
• 会如何影响整个产品中的组件实例？
• 还可能影响哪些其他组件或模式？

在提案继续推进前，团队应先就是否继续达成一致。创建新设计模式页面链接了 新模式讨论 Figma 模板； 如果提案人没有自己的讨论结构，请提供此模板。

步骤 3（仅适用于新模式）：核心组件还是 Recipe/Snowflake

此决定应与 UI Foundation 团队共同做出——提案设计师不得单方面决定。

• 核心组件库候选项。 使用场景较多，或复杂到单个功能团队难以维护。它将成为由 UI Foundation 负责的一级组件库组件。
• Recipe / Snowflake。 使用场景较少，或专用于某个功能界面。由构建它的 功能团队负责。它仍会添加到 Figma 库中，方便其他设计师查找。

与 UI Foundation 安排沟通。逐一梳理使用场景。组件归属以他们的判断为准。Confluence 页面还引用了工程侧的 创建新组件—— 选择核心组件路径时，请阅读该页面。

步骤 4：在 Figma 库中构建

Figma 侧的流程有明确的约定。相关规范——属性顺序、命名、必需状态、文档模式——见 references/figma-conventions.md。主要步骤如下：

• 打开 Tailwind Component Library Figma 文件。
• 创建一个以组件／模式命名的新分支。
• 将新增（或修改后的）UI 模式添加为 Figma Component：新组件放在专用页面上，修改现有组件则放在该组件所在的页面上。
• 对于交互式组件，至少确保包含以下状态：默认、悬停、焦点、激活（适用时）、禁用（适用时）。
• 根据 CL API 设计文档 和现有的 Figma 属性模式命名 Figma 属性。属性顺序很重要——参见 references/figma-conventions.md。
• 在组件旁创建组件文档画板，说明用法、行为、变体和无障碍注意事项。通常应复制并调整现有组件的文档，而不是从头开始。
• 修改组件时，请在每个有改动的组件上添加 Figma 评论，注明改动内容。

步骤 5：评审关卡

• 新模式。 将分支提交给 Design 团队评审。
• 修改。 将分支提交给 Design 团队评审，并且在团队同步会上进行评审。合并前，至少需要另外 2 位设计师批准。
• 在团队同步会上与 UI Foundation 工程团队一起评审改动。
• 如果尚未创建 Jira issue，请在 Component Library board 上创建一个。并在下一次同步会上与 UI Foundation 工程团队确定优先级。

步骤 6：合并时机——Figma 与代码

默认情况下，应等工程团队更新代码后再合并 Figma 分支，这样设计师就不会在 Figma 中看到产品里尚不存在的 UI。但也有例外：

• 设计师现在就需要这些改动。 在 Figma 中的组件文档上添加警告徽标，注明工程进度，合并 Figma 分支，并在 #team-eng-ui-foundation 中向工程团队发送更新。
• 分支维护起来过于繁琐。 同样适用此例外——添加警告后合并并发布通知。

默认遵循严谨的顺序。谨慎使用例外。

与其他技能配合使用

• using-figma。 在提案前搜索时使用 search_design_system 和 get_libraries；检查现有组件时使用 get_metadata 和 get_variable_defs；将模式提升为 Core Component 时，使用 Code Connect 工具（get_code_connect_map、add_code_connect_map、get_context_for_code_connect）建立设计到代码的关联。
• facilitating-design-critique。 步骤 2 中设计团队的对齐环节是一次设计评审会议，而不是一次性的消息沟通。提案者需要帮助来组织会议时，可调用设计评审引导技能。
• navigating-design-jira-process。 Component Library Jira board 属于更大的 Product and Design Jira 工作流。当提案产生工程工作时，可调用 Jira 流程技能，以正确推进各项状态。

常见陷阱

• 跳过提案前的搜索。 始终先使用 search_design_system。
• 由设计师单方面决定 Core／Recipe。 此决定必须经过 UI Foundation 团队讨论。不要提前自行决定。
• 属性名称不符合 CL API 约定。 命名不一致会降低团队使用该库的便利性。请阅读 CL API 设计文档，不要自行发挥。
• 提前合并时跳过警告徽标。 采用例外流程时，必须在 Figma 中添加警告徽标，并在 #team-eng-ui-foundation 中发送消息，二者都不能省略。
• 在没有沟通的情况下先于工程团队合并 Figma 改动。 下游设计师会看到产品中不存在的 UI，并基于它继续开展工作。

输出格式

在请求协助提出模式或修改组件时：

1. 路径 — 新模式或修改内容。
2. 搜索结果 — 库中已有的相关或重叠内容。
3. 设计团队对齐计划 — 评审时要带上哪些内容，以及团队需要权衡哪些问题。
4. 核心组件还是配方的判断（仅适用于新模式） — 如何围绕 UI Foundation 展开讨论。
5. Figma 计划 — 分支名称、页面位置、必需状态、属性顺序、文档画板。
6. 评审流程 — 需要获得哪些设计师批准、UI Foundation 评审、Component Library Jira 事项。
7. 合并时间 — 默认情况或例外情况；如属例外，需执行警告徽标和沟通步骤。