AI × Stencil.jsで進めるデザインシステム実装ガイド ― Tokens Studio から Web Components へつなぐ

AIとStencil.jsを使って初めてデザインシステムを作ったので、そのガイドを前編と後編でまとめました。

前編では、デザインシステムをどんな考え方で設計し、Figmaのデザイン情報をどうコードへ落とし込んでいくかを整理します。
まずは、トークンとコンポーネントの関係、Stencil.jsを選ぶ理由、そして実際に手を動かし始めるまでの流れを見ていきます。

この記事をIDEに読み込ませるコンテキストとして使うのもおすすめです。

このような方に読んでもらいたい

デザインシステムをこれから作ろうとしているエンジニア
Figma → Tokens → Code の流れがよく分からない人
Web Components / Stencil.js を使った設計に興味がある人
AIを使ったコンポーネント実装のワークフローを知りたい人

使用技術

Stencil.js — ネイティブWeb Componentsを作るためのコンパイラ
Tokens Studio — デザイントークンの管理・エクスポート用Figmaプラグイン（2026年時点で無料版で十分）
Style Dictionary — エクスポートしたトークンをCSS変数などの形式に変換
Cursor — AI駆動のIDE

なぜコンポーネント？なぜトークン？（DNA＋臓器で考える）

セットアップに入る前に、デザインシステムの基本モデルをおさらいしましょう。

デザイントークンはシステムの基本的な性質を定義するため、システムの「DNA」と捉えることができます。
色、スペーシング、タイポグラフィ、角丸、シャドウといった見た目のルールを、再利用可能な値として定義しておくことで、UI 全体の一貫性を保ちやすくなります。

トークンの例：

--color-primary: #e60012;
--spacing-m: 16px;
--radius-s: 4px;

コンポーネントは、その「DNA」から作られる「臓器」と言えます。

たとえば、ボタンのスタイルを直接 CSS に書くのではなく、トークンを参照する形にしておけば、トークン側を更新するだけで複数のコンポーネントに変更を反映できます。

つまり、コンポーネントを増やす前にトークンを整理しておくことが、あとから効いてくる設計になります。

.button {
  background: var(--color-primary);
  padding: var(--spacing-m);
  border-radius: var(--radius-s);
}

この形にしておくと、「DNA（tokens.css）」を一度変えるだけで、すべての「臓器」を自動的に更新することができます。

Stencil.jsとは？

Stencilは、ネイティブWeb標準に基づいてWeb Componentsを作るためのコンパイラです。出力されるのはReactでもVueでもAngularでもありません。ただのネイティブWeb Componentsなので、従来のHTMLサイトも含めてさまざまな環境で利用することができます。

どの環境で使える？

StencilはWeb Components標準を出力するので、デザインシステムを次のような環境で使えます：

React
Vue
Angular
Next.js
素のHTML

たとえば、StencilのReactラッパーを生成すれば、Reactチームはこう書くことができます：

<MyButton variant="primary" />

ラッパーを使わない場合や、素のHTMLサイトでは以下のように使えます：

<my-button variant="primary"></my-button>

同じコンポーネント、同じデザインルールですが、異なる環境で再利用しやすいのが特徴です。

この特性は、デザインシステムを「特定のフレームワークの資産」ではなく、複数のフロントエンドで共有できる基盤として扱いたいときに相性がよいと感じました。

1つのロジックとデザインルールを、違うスタックの上でも使い回せるのは大きな利点です。

Stencilワークスペースのセットアップ

1．Stencil CLIで新規プロジェクトを作成：

npm init stencil

2．プロンプトで component スターターを選び、依存関係をインストール：

npm install

3．コンポーネントを生成：

npm run generate

Stencilが以下のファイルを生成します：

.tsx
.css（@stencil/sass プラグインを入れていれば .scss）

テストファイル（.spec.ts と .e2e.ts）

そのあと：

.tsx とスタイルファイルを実装する（スタイルにはデザイントークンを使うこと）
コンポーネントを参照するシンプルなHTMLページを作って、npm start でローカルプレビュー

さらに一歩進めたい場合は、Storybookを導入するのもありです。コンポーネントを個別に開発・ドキュメント化・テストするためのスタンドアロンUIツールで、手書きHTMLプレビューページの代わりになります。この記事では、シンプルな HTMLデモページ を使っています。

スターターが動いたら、次はプロジェクトの構成を決めること。トークン、コンポーネント、デモ、ビルド出力が、それぞれ明確な場所に収まるようにします。

Storybookについては他の記事でも解説をしています。併せてご覧ください。

https://tech.i3design.jp/tag/storybook

デザインシステムのプロジェクト構成例

sample-design-system/
├── src/
│   ├── components/
│   │   ├── my-button/
│   │   │   ├── my-button.tsx        （コンポーネントのロジック＋render関数）
│   │   │   ├── my-button.css       （コンポーネントスタイル — トークン必須）
│   │   │   ├── my-button.spec.ts   （ユニット/specテスト — レンダリング、props、stateの検証）
│   │   │   └── readme.md            （Stencilが自動生成するドキュメント）
│   │   └── ...その他のコンポーネント
│   │
│   ├── tokens/
│   │   └── tokens.css        （自動生成: コンポーネントが使うCSS変数）
│   │
│   ├── assets/
│   │   └── icons/
│   │
│   └── global/
│       ├── reset.css
│       └── global.css
│
├── tokens/
│   ├── token-studio/         （FigmaのTokens Studioエクスポートをここに置く）
│   │   └── ...トークンJSONファイル
│   │
│   └── style-dictionary/     （トークン変換時に使うビルドファイル）
│       └── all-tokens.json
│
├── examples/                 （srcの外 — 本番利用をシミュレートするため実際のdist出力を参照）
│   ├── component-demos/              （各コンポーネントのデモページ — dist/からCSS/JSを読み込む）
│   │   ├── my-button.html
│   │   └── ...その他のデモ
│   └── sample-page.html      （複数のビルド済みコンポーネントを組み合わせたサンプルページ）
│
├── dist/                     （本番ビルド出力 — 利用側プロジェクトがコピーするもの）
│   └── my-design-system/
│       ├── my-design-system.css     （コンパイル済みスタイル＋トークン）
│       ├── my-design-system.esm.js  （カスタム要素を登録するESモジュール）
│       └── assets/
│           └── icons/
│
├── www/                      （Stencil開発サーバーのルート — ローカル開発プレビュー専用）
│
├── scripts/
│   ├── token-studio-parser.js                  （Tokens Studioエクスポート → Style Dictionary形式に変換）
│   ├── style-dictionary-css-variables-fixed.js （オプション: 生成されたトークン出力のフォーマット修正）
│   └── token-build.js                          （トークンパイプライン全体を実行: 読込 → 変換 → src/tokens/*に書出）
│
├── stencil.config.ts
└── style-dictionary.config.js

この構成は自分のデザインシステムで採用したやり方です。あくまで一例であり、唯一の正解ではありません。

いちばん実運用に近いプレビュー方法

この構成で実運用に近いプレビューは、デザインシステムをビルドして（dist/ を更新して）、シンプルな静的サーバーで出力を確認する方法です：

npm run build
npx http-server . -p 8080

examples/ のページが dist/ から実際にコンパイルされたCSS/JSを読み込むので、実際の利用者に最も近い体験になります。

開発中にもっと速いフィードバックループが欲しい場合は、Stencilの組み込み開発サーバーを使うこともできます。
npm start を実行して src/index.html をシンプルなデモページとして使います。プレビュー用のマークアップは自分で書きますが、Stencilが作業中にリビルドとサーブを自動でやってくれます。

Figmaからコードへデザイントークンを取り込む

プロジェクト構成が決まったら、次はトークンパイプラインです。デザインの値がすでにコードに存在していれば、コンポーネントを正しく作りやすくなります。

自分はFigmaの Tokens Studio を使ってデザイントークンを管理しています。無料版でもエクスポートは十分行えるので、最初の導入ハードルはそこまで高くありません（2026年時点）。

初回トークンセットアップ

トークンをコードで使う前に、コードベースが消費できる形式（CSS変数やSCSSなど）に変換する必要があります。このプロジェクトでは、Style Dictionary がその変換を担当します。

ここでは、ひとつ前の Stencil ワークスペースのセットアップを終えた同じプロジェクトをそのまま使います。つまり、npm install はすでに実行済みの前提です。style-dictionary がまだ入っていない場合だけ追加します。

1．style-dictionary が未導入なら、開発依存に追加：

npm install -D style-dictionary

2．Tokens Studioから Multiple files 形式でトークンをエクスポート。

3．エクスポートしたファイルを以下に配置：

tokens/token-studio/

4．トークンをビルド：

npm run build-tokens

このリポジトリでは、npm run build-tokens がTokens StudioのJSONを読み込み、パーサーに通して、使えるトークンファイルを src/tokens/ に出力します。

トークンビルドの仕組み

このプロジェクトではStyle Dictionaryの上にカスタムトークンパイプラインを構築しています：

scripts/token-studio-parser.js が Tokens StudioのJSONをStyle Dictionaryが理解できる形に変換
scripts/style-dictionary-css-variables-fixed.js が CSS/SCSS出力をフォーマット修正して、デザインシステムで使えるようにする

必要なファイルが正しいフォルダに入っていれば、ビルドコマンドで変換まで完了します。手動の再フォーマットは不要です。