Backstage 设计系统全景指南从设计哲学、组件协作流程到 Storybook 与主题定制实践【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstageBackstage 是一个用于构建开发者门户Developer Portal的开源框架而本文介绍的设计系统Design System正是其打造一致、连贯、可复用用户体验的基石。围绕仓库中的 docs/dls/design.md 这份设计团队官方文档本文将系统梳理 Backstage 设计团队的三大工作哲学、新建设计组件与为 Backstage 构建两条完整的协作流程、两大核心优先级以及贡献者如何通过 Issue、Figma 与 Storybook 参与到设计工作中。读完本文你将掌握Backstage 设计系统与 Material UI 的分层关系、设计组件从提案到落地的完整生命周期、基于主题Theme与设计令牌Design Token自定义组织品牌 UI 的方法以及本地运行 Backstage Storybook 的具体步骤。Backstage 设计团队的三大工作哲学原文档开篇即强调和 Backstage 开源项目本身一样这份设计文档也是一份活文档living document会随着设计实践的演化持续更新。设计团队的协作方式建立在三条核心哲学之上。迭代IterativeBackstage 开源设计实践尚属新起步的事业团队希望与社区紧密协作在推进过程中不断迭代与实验探索什么才是最有效的做法。其核心理念是尽早发布、经常发布release early and often并且承诺与开发者共同打造无缝、轻松的交付handoff体验。对社区成员而言若想见证并参与这一成长过程可以关注仓库中带design标签的 issue。协作CollaborativeBackstage 设计团队规模不大但注重协作质量非常珍视与开源社区共事的机会。如果你有想法或组件需求可以通过 Discord 的#design频道与设计团队沟通。团队相信协作胜过个人速度Collaboration trumps individual speed目标是让 Backstage 服务于所有用户。透明Transparent团队承诺让社区随时了解进展通过 GitHub 里程碑了解路线图、通过带design标签的开放 issue 寻找可协助的任务、在 Discord 的#design频道发布更新并透明地分享我们做了什么决定、为什么这样做。Backstage 设计实践两条核心工作流程原文档用两张表清晰定义了设计团队与社区之间的协作方式。这些流程与仓库中真实存在的产物一一对应Figma UI kit、GitHub issue、backstage/core-components包以及 Storybook。流程一新建一个设计组件6 步新建设计组件的完整流程如下步骤说明Step 1平台设计团队在 backstage/backstage GitHub 仓库提交一个 issue提出潜在的新组件。Step 2Backstage 社区在 GitHub 上给出反馈或批准意见。Step 3平台设计团队酌情调整方案并更新 Figma DLS 文档。Step 4设计好的组件以 issue 形式添加到 backstage/backstage GitHub 仓库。Step 5外部或内部 Backstage 开源贡献者构建该组件。Step 6外部或内部贡献者将组件添加到 Backstage Storybook。从仓库源码看这个流程的落地点非常具体自定义 Backstage 组件会被放置在backstage/core-components包中并配套加入 Storybook例如 Progress 组件、Header 等通用 UI 元素都遵循这一路径。社区贡献者正是通过这条流水线把被设计团队审核过的组件沉淀为所有插件开发者可复用的公共资产。流程二为 Backstage 构建8 步这是普通开发者外部或内部贡献者基于设计系统构建自己实体的流程步骤说明Step 1外部或内部贡献者使用 Backstage 后产生构建某个实体的想法。Step 2贡献者查阅 Figma DLS 文档中的 Backstage 开源设计系统文档。Step 3贡献者复用 Backstage Storybook 中的组件与令牌tokens。Step 4贡献者构建自己的 Backstage 实体。Step 5贡献者在 backstage/backstage GitHub 上为实体提交 Pull Request 供审查。Step 6平台设计师与开发者审查实体在 GitHub 上提交反馈或批准。Step 7贡献者完成修改PR 获批并合并实体在 Backstage 上线。Step 8如果该实体包含或本身就是UX 组件则同样加入 Backstage Storybook。设计系统与主题的关系一次看懂分层上图docs/assets/dls/DLS.png直观展示了 Backstage Design System 与基础层的关系设计系统 Backstage UI/UX由 Backstage 设计团队基于用户体验与用户界面决策塑造Material UI底层组件库并且鼓励使用者在此基础上叠加自定义主题Custom Theming以更好地代表各自组织。Backstage 设计系统的两大核心优先级Backstage 设计系统Backstage Design System这是为 Backstage 贡献者准备的一套积木building blocks用于创建出色的插件。原文档反复强调一个观点何必重复造轮子——直接使用已经过设计团队与社区验证的组件即可。为了在整个 Backstage 中打造连贯、一致的用户体验设计团队强烈建议所有插件开发者以 Storybook 作为参考。设计系统本身是崭新且持续演进的需要在社区的帮助下逐步完善。核心 Backstage 用户体验Core Backstage User Experience这是所有 Backstage 用户共享的普适体验既包含插件目录等具体层面也包含端到端工作流等抽象层面。设计团队将联合社区共同打磨这套核心体验以最好地服务用户与组织。如何参与贡献原文档给出了两条最直接的参与路径二者均以 GitHub issue 为主要载体。认领一个 issuePick up an issue初期大部分设计 issue 围绕两件事展开一是为 Backstage 设计系统创建通用组件并加入 Storybook供插件开发者引用二是构建核心 Backstage 用户体验。GitHub 上的 issue 会带有design和/或storybook标签社区成员可以自行浏览并认领感兴趣的任务。如有疑问可在 issue 评论区或 Discord 的#design频道提问。请求一个组件Request a component创建 issue打上design标签或在 Discord#design频道发送消息说明所需组件的细节及其相关用例。设计团队会审查你的请求通常在 1~2 个工作日内回复并告知该组件是否会被纳入设计系统。配套资源与延伸文档原文档列出的核心资源在仓库中均有对应的配套文档可继续深入阅读Storybook用于查看组件。若想帮助建设设计系统也可以把设计好的组件加入 Storybook。仓库中的配套指南 贡献 Storybook 详细说明了 story 的组织方式与本地运行方法。Figma设计团队使用 Figma Community 共享设计资产可以复制其 UI kit 来设计自己的 Backstage 插件。详见 Figma 指南。自定义应用 UI通过扩展主题theme定制 Backstage 实例的外观与感受详见 Customizing Your Apps UI。组件设计规范新建组件或编写插件专属组件前应遵循 组件设计指南其中涵盖布局Layout、配色Color palette与排版Typography三大主题。从设计到代码组件开发者的落地准则设计系统最终要落到代码层面。原文档强调Backstage 设计基于 Material UI并在此基础上扩展、编写了自定义组件以提供特定功能。组件设计指南给出了三条可执行的落地准则。布局优先复用主题感知布局指内容组织与堆叠方式。任何时候都应优先使用 Backstage 自带组件其次回退到 Material UI 组件。若均不满足可以自建组件但不推荐直接使用 HTMLCSS而应使用 Material UI 的布局组件使布局主题感知theme aware——当有人切换主题时布局会随主题变化而无需改动代码。重点使用的布局组件包括Container页面级、Box类似高度可定制的 div、Grid灵活栅格布局、Paper卡片基底提供背景色与边框内边距、Card支持标题、描述、按钮、图片等。配色以主题调色板为唯一来源若只是想在全局范围内微调某个既有组件的颜色可通过自定义主题覆盖该组件的特定样式含内边距、外边距与颜色。而从零开始做组件时应尽量引用主题的调色板color palette。当确实需要显式控制组件颜色时例如组件默认使用主色但你希望用次色最推荐的方式是覆盖组件样式。一个典型示例出自 组件设计指南import { makeStyles, Paper } from material-ui/core; const useStyles makeStyles((theme: Theme) ({ sidebarPaper: { backgroundColor: theme.palette.primary.main, color: theme.palette.primary.contrastText, }, })); export function Sidebar({ children }) { const { sidebarPaper } useStyles(); return Paper className{sidebarPaper}{children}/Paper; }从源码看Backstage 内置了完整的两套调色板light / dark定义于 packages/theme/src/base/palettes.ts浅色主题背景默认#F8F8F8、主色#1F5493并包含status.ok、status.warning、status.error、banner、navigation、tabbar等细分令牌深色主题则使用#333333背景与#9CC9FF主色。令牌名称保持一致变化的只是不同主题下与这些令牌关联的实际颜色值。排版交给 Typography 组件绝大多数场景下Material UI 的Typography /组件会自动使用主题的排版属性字族、字号、字重以及适配上下文环境的调色板颜色——例如 contained 按钮使用白色字体深色主题下按钮会自适应地改用深色字体以保证对比度。只有当父组件是布局型组件、不负责渲染文本时如标题、段落等场景才应显式使用 Typography 组件而非 HTML 原生标签并特别留意其无障碍accessibility建议。Backstage 的默认排版参数同样有源码可依定义于 createBaseThemeOptions.ts默认htmlFontSize为 16默认字族为Helvetica Neue, Helvetica, Roboto, Arial, sans-serif标题从 h154px/700到 h620px/700逐级递减。此外 pageTheme.ts 内置了home、documentation、tool、service、website、library、app、apis等页面主题每个页面主题由渐变色与形状wave、wave2、round、square组合生成页头背景例如home使用 teal 色系 wave 形状。主题定制实战让设计系统长出你的组织品牌设计系统并非一刀切。正如原文档所说鼓励在核心体验之上叠加自定义主题以体现组织特色。仓库中的 Customizing Your Apps UI 给出了完整的两套定制方案。基于 MUI 的自定义主题旧体系通过backstage/theme包提供的createUnifiedTheme与createBaseThemeOptions可以基于内置浅/深主题快速派生品牌主题import { createBaseThemeOptions, createUnifiedTheme, palettes, } from backstage/theme; export const lightTheme createUnifiedTheme({ ...createBaseThemeOptions({ palette: palettes.light, }), fontFamily: Comic Sans MS, defaultPageTheme: home, });在此基础上还可以进一步覆盖调色板、页面主题、排版与组件样式components下的styleOverrides并在应用的themes数组中注册id、title、variant、icon、Provider五个字段让用户能在设置页选择明/暗主题。基于 CSS 变量的 Backstage UI 主题新体系新体系 Backstage UI 完全基于 CSS只需在应用中引入自己的 CSS 文件通过:root或[data-theme-modelight]/[data-theme-modedark]选择器覆盖--bui-*系列设计令牌如--bui-bg-app、--bui-fg-primary、--bui-border-1、--bui-font-regular、--bui-space、--bui-radius-1等即可整体改变外观组件类名统一以.bui-前缀标识便于定向微调。把组件沉淀到 Storybook设计组件的最终归宿是 Backstage Storybook——它是探索可复用 Backstage UI 元素按钮、表格、专用小部件等及其用法的核心场所。配套文档 contributing-to-storybook.md 给出了清晰的规范自定义 Backstage 组件放在backstage/core-components包中并加入 Storybook当既有 Material UI 组件足够时无需重复封装但若希望沉淀一种有主见的用法opinionated usage也可为它编写 story当 story 变得复杂需要特定颜色、变体、参数组合时它就可能成为重构为完整 Backstage 核心组件的候选。新建 story 的规范在待文档化组件旁边创建componentName.stories.tsx文件例如core └── src └── components └── Progress ├── Progress.tsx └── Progress.stories.tsx本地运行进入storybook目录先执行yarn install安装依赖再运行yarn storybook。启动成功后服务运行在6006 端口浏览器访问http://localhost:6006/即可浏览全部组件。仓库根目录 package.json 中的脚本storybook: storybook dev -p 6006印证了这一默认端口。未来方向欢迎设计师加入原文档最后展望了设计团队的未来无论你是正在实施 Backstage 的组织里的设计师、对开发者生产力领域感兴趣的设计师还是对开源设计好奇的设计师都欢迎加入贡献。团队正在幕后搭建若干基础要素样式指南、UX 原则、Figma 文档等以确保设计师参与 Backstage 贡献足够顺畅。总而言之Backstage 设计系统是一套社区共建、以组件复用为核心、以主题为个性化出口的开放体系设计团队负责定义方向与规范贡献者通过 Issue 提案、Figma 对齐、Storybook 沉淀最终让所有插件开发者都能站在被验证过的组件与令牌之上构建出既统一又各具组织特色的开发者门户体验。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考