Создание дизайн-системы на Vue
Создайте дизайн-систему Vue с общими CSS-токенами, компонентами кнопки и поля, тёмной темой, документацией Storybook и сборкой библиотеки в Vite.
Минимальная дизайн-система на Vue — это один npm-пакет, который содержит таблицу стилей с дизайн-токенами и небольшой набор компонентов на <script setup>. Документацию к нему ведут в Storybook, а собирают его в режиме библиотеки Vite.
Если вы работаете с несколькими Vue-приложениями, то наверняка сталкивались с такой картиной: в одном приложении основная кнопка имеет цвет #2563eb, в другом — #3b82f6, а в третьем используется padding: 10px 14px, потому что кто-то подобрал его на глаз. Со временем такие расхождения накапливаются, и исправления в каждом приложении по отдельности их не останавливают.
В этом руководстве мы создадим один общий пакет и установим его во все приложения. Начнём с токенов, затем добавим два компонента и тёмную тему, задокументируем всё в Storybook и опубликуем результат как библиотеку. Если вам нужен контекст о том, зачем вообще нужны дизайн-системы, прочитайте статью о дизайн-системах во фронтенд-разработке. Код рассчитан на Vue 3.4+, Vite 8 и Storybook 10.
Предварительные требования: вы должны уверенно работать с Composition API и <script setup>. Если это не так, начните с основ Vue 3.
Ключевые выводы
- Определяйте дизайн-токены как пользовательские свойства CSS на
:root, чтобы каждый компонент в каждом приложении во время выполнения получал одни и те же значения цветов, отступов и типографики. - Кнопка с одним пропсом
variantи одним пропсомsizeне позволяет задать конфликтующие стили, в отличие от набора булевых пропсов. - Начиная с Vue 3.4, рекомендуемый способ поддержки
v-modelв пользовательском поле ввода —defineModel(). - В режиме библиотеки 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 в виде пользовательских свойств CSS (CSS custom properties), объявленных на :root. Пользовательские свойства наследуются и вычисляются во время выполнения. Это значит, что каждый компонент в каждом приложении получает одни и те же значения, а переопределение токена в одном месте меняет его везде. Добавьте к именам префикс --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
У кнопки в дизайн-системе должен быть один пропс variant и один пропс size, каждый из которых сопоставлен с CSS-классом. Не заводите отдельный булев пропс под каждый стиль. При булевых пропсах вызывающий код может написать <Button primary danger>, и ничто в API этому не помешает:
<!-- Before: conflicting states are expressible -->
<Button primary danger small>Delete</Button>
Пропсы с типизированными объединениями (union types) допускают ровно одно значение для каждого измерения:
<!-- 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>, поэтому работу с клавиатурой и поведение в формах обеспечивает браузер. Слот по умолчанию принимает текст или иконки. Стили ссылаются только на токены и не содержат ни одного HEX-значения. Storybook считывает JSDoc-комментарии к пропсам и показывает их на панели документации.
Поле ввода с defineModel(), меткой и пробросом атрибутов
Начиная с Vue 3.4, рекомендуемый способ поддержки v-model в компоненте — defineModel(). Он возвращает 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. Однако корневым элементом при этом становится <label>, поэтому по умолчанию такие атрибуты, как placeholder, type и name, попали бы на метку. Установка inheritAttrs: false через defineOptions отключает это поведение, а v-bind="$attrs" пробрасывает эти атрибуты в <input>. При такой настройке class и style тоже применяются к полю ввода, а не к метке.
Светлая и тёмная темы на основе одних и тех же токенов
Дизайн-системе на 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'
Storybook для Vue
Storybook рендерит каждый компонент дизайн-системы изолированно, поэтому все варианты можно просмотреть, не запуская приложение. О том, как истории (stories) превращаются в живую документацию, читайте в статье о документации UI в Storybook. Инициализируйте Storybook в корне проекта:
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 по стилизации предписывает добавлять глобальный CSS для всех историй через импорт в .storybook/preview.ts:
// .storybook/preview.ts
import type { Preview } from '@storybook/vue3-vite'
import '../src/tokens.css'
const preview: Preview = {}
export default preview
Следующая история отображает все варианты рядом и оставляет size доступным для редактирования через Controls. В ней используется паттерн с типизированными 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>`,
}),
}
Сборка дизайн-системы на Vue в режиме библиотеки Vite
Режим библиотеки 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.
Используйте структуру package.json, которую рекомендует Vite. Укажите vue как peer-зависимость — так 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
При установке по локальному пути создаётся симлинк. В этом случае import 'vue' в бандле может разрешиться в копию из design-system/node_modules, установленную туда для сборки и 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 в дизайн-системе и установить полученный tar-архив, который содержит только файлы, перечисленные в 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 в бандле может разрешиться в копию из собственной папки node_modules дизайн-системы. Добавьте resolve.dedupe со значением vue в конфигурацию Vite приложения-потребителя — это заставит Vite разрешать перечисленные зависимости в копию из корня проекта. Другой вариант — выполнить npm pack и установить tar-архив, который содержит только файлы, перечисленные в files.
Генерирует ли режим библиотеки Vite файлы деклараций TypeScript для Vue-компонентов?
Нет. Vite только транспилирует TypeScript и не создаёт файлы .d.ts, поэтому по умолчанию потребители не получают типы пропсов. Запускайте vue-tsc --declaration --emitDeclarationOnly после vite build: 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