根本问题在于缺乏调用契约：必须统一@import路径、添加命名空间、参数覆盖全部可变维度并使用语义变量默认值；正交拆分尺寸/颜色/状态等独立mixin，链式组合实现高内聚低耦合。
为什么直接 import 一堆 mixin 文件反而让样式更难维护
团队一上来就建个 mixins/ 目录，把所有 .flex()、.clearfix()、.text-truncate() 全塞进去，结果是：没人知道哪个 mixin 被谁用了，改一个 @spacing-sm 值，三个组件的边距全错位，调试时翻十页 CSS 才找到源头。根本问题不是 mixin 多，而是没建立调用契约——mixin 不是工具箱，是接口协议。
必须满足三点才叫“基础设施”：
-
@import路径统一收口在core/index.less，禁止组件文件里直接@import "../../mixins/flex" - 所有 mixin 必须带命名空间，比如
.ui-flex()而非裸.flex()，避免和第三方库或未来 CSS 原生属性冲突 - 每个 mixin 的参数必须覆盖全部可变维度，且默认值来自语义变量（如
@spacing-md），不能写死12px
如何设计真正可组合的原子 mixin（不是功能开关）
常见错误是写一个 .button(@size, @theme, @state) 想包打天下，结果新增一个 ghost 状态就得复制整段代码。正交拆分才是关键：尺寸、颜色、状态、圆角、过渡必须各自独立，且能自由组合。
正确结构示例：
立即学习“前端免费学习笔记（深入）”；
.button-base() {
border: none;
outline: none;
transition: background-color 0.2s, border-color 0.2s;
}
<p>.button-size(@size) when (isnumber(@size)) {
height: @size;
padding: 0 (@size <em> 0.4);
font-size: (@size </em> 0.45);
}</p><p>.button-theme(@bg, @border, @text) {
background-color: @bg;
border-color: @border;
color: @text;
}</p><p>.button-state(@state) when (@state = disabled) {
background-color: desaturate(@bg, 50%);
color: fadeout(@text, 30%);
cursor: not-allowed;
}
调用时链式组合：.button-base(); .button-size(32px); .button-theme(#007bff, #0056b3, #fff); .button-state(disabled);
这样改尺寸只动 .button-size()，换主题只换 .button-theme() 参数，不会牵一发而动全身。
PigX UI Pro 前端开发指南 - Vue 3 + TypeScript + Element Plus。当用户提到 PigX UI、PigX 前端、lgb-mgui 项目、Vue 3 企业级后台开发、Element Plus 后台开发时使用此技能。
Less-loader 配置不当会让整个 mixin 库失效
写了规范的 mixin，但编译报错 Cannot resolve variable @text-color 或生成的 CSS 里全是空括号，90% 是路径解析失败。Less 编译器不走 Webpack 的 resolve.alias，@import "@/styles/core" 必然报错。
Webpack 用户必须在 less-loader 的 lessOptions.paths 中显式声明：
lessOptions: {
paths: [
path.resolve(__dirname, 'src/styles'),
path.resolve(__dirname, 'node_modules')
]
}
Vite 用户需在 vite.config.ts 中配置：
css: {
preprocessorOptions: {
less: {
additionalData: `@import "@/styles/core/index.less";`,
javascriptEnabled: true
}
}
}
注意：additionalData 会注入到每个 Less 文件顶部，确保变量和 mixin 在任何地方都能被识别，但别滥用——只注入 core/index.less，不要把具体组件 mixin 也塞进去。
为什么 CSS 体积暴增却查不到原因
一个 .card() mixin 被调用了 17 次，最终 CSS 里就出现 17 份完全相同的 box-shadow: 0 2px 8px rgba(0,0,0,0.1)。Less 不做去重，它只是文本展开器。
控制体积的关键动作：
- 禁用
lessc --compress，开发期保留完整注释和换行，便于定位哪段 CSS 来自哪个 mixin 调用 - 对高频复用的视觉规则（如阴影、圆角、过渡），抽成 CSS 自定义属性（
--card-shadow），mixin 内部只引用变量，而非重复输出值 - 用
// debug: .card() called with @variant: highlight在 mixin 开头加注释，编译后能在 CSS 里看到上下文
最易被忽略的一点：mixin 的“正交性”不是写法问题，是组织问题。当你要给按钮加 loading 状态时，不该新增 .button-loading()，而应让 .button-state(loading) 接管——否则每加一个状态，mixin 数量就指数增长。
