Construindo um design system em Vue
Crie um sistema de design Vue com tokens CSS compartilhados, componentes de botão e campo, tema escuro, documentação no Storybook e empacotamento com Vite.
Um design system mínimo em Vue é um único pacote npm que contém uma folha de estilos com design tokens e um pequeno conjunto de componentes <script setup>. Você o documenta no Storybook e gera o bundle com o modo de biblioteca (library mode) do Vite.
Se você trabalha com mais de um app Vue, provavelmente já viu isto acontecer: o botão primário de um app é #2563eb, o de outro é #3b82f6, e um terceiro app usa padding: 10px 14px porque alguém definiu no olho. Essas diferenças se acumulam com o tempo, e corrigir cada app separadamente não impede que elas continuem surgindo.
Este tutorial cria um único pacote compartilhado e o instala em todos os apps. Você começa pelos tokens, adiciona dois componentes e um tema escuro, documenta tudo no Storybook e publica o resultado como biblioteca. Se precisar de contexto sobre por que design systems são importantes, leia design systems para desenvolvimento front-end. O código tem como alvo Vue 3.4+, Vite 8 e Storybook 10.
Pré-requisitos: você deve estar familiarizado com a Composition API e com <script setup>. Se não estiver, comece pelos fundamentos do Vue 3.
Principais conclusões
- Defina os design tokens como CSS custom properties em
:root, para que todos os componentes de todos os apps leiam os mesmos valores de cor, espaçamento e tipografia em tempo de execução. - Um botão com uma prop
variante uma propsizenão consegue expressar estilos conflitantes, ao contrário de um conjunto de props booleanas. - Desde o Vue 3.4,
defineModel()é a forma recomendada de dar suporte av-modelem um input customizado. - No modo de biblioteca do Vite, marque
vuecomo external para que o pacote use a cópia do Vue do app consumidor em vez de embutir a sua própria. - O Vite gera o CSS de uma biblioteca como um único arquivo, que você expõe pelo mapa
exportsdo pacote.
O objetivo: um pacote que todo app Vue instala
O pacote final entrega três coisas: style.css (tokens mais os estilos dos componentes), os próprios componentes e um ponto de entrada JavaScript que exporta esses componentes. Esta é a árvore do projeto:
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
Design tokens como CSS custom properties
Coloque seus design tokens em src/tokens.css como CSS custom properties declaradas em :root. Custom properties são herdadas e resolvidas em tempo de execução. Isso significa que todos os componentes de todos os apps leem os mesmos valores, e redefinir um token em um único lugar o altera em todos os lugares. Use o prefixo --ds- nos nomes para que eles não colidam com variáveis que os apps consumidores já definem.
/* 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;
}
Um botão com props de variante e tamanho
Um botão de design system deve ter uma prop variant e uma prop size, cada uma mapeada para uma classe CSS. Não adicione uma prop booleana para cada estilo. Com booleanas, quem chama o componente pode escrever <Button primary danger>, e nada na API impede isso:
<!-- Before: conflicting states are expressible -->
<Button primary danger small>Delete</Button>
Props tipadas com union types permitem exatamente um valor por eixo:
<!-- 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>
O DsButton renderiza um <button> nativo, então o navegador cuida do comportamento de teclado e de formulário. O slot padrão aceita texto ou ícones. Os estilos referenciam apenas tokens e não contêm valores hexadecimais. O Storybook lê os comentários JSDoc das props e os exibe no painel de documentação.
Um input com defineModel(), label e repasse de atributos
Desde o Vue 3.4, defineModel() é a forma recomendada de dar suporte a v-model em um componente. Ele retorna uma ref que se mantém sincronizada com a modelValue do componente pai e emite update:modelValue sempre que o filho a altera. Não defina um valor padrão para ele. A documentação do Vue alerta que um valor padrão, quando o pai não fornece nenhum valor, deixa pai e filho dessincronizados.
<!-- 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>
Envolver o <input> em seu <label> dá ao input um nome acessível, então o componente não precisa de uma prop id. Porém, o elemento raiz é o <label>, então, por padrão, atributos como placeholder, type e name iriam parar no label. Definir inheritAttrs: false por meio de defineOptions desativa esse comportamento, e v-bind="$attrs" repassa esses atributos para o <input>. Com essa configuração, class e style também vão para o input em vez do label.
Temas claro e escuro a partir dos mesmos tokens
Um design system em Vue não precisa de novos componentes para o modo escuro. Redefina as mesmas custom properties sob um seletor [data-theme="dark"] e dentro de uma media query prefers-color-scheme: dark, e todos os componentes que as leem mudam automaticamente. Adicione isto ao 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;
}
}
A media query segue a configuração do sistema operacional. A proteção :not([data-theme="light"]) respeita o usuário que escolhe explicitamente o modo claro. Para definir um tema a partir do app, basta uma linha:
document.documentElement.dataset.theme = 'dark'
Storybook para Vue
O Storybook renderiza cada componente do design system de forma isolada, para que você possa revisar todas as variantes sem rodar um app. Para entender como as stories se transformam em documentação viva, veja documentação de UI com Storybook. Inicialize-o a partir da raiz do projeto:
npm create storybook@latest
O instalador detecta o Vite e o Vue e configura o framework @storybook/vue3-vite. A partir do Storybook 10.6, o engine padrão vue-docgen-api está obsoleto (deprecated), e a opção recomendada é 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
Carregue os tokens globalmente. O guia de estilização do Storybook orienta adicionar CSS global para todas as suas stories importando-o em .storybook/preview.ts:
// .storybook/preview.ts
import type { Preview } from '@storybook/vue3-vite'
import '../src/tokens.css'
const preview: Preview = {}
export default preview
A story a seguir renderiza todas as variantes lado a lado e mantém size editável pelos Controls. Ela usa o padrão tipado com Meta e 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>`,
}),
}
Empacote o design system Vue com o modo de biblioteca do Vite
O modo de biblioteca do Vite compila src/index.ts em um bundle distribuível em vez de um app. O ponto de entrada importa os tokens, para que eles acabem na folha de estilos gerada, e depois reexporta os componentes:
// src/index.ts
import './tokens.css'
export { default as DsButton } from './components/DsButton.vue'
export { default as DsInput } from './components/DsInput.vue'
O exemplo da documentação do Vite não inclui o @vitejs/plugin-vue, mas uma biblioteca Vue precisa dele para compilar arquivos .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' } },
},
},
})
O Vite 8 usa build.rolldownOptions. O antigo build.rollupOptions é um alias obsoleto dele. Marque vue como external para que o pacote use a cópia do Vue do app consumidor em vez de embutir a sua própria; duas cópias do Vue na mesma página quebram a reatividade e as instâncias de componentes. O Vite gera todo o CSS da biblioteca em uma única folha de estilos. Sem cssFileName, esse arquivo recebe o nome definido em fileName; por isso, aqui, cssFileName: 'style' gera dist/style.css.
Use a estrutura de package.json recomendada pelo Vite. Liste vue como peer dependency, o que informa ao npm que o app hospedeiro o fornece:
{
"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" }
}
Execute npx vite build, depois confira a pasta dist/ e verifique se cada caminho em exports corresponde a um arquivo que foi de fato gerado.
Instale em outro app
Instale o pacote a partir de um workspace ou de um caminho local. Importe o CSS uma única vez no ponto de entrada do app e, depois, importe os componentes onde precisar:
npm install ../design-system
Uma instalação por caminho local cria um symlink. Com isso, o import 'vue' do bundle pode ser resolvido para a cópia em design-system/node_modules, que foi instalada ali para o build e para o Storybook, e a página acaba com duas cópias do Vue. Para evitar isso, configure o Vite do app consumidor para resolver vue a partir da raiz do próprio projeto:
// 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'] },
})
Como alternativa, execute npm pack no design system e instale o tarball resultante, que contém apenas os arquivos listados em 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>
Mantenha-o pequeno
Cada componente que você adiciona a um design system Vue compartilhado é mais uma API com a qual todos os apps precisam manter compatibilidade. Comece com tokens, um botão e um input. Só adicione um componente ao pacote compartilhado quando pelo menos dois apps precisarem dele; todo o resto fica no app que o utiliza. Seu próximo passo é instalar o pacote no seu segundo app, substituir o botão feito à mão desse app pelo DsButton e remover os valores de cor fixos no código em favor dos tokens --ds-.
Perguntas frequentes
Por que fico com duas cópias do Vue depois de instalar o design system a partir de um caminho local?
Uma instalação por caminho local ou por workspace cria um symlink, então o import de vue no bundle pode ser resolvido para a cópia que está no node_modules da própria pasta do design system. Adicione resolve.dedupe com vue à configuração do Vite do app consumidor, o que força o Vite a resolver as dependências listadas para a cópia na raiz do projeto. Como alternativa, execute npm pack e instale o tarball, que contém apenas os arquivos listados em files.
O modo de biblioteca do Vite gera arquivos de declaração TypeScript para componentes Vue?
Não. O Vite apenas transpila TypeScript e não gera arquivos .d.ts, então, por padrão, os consumidores não recebem os tipos das props. Execute vue-tsc --declaration --emitDeclarationOnly depois do vite build, porque o vue-tsc entende arquivos .vue e o tsc puro não. Execute-o depois do build porque o vite build esvazia o diretório de saída por padrão. O plugin vite-plugin-dts é uma alternativa que roda dentro do build do Vite.
Os design tokens devem ser variáveis Sass ou CSS custom properties?
Use CSS custom properties para qualquer token que mude conforme o tema. Variáveis Sass são compiladas em valores fixos em tempo de build e não existem no navegador, então um seletor data-theme ou uma media query prefers-color-scheme não consegue redefini-las. Custom properties são resolvidas em tempo de execução e herdadas pelo DOM. O Sass ainda pode gerar as declarações das custom properties, caso a equipe prefira escrever os tokens em Sass.
Se um app importa apenas o DsButton, ele ainda carrega o CSS de todos os componentes?
Sim. O modo de biblioteca do Vite gera uma única folha de estilos para toda a biblioteca, então importar o style.css carrega os tokens e os estilos de todos os componentes, independentemente de quais componentes o app realmente usa. No lado do JavaScript é diferente: o build em ES module reexporta cada componente pelo nome, então o bundler do app consumidor pode aplicar tree-shaking nos componentes que nunca importa. Com um conjunto pequeno de componentes, a folha de estilos compartilhada tem um custo baixo.
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