EUI 设计系统同步指南：让 Figma Borealis 组件库与代码变更保持对齐

EUI 设计系统同步指南让 Figma Borealis 组件库与代码变更保持对齐【免费下载链接】euiElastic UI Framework 项目地址: https://gitcode.com/GitHub_Trending/eu/euiEUIElastic UI作为支撑 Elastic 全线产品的开源组件库其视觉语言由代码组件、设计 Token与设计资产Figma 库共同定义。本篇指南以 wiki/contributing-to-eui/designing/README.md 为骨架系统讲解在提交影响视觉、行为或属性的代码变更时如何判定是否需要同步更新 Figma 库并完整走通设计审查流程同时结合仓库内的主题 Token、图标与组件源码帮助你理解代码改了什么 → 设计资产要改什么的对应关系。为什么需要设计系统同步EUI 不是一个孤立的代码仓库它同时维护着两份事实来源代码侧packages/eui下的 React 组件实现、Emotion 样式以及packages/eui-theme-borealis、packages/eui-theme-common中的设计 Token 定义设计侧Elastic UI Borealis Figma 库这是设计团队制作界面、标注规范、评审改动的唯一权威资产。当任何代码变更影响了组件的视觉设计、行为或属性时若 Figma 库不同步就会出现设计稿与实现不一致的割裂——下游产品团队照着过时的 Figma 画界面工程师却已按新代码实现最终在 Kibana 等消费方产品中形成肉眼可见的偏差。因此EUI 贡献规范要求凡涉及设计影响的 PR都必须让 Figma 库保持同步以维持整个 Elastic 生态中设计与开发的一致性。哪些代码变更需要同步更新 Figma文档明确了六类会影响设计、必须触发 Figma 库更新的代码变更。这六类正是贡献者在提交 PR 前需要逐条自查的清单变更类型典型内容影响面组件视觉变化样式修改、颜色更新、间距调整、排版调整所有使用该组件的页面与设计稿新增组件走完四步组件创建流程后交付的新组件Figma 库需新增对应组件及其变体Props 修改增加、删除或改变影响视觉输出的组件属性属性面板、组件示例、文档示例图标新增/修改新图标或对既有图标的修改图标库、EuiIcon组件、文档搜索设计 Token 更新颜色、间距、排版等 Token 的变动主题包、全局样式、全量组件行为变化交互、状态hover/active/disabled、动画用户可感知的体验变化需要特别说明的是这些变更的代码实现本身位于仓库内贡献者可以在提交代码的同时完成设计资产对齐组件视觉与 Props 修改实现于 packages/eui/src/components 下的对应组件目录如button、form、table样式采用 Emotion 方案编写规范见 wiki/contributing-to-eui/developing/writing-styles-with-emotion.md设计 Token 的真身则分布在 packages/eui-theme-borealis/src/variablesBorealis 主题专属 Token与 packages/eui-theme-common/src通用 Token 类型与构建逻辑中新增组件的完整流程见 wiki/contributing-to-eui/developing/README.md四步React 实现 → Emotion 样式 → 测试 → 文档示例文件组织规范见 wiki/contributing-to-eui/developing/creating-component-files.md图标设计规范与入库步骤见 wiki/contributing-to-eui/developing/creating-icons.md。设计审查流程三步走当你的 PR 命中上述任一变更类型时按以下流程推进设计同步与审查联系设计同事如果需要先联系你团队中的设计同事让他们在整个过程中提供支持例如帮助你确认 Figma 中的做法是否符合组件规范。在 Figma 库中创建分支在 Elastic UI Borealis 库中新建一个包含拟议变更的 Figma 分支并在分支中链接对应的 PR让设计与代码能够相互追溯。发起设计审查使用 Figma 内置的审查工作流请求设计评审或将分支分享到团队的#eui-designSlack 频道等待设计团队反馈。这三步完成后设计评审通过、代码 PR 也通过 Review 后Figma 分支合回主库代码合并进main一份变更即同时完成两侧的落地。深入源码设计 Token 如何与 Figma 对应要判断Token 更新类变更的影响范围需要先理解仓库中主题的结构。从源码看Borealis 主题在 packages/eui-theme-borealis/src/index.ts 中通过buildTheme(euiThemeBorealis, EUI_THEME_BOREALIS)构建其中euiThemeBorealis这一EuiThemeShape对象聚合了colors、size、border、font、animation、breakpoint、levels、shadows、focus、components、flags、overrides等所有 Token 分组。其中 packages/eui-theme-borealis/src/variables/_components.ts 是最能体现设计与代码一一对应的文件它为 badge、breadcrumbs、code、dataGrid、header、popover、table、tooltip、tour 等数十个组件定义了独立的组件级颜色 Token例如// packages/eui-theme-borealis/src/variables/_components.ts节选 const component_colors: _EuiThemeComponentColors { badgeBackground: computed( ([backgroundLightText]) backgroundLightText, [colors.backgroundFilledText] ), tableRowBackgroundHover: computed( ([backgroundBaseInteractiveHover]) backgroundBaseInteractiveHover, [colors.backgroundBaseInteractiveHover] ), // ... };可以观察到两个关键模式Token 派生关系组件级 Token 大量通过computed从语义色如backgroundBaseInteractiveHover派生而不是写死色值。这意味着改动一个语义色会自动级联到多个组件的视觉——这类改动在 Figma 侧同样要同步更新所有引用该色板的组件。明暗双态components对象同时导出LIGHT与DARK两组颜色暗色模式下会覆盖 code、loading、table、tour 等组件的部分 Token见_components.ts中DARK: { ...component_colors, ... }的重写逻辑。因此任何颜色类变更都必须同时核对明、暗两套主题下的 Figma 展示。主题包构建说明可参考 packages/eui-theme-borealis/README.md需要先yarn安装依赖并执行yarn workspaces foreach -Rti --from elastic/eui-theme-borealis run build构建本地依赖包。深入源码图标变更如何落入代码库图标新增/修改是六类变更中最常见的一类其代码侧流程在 wiki/contributing-to-eui/developing/creating-icons.md 中有完整描述与设计同步直接相关的是以下入库步骤将 SVG 文件放入packages/eui/src/components/icon/svgs目录在packages/eui/src/components/icon/icon_map.ts中按字母序添加 SVG 导入引用并可附带元数据。仓库中真实存在大量这样的写法// packages/eui/src/components/icon/icon_map.ts节选 accessibility: withMetadata(() import(./assets/accessibility), { category: glyph, synonyms: [accessibility, a11y], }), agentApp: withMetadata(() import(./assets/app_fleet), { category: app, synonyms: [fleet], }),其中category与synonyms均为可选字段用于让图标参与文档站点的搜索与分组——这一点与 Figma 侧在组件描述中补充同义词以便设计师检索的做法遥相呼应两边都在做可发现性discoverability建设。进入packages/eui目录执行yarn compile-icons编译随后启动文档站yarn workspace elastic/eui-website build:workspaces yarn workspace elastic/eui-website start在本地预览图标并切换到暗色模式确认图形在反色下仍清晰可见运行yarn run test-unit icon -u生成/更新 Jest 快照。设计侧同样遵循一套严格规范16x16 viewbox、1px 描边、方形端点、外圆内方转角、2D 透视、1px 安全区、光学居中等详见上文给出的图标指南文档——PR 中的图标必须同时满足设计与代码两侧的规范这正是设计系统同步在图标维度上的具体体现。一份自检清单提交影响设计的 PR 前把文档与仓库规范合并可以整理出如下提交前自检清单我的变更是否命中六类设计影响变更视觉 / 新组件 / Props / 图标 / Token / 行为若是是否已在 Figma Borealis 库创建分支并放入拟议变更Figma 分支是否链接了对应 PR 编号颜色类变更是否同时校验了LIGHT与DARK两套主题 Token图标类变更是否满足设计规范并已完成icon_map.ts、compile-icons、暗色预览与快照更新是否通过 Figma 内置流程或#eui-design频道发起了设计审查设计审查通过、PR 合并后Figma 分支是否合回主库遵循这套同步机制代码与设计资产才能始终指向同一套视觉真相——这正是 EUI 在 Elastic 庞大产品矩阵中保持设计一致性的基础设施。延伸阅读EUI 贡献总览贡献流程、PR 规范、提交信息约定组件开发与架构组件创建四步流程与模式约定图标创建指南图标设计规范与入库步骤Emotion 样式编写规范Borealis 主题包Token 构建与本地依赖说明Borealis 组件 Token 实现图标注册与元数据【免费下载链接】euiElastic UI Framework 项目地址: https://gitcode.com/GitHub_Trending/eu/eui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考