12k
All articles

Ein Design-System in Vue aufbauen

Erstellen Sie ein Vue-Designsystem mit gemeinsamen CSS-Tokens, Button- und Eingabekomponenten, Dark Mode, Storybook-Doku und Vite-Bibliotheksbuild für mehrere Apps.

OpenReplay Team
OpenReplay Team
Ein Design-System in Vue aufbauen

Ein minimales Vue-Design-System ist ein einzelnes npm-Paket, das ein Stylesheet mit Design Tokens und eine kleine Auswahl an <script setup>-Komponenten enthält. Dokumentiert wird es in Storybook, gebündelt mit dem Library-Modus von Vite.

Wenn Sie mit mehr als einer Vue-App arbeiten, kennen Sie das wahrscheinlich: Der primäre Button der einen App ist #2563eb, der einer anderen #3b82f6, und eine dritte App verwendet padding: 10px 14px, weil jemand den Wert nach Augenmaß festgelegt hat. Diese Abweichungen häufen sich mit der Zeit an, und wenn Sie jede App einzeln korrigieren, verhindert das keine neuen.

In diesem Tutorial erstellen Sie ein gemeinsames Paket und installieren es in jeder App. Sie beginnen mit Tokens, fügen zwei Komponenten und ein Dark Theme hinzu, dokumentieren alles in Storybook und veröffentlichen das Ergebnis als Library. Hintergrundwissen dazu, warum Design-Systeme wichtig sind, finden Sie unter Design-Systeme für die Frontend-Entwicklung. Der Code richtet sich an Vue 3.4+, Vite 8 und Storybook 10.

Voraussetzungen: Sie sollten mit der Composition API und <script setup> vertraut sein. Falls nicht, beginnen Sie mit den Grundlagen von Vue 3.

Die wichtigsten Erkenntnisse

  • Definieren Sie Design Tokens als CSS Custom Properties auf :root, damit jede Komponente in jeder App zur Laufzeit dieselben Werte für Farben, Abstände und Typografie ausliest.
  • Ein Button mit einem variant-Prop und einem size-Prop kann keine widersprüchlichen Stile abbilden, wie es bei einer Reihe boolescher Props möglich ist.
  • Seit Vue 3.4 ist defineModel() der empfohlene Weg, v-model in einem eigenen Input zu unterstützen.
  • Markieren Sie im Library-Modus von Vite vue als extern, damit das Paket die Vue-Instanz der konsumierenden App verwendet, statt eine eigene mitzubündeln.
  • Vite gibt das CSS einer Library als einzelne Datei aus, die Sie über die exports-Map des Pakets bereitstellen.

Das Ziel: Ein Paket, das jede Vue-App installiert

Das fertige Paket liefert drei Dinge aus: style.css (Tokens plus Komponenten-Styles), die Komponenten selbst und einen JavaScript-Einstiegspunkt, der diese Komponenten exportiert. So sieht die Projektstruktur aus:

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 als CSS Custom Properties

Legen Sie Ihre Design Tokens in src/tokens.css als CSS Custom Properties ab, die auf :root deklariert werden. Custom Properties werden vererbt und zur Laufzeit aufgelöst. Dadurch liest jede Komponente in jeder App dieselben Werte aus, und wenn Sie einen Token an einer Stelle neu definieren, ändert er sich überall. Versehen Sie die Namen mit dem Präfix --ds-, damit sie nicht mit Variablen kollidieren, die die konsumierenden Apps bereits definieren.

/* 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;
}

Ein Button mit Variant- und Size-Props

Ein Button in einem Design-System sollte genau einen variant-Prop und einen size-Prop haben, die jeweils auf eine CSS-Klasse abgebildet werden. Fügen Sie nicht für jeden Stil einen booleschen Prop hinzu. Mit booleschen Props kann ein Aufrufer <Button primary danger> schreiben, und nichts in der API verhindert das:

<!-- Before: conflicting states are expressible -->
<Button primary danger small>Delete</Button>

Typisierte Union-Props erlauben genau einen Wert pro Dimension:

<!-- 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 rendert ein natives <button>-Element, sodass der Browser Tastatur- und Formularverhalten übernimmt. Der Default-Slot nimmt Text oder Icons auf. Die Styles referenzieren ausschließlich Tokens und enthalten keine Hex-Werte. Storybook liest die JSDoc-Kommentare an den Props aus und zeigt sie im Docs-Panel an.

Ein Input mit defineModel(), Label und Attribut-Durchreichung

Seit Vue 3.4 ist defineModel() der empfohlene Weg, v-model in einer Komponente zu unterstützen. Es gibt ein Ref zurück, das mit dem modelValue der Elternkomponente synchron bleibt und update:modelValue emittiert, sobald die Kindkomponente den Wert ändert. Geben Sie ihm keinen Default-Wert. Die Vue-Dokumentation warnt, dass ein Default-Wert ohne übergebenen Wert der Elternkomponente dazu führt, dass Eltern- und Kindkomponente nicht mehr synchron sind.

<!-- 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>

Indem Sie das <input> in sein <label> einbetten, erhält das Input einen zugänglichen Namen (Accessible Name), und die Komponente benötigt keinen id-Prop. Das Root-Element ist allerdings das <label>, sodass Attribute wie placeholder, type und name standardmäßig auf dem Label landen würden. Wenn Sie inheritAttrs: false über defineOptions setzen, wird dieses Verhalten deaktiviert, und v-bind="$attrs" leitet diese Attribute an das <input> weiter. Mit diesem Setup gehen auch class und style an das Input statt an das Label.

Light und Dark Theme aus denselben Tokens

Ein Vue-Design-System braucht für den Dark Mode keine neuen Komponenten. Definieren Sie dieselben Custom Properties unter einem [data-theme="dark"]-Selektor und innerhalb einer prefers-color-scheme: dark-Media-Query neu, und jede Komponente, die sie ausliest, wechselt automatisch. Ergänzen Sie tokens.css um Folgendes:

[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;
  }
}

Die Media-Query folgt der Einstellung des Betriebssystems. Die Bedingung :not([data-theme="light"]) respektiert Nutzer, die explizit den Light Mode wählen. Um ein Theme aus der App heraus zu setzen, genügt eine Zeile:

document.documentElement.dataset.theme = 'dark'

Storybook für Vue

Storybook rendert jede Komponente des Design-Systems isoliert, sodass Sie alle Varianten prüfen können, ohne eine App zu starten. Hintergrundinformationen dazu, wie aus Stories eine lebendige Dokumentation wird, finden Sie unter UI-Dokumentation mit Storybook. Initialisieren Sie Storybook im Projektstammverzeichnis:

npm create storybook@latest

Der Installer erkennt Vite und Vue und konfiguriert das @storybook/vue3-vite-Framework. Seit Storybook 10.6 ist die Standard-Engine vue-docgen-api als veraltet (deprecated) markiert; empfohlen wird stattdessen 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

Laden Sie die Tokens global. Laut dem Styling-Leitfaden von Storybook fügen Sie globales CSS für alle Stories hinzu, indem Sie es in .storybook/preview.ts importieren:

// .storybook/preview.ts
import type { Preview } from '@storybook/vue3-vite'
import '../src/tokens.css'

const preview: Preview = {}
export default preview

Die folgende Story rendert alle Varianten nebeneinander und hält size über die Controls editierbar. Sie verwendet das typisierte Meta- und StoryObj-Muster:

// 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>`,
  }),
}

Das Vue-Design-System mit dem Library-Modus von Vite paketieren

Der Library-Modus von Vite baut src/index.ts zu einem verteilbaren Bundle statt zu einer App. Der Einstiegspunkt importiert die Tokens, damit sie im ausgegebenen Stylesheet landen, und re-exportiert anschließend die Komponenten:

// src/index.ts
import './tokens.css'
export { default as DsButton } from './components/DsButton.vue'
export { default as DsInput } from './components/DsInput.vue'

Das Beispiel in der Vite-Dokumentation lässt @vitejs/plugin-vue weg, eine Vue-Library benötigt es jedoch, um .vue-Dateien zu kompilieren:

// 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 verwendet build.rolldownOptions. Das ältere build.rollupOptions ist ein veralteter Alias dafür. Markieren Sie vue als external, damit das Paket die Vue-Instanz der konsumierenden App verwendet, statt eine eigene mitzubündeln – zwei Vue-Kopien auf einer Seite zerstören die Reaktivität und die Komponenteninstanzen. Vite gibt das gesamte CSS der Library als ein einziges Stylesheet aus. Ohne cssFileName übernimmt diese Datei ihren Namen von fileName; hier erzeugt cssFileName: 'style' daher dist/style.css.

Verwenden Sie die von Vite empfohlene Struktur für die package.json. Führen Sie vue als Peer Dependency auf, womit Sie npm mitteilen, dass die Host-App es bereitstellt:

{
  "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" }
}

Führen Sie npx vite build aus, prüfen Sie anschließend dist/ und stellen Sie sicher, dass jeder Pfad in exports auf eine tatsächlich erzeugte Datei verweist.

Installation in einer anderen App

Installieren Sie das Paket aus einem Workspace oder über einen lokalen Pfad. Importieren Sie das CSS einmalig im Einstiegspunkt der App und importieren Sie die Komponenten dann dort, wo Sie sie benötigen:

npm install ../design-system

Eine Installation über einen lokalen Pfad erzeugt einen Symlink. Das import 'vue' des Bundles kann dann auf die Kopie in design-system/node_modules aufgelöst werden, die dort für den Build und Storybook installiert wurde – und die Seite enthält am Ende zwei Vue-Kopien. Um das zu verhindern, weisen Sie die Vite-Konfiguration der konsumierenden App an, vue aus ihrem eigenen Projektstammverzeichnis aufzulösen:

// 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'] },
})

Alternativ führen Sie im Design-System npm pack aus und installieren das resultierende Tarball, das nur die in files aufgeführten Dateien enthält.

// 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>

Halten Sie es schlank

Jede Komponente, die Sie einem gemeinsamen Vue-Design-System hinzufügen, ist eine weitere API, mit der jede App kompatibel bleiben muss. Beginnen Sie mit Tokens, einem Button und einem Input. Nehmen Sie eine Komponente erst dann in das gemeinsame Paket auf, wenn mindestens zwei Apps sie benötigen; alles andere bleibt in der App, die es verwendet. Ihr nächster Schritt: Installieren Sie das Paket in Ihrer zweiten App, ersetzen Sie deren selbst gebauten Button durch DsButton und entfernen Sie die hartcodierten Farbwerte zugunsten der --ds--Tokens.

FAQs

Warum habe ich nach der Installation des Design-Systems über einen lokalen Pfad zwei Vue-Kopien?

Eine Installation über einen lokalen Pfad oder einen Workspace erzeugt einen Symlink, sodass der Import von vue im Bundle auf die Kopie im eigenen node_modules-Ordner des Design-Systems aufgelöst werden kann. Fügen Sie der Vite-Konfiguration der konsumierenden App resolve.dedupe mit vue hinzu – damit zwingen Sie Vite, die aufgeführten Abhängigkeiten auf die Kopie im Projektstammverzeichnis aufzulösen. Alternativ führen Sie npm pack aus und installieren das Tarball, das nur die in files aufgeführten Dateien enthält.

Erzeugt der Library-Modus von Vite TypeScript-Deklarationsdateien für Vue-Komponenten?

Nein. Vite transpiliert TypeScript lediglich und gibt keine .d.ts-Dateien aus, sodass Konsumenten standardmäßig keine Prop-Typen erhalten. Führen Sie nach vite build den Befehl vue-tsc --declaration --emitDeclarationOnly aus, denn vue-tsc versteht .vue-Dateien, das einfache tsc hingegen nicht. Führen Sie ihn nach dem Build aus, da vite build das Ausgabeverzeichnis standardmäßig leert. Alternativ können Sie das Plugin vite-plugin-dts verwenden, das innerhalb des Vite-Builds läuft.

Sollten Design Tokens Sass-Variablen oder CSS Custom Properties sein?

Verwenden Sie CSS Custom Properties für alle Tokens, die sich durch Themes ändern. Sass-Variablen werden zur Build-Zeit zu festen Werten kompiliert und existieren im Browser nicht, sodass weder ein data-theme-Selektor noch eine prefers-color-scheme-Media-Query sie neu definieren kann. Custom Properties werden zur Laufzeit aufgelöst und über das DOM vererbt. Sass kann die Deklarationen der Custom Properties dennoch erzeugen, falls ein Team Tokens lieber in Sass verfasst.

Wenn eine App nur DsButton importiert, lädt sie dann trotzdem das CSS aller Komponenten?

Ja. Der Library-Modus von Vite gibt ein einziges Stylesheet für die gesamte Library aus, sodass der Import von style.css die Tokens und die Styles aller Komponenten lädt – unabhängig davon, welche Komponenten die App tatsächlich verwendet. Auf der JavaScript-Seite sieht es anders aus: Der ES-Module-Build re-exportiert jede Komponente namentlich, sodass der Bundler der konsumierenden App Komponenten, die nie importiert werden, per Tree-Shaking entfernen kann. Bei einer kleinen Komponentenauswahl fällt das gemeinsame Stylesheet kaum ins Gewicht.

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.