主题
样式规范
组件库不能靠 scoped 做隔离,也不该把库前缀散落在几十个文件里。规则只有一条:所有类名和 CSS 变量都从 lib.config.ts 的 cssPrefix 派生,组件代码里不写死前缀。
源码用纯 CSS、SCSS 还是 Less,只在 pnpm bootstrap 问一次。发布物始终是 CSS,使用方不安装预处理器。
命名约定
以 cssPrefix: 'pl'、组件 button 为例:
| 角色 | 写法 | 示例 | 用途 |
|---|---|---|---|
| Block | <prefix>-<block> | pl-button | 组件根节点 |
| Block 变体 | <prefix>-<block>-<后缀> | pl-button-group | 同族组件,例如按钮组 |
| Element | __<element> | pl-button__content | 组件内部节点 |
| Modifier | --<modifier> | pl-button--primary | 由 props 决定的外观分支 |
| State | is-<state> | is-disabled | 临时状态,与 Block 组合 |
| 全局令牌 | --<prefix>-<name> | --pl-color-primary | 跨组件复用的设计令牌 |
| 组件级变量 | --<prefix>-<block>-<name> | --pl-button-bg | 只属于该组件的可覆盖变量 |
State 故意不带组件前缀。它描述的是「当前是什么状态」,配合 Block 使用即可定位:.pl-button.is-disabled。
前缀只有一个来源
text
lib.config.ts (cssPrefix)
└─ pnpm gen sync
└─ packages/utils/src/css-prefix.ts → export const CSS_PREFIX = 'pl'
└─ createNamespace() 的默认前缀packages/utils/src/css-prefix.ts 带有 // generated by contract:sync 标记,不要手改。要换前缀就改 lib.config.ts,再执行 pnpm gen sync;pnpm bootstrap 初始化新库时会一并写好这两个文件,并把模板里 pl- 开头的类名批量改成新前缀。
createNamespace
ts
import { createNamespace } from '@internal/utils';
const ns = createNamespace('button');| 方法 | 返回 |
|---|---|
ns.b() | pl-button |
ns.b('group') | pl-button-group |
ns.e('content') | pl-button__content |
ns.m('primary') | pl-button--primary |
ns.be('group', 'item') | pl-button-group__item |
ns.em('icon', 'large') | pl-button__icon--large |
ns.is('disabled') | is-disabled |
ns.is('disabled', false) | '' |
ns.cssVar('color-primary') | --pl-color-primary |
ns.cssVarBlock('bg') | --pl-button-bg |
ns.prefix / ns.block | 'pl' / 'button' |
第二个参数可以显式指定前缀,例如 createNamespace('button', 'demo'),仅在测试或特殊子命名空间时才需要。
在组件里使用
生成器产出的骨架已经接好命名空间,实现时继续往下加 element 和 modifier 即可:
vue
<script setup lang="ts">
import { createNamespace, cx } from '@internal/utils';
defineOptions({ name: 'PlButton' });
const props = withDefaults(defineProps<{ type?: 'primary' | 'default'; disabled?: boolean }>(), {
type: 'default',
disabled: false,
});
const ns = createNamespace('button');
</script>
<template>
<button
:class="cx(ns.b(), ns.m(props.type), ns.is('disabled', props.disabled))"
:disabled="props.disabled"
>
<span :class="ns.e('content')">
<slot />
</span>
</button>
</template>ns.is() 在条件为 false 时返回空字符串,cx 会把它过滤掉;用数组绑定 :class="[ns.b(), ns.is('disabled', props.disabled)]" 也可以,Vue 同样会忽略空串。
样式怎么写
CSS 读不到运行时变量,所以 <style> 里仍然写字面量类名,前缀必须与 cssPrefix 一致:
vue
<style>
.pl-button {
background: var(--pl-button-bg, var(--pl-color-bg));
border: 1px solid var(--pl-color-border);
}
.pl-button__content {
display: inline-flex;
gap: 4px;
}
.pl-button.is-disabled {
opacity: 0.5;
cursor: not-allowed;
}
</style>把组件级变量写成 var(--pl-button-bg, <默认值>),使用方就能只覆盖一个变量而不必和选择器权重较劲:
css
.checkout-page {
--pl-button-bg: #f5f7fa;
}令牌定义在 packages/core/styles/tokens.css,完整引入走 style.css,按需引入要单独引 @plinth/ui/tokens.css,见使用组件库。
CSS 预处理器
基座出厂不装预处理器:模板依赖里没有 sass-embedded / sass / less,示例组件是纯 <style>。接不接、接 SCSS 还是 Less,只在 pnpm bootstrap 问一次。
选完之后基座会写好依赖和 lib.config.ts 的 preprocessor 字段;之后 pnpm gen component 读取该字段,带样式的骨架自动带上对应 lang。作者不必再手改 catalog 或各包 package.json。
初始化时选择
交互式会问 CSS preprocessor。非交互:
bash
pnpm bootstrap --yes --name @acme/ui --prefix Ac --registry https://registry.npmjs.org/ --preprocessor none
pnpm bootstrap --yes --name @acme/ui --prefix Ac --registry https://registry.npmjs.org/ --preprocessor scss
pnpm bootstrap --yes --name @acme/ui --prefix Ac --registry https://registry.npmjs.org/ --preprocessor less--preprocessor 默认 none。不要根据底层 UI 框架的源码语言来选:Ant Design Vue 用 Less、Antdv Next 用 CSS-in-JS、Element Plus 用 SCSS、TDesign 用 Less,只表示它们怎么构建;二开并不编译对方源码,主题桥接仍是 packages/core/styles/tokens.css。
| 选项 | 写入 lib.config.ts | 依赖 | 已有库组件 | 之后 pnpm gen component --style |
|---|---|---|---|---|
none(默认) | preprocessor: 'none' | 不增依赖 | 保持 <style> | <style> |
scss | preprocessor: 'scss' | catalog 增加 sass-embedded,并写入根目录、docs、playground、@internal/build、发布包 | <style> 改为 <style lang="scss"> | <style lang="scss"> |
less | preprocessor: 'less' | 同上,包名换成 less | <style lang="less"> | <style lang="less"> |
preprocessor 与 cssPrefix 一样,是唯一来源。pnpm gen component 不会再问预处理器。选了 scss 时不要再装一份纯 JS 的 sass,以免两个实现抢解析顺序。
生成组件
bash
pnpm gen component date-picker --style生成器只问组件名和是否带 <style>。若 bootstrap 选了 scss,骨架会是:
vue
<script setup lang="ts">
import { createNamespace } from '@internal/utils';
defineOptions({ name: 'PlDatePicker' });
const ns = createNamespace('date-picker');
</script>
<template>
<div :class="ns.b()">
<slot />
</div>
</template>
<style lang="scss">
.pl-date-picker {
color: var(--pl-color-text);
}
</style>类名仍由 createNamespace 给出。可以在 SCSS / Less 里用 &__element 嵌套,编译结果必须仍是 .pl-date-picker__panel 这种 BEM 类名。也可以抽到同目录 .scss / .less 再 import;契约层会识别这些扩展名。
文档示例和 playground 属于应用代码,不受库组件的 lang 约束。
初始化之后改选择
pnpm bootstrap 只能跑一次。若当时选了 none,后来才要 SCSS:
- 把
lib.config.ts的preprocessor改成'scss'。 - 在
pnpm-workspace.yaml的catalog:增加'sass-embedded': ^1.93.0(Less 则是'less': ^4.4.0)。 - 在下列文件的
devDependencies中写入"sass-embedded": "catalog:"(Less 换成less):- 根目录
package.json docs/package.jsonplayground/package.json(若还保留 playground)internal/build/package.jsonpackages/core/package.json
- 根目录
- 把
packages/components/**/*.vue里无lang的<style>改成<style lang="scss">。 pnpm install && pnpm verify。
从 scss 换成 less(或反过来)时,同步替换包名和 lang,不要两个编译器并存。
硬性约束
- 不写
<style scoped>。隔离依靠前缀,理由见新增组件;packages/**/*.vue上的 lint 规则会直接拦住。 - 不写裸标签选择器(
button {}、input {})和全局元素样式,所有规则都从自己的 Block 类名起步。 - Element 只有一层。
pl-button__content__icon是错的,需要层级就新起一个 Block。 - 不在 TS 或模板里手拼前缀字符串(
'pl-' + name、`pl-button--${type}`),一律走createNamespace。 - 不在预处理器里另写一套变量拼类名,也不用 Sass / Less 变量当主题 API。可覆盖值继续用
var(--pl-button-bg, <默认值>)。 - 不把
.scss/.less写进发布包的exports,使用方只消费 CSS。 - 二开第三方组件时同样从自己的 Block 往下写,不要输出全局
.ant-*/.el-*/.t-*规则,详见 UI 框架。