12k
All articles

在 Vue 中构建设计系统

构建 Vue 设计系统,包含共享 CSS 令牌、按钮与输入组件、深色主题和 Storybook 文档,并用 Vite 打包供多个应用使用。

OpenReplay Team
OpenReplay Team
在 Vue 中构建设计系统

一个最小化的 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 自定义属性,这样每个应用中的每个组件在运行时读取的都是相同的颜色、间距和字体值。
  • 只有一个 variant prop 和一个 size prop 的按钮,不会像一组布尔 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。在组件数量较少的情况下,共享样式表带来的开销很小。

DevTools for the frontend

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

We use cookies to improve your experience. By using our site, you accept cookies.