12k
All articles

Construire un design system avec Vue

Créez un design system Vue avec des variables CSS partagées, des composants bouton et champ, un thème sombre, Storybook et Vite pour plusieurs applications.

OpenReplay Team
OpenReplay Team
Construire un design system avec Vue

Un design system Vue minimal se résume à un seul package npm contenant une feuille de style de design tokens et un petit ensemble de composants <script setup>. On le documente dans Storybook et on le package avec le mode bibliothèque de Vite.

Si vous travaillez sur plusieurs applications Vue, vous avez probablement déjà constaté ce phénomène : le bouton principal d’une application est en #2563eb, celui d’une autre en #3b82f6, et une troisième utilise padding: 10px 14px parce que quelqu’un l’a réglé à l’œil. Ces écarts s’accumulent avec le temps, et les corriger application par application n’empêche pas qu’ils réapparaissent.

Ce tutoriel construit un package partagé unique, installé dans chaque application. Vous commencerez par les tokens, ajouterez deux composants et un thème sombre, les documenterez dans Storybook, puis publierez le résultat sous forme de bibliothèque. Pour comprendre pourquoi les design systems sont importants, lisez design systems for front-end development. Le code cible Vue 3.4+, Vite 8 et Storybook 10.

Prérequis : vous devez être à l’aise avec la Composition API et <script setup>. Si ce n’est pas le cas, commencez par les fondamentaux de Vue 3.

Points clés

  • Définissez les design tokens sous forme de propriétés personnalisées CSS sur :root, afin que chaque composant de chaque application lise les mêmes valeurs de couleur, d’espacement et de typographie à l’exécution.
  • Un bouton doté d’une seule prop variant et d’une seule prop size ne peut pas exprimer de styles contradictoires, contrairement à un ensemble de props booléennes.
  • Depuis Vue 3.4, defineModel() est la méthode recommandée pour prendre en charge v-model sur un champ de saisie personnalisé.
  • En mode bibliothèque de Vite, déclarez vue comme dépendance externe afin que le package utilise l’instance de Vue de l’application consommatrice au lieu d’embarquer la sienne.
  • Vite génère le CSS d’une bibliothèque dans un fichier unique, que vous exposez via la map exports du package.

L’objectif : un seul package installé par chaque application Vue

Le package final fournit trois éléments : style.css (tokens et styles des composants), les composants eux-mêmes et un point d’entrée JavaScript qui exporte ces composants. Voici l’arborescence du projet :

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

Des design tokens sous forme de propriétés personnalisées CSS

Placez vos design tokens dans src/tokens.css sous forme de propriétés personnalisées CSS déclarées sur :root. Les propriétés personnalisées sont héritées et résolues à l’exécution. Ainsi, chaque composant de chaque application lit les mêmes valeurs, et redéfinir un token à un seul endroit le modifie partout. Préfixez les noms par --ds- afin d’éviter toute collision avec des variables déjà définies par les applications consommatrices.

/* 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 bouton avec des props variant et size

Le bouton d’un design system doit avoir une seule prop variant et une seule prop size, chacune associée à une classe CSS. N’ajoutez pas une prop booléenne pour chaque style. Avec des booléens, un appelant peut écrire <Button primary danger>, et rien dans l’API ne l’en empêche :

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

Des props typées en union n’autorisent qu’une seule valeur par axe :

<!-- 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 affiche un <button> natif : le navigateur gère donc le comportement clavier et l’intégration aux formulaires. Le slot par défaut accepte du texte ou des icônes. Les styles ne référencent que des tokens et ne contiennent aucune valeur hexadécimale. Storybook lit les commentaires JSDoc des props et les affiche dans le panneau de documentation.

Un champ de saisie avec defineModel(), un label et la transmission des attributs

Depuis Vue 3.4, defineModel() est la méthode recommandée pour prendre en charge v-model sur un composant. Elle renvoie une ref synchronisée avec la modelValue du parent et émet update:modelValue chaque fois que l’enfant la modifie. Ne lui attribuez pas de valeur par défaut : la documentation de Vue avertit qu’une valeur par défaut, en l’absence de valeur transmise par le parent, désynchronise le parent et l’enfant.

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

Imbriquer l’<input> dans son <label> fournit au champ un nom accessible, si bien que le composant n’a pas besoin d’une prop id. Toutefois, l’élément racine étant le <label>, des attributs tels que placeholder, type ou name atterriraient par défaut sur le label. Définir inheritAttrs: false via defineOptions désactive ce comportement, et v-bind="$attrs" transmet ces attributs à l’<input>. Avec cette configuration, class et style sont également appliqués au champ plutôt qu’au label.

Thèmes clair et sombre à partir des mêmes tokens

Un design system Vue n’a pas besoin de nouveaux composants pour le mode sombre. Redéfinissez les mêmes propriétés personnalisées sous un sélecteur [data-theme="dark"] et dans une media query prefers-color-scheme: dark : tous les composants qui les lisent basculent automatiquement. Ajoutez ceci à 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 suit le réglage du système d’exploitation. La garde :not([data-theme="light"]) respecte le choix d’un utilisateur qui opte explicitement pour le mode clair. Pour définir un thème depuis l’application, une seule ligne suffit :

document.documentElement.dataset.theme = 'dark'

Storybook pour Vue

Storybook affiche chaque composant du design system de manière isolée, ce qui permet de passer en revue toutes les variantes sans lancer d’application. Pour comprendre comment les stories deviennent une documentation vivante, consultez Storybook UI documentation. Initialisez-le depuis la racine du projet :

npm create storybook@latest

L’installateur détecte Vite et Vue et configure le framework @storybook/vue3-vite. Depuis Storybook 10.6, le moteur par défaut vue-docgen-api est déprécié, et l’option recommandée est 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

Chargez les tokens globalement. Le guide de stylisation de Storybook recommande d’ajouter le CSS global de toutes vos stories en l’important dans .storybook/preview.ts :

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

const preview: Preview = {}
export default preview

La story suivante affiche toutes les variantes côte à côte et laisse size modifiable via les Controls. Elle utilise le pattern typé Meta et 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>`,
  }),
}

Packager le design system Vue avec le mode bibliothèque de Vite

Le mode bibliothèque de Vite compile src/index.ts en un bundle distribuable plutôt qu’en application. Le point d’entrée importe les tokens, afin qu’ils figurent dans la feuille de style générée, puis réexporte les composants :

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

L’exemple de la documentation de Vite omet @vitejs/plugin-vue, mais une bibliothèque Vue en a besoin pour compiler les fichiers .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 utilise build.rolldownOptions. L’ancienne option build.rollupOptions en est un alias déprécié. Déclarez vue comme external afin que le package utilise l’instance de Vue de l’application consommatrice au lieu d’embarquer la sienne : deux copies de Vue sur une même page cassent la réactivité et les instances de composants. Vite génère tout le CSS de la bibliothèque dans une seule feuille de style. Sans cssFileName, ce fichier prend son nom de fileName ; ici, cssFileName: 'style' produit donc dist/style.css.

Utilisez la structure de package.json recommandée par Vite. Déclarez vue comme peer dependency, ce qui indique à npm que l’application hôte la fournit :

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

Exécutez npx vite build, puis inspectez dist/ et vérifiez que chaque chemin déclaré dans exports correspond bien à un fichier réellement généré.

L’installer dans une autre application

Installez le package depuis un workspace ou un chemin local. Importez le CSS une seule fois dans le point d’entrée de l’application, puis importez les composants là où vous en avez besoin :

npm install ../design-system

Une installation depuis un chemin local crée un lien symbolique. L’import 'vue' du bundle peut alors être résolu vers la copie présente dans design-system/node_modules, installée pour le build et Storybook, et la page se retrouve avec deux copies de Vue. Pour l’éviter, configurez Vite dans l’application consommatrice afin qu’il résolve vue depuis la racine de son propre projet :

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

Autre solution : exécutez npm pack dans le design system et installez l’archive tarball obtenue, qui ne contient que les fichiers listés dans 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>

Restez minimaliste

Chaque composant ajouté à un design system Vue partagé représente une API supplémentaire avec laquelle chaque application doit rester compatible. Commencez par les tokens, un bouton et un champ de saisie. N’ajoutez un composant au package partagé que lorsqu’au moins deux applications en ont besoin ; tout le reste demeure dans l’application qui l’utilise. Prochaine étape : installez le package dans votre deuxième application, remplacez son bouton fait maison par DsButton et supprimez ses valeurs de couleur codées en dur au profit des tokens --ds-.

FAQ

Pourquoi ai-je deux copies de Vue après avoir installé le design system depuis un chemin local ?

Une installation depuis un chemin local ou un workspace crée un lien symbolique : l'import de vue dans le bundle peut donc être résolu vers la copie située dans le node_modules du dossier design-system. Ajoutez resolve.dedupe avec vue dans la configuration Vite de l'application consommatrice, ce qui oblige Vite à résoudre les dépendances listées vers la copie présente à la racine du projet. Vous pouvez aussi exécuter npm pack et installer l'archive tarball, qui ne contient que les fichiers listés dans files.

Le mode bibliothèque de Vite génère-t-il des fichiers de déclaration TypeScript pour les composants Vue ?

Non. Vite se contente de transpiler le TypeScript et ne génère pas de fichiers .d.ts : les consommateurs ne disposent donc d'aucun typage des props par défaut. Exécutez vue-tsc --declaration --emitDeclarationOnly après vite build, car vue-tsc comprend les fichiers .vue, contrairement à tsc. Lancez-le après le build, car vite build vide par défaut le répertoire de sortie. Le plugin vite-plugin-dts constitue une alternative qui s'exécute au sein du build Vite.

Les design tokens doivent-ils être des variables Sass ou des propriétés personnalisées CSS ?

Utilisez des propriétés personnalisées CSS pour tout token modifié par les thèmes. Les variables Sass sont compilées en valeurs figées au moment du build et n'existent pas dans le navigateur : un sélecteur data-theme ou une media query prefers-color-scheme ne peut donc pas les redéfinir. Les propriétés personnalisées sont résolues à l'exécution et héritées à travers le DOM. Sass peut toutefois générer les déclarations de propriétés personnalisées si l'équipe préfère rédiger ses tokens en Sass.

Si une application n'importe que DsButton, charge-t-elle quand même le CSS de tous les composants ?

Oui. Le mode bibliothèque de Vite génère une seule feuille de style pour toute la bibliothèque : importer style.css charge donc les tokens et les styles de tous les composants, quels que soient ceux que l'application utilise réellement. Côté JavaScript, c'est différent : le build en module ES réexporte chaque composant par son nom, si bien que le bundler de l'application consommatrice peut éliminer par tree-shaking les composants qu'elle n'importe jamais. Avec un petit nombre de composants, la feuille de style partagée a un coût négligeable.

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.