一个最小化的 Vue 设计系统就是一个 npm 包,其中包含一份定义设计令牌(design tokens)的样式表和一小组 <script setup> 组件。你可以用 Storybook 为它编写文档,并通过 Vite 库模式进行打包。
如果你同时维护多个 Vue 应用,大概率遇到过这种情况:一个应用的主按钮颜色是 #2563eb,另一个是 #3b82f6,而第三个应用用的是 padding: 10px 14px,只因为当初有人凭感觉调了一下。这些差异会随着时间不断累积,而逐个修复各个应用并不能从根本上阻止它们出现。
本教程将构建一个共享包,并在所有应用中安装它。你将从设计令牌入手,添加两个组件和一套暗色主题,在 Storybook 中为它们编写文档,最后将成果作为库发布。如果你想先了解设计系统为何重要,可以阅读 design systems for front-end development。本文代码基于 Vue 3.4+、Vite 8 和 Storybook 10。
前置知识: 你应当熟悉组合式 API(Composition API)和 <script setup>。如果还不熟悉,请先阅读 the fundamentals of Vue 3。
核心要点
- 将设计令牌定义为
:root上的 CSS 自定义属性,这样每个应用中的每个组件在运行时读取的都是相同的颜色、间距和字体值。 - 只有一个
variantprop 和一个sizeprop 的按钮,不会像一组布尔 prop 那样表达出相互冲突的样式。 - 从 Vue 3.4 开始,
defineModel()是在自定义输入组件上支持v-model的推荐方式。 - 在 Vite 库模式下,将
vue标记为 external,使包使用宿主应用中的 Vue,而不是自己打包一份。 - Vite 会将库的 CSS 输出为单个文件,你可以通过包的
exports映射将其暴露出去。
目标:一个所有 Vue 应用都能安装的包
最终完成的包包含三部分:style.css(设计令牌及组件样式)、组件本身,以及导出这些组件的 JavaScript 入口文件。项目结构如下:
design-system/
├── .storybook/
│ ├── main.ts
│ └── preview.ts
├── src/
│ ├── tokens.css
│ ├── index.ts
│ └── components/
│ ├── DsButton.vue
│ ├── DsButton.stories.ts
│ └── DsInput.vue
├── package.json
└── vite.config.ts
以 CSS 自定义属性定义设计令牌
将设计令牌写在 src/tokens.css 中,作为声明在 :root 上的 CSS 自定义属性。自定义属性可以继承,并在运行时解析。这意味着每个应用中的每个组件读取的都是同一组值,只需在一处重新定义某个令牌,所有地方都会随之改变。为变量名加上 --ds- 前缀,避免与宿主应用中已有的变量发生冲突。
/* src/tokens.css */
:root {
--ds-color-primary: #2563eb;
--ds-color-danger: #dc2626;
--ds-color-surface: #ffffff;
--ds-color-text: #111827;
--ds-color-border: #d1d5db;
--ds-space-1: 0.25rem;
--ds-space-2: 0.5rem;
--ds-space-3: 0.75rem;
--ds-space-4: 1rem;
--ds-font-size-sm: 0.875rem;
--ds-font-size-md: 1rem;
--ds-font-size-lg: 1.125rem;
--ds-radius: 0.375rem;
}
带有 variant 和 size prop 的按钮
设计系统中的按钮应当只有一个 variant prop 和一个 size prop,并分别映射到对应的 CSS 类。不要为每种样式都添加一个布尔 prop。使用布尔 prop 时,调用方可以写出 <Button primary danger> 这样的代码,而 API 本身无法阻止:
<!-- Before: conflicting states are expressible -->
<Button primary danger small>Delete</Button>
而带类型的联合类型 prop 在每个维度上只允许取一个值:
<!-- src/components/DsButton.vue -->
<script setup lang="ts">
import { computed } from 'vue'
const props = withDefaults(defineProps<{
/** Visual style of the button */
variant?: 'primary' | 'secondary' | 'danger'
/** Padding and font size */
size?: 'sm' | 'md' | 'lg'
}>(), { variant: 'primary', size: 'md' })
const classes = computed(() => [
'ds-button',
`ds-button--${props.variant}`,
`ds-button--${props.size}`,
])
</script>
<template>
<button :class="classes"><slot /></button>
</template>
<style>
.ds-button { border: 1px solid transparent; border-radius: var(--ds-radius); cursor: pointer; }
.ds-button--primary { background: var(--ds-color-primary); color: var(--ds-color-surface); }
.ds-button--secondary { background: var(--ds-color-surface); color: var(--ds-color-text); border-color: var(--ds-color-border); }
.ds-button--danger { background: var(--ds-color-danger); color: var(--ds-color-surface); }
.ds-button--sm { padding: var(--ds-space-1) var(--ds-space-2); font-size: var(--ds-font-size-sm); }
.ds-button--md { padding: var(--ds-space-2) var(--ds-space-3); font-size: var(--ds-font-size-md); }
.ds-button--lg { padding: var(--ds-space-3) var(--ds-space-4); font-size: var(--ds-font-size-lg); }
</style>
DsButton 渲染的是原生 <button>,因此键盘交互和表单行为都由浏览器处理。默认插槽可接收文本或图标。样式中只引用设计令牌,不包含任何十六进制色值。Storybook 会读取 prop 上的 JSDoc 注释,并将其显示在文档面板中。
使用 defineModel()、标签与属性透传的输入框
从 Vue 3.4 开始,defineModel() 是推荐的方式,用于让组件支持 v-model。它返回一个 ref,该 ref 与父组件的 modelValue 保持同步,并在子组件修改它时触发 update:modelValue 事件。不要为它设置默认值。Vue 文档警告称,如果设置了默认值而父组件没有传值,会导致父子组件之间状态不同步。
<!-- src/components/DsInput.vue -->
<script setup lang="ts">
defineOptions({ inheritAttrs: false })
defineProps<{ /** Visible label text */ label: string }>()
const model = defineModel<string>()
</script>
<template>
<label class="ds-input">
<span>{{ label }}</span>
<input v-model="model" v-bind="$attrs" />
</label>
</template>
将 <input> 包裹在 <label> 内部,可以为输入框提供无障碍名称(accessible name),因此组件无需额外的 id prop。不过,由于根元素是 <label>,默认情况下 placeholder、type 和 name 等属性会落到 label 上。通过 defineOptions 设置 inheritAttrs: false 可以关闭这一行为,再由 v-bind="$attrs" 将这些属性转发到 <input> 上。在这种配置下,class 和 style 也会作用于 input 而非 label。
基于同一组令牌实现亮色与暗色主题
Vue 设计系统并不需要为暗色模式编写新组件。只需在 [data-theme="dark"] 选择器下以及 prefers-color-scheme: dark 媒体查询中重新定义同一组自定义属性,所有读取这些属性的组件就会自动切换。将以下内容添加到 tokens.css:
[data-theme="dark"] {
--ds-color-surface: #111827;
--ds-color-text: #f9fafb;
--ds-color-border: #374151;
}
@media (prefers-color-scheme: dark) {
:root:not([data-theme="light"]) {
--ds-color-surface: #111827;
--ds-color-text: #f9fafb;
--ds-color-border: #374151;
}
}
媒体查询会跟随操作系统的设置。:not([data-theme="light"]) 这一守卫条件则尊重用户主动选择亮色模式的意愿。在应用中设置主题只需一行代码:
document.documentElement.dataset.theme = 'dark'
在 Vue 中使用 Storybook
Storybook 会在隔离环境中渲染每个设计系统组件,因此无需运行应用即可审查所有变体。关于 story 如何转化为活文档的背景知识,请参阅 Storybook UI documentation。在项目根目录下执行初始化:
npm create storybook@latest
安装程序会检测到 Vite 和 Vue,并自动配置 @storybook/vue3-vite 框架。从 Storybook 10.6 起,默认的 vue-docgen-api 引擎已被弃用,推荐改用 vue-component-meta:
// .storybook/main.ts
import type { StorybookConfig } from '@storybook/vue3-vite'
const config: StorybookConfig = {
stories: ['../src/**/*.stories.ts'],
framework: {
name: '@storybook/vue3-vite',
options: { docgen: 'vue-component-meta' },
},
}
export default config
全局加载设计令牌。Storybook 的样式指南指出,要为所有 story 添加全局 CSS,可以在 .storybook/preview.ts 中导入它:
// .storybook/preview.ts
import type { Preview } from '@storybook/vue3-vite'
import '../src/tokens.css'
const preview: Preview = {}
export default preview
下面的 story 会并排渲染所有变体,同时保留通过 Controls 编辑 size 的能力。它采用了带类型的 Meta 和 StoryObj 写法:
// src/components/DsButton.stories.ts
import type { Meta, StoryObj } from '@storybook/vue3-vite'
import DsButton from './DsButton.vue'
const meta = {
component: DsButton,
argTypes: {
size: { control: 'radio', options: ['sm', 'md', 'lg'] },
},
} satisfies Meta<typeof DsButton>
export default meta
type Story = StoryObj<typeof meta>
export const AllVariants: Story = {
args: { size: 'md' },
render: (args) => ({
components: { DsButton },
setup: () => ({ args, variants: ['primary', 'secondary', 'danger'] }),
template: `
<div style="display: flex; gap: 8px">
<DsButton v-for="v in variants" :key="v" v-bind="args" :variant="v">{{ v }}</DsButton>
</div>`,
}),
}
使用 Vite 库模式打包 Vue 设计系统
Vite 库模式会将 src/index.ts 构建为可分发的包,而不是一个应用。入口文件导入设计令牌,使其被打包进最终输出的样式表,然后重新导出各个组件:
// src/index.ts
import './tokens.css'
export { default as DsButton } from './components/DsButton.vue'
export { default as DsInput } from './components/DsInput.vue'
Vite 文档中的示例省略了 @vitejs/plugin-vue,但 Vue 库需要它来编译 .vue 文件:
// vite.config.ts
import { resolve } from 'node:path'
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
export default defineConfig({
plugins: [vue()],
build: {
lib: {
entry: resolve(import.meta.dirname, 'src/index.ts'),
name: 'DesignSystem',
fileName: 'design-system',
cssFileName: 'style',
},
rolldownOptions: {
external: ['vue'],
output: { globals: { vue: 'Vue' } },
},
},
})
Vite 8 使用 build.rolldownOptions,旧的 build.rollupOptions 已成为它的弃用别名。将 vue 标记为 external,使包使用宿主应用中的 Vue,而不是自己打包一份;同一页面中存在两份 Vue 会破坏响应式系统和组件实例。Vite 会将库的所有 CSS 输出为一个样式表。如果不设置 cssFileName,该文件将以 fileName 命名,因此这里通过 cssFileName: 'style' 生成 dist/style.css。
采用 Vite 推荐的 package.json 结构。将 vue 列为 peer dependency,以告知 npm 由宿主应用提供它:
{
"name": "design-system",
"version": "0.1.0",
"type": "module",
"files": ["dist"],
"main": "./dist/design-system.umd.cjs",
"module": "./dist/design-system.js",
"exports": {
".": {
"import": "./dist/design-system.js",
"require": "./dist/design-system.umd.cjs"
},
"./style.css": "./dist/style.css"
},
"peerDependencies": { "vue": "^3.4.0" }
}
运行 npx vite build,然后检查 dist/ 目录,确保 exports 中的每个路径都对应一个实际生成的文件。
在其他应用中安装
从 workspace 或本地路径安装该包。在应用入口中导入一次 CSS,然后在需要的地方导入组件:
npm install ../design-system
通过本地路径安装会创建一个符号链接(symlink)。这样一来,包中的 import 'vue' 可能会解析到 design-system/node_modules 中的那份 Vue(它是为构建和 Storybook 而安装的),最终页面上会出现两份 Vue。为避免这种情况,需要在宿主应用的 Vite 配置中让 vue 从其自身项目根目录解析:
// vite.config.ts in the consuming app
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
export default defineConfig({
plugins: [vue()],
resolve: { dedupe: ['vue'] },
})
另一种做法是在设计系统项目中运行 npm pack,然后安装生成的 tarball,其中只包含 files 中列出的文件。
// main.ts
import { createApp } from 'vue'
import 'design-system/style.css'
import App from './App.vue'
createApp(App).mount('#app')
<script setup lang="ts">
import { ref } from 'vue'
import { DsButton, DsInput } from 'design-system'
const email = ref('')
</script>
<template>
<DsInput v-model="email" label="Email" type="email" placeholder="you@example.com" />
<DsButton variant="primary" size="lg">Subscribe</DsButton>
</template>
保持精简
向共享的 Vue 设计系统中每添加一个组件,就多了一套所有应用都必须保持兼容的 API。从设计令牌、一个按钮和一个输入框开始。只有当至少两个应用需要某个组件时,才将它加入共享包;其余组件都留在使用它的应用中。下一步,请在你的第二个应用中安装这个包,用 DsButton 替换该应用中手写的按钮,并将其中硬编码的颜色值改为 --ds- 令牌。
常见问题
为什么从本地路径安装设计系统后会出现两份 Vue?
通过本地路径或 workspace 安装会创建符号链接,因此包中对 vue 的导入可能会解析到 design-system 文件夹自身 node_modules 中的那份 Vue。在宿主应用的 Vite 配置中添加包含 vue 的 resolve.dedupe,强制 Vite 将列出的依赖解析到项目根目录中的副本。另一种做法是运行 npm pack 并安装生成的 tarball,其中只包含 files 中列出的文件。
Vite 库模式会为 Vue 组件生成 TypeScript 声明文件吗?
不会。Vite 只负责转译 TypeScript,不会输出 .d.ts 文件,因此默认情况下使用方拿不到 prop 类型。请在 vite build 之后运行 vue-tsc --declaration --emitDeclarationOnly,因为 vue-tsc 能够理解 .vue 文件,而普通的 tsc 不能。之所以要在构建之后运行,是因为 vite build 默认会清空输出目录。vite-plugin-dts 插件是另一种选择,它在 Vite 构建过程中运行。
设计令牌应该用 Sass 变量还是 CSS 自定义属性?
凡是会随主题变化的令牌,都应使用 CSS 自定义属性。Sass 变量在构建时被编译为固定值,在浏览器中并不存在,因此 data-theme 选择器或 prefers-color-scheme 媒体查询无法重新定义它们。自定义属性在运行时解析,并会沿 DOM 继承。如果团队更喜欢用 Sass 编写令牌,仍然可以用 Sass 来生成自定义属性声明。
如果应用只导入了 DsButton,是否仍会加载所有组件的 CSS?
是的。Vite 库模式会为整个库输出一个样式表,因此导入 style.css 会加载设计令牌以及所有组件的样式,无论应用实际使用了哪些组件。JavaScript 部分则不同:ES 模块构建会按名称重新导出每个组件,因此宿主应用的打包工具可以对从未导入的组件进行 tree-shaking。在组件数量较少的情况下,共享样式表带来的开销很小。
Gain Debugging Superpowers
Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers.
Star on GitHub12k