Vueでデザインシステムを構築する
共有CSSトークン、ボタンと入力コンポーネント、ダークテーマ、Storybookのドキュメントを備えたVueデザインシステムを作り、Viteで複数アプリ向けにパッケージ化します。
最小構成のVueデザインシステムは、デザイントークンのスタイルシートと少数の<script setup>コンポーネントを含む、1つのnpmパッケージです。ドキュメントはStorybookで作成し、バンドルにはViteのライブラリモードを使います。
複数のVueアプリに携わっていれば、次のような状況に遭遇したことがあるでしょう。あるアプリのプライマリボタンは#2563eb、別のアプリでは#3b82f6、さらに3つ目のアプリでは誰かが目分量で決めたpadding: 10px 14pxが使われている。こうした差異は時間とともに積み重なり、アプリごとに個別に修正しても根本的な解決にはなりません。
このチュートリアルでは、共有パッケージを1つ構築し、それをすべてのアプリにインストールします。まずトークンを定義し、2つのコンポーネントとダークテーマを追加し、Storybookでドキュメント化したうえで、ライブラリとして公開します。デザインシステムがなぜ重要なのか背景を知りたい場合は、フロントエンド開発のためのデザインシステムを参照してください。コードはVue 3.4以降、Vite 8、Storybook 10を対象としています。
前提条件: Composition APIと<script setup>を使いこなせることを前提とします。不安がある場合は、Vue 3の基礎から始めてください。
重要なポイント
- デザイントークンは
:root上のCSSカスタムプロパティとして定義します。これにより、すべてのアプリのすべてのコンポーネントが、実行時に同じカラー、スペーシング、タイポグラフィの値を参照できます。 variantプロパティとsizeプロパティを1つずつ持つボタンは、複数のbooleanプロパティを持つボタンとは異なり、矛盾したスタイルを表現できません。- Vue 3.4以降、カスタム入力で
v-modelをサポートするにはdefineModel()を使うのが推奨される方法です。 - Viteのライブラリモードでは、
vueをexternalに指定し、パッケージ自体にVueをバンドルせず、利用側アプリのVueを使うようにします。 - Viteはライブラリ のCSSを単一のファイルとして出力するので、パッケージの
exportsマップを通じて公開します。
ゴール:すべてのVueアプリがインストールする1つのパッケージ
完成したパッケージには、style.css(トークンとコンポーネントのスタイル)、コンポーネント本体、そしてそれらのコンポーネントをエクスポートするJavaScriptのエントリーポイントの3つが含まれます。プロジェクトの構成は次のとおりです。
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に、:root上で宣言したCSSカスタムプロパティとして記述します。カスタムプロパティは継承され、実行時に解決されます。つまり、すべてのアプリのすべてのコンポーネントが同じ値を参照し、1か所でトークンを再定義すれば、その変更がすべてに反映されます。名前には--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プロパティを1つずつ持たせ、それぞれをCSSクラスにマッピングします。スタイルごとにbooleanプロパティを追加するのは避けてください。booleanを使うと、呼び出し側で<Button primary danger>と書けてしまい、APIにはそれを防ぐ手段がありません。
<!-- Before: conflicting states are expressible -->
<Button primary danger small>Delete</Button>
型付きのユニオン型プロパティなら、各軸で指定できる値はちょうど1つです。
<!-- 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>をレンダリングするため、キーボード操作やフォームの挙動はブラウザが処理します。デフォルトスロットにはテキストやアイコンを渡せます。スタイルはトークンのみを参照しており、16進数のカラー値は一切含まれていません。Storybookはプロパティに付けたJSDocコメントを読み取り、Docsパネルに表示します。
defineModel()、ラベル、属性のパススルーを備えた入力コンポーネント
Vue 3.4以降、defineModel()がコンポーネントでv-modelをサポートするための推奨される方法です。defineModel()は親のmodelValueと同期したrefを返し、子がその値を変更するたびにupdate:modelValueをemitします。デフォルト値は設定しないでください。親から値が渡されない状態でデフォルト値を設定すると、親と子の同期が取れなくなると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>の内側に配置すると、入力要素にアクセシブルな名前が付与されるため、コンポーネントにidプロパティを用意する必要がありません。ただし、ルート要素は<label>なので、デフォルトではplaceholder、type、nameなどの属性がラベル側に付与されてしまいます。defineOptionsでinheritAttrs: falseを設定するとこの挙動が無効になり、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;
}
}
メディアクエリはOSの設定に従います。:not([data-theme="light"])のガードにより、明示的にライトモードを選択したユーザーの意思が尊重されます。アプリからテーマを設定するには、次の1行で済みます。
document.documentElement.dataset.theme = 'dark'
Vue向けStorybook
Storybookはデザインシステムの各コンポーネントを独立した状態でレンダリングするため、アプリを起動しなくてもすべてのバリアントを確認できます。ストーリーがどのように生きたドキュメントになるかについては、StorybookによるUIドキュメントを参照してください。プロジェクトのルートで初期化します。
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>`,
}),
}
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を使うようにします。1つのページにVueが2つ存在すると、リアクティビティやコンポーネントインスタンスが正しく機能しなくなります。Viteはライブラリのすべての CSSを1つのスタイルシートとして出力します。cssFileNameを指定しない場合、そのファイル名はfileNameから決まるため、ここではcssFileName: 'style'を指定してdist/style.cssを生成しています。
package.jsonはViteが推奨する構成にします。vueはpeer dependencyとして記載し、ホスト側のアプリがVueを提供することを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に記載したすべてのパスが実際に出力されたファイルと一致していることを確かめてください。
別のアプリにインストールする
パッケージはワークスペースまたはローカルパスからインストールします。アプリのエントリーポイントでCSSを一度だけインポートし、コンポーネントは必要な箇所でインポートします。
npm install ../design-system
ローカルパスでのインストールはシンボリックリンクになります。そのため、バンドル内のimport 'vue'が、ビルドやStorybook用にインストールされたdesign-system/node_modules内のVueに解決されてしまい、ページ上にVueが2つ存在する状態になる可能性があります。これを防ぐには、利用側アプリの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を実行し、生成されたtarballをインストールすることもできます。tarballには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デザインシステムにコンポーネントを1つ追加するたびに、すべてのアプリが互換性を維持しなければならないAPIが1つ増えます。まずはトークン、ボタン、入力コンポーネントから始めましょう。共有パッケージにコンポーネントを追加するのは、少なくとも2つのアプリで必要になったときだけにし、それ以外は使用するアプリ内にとどめておきます。次のステップとして、2つ目のアプリにパッケージをインストールし、そのアプリで独自に実装されているボタンをDsButtonに置き換え、ハードコードされたカラー値を--ds-トークンに置き換えてください。
よくある質問
ローカルパスからデザインシステムをインストールすると、Vueが2つ存在してしまうのはなぜですか?
ローカルパスやワークスペースからのインストールではシンボリックリンクが作成されるため、バンドル内のvueのインポートが、design-systemフォルダ自身のnode_modules内のVueに解決されることがあります。利用側アプリのVite設定にvueを指定したresolve.dedupeを追加すると、記載された依存関係はプロジェクトルートにあるものに強制的に解決されます。別の方法として、npm packを実行してtarballをインストールすることもできます。tarballにはfilesに記載したファイルのみが含まれます。
Viteのライブラリモードは、VueコンポーネントのTypeScript型定義ファイルを生成しますか?
いいえ。ViteはTypeScriptのトランスパイルのみを行い、.d.tsファイルは出力しないため、デフォルトでは利用側でプロパティの型を得られません。vite buildの後にvue-tsc --declaration --emitDeclarationOnlyを実行してください。vue-tscは.vueファイルを理解できますが、通常のtscは理解できません。vite buildはデフォルトで出力ディレクトリを空にするため、必ずビルドの後に実行してください。Viteのビルド内で動作するvite-plugin-dtsプラグインを代わりに使うこともできます。
デザイントークンはSass変数とCSSカスタムプロパティのどちらにすべきですか?
テーマによって変化するトークンには、CSSカスタムプロパティを使用してください。Sass変数はビルド時に固定値へコンパイルされ、ブラウザ上には存在しないため、data-themeセレクタやprefers-color-schemeメディアクエリで再定義することができません。カスタムプロパティは実行時に解決され、DOMを通じて継承されます。チームがSassでトークンを記述したい場合は、Sassを使ってカスタムプロパティの宣言を生成することも可能です。
アプリがDsButtonだけをインポートした場合でも、すべてのコンポーネントのCSSが読み込まれますか?
はい。Viteのライブラリモードはライブラリ全体で1つのスタイルシートを出力するため、style.cssをインポートすると、アプリが実際にどのコンポーネントを使っているかにかかわらず、トークンとすべてのコンポーネントのスタイルが読み込まれます。JavaScript側は異なります。ESモジュールのビルドでは各コンポーネントが名前付きで再エクスポートされるため、利用側アプリのバンドラーはインポートされていないコンポーネントをツリーシェイキングで除外できます。コンポーネント数が少なければ、共有スタイルシートによるコストはわずかです。
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