从零构建企业级设计系统：原子设计、React与Stitches实战

1. 项目概述一个设计系统的诞生与价值最近在整理团队过去一年的项目文档发现一个有趣的现象无论是新来的实习生还是合作多年的产品经理在讨论界面细节时总会出现一些“鸡同鸭讲”的尴尬时刻。比如PM说“这个按钮用主色”前端同学会反问“是primary-600还是brand-blue”设计师交付了一个“中等圆角”的卡片到了开发手里可能变成了border-radius: 8px也可能是4px。这些看似微小的不一致日积月累最终导致产品体验割裂、开发效率低下、设计还原度打折扣。这正是我决定牵头搭建一个内部设计系统并将其命名为“DesignSystem”的初衷。它不是一个简单的UI组件库而是一套完整的、用于构建数字产品的设计语言和前端基础设施。你可以把它理解为一本不断更新的、所有产品相关人员都必须遵守的“产品宪法”。它规定了从色彩、字体、间距到复杂交互组件的所有标准确保从设计稿到最终上线的产品每一个像素、每一次交互都保持高度一致。这个项目适合所有参与产品研发的成员设计师可以基于统一的“原子”进行高效创作避免重复造轮子前端工程师能获得一套开箱即用、语义清晰、可访问性良好的高质量代码组件大幅提升开发速度和代码质量产品经理和测试同学也能在统一的认知框架下进行沟通和验收。更重要的是它为产品的规模化、跨团队协作以及未来的品牌升级打下了坚实的地基。接下来我将从零开始拆解我们构建这套“DesignSystem”的完整思路、核心技术与踩坑实录。2. 设计系统的核心架构与设计决策2.1 原子设计理论的应用与本地化改造我们设计系统的理论基础是Brad Frost提出的“原子设计”Atomic Design方法论。这套理论将界面元素像化学物质一样分层原子Atoms、分子Molecules、有机体Organisms、模板Templates和页面Pages。但在实际落地时我们并没有生搬硬套而是根据团队的协作习惯和技术栈做了本地化改造。我们的分层结构如下设计令牌Design Tokens这是比“原子”更基础的层级包含了所有原始的、不可再分的样式值。例如颜色、字体大小、字重、间距、阴影、圆角等。它们以CSS变量或SCSS变量的形式存在是整套系统的“源代码”。基础组件Atoms / Base Components对应原子设计中的“原子”是最基础的UI构件。例如按钮Button、输入框Input、图标Icon、文本Text。它们只包含最基础的样式和交互不包含业务逻辑。复合组件Molecules / Composite Components由多个基础组件组合而成完成一个相对独立的功能单元。例如带搜索按钮的搜索框SearchBar、表单字段FormField包含Label、Input、Error Message、导航项NavItem。区块组件Organisms / Block Components由多个复合组件或基础组件组合而成形成一个完整的、可复用的页面区块。例如页头Header、侧边导航Sidebar、卡片列表CardList、模态对话框Modal。页面模板Templates定义了页面的骨架和布局是“有机体”的组合。它不包含真实内容只规定各个区块的位置和关系。例如后台管理模板、用户中心模板、列表页模板。业务组件Business Components这是一个额外的层级用于封装特定业务场景下的复杂UI逻辑。它们基于上述所有层级构建但包含了业务状态和数据流。例如商品选择器、用户角色分配器、数据图表封装器。注意很多团队在设计系统初期会过度设计试图用一个完美的架构解决所有问题。我们的经验是“演进优于预先设计”。我们最初只定义了“设计令牌”和“基础组件”随着项目迭代当某些组合模式反复出现超过3次时我们才将其抽象为“复合组件”或“区块组件”。过早抽象会增加维护成本且可能不符合实际使用场景。2.2 技术栈选型为什么是React TypeScript Stitches选择合适的技术栈是设计系统稳定和高效的基础。我们评估了多个方案最终选型如下核心库React 18。选择React是因为其组件化思想与设计系统天然契合庞大的社区和生态提供了丰富的工具和解决方案团队技术栈也统一。语言TypeScript。这是设计系统的“安全带”。它能提供强大的类型提示确保组件属性Props的使用安全自动生成文档并在团队协作中极大减少因参数传递错误导致的Bug。对于设计系统这种需要被多人频繁使用的基建项目类型安全至关重要。样式方案Stitches。这是我们选型中争议最大但最终被证明最成功的一环。我们对比了传统的CSS-in-JS如styled-components、Utility-First的Tailwind CSS以及CSS Modules。Stitches的优势在于它提供了极佳的TypeScript支持样式属性可以直接获得类型提示和自动补全。它基于设计令牌Tokens构建强制开发者使用系统定义好的颜色、间距等变量从根源上保证了样式一致性。它生成的CSS是静态的、可预测的性能优于运行时生成样式的方案并且支持服务端渲染SSR。它提供了强大的变体VariantsAPI让我们可以像定义函数一样定义组件的不同视觉状态如size: small | medium | large,variant: primary | secondary | ghost代码非常优雅且类型安全。// 使用Stitches定义一个按钮组件的样式和变体示例 import { styled } from ‘stitches/react’; export const Button styled(‘button’, { // 基础样式全部使用设计令牌 all: ‘unset’, alignItems: ‘center’, boxSizing: ‘border-box’, display: ‘inline-flex’, fontFamily: ‘$fonts$sans’, fontWeight: ‘$fontWeights$medium’, lineHeight: ‘1’, borderRadius: ‘$radii$md’, // 变体定义 variants: { variant: { primary: { backgroundColor: ‘$colors$primary9’, color: ‘white’, ‘:hover’: { backgroundColor: ‘$colors$primary10’ }, }, secondary: { backgroundColor: ‘$colors$gray3’, color: ‘$colors$gray11’, ‘:hover’: { backgroundColor: ‘$colors$gray4’ }, }, ghost: { backgroundColor: ‘transparent’, color: ‘$colors$gray11’, ‘:hover’: { backgroundColor: ‘$colors$grayA3’ }, }, }, size: { small: { fontSize: ‘$fontSizes$xs’, padding: ‘$space$2 $space$3’, }, medium: { fontSize: ‘$fontSizes$sm’, padding: ‘$space$3 $space$4’, }, large: { fontSize: ‘$fontSizes$base’, padding: ‘$space$4 $space$6’, }, }, }, // 默认变体 defaultVariants: { variant: ‘primary’, size: ‘medium’, }, });构建与打包Vite tsup。我们使用Vite作为开发服务器提供极快的热更新。使用tsup进行库的打包因为它零配置、基于ESBuild打包速度极快并且能轻松输出ESM、CJS等多种格式兼容现代和传统构建工具。文档与演示Storybook。这是设计系统的门户和活文档。每个组件都有独立的.stories.tsx文件用于展示组件的所有变体、状态和使用示例。它支持交互式测试、自动生成属性Args表格并且可以发布为静态站点方便非开发人员如设计师、产品查阅。3. 设计令牌Design Tokens的深度实践设计令牌是整个系统的基石管理好它们就管理了产品的视觉一致性。我们将其分为几类并采用结构化命名。3.1 令牌的分类与命名策略我们使用kebab-case短横线连接作为CSS变量名但在TypeScript/JavaScript中会转换为camelCase。令牌主要分为颜色Colors采用语义化命名而非具体色值。我们参考了Radix Colors等成熟方案建立了多级色彩系统。primary-1到primary-12主色阶用于按钮、链接等主要交互元素。gray-1到gray-12中性色阶用于文本、背景、边框。success-*,warning-*,error-*功能色阶用于状态提示。background-primary,background-secondary背景色。text-primary,text-secondary,text-disabled文本色。border-primary,border-secondary边框色。间距Spacing采用4px基准的倍率系统。我们定义了$space-1(4px),$space-2(8px),$space-3(12px),$space-4(16px) … 直到$space-12(48px)。所有组件的内外边距、间隙都必须使用这些令牌确保了视觉节奏的统一。字体与排版TypographyfontSizes:xs,sm,base,lg,xl,2xl…fontWeights:normal,medium,semibold,bold。lineHeights:none,tight,snug,normal,relaxed。fontFamilies:sans(系统UI字体栈),mono(等宽字体)。圆角Radiinone,sm,md,lg,full。阴影Shadowsxs,sm,md,lg,xl每个等级定义了x, y, blur, spread, color。3.2 令牌的实现与同步我们使用一个单独的tokens.config.ts文件来集中定义所有令牌。这个文件是“单一数据源”。// tokens.config.ts export const tokens { colors: { primary: { 1: ‘hsl(210, 100%, 99%)’, 2: ‘hsl(210, 100%, 98%)’, // … 直到 12 9: ‘hsl(211, 90%, 48%)’, 10: ‘hsl(211, 90%, 42%)’, }, gray: { /* … */ }, background: { primary: ‘$colors$gray1’, secondary: ‘$colors$gray2’, }, text: { primary: ‘$colors$gray12’, secondary: ‘$colors$gray11’, }, }, space: { 1: ‘4px’, 2: ‘8px’, // … 直到 12 }, fontSizes: { xs: ‘0.75rem’, // 12px sm: ‘0.875rem’, // 14px base: ‘1rem’, // 16px lg: ‘1.125rem’, // 18px }, // … 其他令牌 } as const; // 然后通过脚本或Stitches的createStitches配置将这些对象转换为CSS变量。关键挑战设计与代码的同步。设计师在Figma中维护一套样式开发在代码中维护另一套极易不同步。我们的解决方案是使用Figma Tokens插件设计师在Figma中定义的样式可以导出为JSON文件。我们编写了一个Node.js脚本定期或通过Git Hook在提交时运行将Figma导出的JSON与我们的tokens.config.ts进行比对和部分合并。对于无法自动合并的冲突如新增了设计师未沟通的令牌脚本会报错并提示人工处理。这确保了设计源头和代码实现的一致性。实操心得不要试图一次性定义完美的令牌系统。我们从最核心的primary-9主色、gray-12主要文字色和space-4基础间距开始在开发前三个基础组件Button, Text, Box的过程中逐步发现并补充缺失的令牌。这种“按需定义”的方式避免了过度设计也让团队更快地上手理解令牌的意义。4. 基础组件的构建哲学与封装艺术基础组件是设计系统被使用最多的部分其API设计直接决定了开发体验。4.1 组件API设计原则我们遵循以下原则直观性属性名应清晰明了如size,variant,disabled。一致性相似功能的组件使用相似的属性名和取值。例如所有可调整大小的组件都使用sizesm | md | lg。可组合性组件应尽可能简单、专注。复杂功能通过组合实现。例如一个复杂的表单对话框应由Modal、Form、Input、Button组合而成而不是一个庞大的FormModal组件。可访问性A11y内置组件默认应具备基本的可访问性如正确的ARIA属性、键盘导航、焦点管理。例如Button组件默认渲染为button标签而非div模态框会自动管理焦点陷阱。向前兼容避免破坏性变更。新增功能优先通过扩展API实现废弃API需提供警告和迁移路径。4.2 以Button组件为例的完整实现解析Button组件看似简单但要做得健壮却需要考虑很多边界情况。import React, { forwardRef } from ‘react’; import { Slot } from ‘radix-ui/react-slot’; // 用于处理asChild属性 import { ButtonStyled } from ‘./Button.styles’; // 上述Stitches样式组件 export interface ButtonProps extends React.ComponentPropsWithoutRef‘button’ { /** 按钮的视觉变体 */ variant?: ‘primary’ | ‘secondary’ | ‘ghost’ | ‘danger’; /** 按钮尺寸 */ size?: ‘small’ | ‘medium’ | ‘large’; /** 是否处于加载状态 */ loading?: boolean; /** 加载状态下显示的文本 */ loadingText?: string; /** 是否禁用 */ disabled?: boolean; /** 点击按钮时触发 */ onClick?: React.MouseEventHandlerHTMLButtonElement; /** 子元素可以是文字或图标 */ children?: React.ReactNode; /** 左侧图标 */ leftIcon?: React.ReactElement; /** 右侧图标 */ rightIcon?: React.ReactElement; /** 是否渲染为其他元素如asChild{true}且子元素是a则渲染为a */ asChild?: boolean; } export const Button forwardRefHTMLButtonElement, ButtonProps( ( { variant ‘primary’, size ‘medium’, loading false, loadingText, disabled, children, leftIcon, rightIcon, asChild false, onClick, …props }, ref ) { // 处理交互状态加载状态应隐含禁用状态 const isDisabled disabled || loading; // 处理点击事件在禁用或加载状态下阻止默认行为 const handleClick (event: React.MouseEventHTMLButtonElement) { if (isDisabled) { event.preventDefault(); return; } onClick?.(event); }; // 克隆图标元素为其添加统一的样式类 const clonedLeftIcon leftIcon ? React.cloneElement(leftIcon, { className: button-icon ${leftIcon.props.className || ‘’}, ‘aria-hidden’: true, // 对屏幕阅读器隐藏装饰性图标 }) : null; const clonedRightIcon rightIcon ? React.cloneElement(rightIcon, { className: ‘button-icon’, ‘aria-hidden’: true }) : null; // 使用Radix UI的Slot来处理asChild实现渲染委派 const Comp asChild ? Slot : ‘button’; return ( ButtonStyled as{Comp} // Stitches的as属性配合Slot variant{variant} size{size} disabled{isDisabled} aria-disabled{isDisabled} // 增加ARIA状态增强可访问性 onClick{handleClick} ref{ref} {…props} {/* 加载状态 */} {loading ( Spinner size“small” / {/* 一个独立的旋转图标组件 */} {loadingText || children} {/* 显示加载文本或原文本 */} / )} {/* 非加载状态 */} {!loading ( {clonedLeftIcon} {children} {clonedRightIcon} / )} /ButtonStyled ); } ); Button.displayName ‘Button’; // 为调试方便设置显示名这个实现考虑了哪些细节类型安全完整的TypeScript接口包括详细的JSDoc注释在IDE中能获得完美提示。可访问性使用了原生的button元素正确处理了disabled和aria-disabled图标添加了aria-hidden。状态处理loading状态自动隐含disabled并阻止点击事件。灵活性通过asChild和Slot允许按钮渲染为a或其他自定义元素而不会破坏样式和交互。这是实现“组合优于继承”的关键。样式分离样式逻辑在Button.styles.ts中通过Stitches管理使组件逻辑更清晰。4.3 图标组件的标准化管理图标是另一个高频且易混乱的领域。我们放弃了在组件内直接使用SVG代码或图片而是建立了统一的图标库。来源所有图标均来自一个设计源如Figma的图标库。构建使用svgr/cli或svg-sprite工具将SVG文件批量转换为React组件。使用生成一个统一的Icon组件通过name属性来指定使用哪个图标。import { Icon } from ‘our-design-system/icons’; Icon name“search” size“sm” color“currentColor” /好处树摇优化只打包用到的图标、样式统一控制颜色、大小、易于替换和更新。5. 文档、协作与交付流程一个没有好文档和易用交付流程的设计系统是没有生命的。5.1 使用Storybook构建活文档我们为每个组件创建.stories.tsx文件。Storybook不仅展示组件还允许我们编写使用示例展示不同属性组合下的组件形态。交互测试在浏览器内直接操作组件验证交互逻辑。自动生成属性表通过ArgTypes自动从TypeScript定义生成属性文档包括类型、默认值和描述。编写“Play”函数模拟用户交互流程用于可视化测试。发布静态站点通过CI/CD自动构建并部署到内部服务器供全公司访问。5.2 版本管理与发布策略我们采用语义化版本SemVer主版本.次版本.修订号。修订号内部bug修复、样式微调等向后兼容的改动。次版本新增组件、为现有组件新增非破坏性功能如新的variant。主版本包含破坏性变更如重命名属性、移除组件、重大设计更新。发布流程通过GitHub Actions自动化合并到main分支触发CI。运行测试、构建和Storybook构建。使用changesets工具管理版本变更日志。开发者提交PR时如果修改了设计系统包需要运行pnpm changeset选择影响版本并描述变更。维护者合并所有changesets后CI会自动计算新版本、更新CHANGELOG.md、发布到私有NPM仓库并部署更新后的文档站点。5.3 设计-开发协作流程我们建立了“设计令牌驱动”的协作流程设计阶段设计师在Figma中使用已定义好的颜色、文本样式等组件库进行设计。评审与标注设计评审通过后设计师使用Figma Tokens插件检查并同步令牌。开发人员直接从Figma inspect面板查看所有尺寸、颜色都已是对应的令牌名称如$colors-primary-9而非具体的色值。开发实现开发人员根据设计稿使用对应的设计令牌和组件进行编码。因为源头一致还原度极高。验收产品或设计师通过部署的Storybook或测试环境进行验收重点关注交互和状态基础样式因有系统保证通常无需检查。6. 常见问题、挑战与应对策略在建设和推广设计系统的过程中我们遇到了无数挑战以下是其中最典型的几个及其解决方案。6.1 如何说服业务团队使用挑战业务团队追求快速迭代认为引入设计系统会增加前期成本不如直接写“行内样式”快。策略创造即时价值我们先封装了业务中最常用、最痛苦的组件如复杂表格、高级搜索筛选器、图表卡片。让业务团队看到使用这些组件能直接节省他们数天的开发时间。提供平滑迁移路径我们不要求旧项目一次性重构。而是提供“混合使用”方案允许在旧项目中逐步安装、引入新组件。同时编写详细的迁移指南和代码模版。建立数据反馈我们统计了使用设计系统组件后常见页面的开发时长变化、UI缺陷率变化。用数据证明长期效率的提升和质量的保障。提供强力支持设立“设计系统答疑”时段快速响应业务团队在使用中遇到的问题并积极根据他们的反馈迭代组件。6.2 如何管理设计系统的演进与业务需求的变化挑战业务方经常提出个性化需求要求组件支持某种特殊样式或交互这可能破坏系统的通用性。策略设立需求过滤机制所有对设计系统的需求不能直接提交代码PR。必须先提Issue经过核心维护者通常由一名设计师和一名前端共同担任评审。评审标准是这个需求是否具有普遍性是否至少有2-3个其他业务场景也会用到提供逃生舱如果需求确实是个性化的我们指导业务方在业务层进行扩展而不是修改基础组件。例如通过组合基础组件、添加外层包装样式、或使用className覆盖少数样式来实现。我们在文档中明确展示了这些“高级用法”。定期回顾与抽象每季度回顾一次业务方提出的“个性化需求”。如果发现某种模式重复出现我们就将其抽象、设计并纳入到设计系统的下一个次版本中。6.3 性能与包体积优化挑战组件库越来越大如何避免影响业务项目的构建速度和打包体积策略按需引入Tree Shaking确保库发布为ES Modules格式并且每个组件都是独立导出。业务项目通过import { Button } from ‘our-design-system’引入时打包工具能只打包用到的组件。代码分割将图标、大型工具函数如日期处理拆分为独立的子包our-design-system/icons,our-design-system/utils让业务方按需安装。依赖优化严格审查第三方依赖。例如我们选择体积小、模块化好的工具如date-fns替代moment.js。将react、react-dom设置为peerDependencies避免重复打包。样式体积控制Stitches生成的CSS是静态的且只会生成实际使用到的样式组合的CSS类名有效控制了样式文件体积。6.4 样式覆盖与主题定制难题挑战业务方在某些场景下确实需要微调组件样式如何平衡系统一致性和灵活性策略提供稳定的CSS选择器我们为每个组件容器元素都添加了稳定的>