这套样式系统我前后在三个项目里踩完坑才定型的。最早那个项目改一次主题色要全工程CtrlShiftF全局替换生怕漏掉哪个角落后来的项目组件样式互相污染改一个按钮连表格边框都变了再后来的项目暗色模式推了快一个月前端群里天天扯皮。直到我把第四章这套思路捋清楚这些问题才算真正收口。这篇文章就聊聊样式系统从设计、选型到落地的完整过程写给所有被CSS折磨过的前端同学不管你在用Vue、React还是小程序WebView这套方法论基本都通用。1. 样式系统的定位与整体设计思路1.1 样式系统到底解决什么问题很多团队把样式系统单纯理解成“写一套好看的主题色变量”这是典型的误解。样式系统不是几段CSS代码而是一整套从设计到代码的规则链路它的核心目标有三个一致性、可维护性、可扩展性。一致性好理解两个工程师写出来的按钮不能一个圆角4px一个8px一屏页面里的主色调不能一个偏蓝一个偏绿。可维护性说的是业务迭代成本产品经理今天说主色从蓝色换成紫色如果是散落式写法你需要在几十个文件里找#1677ff而有了样式系统你只需要改一行变量。可扩展性更实在暗色模式、品牌换肤、多端适配这些需求在样式系统面前是日常操作在没有样式系统的工程面前就是一次重构。从团队协作角度看样式系统还是设计和前端之间的翻译层。设计师交付的组件规范落到代码里应该是结构化的Design Token而不是一张JPG截图让前端照着去吸色。我在第四章里反复强调一个理念样式系统是工程基础设施不是样式代码本身。1.2 主流方案选型对比市面上做样式系统的技术方案不少各有各的适用场景我按这几年实际踩坑的体验把它们分成几个流派方案核心机制优点痛点典型场景原生CSS CSS变量运行时变量继承与覆盖零依赖、性能好、可在浏览器调试面板直接改变量多了易混乱无作用域隔离中后台项目、多主题需求CSS Modules构建期类名局部化天然隔离、无污染、与组件结合紧密动态主题切换麻烦类名可读性差React/Vue组件库开发CSS-in-JSstyled-componentsJS生成样式并注入style标签动态样式能力极强、可随组件生命周期变化运行时开销高、SSR处理复杂、调试隔离难受强交互的营销组件Tailwind CSS工具类原子化组合开发效率高、体积优化空间大类名冗长、设计约束由配置驱动、新手维护成本高快速原型、偏好实用优先的团队Sass/Less预处理器编译期变量、混合宏、函数语法能力强、生态成熟变量是编译期的运行时主题切换难传统Vue/React工程我来做个主观一点的点评。Tailwind效率是真的高但样式系统和“工具类组合”之间其实还需要一层设计约束否则几十个类名堆出一个按钮维护者看到就想换工作。CSS-in-JS动态能力很强但我在中后台项目里跑过一轮运行时开销和SSR问题确实存在如果你不是在做重交互的营销站完全可以绕开。CSS Modules是隔离神器但处理暗色模式这类全局主题问题时你会发现隔离反而成了阻碍。综合下来我的选型结论非常固定底层用CSS变量做设计令牌层结构上配合一条命名规范必要时引入CSS Modules做组件级隔离。这套组合在Vue、React、微前端、小程序WebView场景里都跑得通。1.3 为什么我坚持用CSS变量打底CSS变量这套方案最大的优势是“运行时覆盖”。别的方案里主题切换通常要重新编译样式或重新渲染整个组件树而CSS变量只需要你给根节点换一个>{ color: { brand: { primary: #1677ff, hover: #4096ff, active: #0958d9 }, text: { primary: rgba(0, 0, 0, 0.88), secondary: rgba(0, 0, 0, 0.65), disabled: rgba(0, 0, 0, 0.25) }, bg: { page: #f5f5f5, container: #ffffff }, status: { success: #52c41a, warning: #faad14, error: #ff4d4f } }, spacing: { xs: 4px, sm: 8px, md: 16px, lg: 24px, xl: 32px }, radius: { sm: 4px, md: 8px, lg: 12px } }这个JSON最终生成的CSS变量大概是这样的:root { --color-brand-primary: #1677ff; --color-brand-hover: #4096ff; --color-brand-active: #0958d9; --color-text-primary: rgba(0, 0, 0, 0.88); --color-bg-page: #f5f5f5; --spacing-md: 16px; --radius-md: 8px; }很多团队在这里会犯一个毛病JSON是有了JS脚本也写了但设计师一改稿前端不更新JSON直接在tokens.css里手改值。一旦出现这种情况设计令牌就名存实亡了。务必把tokens.json定义为唯一事实来源任何样式调整先改JSON再生成CSS这个流程一定要固化到项目规范里。2.2 变量定义规范与命名陷阱变量体系设计得好不好直接影响整个样式系统的可维护性。我在命名上有一套固定习惯所有自定义变量统一以双横线开头语义结构是--类别-修饰-属性。类别有color、font、spacing、radius、shadow、z、duration这几大类形容词放在语义后。一个容易踩的坑是把变量名起得太笼统。比如同时存在--primary和--color-primary两处代码一处引用前者一处引用后者改主题时就是漏网之鱼。我建议在项目规范里写明全局基础变量只允许出现在tokens.css中业务组件里如果要定义局部变量必须在组件作用域内定义且命名以组件名为前缀比如.btn里的变量叫--btn-height避免污染全局。再有就是别把变量值直接写成魔法值。很多时候你会发现代码里出现--margin-lg: var(--spacing-lg)这种“再包一层”的写法看起来冗余但实际是合理的。语义层和基础层分离的好处是当设计体系调整时你只动基础层不动业务引用。比如所有卡片阴影业务代码统一用--shadow-card哪天设计说阴影模糊半径要小一点你只改这一处就够了而不是全工程搜box-shadow。2.3 主题切换暗色模式实现原理用CSS变量做暗色模式核心机制就是“根节点属性切换变量集合法”。具体做法是在:root下定义亮色主题变量在[data-themedark]下定义同名变量的暗色值:root { --color-bg-page: #f5f5f5; --color-bg-container: #ffffff; --color-text-primary: rgba(0, 0, 0, 0.88); } [data-themedark] { --color-bg-page: #0a0a0a; --color-bg-container: #141414; --color-text-primary: rgba(255, 255, 255, 0.85); }切换时只需要修改document.documentElement的>:root { --breakpoint-sm: 576px; --breakpoint-md: 768px; --breakpoint-lg: 992px; --breakpoint-xl: 1200px; }CSS变量在media查询里有一个非常尴尬的限制media不接受var()作为条件值。这意味着你无法写出media (max-width: var(--breakpoint-md))。现实做法是断点常量仍然用变量定义但媒体查询里手写值并且通过代码规范保证不出现“新断点值”。也就是说业务代码里只允许出现这四五个断点值一旦要加新的必须回到设计令牌里评审。再讲一个这几年很实用的能力容器查询Container Queries。过去组件级响应式只能靠窗口宽度媒体查询然后组件内部通过window.innerWidth判断状态这在复杂布局里很难受。比如同一套图表组件左边窄栏和右侧宽栏渲染出来的尺寸结构完全不同。容器查询的思路是把“断点”从视口层面下放到容器层面.component { container-type: inline-size; } container (max-width: 400px) { .component__title { font-size: 14px; } }这套能力在现代浏览器里已经非常成熟了样式的响应式判断由“页面长什么样”升级成了“我所在的容器长什么样”在仪表盘和低代码平台这类场景里非常实用。我在第四章配套工程里就做了一层容器查询的封装组件内部可以用容器查询实现折叠、扩张等多形态切换。3. 实操过程从零搭一套可直接落地的样式系统3.1 初始化目录结构与全局样式文件下面这套目录结构是我在Vite Vue 3和Vite React两个工程里都在用的标准布局src/ styles/ tokens/ index.css # 引入以下全部基础变量 color.css # 颜色相关变量 typography.css # 字体族、字号、行高 spacing.css # 间距、尺寸 radius.css # 圆角 shadow.css # 阴影 zindex.css # 层级别 breakpoint.css # 断点变量 base/ reset.css # 基础样式重置 global.css # 全局基础元素样式 utilities/ index.css # 工具类 components/ button.css # 组件样式这里只是示例大型工程通常按组件目录拆分tokens目录里的文件都只放变量声明不放任何业务样式。base目录负责reset和全局元素默认样式。utilities目录放一些跨组件复用的工具类。components目录按业务组件粒度拆样式文件。这里说一个容易忽略的点reset样式不要粗暴地清空所有margin和padding。很多项目引入一份老式reset.css导致标题、列表、表单的默认样式全部归零然后又得投入大量代码去重建。我习惯用modern-normalize这种风格保留合理的用户代理默认样式只纠正跨浏览器差异。3.2 组件样式组织与BEM命名约定样式隔离只靠命名约定显然不够硬但命名约定仍然是最直观的沟通手段。我在工程里硬性推广BEM命名同时搭配scopedVue或CSS ModulesReact做物理隔离。注意BEM的主要价值是让类名“自解释”让DOM结构一目了然。拿一个搜索框组件举例div classsearch-panel div classsearch-panel__input-wrap input classsearch-panel__input typetext / button classsearch-panel__btn search-panel__btn--primary搜索/button /div /div.search-panel__input-wrap { display: flex; gap: var(--spacing-sm); } .search-panel__btn--primary { background-color: var(--color-brand-primary); color: #ffffff; }BEM的block__element--modifier三段式结构看起来很呆但工程化之后维护性极好。搜索引擎能精确匹配到类名调试面板里一眼看出当前元素属于哪个组件、什么状态。在Vue SFC里配合scopedBEM类名仍然会保留在产物中对问题排查帮助特别大。另外要强调一个细节组件样式里面不要混入跟组件结构无关的视觉魔法值。间距一律用var(--spacing-*)颜色一律用var(--color-*)字号一律用var(--font-size-*)。如果在组件里写死了18px、#333这种裸值设计师下轮调整令牌时肯定会漏网。3.3 在组件库基础上做主题覆盖的正确姿势大多数中后台项目不会从零写组件而是站在Element Plus、Antd这类组件库的肩膀上。所以样式系统搭建的另一个关键环节是让第三方组件库融入你的令牌体系。以Element Plus为例它内部的设计变量其实已经统一到了一个命名空间你可以直接覆盖对应CSS变量来实现主题改造:root { --el-color-primary: var(--color-brand-primary); --el-color-primary-light-3: var(--color-brand-hover); --el-border-radius-base: var(--radius-md); --el-font-size-base: var(--font-size-md); } [data-themedark] { --el-bg-color: #141414; --el-text-color-primary: rgba(255, 255, 255, 0.85); }这种做法比暴力覆盖组件样式类优雅一万倍。它走的是组件库的变量设计缺口不需要!important不影响组件库内部的状态逻辑而且主题切换时全链路自动生效。但变量覆盖做不到100%。比如某些组件内部使用了硬编码值而不是引用变量这时候你就得用::deep()或:deep()来穿透作用域style scoped .search-panel :deep(.el-input__wrapper) { box-shadow: 0 0 0 1px var(--color-brand-primary) inset; } /style这个:deep()是Vue scoped样式里最常用的逃逸口。React工程如果用CSS Modules对应机制是:global或:global(.xxx)。我的经验是这样的组件库样式覆盖尽量先找变量入口次选:deep()最后才考虑BEM命名空间去覆盖。直接套用全局类名覆盖是最危险的因为多个项目引入同一份覆盖文件后组件的升级会直接把你的补丁冲掉排查难度极高。3.4 沉淀工具类减少业务代码重复劳动样式系统不是一禁了之工具类的合理沉淀能极大提升业务效率。我这里的工具类分两类一类是纯工具型只是顺手封装的常用样式另一类是设计令牌的快捷映射比如下面这种.text-ellipsis { overflow: hidden; white-space: nowrap; text-overflow: ellipsis; } .flex-center { display: flex; align-items: center; justify-content: center; } .color-primary { color: var(--color-brand-primary); } .bg-container { background-color: var(--color-bg-container); }但是工具类要控制规模别把所有样式都改成classmt-8 px-4 text-sm这种。这种工具类泛滥之后模板里全是类名堆叠视觉设计逻辑反而被淹没了。我的边界是布局类、文本省略类、清除浮动类这些与业务无关的“结构样式”可以做工具类带有明显视觉语义的比如间距大小、文本颜色应该让组件持有绝不能让人在模板里随手堆。很多团队还会把组件库里的Loading图标、按钮尺寸等封装成配置这些都是工具层的延伸。但记住工具类的代码也要走变量不能写死。3.5 在微前端与小程序场景下的样式隔离策略热词里频繁出现qiankun和uni-app这里值得单独说一嘴。微前端环境下主应用和子应用同时存在于一个页面全局CSS变量必然互相影响。我在qiankun子应用落地样式系统的实践方案是给每个子应用的tokens.css变量加子应用前缀作用域不用:root而是用[data-appsub-app-a]选择器[data-appsub-app-a] { --color-brand-primary: #1677ff; } [data-appsub-app-b] { --color-brand-primary: #722ed1; }根元素挂上对应属性后子应用内部的组件全部沿用自己命名空间下的令牌互不干扰。主题切换在微前端环境下只需要主应用维护一个全局状态通过自定义事件广播给子应用子应用监听后各自切换根节点的>script (function () { var theme localStorage.getItem(app-theme) || light; document.documentElement.setAttribute(data-theme, theme); })(); /script这个脚本执行时机在所有CSS和JS之前可以避免绝大多数闪屏。如果项目里有动态修改主题的需求还要在切换主题后把状态同步到localStorage。这里要注意如果你的构建工具会强制给script标签加defer必须确认这段关键脚本没有被打上延迟标记否则白搭。4.3 样式污染与优先级剁手我在第四章特别强调BEM作用域隔离双管齐下但真正遇到的污染场景常常是跨组件的“非预期命中”。比如一个固定类名.container在A页面是表单容器在B页面被某个表格库的样式覆盖了。前端工程的样式作用域设计我给出的优先级顺序是这样的场景推荐策略Vue SFC组件样式scoped BEM逃逸用:deep()React组件样式CSS Modules BEM逃逸用:global跨端小程序样式组件类名必须带业务前缀避免全局命中微前端子应用子应用作用域属性 命名空间类名组件间样式别指望靠优先级去斗正确做法是从源头阻隔。一旦出现需要靠!important才能压住的反模式就要回去追问这条样式的归属是否放错了位置。4.4 组件库样式怎么改都纹丝不动明明在:root里覆盖了Element Plus或者Antd的变量组件渲染出来的效果还是原样。这种case十有八九是样式加载顺序的问题。组件库的样式在你的tokens.css之后加载后者把变量覆盖又顶回去了。解决方案很直接把你自己的覆盖样式文件放在组件库样式之后引入。如果是使用Vite或Webpack的按需引入组件库样式的顺序由打包插件的注入顺序决定这时候要给覆盖文件手动置后。另外还有一个高频问题组件库内部某些样式用的是书写顺序差异带来的隐性优先级常规手段怎么调试都无效。第一步确认你覆盖的选择器权重不低于组件库自身的权重第二步检查有没有开启样式隔离的额外规则第三步再考虑浏览器缓存导致的旧样式未更新。4.5 构建后关键CSS丢失或顺序错乱样式系统搭好之后本地开发一切正常打包上线后发现变了的主题色又回去了或者暗色模式下部分样式错乱。这种问题通常出在构建插件的CSS抽取顺序上。Vite环境下CSS代码分割和抽取顺序一般会比较稳定但如果你使用了组件库按需加载、又混入了手写的覆盖样式产物顺序就可能不如预想。解决方法是把覆盖样式单独配置成一个入口文件设置采样保证它在组件库样式之后。也可以直接看构建产物的CSS文件名列表找到对应顺序关系做调整。再提醒一个PostCSS相关的细节如果你使用了cssnano这类压缩插件默认的mergeLonghand合并属性可能会把某些层叠上下文相关的样式压出问题。遇到样式压缩后排版错乱先把cssnano的mergeLonghand关掉试试。一点真心话搭这套样式系统我前前后后重写了三个版本最大的领悟是你提前定义好的变量和规范会决定未来所有人和代码的相处方式。别指望一口气把所有工具类和组件样式都写完先把令牌体系稳定下来再让业务代码慢慢向变量靠拢。就像盖房子先打地基地基不牢后面所有装修都是白费。每次拿到一个老项目我第一件事永远是先把散落的色值和间距值抽成变量再把项目里所有!important揪出来清一遍。做完这两步后面接暗色模式、接换肤、接业务扩展手感会顺非常多。这套第四章的方法值得你认真试一次。 
长河君 · 2026/10/6 19:49:34 · 阅读 1.2k 前端样式系统设计与落地：从CSS变量到暗色模式的完整实践
这套样式系统我前后在三个项目里踩完坑才定型的。最早那个项目改一次主题色要全工程CtrlShiftF全局替换生怕漏掉哪个角落后来的项目组件样式互相污染改一个按钮连表格边框都变了再后来的项目暗色模式推了快一个月前端群里天天扯皮。直到我把第四章这套思路捋清楚这些问题才算真正收口。这篇文章就聊聊样式系统从设计、选型到落地的完整过程写给所有被CSS折磨过的前端同学不管你在用Vue、React还是小程序WebView这套方法论基本都通用。1. 样式系统的定位与整体设计思路1.1 样式系统到底解决什么问题很多团队把样式系统单纯理解成“写一套好看的主题色变量”这是典型的误解。样式系统不是几段CSS代码而是一整套从设计到代码的规则链路它的核心目标有三个一致性、可维护性、可扩展性。一致性好理解两个工程师写出来的按钮不能一个圆角4px一个8px一屏页面里的主色调不能一个偏蓝一个偏绿。可维护性说的是业务迭代成本产品经理今天说主色从蓝色换成紫色如果是散落式写法你需要在几十个文件里找#1677ff而有了样式系统你只需要改一行变量。可扩展性更实在暗色模式、品牌换肤、多端适配这些需求在样式系统面前是日常操作在没有样式系统的工程面前就是一次重构。从团队协作角度看样式系统还是设计和前端之间的翻译层。设计师交付的组件规范落到代码里应该是结构化的Design Token而不是一张JPG截图让前端照着去吸色。我在第四章里反复强调一个理念样式系统是工程基础设施不是样式代码本身。1.2 主流方案选型对比市面上做样式系统的技术方案不少各有各的适用场景我按这几年实际踩坑的体验把它们分成几个流派方案核心机制优点痛点典型场景原生CSS CSS变量运行时变量继承与覆盖零依赖、性能好、可在浏览器调试面板直接改变量多了易混乱无作用域隔离中后台项目、多主题需求CSS Modules构建期类名局部化天然隔离、无污染、与组件结合紧密动态主题切换麻烦类名可读性差React/Vue组件库开发CSS-in-JSstyled-componentsJS生成样式并注入style标签动态样式能力极强、可随组件生命周期变化运行时开销高、SSR处理复杂、调试隔离难受强交互的营销组件Tailwind CSS工具类原子化组合开发效率高、体积优化空间大类名冗长、设计约束由配置驱动、新手维护成本高快速原型、偏好实用优先的团队Sass/Less预处理器编译期变量、混合宏、函数语法能力强、生态成熟变量是编译期的运行时主题切换难传统Vue/React工程我来做个主观一点的点评。Tailwind效率是真的高但样式系统和“工具类组合”之间其实还需要一层设计约束否则几十个类名堆出一个按钮维护者看到就想换工作。CSS-in-JS动态能力很强但我在中后台项目里跑过一轮运行时开销和SSR问题确实存在如果你不是在做重交互的营销站完全可以绕开。CSS Modules是隔离神器但处理暗色模式这类全局主题问题时你会发现隔离反而成了阻碍。综合下来我的选型结论非常固定底层用CSS变量做设计令牌层结构上配合一条命名规范必要时引入CSS Modules做组件级隔离。这套组合在Vue、React、微前端、小程序WebView场景里都跑得通。1.3 为什么我坚持用CSS变量打底CSS变量这套方案最大的优势是“运行时覆盖”。别的方案里主题切换通常要重新编译样式或重新渲染整个组件树而CSS变量只需要你给根节点换一个>{ color: { brand: { primary: #1677ff, hover: #4096ff, active: #0958d9 }, text: { primary: rgba(0, 0, 0, 0.88), secondary: rgba(0, 0, 0, 0.65), disabled: rgba(0, 0, 0, 0.25) }, bg: { page: #f5f5f5, container: #ffffff }, status: { success: #52c41a, warning: #faad14, error: #ff4d4f } }, spacing: { xs: 4px, sm: 8px, md: 16px, lg: 24px, xl: 32px }, radius: { sm: 4px, md: 8px, lg: 12px } }这个JSON最终生成的CSS变量大概是这样的:root { --color-brand-primary: #1677ff; --color-brand-hover: #4096ff; --color-brand-active: #0958d9; --color-text-primary: rgba(0, 0, 0, 0.88); --color-bg-page: #f5f5f5; --spacing-md: 16px; --radius-md: 8px; }很多团队在这里会犯一个毛病JSON是有了JS脚本也写了但设计师一改稿前端不更新JSON直接在tokens.css里手改值。一旦出现这种情况设计令牌就名存实亡了。务必把tokens.json定义为唯一事实来源任何样式调整先改JSON再生成CSS这个流程一定要固化到项目规范里。2.2 变量定义规范与命名陷阱变量体系设计得好不好直接影响整个样式系统的可维护性。我在命名上有一套固定习惯所有自定义变量统一以双横线开头语义结构是--类别-修饰-属性。类别有color、font、spacing、radius、shadow、z、duration这几大类形容词放在语义后。一个容易踩的坑是把变量名起得太笼统。比如同时存在--primary和--color-primary两处代码一处引用前者一处引用后者改主题时就是漏网之鱼。我建议在项目规范里写明全局基础变量只允许出现在tokens.css中业务组件里如果要定义局部变量必须在组件作用域内定义且命名以组件名为前缀比如.btn里的变量叫--btn-height避免污染全局。再有就是别把变量值直接写成魔法值。很多时候你会发现代码里出现--margin-lg: var(--spacing-lg)这种“再包一层”的写法看起来冗余但实际是合理的。语义层和基础层分离的好处是当设计体系调整时你只动基础层不动业务引用。比如所有卡片阴影业务代码统一用--shadow-card哪天设计说阴影模糊半径要小一点你只改这一处就够了而不是全工程搜box-shadow。2.3 主题切换暗色模式实现原理用CSS变量做暗色模式核心机制就是“根节点属性切换变量集合法”。具体做法是在:root下定义亮色主题变量在[data-themedark]下定义同名变量的暗色值:root { --color-bg-page: #f5f5f5; --color-bg-container: #ffffff; --color-text-primary: rgba(0, 0, 0, 0.88); } [data-themedark] { --color-bg-page: #0a0a0a; --color-bg-container: #141414; --color-text-primary: rgba(255, 255, 255, 0.85); }切换时只需要修改document.documentElement的>:root { --breakpoint-sm: 576px; --breakpoint-md: 768px; --breakpoint-lg: 992px; --breakpoint-xl: 1200px; }CSS变量在media查询里有一个非常尴尬的限制media不接受var()作为条件值。这意味着你无法写出media (max-width: var(--breakpoint-md))。现实做法是断点常量仍然用变量定义但媒体查询里手写值并且通过代码规范保证不出现“新断点值”。也就是说业务代码里只允许出现这四五个断点值一旦要加新的必须回到设计令牌里评审。再讲一个这几年很实用的能力容器查询Container Queries。过去组件级响应式只能靠窗口宽度媒体查询然后组件内部通过window.innerWidth判断状态这在复杂布局里很难受。比如同一套图表组件左边窄栏和右侧宽栏渲染出来的尺寸结构完全不同。容器查询的思路是把“断点”从视口层面下放到容器层面.component { container-type: inline-size; } container (max-width: 400px) { .component__title { font-size: 14px; } }这套能力在现代浏览器里已经非常成熟了样式的响应式判断由“页面长什么样”升级成了“我所在的容器长什么样”在仪表盘和低代码平台这类场景里非常实用。我在第四章配套工程里就做了一层容器查询的封装组件内部可以用容器查询实现折叠、扩张等多形态切换。3. 实操过程从零搭一套可直接落地的样式系统3.1 初始化目录结构与全局样式文件下面这套目录结构是我在Vite Vue 3和Vite React两个工程里都在用的标准布局src/ styles/ tokens/ index.css # 引入以下全部基础变量 color.css # 颜色相关变量 typography.css # 字体族、字号、行高 spacing.css # 间距、尺寸 radius.css # 圆角 shadow.css # 阴影 zindex.css # 层级别 breakpoint.css # 断点变量 base/ reset.css # 基础样式重置 global.css # 全局基础元素样式 utilities/ index.css # 工具类 components/ button.css # 组件样式这里只是示例大型工程通常按组件目录拆分tokens目录里的文件都只放变量声明不放任何业务样式。base目录负责reset和全局元素默认样式。utilities目录放一些跨组件复用的工具类。components目录按业务组件粒度拆样式文件。这里说一个容易忽略的点reset样式不要粗暴地清空所有margin和padding。很多项目引入一份老式reset.css导致标题、列表、表单的默认样式全部归零然后又得投入大量代码去重建。我习惯用modern-normalize这种风格保留合理的用户代理默认样式只纠正跨浏览器差异。3.2 组件样式组织与BEM命名约定样式隔离只靠命名约定显然不够硬但命名约定仍然是最直观的沟通手段。我在工程里硬性推广BEM命名同时搭配scopedVue或CSS ModulesReact做物理隔离。注意BEM的主要价值是让类名“自解释”让DOM结构一目了然。拿一个搜索框组件举例div classsearch-panel div classsearch-panel__input-wrap input classsearch-panel__input typetext / button classsearch-panel__btn search-panel__btn--primary搜索/button /div /div.search-panel__input-wrap { display: flex; gap: var(--spacing-sm); } .search-panel__btn--primary { background-color: var(--color-brand-primary); color: #ffffff; }BEM的block__element--modifier三段式结构看起来很呆但工程化之后维护性极好。搜索引擎能精确匹配到类名调试面板里一眼看出当前元素属于哪个组件、什么状态。在Vue SFC里配合scopedBEM类名仍然会保留在产物中对问题排查帮助特别大。另外要强调一个细节组件样式里面不要混入跟组件结构无关的视觉魔法值。间距一律用var(--spacing-*)颜色一律用var(--color-*)字号一律用var(--font-size-*)。如果在组件里写死了18px、#333这种裸值设计师下轮调整令牌时肯定会漏网。3.3 在组件库基础上做主题覆盖的正确姿势大多数中后台项目不会从零写组件而是站在Element Plus、Antd这类组件库的肩膀上。所以样式系统搭建的另一个关键环节是让第三方组件库融入你的令牌体系。以Element Plus为例它内部的设计变量其实已经统一到了一个命名空间你可以直接覆盖对应CSS变量来实现主题改造:root { --el-color-primary: var(--color-brand-primary); --el-color-primary-light-3: var(--color-brand-hover); --el-border-radius-base: var(--radius-md); --el-font-size-base: var(--font-size-md); } [data-themedark] { --el-bg-color: #141414; --el-text-color-primary: rgba(255, 255, 255, 0.85); }这种做法比暴力覆盖组件样式类优雅一万倍。它走的是组件库的变量设计缺口不需要!important不影响组件库内部的状态逻辑而且主题切换时全链路自动生效。但变量覆盖做不到100%。比如某些组件内部使用了硬编码值而不是引用变量这时候你就得用::deep()或:deep()来穿透作用域style scoped .search-panel :deep(.el-input__wrapper) { box-shadow: 0 0 0 1px var(--color-brand-primary) inset; } /style这个:deep()是Vue scoped样式里最常用的逃逸口。React工程如果用CSS Modules对应机制是:global或:global(.xxx)。我的经验是这样的组件库样式覆盖尽量先找变量入口次选:deep()最后才考虑BEM命名空间去覆盖。直接套用全局类名覆盖是最危险的因为多个项目引入同一份覆盖文件后组件的升级会直接把你的补丁冲掉排查难度极高。3.4 沉淀工具类减少业务代码重复劳动样式系统不是一禁了之工具类的合理沉淀能极大提升业务效率。我这里的工具类分两类一类是纯工具型只是顺手封装的常用样式另一类是设计令牌的快捷映射比如下面这种.text-ellipsis { overflow: hidden; white-space: nowrap; text-overflow: ellipsis; } .flex-center { display: flex; align-items: center; justify-content: center; } .color-primary { color: var(--color-brand-primary); } .bg-container { background-color: var(--color-bg-container); }但是工具类要控制规模别把所有样式都改成classmt-8 px-4 text-sm这种。这种工具类泛滥之后模板里全是类名堆叠视觉设计逻辑反而被淹没了。我的边界是布局类、文本省略类、清除浮动类这些与业务无关的“结构样式”可以做工具类带有明显视觉语义的比如间距大小、文本颜色应该让组件持有绝不能让人在模板里随手堆。很多团队还会把组件库里的Loading图标、按钮尺寸等封装成配置这些都是工具层的延伸。但记住工具类的代码也要走变量不能写死。3.5 在微前端与小程序场景下的样式隔离策略热词里频繁出现qiankun和uni-app这里值得单独说一嘴。微前端环境下主应用和子应用同时存在于一个页面全局CSS变量必然互相影响。我在qiankun子应用落地样式系统的实践方案是给每个子应用的tokens.css变量加子应用前缀作用域不用:root而是用[data-appsub-app-a]选择器[data-appsub-app-a] { --color-brand-primary: #1677ff; } [data-appsub-app-b] { --color-brand-primary: #722ed1; }根元素挂上对应属性后子应用内部的组件全部沿用自己命名空间下的令牌互不干扰。主题切换在微前端环境下只需要主应用维护一个全局状态通过自定义事件广播给子应用子应用监听后各自切换根节点的>script (function () { var theme localStorage.getItem(app-theme) || light; document.documentElement.setAttribute(data-theme, theme); })(); /script这个脚本执行时机在所有CSS和JS之前可以避免绝大多数闪屏。如果项目里有动态修改主题的需求还要在切换主题后把状态同步到localStorage。这里要注意如果你的构建工具会强制给script标签加defer必须确认这段关键脚本没有被打上延迟标记否则白搭。4.3 样式污染与优先级剁手我在第四章特别强调BEM作用域隔离双管齐下但真正遇到的污染场景常常是跨组件的“非预期命中”。比如一个固定类名.container在A页面是表单容器在B页面被某个表格库的样式覆盖了。前端工程的样式作用域设计我给出的优先级顺序是这样的场景推荐策略Vue SFC组件样式scoped BEM逃逸用:deep()React组件样式CSS Modules BEM逃逸用:global跨端小程序样式组件类名必须带业务前缀避免全局命中微前端子应用子应用作用域属性 命名空间类名组件间样式别指望靠优先级去斗正确做法是从源头阻隔。一旦出现需要靠!important才能压住的反模式就要回去追问这条样式的归属是否放错了位置。4.4 组件库样式怎么改都纹丝不动明明在:root里覆盖了Element Plus或者Antd的变量组件渲染出来的效果还是原样。这种case十有八九是样式加载顺序的问题。组件库的样式在你的tokens.css之后加载后者把变量覆盖又顶回去了。解决方案很直接把你自己的覆盖样式文件放在组件库样式之后引入。如果是使用Vite或Webpack的按需引入组件库样式的顺序由打包插件的注入顺序决定这时候要给覆盖文件手动置后。另外还有一个高频问题组件库内部某些样式用的是书写顺序差异带来的隐性优先级常规手段怎么调试都无效。第一步确认你覆盖的选择器权重不低于组件库自身的权重第二步检查有没有开启样式隔离的额外规则第三步再考虑浏览器缓存导致的旧样式未更新。4.5 构建后关键CSS丢失或顺序错乱样式系统搭好之后本地开发一切正常打包上线后发现变了的主题色又回去了或者暗色模式下部分样式错乱。这种问题通常出在构建插件的CSS抽取顺序上。Vite环境下CSS代码分割和抽取顺序一般会比较稳定但如果你使用了组件库按需加载、又混入了手写的覆盖样式产物顺序就可能不如预想。解决方法是把覆盖样式单独配置成一个入口文件设置采样保证它在组件库样式之后。也可以直接看构建产物的CSS文件名列表找到对应顺序关系做调整。再提醒一个PostCSS相关的细节如果你使用了cssnano这类压缩插件默认的mergeLonghand合并属性可能会把某些层叠上下文相关的样式压出问题。遇到样式压缩后排版错乱先把cssnano的mergeLonghand关掉试试。一点真心话搭这套样式系统我前前后后重写了三个版本最大的领悟是你提前定义好的变量和规范会决定未来所有人和代码的相处方式。别指望一口气把所有工具类和组件样式都写完先把令牌体系稳定下来再让业务代码慢慢向变量靠拢。就像盖房子先打地基地基不牢后面所有装修都是白费。每次拿到一个老项目我第一件事永远是先把散落的色值和间距值抽成变量再把项目里所有!important揪出来清一遍。做完这两步后面接暗色模式、接换肤、接业务扩展手感会顺非常多。这套第四章的方法值得你认真试一次。