Cómo crear un sistema de diseño en Vue
Crea un sistema de diseño Vue con tokens CSS compartidos, componentes de botón y campo, modo oscuro, documentación en Storybook y empaquetado con Vite.
Un sistema de diseño mínimo en Vue es un único paquete npm que contiene una hoja de estilos con design tokens y un pequeño conjunto de componentes <script setup>. Se documenta en Storybook y se empaqueta con el modo librería de Vite.
Si trabajas con más de una aplicación Vue, probablemente hayas visto que esto ocurre: el botón principal de una aplicación es #2563eb, el de otra es #3b82f6, y una tercera usa padding: 10px 14px porque alguien lo ajustó a ojo. Estas diferencias se acumulan con el tiempo, y corregir cada aplicación por separado no impide que sigan apareciendo.
En este tutorial se crea un único paquete compartido que se instala en todas las aplicaciones. Empezarás con los tokens, añadirás dos componentes y un tema oscuro, los documentarás en Storybook y publicarás el resultado como librería. Si necesitas contexto sobre por qué importan los sistemas de diseño, lee sistemas de diseño para el desarrollo front-end. El código está pensado para Vue 3.4+, Vite 8 y Storybook 10.
Requisitos previos: Debes sentirte cómodo con la Composition API y <script setup>. Si no es así, empieza por los fundamentos de Vue 3.
Puntos clave
- Define los design tokens como propiedades personalizadas de CSS en
:root, de modo que todos los componentes de todas las aplicaciones lean los mismos valores de color, espaciado y tipografía en tiempo de ejecución. - Un botón con una prop
varianty una propsizeno puede expresar estilos contradictorios como sí lo permite un conjunto de props booleanas. - Desde Vue 3.4,
defineModel()es la forma recomendada de dar soporte av-modelen un input personalizado. - En el modo librería de Vite, marca
vuecomo externo para que el paquete use la copia de Vue de la aplicación consumidora en lugar de incluir la suya propia. - Vite genera el CSS de una librería como un único archivo, que se expone a través del mapa
exportsdel paquete.
El objetivo: un paquete que instalan todas las aplicaciones Vue
El paquete final incluye tres elementos: style.css (tokens más estilos de los componentes), los propios componentes y un punto de entrada JavaScript que exporta esos componentes. Esta es la estructura del proyecto:
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 propiedades personalizadas de CSS
Coloca tus design tokens en src/tokens.css como propiedades personalizadas de CSS declaradas en :root. Las propiedades personalizadas se heredan y se resuelven en tiempo de ejecución. Esto significa que todos los componentes de todas las aplicaciones leen los mismos valores, y redefinir un token en un solo lugar lo cambia en todas partes. Añade el prefijo --ds- a los nombres para que no colisionen con variables que las aplicaciones consumidoras ya definan.
/* 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;
}
Un botón con props de variante y tamaño
El botón de un sistema de diseño debe tener una prop variant y una prop size, cada una asociada a una clase CSS. No añadas una prop booleana por cada estilo. Con booleanos, quien use el componente puede escribir <Button primary danger>, y nada en la API lo impide:
<!-- Before: conflicting states are expressible -->
<Button primary danger small>Delete</Button>
Las props tipadas como uniones permiten exactamente un valor por eje:
<!-- 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 renderiza un <button> nativo, por lo que el navegador se encarga del comportamiento del teclado y de los formularios. El slot por defecto acepta texto o iconos. Los estilos solo hacen referencia a tokens y no contienen valores hexadecimales. Storybook lee los comentarios JSDoc de las props y los muestra en el panel de documentación.
Un input con defineModel(), una etiqueta y paso de atributos
Desde Vue 3.4, defineModel() es la forma recomendada de dar soporte a v-model en un componente. Devuelve una ref que se mantiene sincronizada con el modelValue del componente padre y emite update:modelValue cada vez que el hijo la modifica. No le asignes un valor por defecto. La documentación de Vue advierte que un valor por defecto sin un valor proporcionado por el padre provoca que padre e hijo pierdan la sincronización.
<!-- 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 el <input> dentro de su <label> le proporciona un nombre accesible, por lo que el componente no necesita una prop id. Sin embargo, el elemento raíz es el <label>, así que, por defecto, atributos como placeholder, type y name acabarían en la etiqueta. Establecer inheritAttrs: false mediante defineOptions desactiva ese comportamiento, y v-bind="$attrs" reenvía esos atributos al <input>. Con esta configuración, class y style también se aplican al input en lugar de a la etiqueta.
Temas claro y oscuro a partir de los mismos tokens
Un sistema de diseño en Vue no necesita componentes nuevos para el modo oscuro. Redefine las mismas propiedades personalizadas bajo un selector [data-theme="dark"] y dentro de una media query prefers-color-scheme: dark, y todos los componentes que las leen cambiarán automáticamente. Añade esto a 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;
}
}
La media query sigue la configuración del sistema operativo. La condición :not([data-theme="light"]) respeta al usuario que elige explícitamente el modo claro. Para establecer un tema desde la aplicación, basta con una línea:
document.documentElement.dataset.theme = 'dark'
Storybook para Vue
Storybook renderiza cada componente del sistema de diseño de forma aislada, lo que te permite revisar todas las variantes sin ejecutar una aplicación. Para saber más sobre cómo las stories se convierten en documentación viva, consulta documentación de UI con Storybook. Inicialízalo desde la raíz del proyecto:
npm create storybook@latest
El instalador detecta Vite y Vue y configura el framework @storybook/vue3-vite. A partir de Storybook 10.6, el motor por defecto vue-docgen-api está obsoleto, y la opción recomendada es 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
Carga los tokens de forma global. La guía de estilos de Storybook indica que el CSS global para todas las stories se añade importándolo en .storybook/preview.ts:
// .storybook/preview.ts
import type { Preview } from '@storybook/vue3-vite'
import '../src/tokens.css'
const preview: Preview = {}
export default preview
La siguiente story renderiza todas las variantes una junto a otra y mantiene size editable a través de Controls. Utiliza el patrón tipado con Meta y 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>`,
}),
}
Empaqueta el sistema de diseño de Vue con el modo librería de Vite
El modo librería de Vite compila src/index.ts en un bundle distribuible en lugar de en una aplicación. El punto de entrada importa los tokens, de modo que acaben en la hoja de estilos generada, y después reexporta los componentes:
// src/index.ts
import './tokens.css'
export { default as DsButton } from './components/DsButton.vue'
export { default as DsInput } from './components/DsInput.vue'
El ejemplo de la documentación de Vite omite @vitejs/plugin-vue, pero una librería de Vue lo necesita para compilar los archivos .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 utiliza build.rolldownOptions. El antiguo build.rollupOptions es un alias obsoleto de esta opción. Marca vue como external para que el paquete use la copia de Vue de la aplicación consumidora en lugar de incluir la suya propia; tener dos copias de Vue en una misma página rompe la reactividad y las instancias de los componentes. Vite genera todo el CSS de la librería en una única hoja de estilos. Sin cssFileName, ese archivo toma su nombre de fileName, así que aquí cssFileName: 'style' genera dist/style.css.
Usa la estructura de package.json que recomienda Vite. Declara vue como peer dependency, lo que le indica a npm que la aplicación anfitriona lo proporciona:
{
"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" }
}
Ejecuta npx vite build, revisa dist/ y asegúrate de que cada ruta de exports corresponde a un archivo realmente generado.
Instálalo en otra aplicación
Instala el paquete desde un workspace o una ruta local. Importa el CSS una sola vez en el punto de entrada de la aplicación y después importa los componentes allí donde los necesites:
npm install ../design-system
Una instalación desde una ruta local crea un enlace simbólico. En ese caso, el import 'vue' del bundle puede resolverse a la copia de design-system/node_modules, instalada allí para la compilación y para Storybook, y la página termina con dos copias de Vue. Para evitarlo, indica en la configuración de Vite de la aplicación consumidora que resuelva vue desde la raíz de su propio proyecto:
// 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, ejecuta npm pack en el sistema de diseño e instala el tarball resultante, que contiene únicamente los archivos indicados en 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>
Mantenlo pequeño
Cada componente que añades a un sistema de diseño compartido en Vue es una API más con la que todas las aplicaciones deben mantener la compatibilidad. Empieza con los tokens, un botón y un input. Añade un componente al paquete compartido solo cuando al menos dos aplicaciones lo necesiten; todo lo demás debe quedarse en la aplicación que lo usa. Tu siguiente paso es instalar el paquete en tu segunda aplicación, sustituir el botón hecho a mano de esa aplicación por DsButton y eliminar sus valores de color fijos en favor de los tokens --ds-.
Preguntas frecuentes
¿Por qué obtengo dos copias de Vue después de instalar el sistema de diseño desde una ruta local?
Una instalación desde una ruta local o un workspace crea un enlace simbólico, por lo que el import de vue del bundle puede resolverse a la copia que hay en el propio node_modules de la carpeta del sistema de diseño. Añade resolve.dedupe con vue a la configuración de Vite de la aplicación consumidora, lo que obliga a Vite a resolver las dependencias indicadas a la copia de la raíz del proyecto. Como alternativa, ejecuta npm pack e instala el tarball, que solo contiene los archivos indicados en files.
¿Genera el modo librería de Vite archivos de declaración de TypeScript para los componentes de Vue?
No. Vite solo transpila TypeScript y no genera archivos .d.ts, por lo que, por defecto, los consumidores no obtienen los tipos de las props. Ejecuta vue-tsc --declaration --emitDeclarationOnly después de vite build, ya que vue-tsc entiende los archivos .vue y tsc no. Ejecútalo después de la compilación porque vite build vacía el directorio de salida por defecto. El plugin vite-plugin-dts es una alternativa que se ejecuta dentro de la compilación de Vite.
¿Los design tokens deben ser variables de Sass o propiedades personalizadas de CSS?
Usa propiedades personalizadas de CSS para cualquier token que cambie según el tema. Las variables de Sass se compilan a valores fijos en tiempo de compilación y no existen en el navegador, por lo que un selector data-theme o una media query prefers-color-scheme no pueden redefinirlas. Las propiedades personalizadas se resuelven en tiempo de ejecución y se heredan a través del DOM. Sass puede seguir generando las declaraciones de propiedades personalizadas si el equipo prefiere definir los tokens en Sass.
Si una aplicación importa solo DsButton, ¿sigue cargando el CSS de todos los componentes?
Sí. El modo librería de Vite genera una única hoja de estilos para toda la librería, por lo que importar style.css carga los tokens y los estilos de todos los componentes, independientemente de cuáles use realmente la aplicación. En la parte de JavaScript es distinto: la compilación como módulo ES reexporta cada componente por su nombre, de modo que el bundler de la aplicación consumidora puede aplicar tree-shaking a los componentes que nunca importa. Con un conjunto reducido de componentes, la hoja de estilos compartida tiene un coste mínimo.
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