Penpot × Storybook：デザインシステムをコンポーネント単位で双方向同期する実践ガイド
プロダクトの規模が拡大するにつれて、デザイナーとエンジニアの間で「デザインの正解はどこにあるのか」という不毛な同期ズレが起きる。Figmaと閉じたエコシステムに依存する時代は終わりを告げた。今、オープンソースの旗手である Penpot と、フロントエンドのコンポーネント駆動開発（CDD）の要である Storybook を直結させ、真の「シングル・ソース・オブ・トゥルース（Single Source of Truth）」を構築する時が来ている。
本稿では、単なるツールの紹介ではなく、デザインシステムをコンポーネント単位で完全に同期させ、開発速度を劇的に跳ね上げる実践的なワークフローを、テックリードの視点からコードと設定の具体例を交えて解き明かす。
—
1. なぜ「Penpot + Storybook」なのか：オープンソースが生むシナジー
商用クローズドなツールチェーンでは、APIの制限やライセンスコストの壁が常にチームの足枷となる。PenpotはSVGをネイティブデータ構造とし、CSS GridやFlexboxの概念をそのままデザインキャンバスに持ち込んだ、いわば「デザイナーのためのブラウザ・コードエディタ」だ。
一方のStorybookは、UIコンポーネントを孤立した環境で構築・テストするための業界標準である。
この2つを結合させる意義は以下の3点に集約される。
1. メンタルモデルの完全一致: Penpotのレイアウト構造（Flex/Grid）は、そのままCSSのそれに直結する。デザイナーが作ったレイアウトは、エンジニアにとってそのまま意味のあるDOM構造になる。
2. トークンとコンポーネントの完全同期: CSS Variables（デザイン・トークン）を軸に据えることで、デザイン変更が即座にコード側へ波及するパイプラインを作れる。
3. ベンダーロックインからの解放: 完全なオープンフォーマット（SVG、JSON、CSS）ベースであるため、CI/CDパイプラインに組み込みやすい。
—
2. 開発スピードを極限まで高める：Penpotの隠れた神ショートカット
デザインプロセスを高速化し、エンジニアとの共通言語を形成するためには、Penpotの高度なショートカットを体に叩き込む必要がある。
| ショートカット (Mac / Win) | 動作・機能 | テックリード的解説 |
| :— | :— | :— |
| `Shift` + `R` | ルーラー / ガイド表示 | グリッドシステムの厳格な維持に不可欠。 |
| `Alt` + H / V / L | Flexboxコンテナ内の整列 | CSS Flexboxの `justify-content` の挙動を直感的にデザインに落とし込む。 |
| `Ctrl/Cmd` + `Alt` + `K` | コンポーネント化 | 選択要素をマスターコンポーネントへ瞬時に昇格。Storybookの `.stories.tsx` の単位と1:1で対応させる。 |
| `Alt` + ホバー | スペック（寸法・距離）の詳細表示 | デザイナーの意図したマージンがCSSのどプロパティに該当するかを即座に視覚化。 |
—
3. ワークフロー構築：PenpotからStorybookへのデータ同期パイプライン
デザインの変更をエンジニアのStorybookへシームレスに流し込むための実践的なアーキテクチャは以下の通りだ。
[Penpot (Design)]
│ (Webhook / Export)
▼
[Design Tokens (JSON)] ──> [Style Dictionary] ──> [CSS Variables / Tailwind Config]
│ │
▼ ▼
[Penpot API / Plugins] ─── (Sync) ──────────────────> [Storybook / React Components]
① 絶対入れるべき神プラグインと拡張
Penpotのプラグインエコシステムを活用し、デザインメタデータをJSONとして抽出し、Gitリポジトリへ自動同期するカスタムCIアクションを組む。
- Penpot Tokens Exporter: カラー、タイポグラフィ、スペーシングなどのデザイン・トークンをW3Cデザイン・トークン仕様のJSON形式でエクスポートする。
—
4. 実用的な設定ファイルのベストプラクティス構成
チーム開発において、設定ファイルの整合性は生命線である。以下に、Penpotのデザイン・トークンを受け取り、Storybookとフロントエンドコードベース全体で共有するための設定ファイルの模範解答を示す。
1. デザイン・トークンの定義 (`tokens/design-tokens.json`)
Penpotからエクスポート、またはCI経由で同期されるW3C仕様に準拠したデザイントークン。
{
“color”: {
“primary”: {
“500”: { “value”: “#6366f1”, “type”: “color”, “comment”: “ブランドメインカラー (Penpot: Primary/500)” },
“600”: { “value”: “#4f46e5”, “type”: “color”, “comment”: “ブランドホバーカラー” }
},
“neutral”: {
“100”: { “value”: “#f3f4f6”, “type”: “color” },
“900”: { “value”: “#111827”, “type”: “color” }
}
},
“spacing”: {
“base”: { “value”: “4px”, “type”: “dimension” },
“sm”: { “value”: “{spacing.base} 2”, “type”: “dimension” }, / 8px /
“md”: { “value”: “{spacing.base} 4”, “type”: “dimension” }, / 16px /
“lg”: { “value”: “{spacing.base} 6”, “type”: “dimension” } / 24px /
}
}
2. Style Dictionaryによるビルド設定 (`style-dictionary.config.js`)
トークンをCSS VariablesやTailwindのフォーマットにトランスパイルする。これにより、Penpotの変更がビルド時に自動でコード側へ反映される。
module.exports = {
// トークンファイルの指定
source: [‘tokens//.json’],
platforms: {
css: {
transformGroup: ‘css’,
buildPath: ‘src/styles/’,
files: [
{
destination: ‘variables.css’,
format: ‘css/variables’,
options: {
outputReferences: true, // 参照関係（例: spacing.sm）を維持して出力
},
},
],
},
js: {
transformGroup: ‘js’,
buildPath: ‘src/tokens/’,
files: [
{
destination: ‘tokens.ts’,
format: ‘javascript/es6’,
},
],
},
},
};
3. Storybook連携のためのプレビュー設定 (`.storybook/preview.js`)
生成されたCSS変数と、Penpot側で定義されたブレイクポイント・テーマをStorybook全体に適用する。
import ‘../src/styles/variables.css’; // Penpotから同期されたCSS変数をインポート
import { INITIAL_VIEWPORTS } from ‘@storybook/addon-viewport’;
/ @type { import(‘@storybook/react’).Preview } /
const preview = {
parameters: {
actions: { argTypesRegex: ‘^on[A-Z].’ },
controls: {
matchers: {
color: /(background|color)$/i,
date: /Date$/,
},
},
// Penpotのデザインフレームワークに合わせたビューポート設定
viewport: {
viewports: {
…INITIAL_VIEWPORTS,
penpotMobile: {
name: ‘Penpot Mobile (390px)’,
styles: { width: ‘390px’, height: ‘844px’ },
},
penpotDesktop: {
name: ‘Penpot Desktop (1440px)’,
styles: { width: ‘1440px’, height: ‘900px’ },
},
},
},
},
};
export default preview;
—
5. チーム開発における運用ルールとガバナンス
ツールと設定が整っても、運用ルールが曖昧であればシステムは崩壊する。以下の3つのルールをチームの合意事項（Definition of Done: 完了の定義）として定着させよ。
1. 「Direct Edit禁止」の原則:
エンジニアはStorybookやコンポーネントコード側で勝手にハードコードされたカラーコードやマージン（例: `margin: 15px;`）を使ってはならない。必ずPenpotから同期されたCSS変数（`var(–spacing-md)`等）を参照すること。
2. PR連携による目視確認:
PenpotのWebhookまたはGitHub Actionsを構成し、デザインファイルが更新された際に、差分が自動的にStorybook上のVisual Tests（Chromatic等）へフックされるフローを構築する。
3. コンポーネント命名規則の1:1マッピング:
Penpot上のコンポーネント名（例: `Button / Primary`）と、Storybook上の階層（例: `Components/Button/Primary`）のパスを完全に一致させる。これにより、デザイナーとエンジニアがSlack等で会話する際のコンテキストスイッチをゼロにする。
—
結び：オープンなデザインシステムが開発組織を強くする
PenpotとStorybookの統合は、単に「ツールを連携させる」という技術的な話にとどまらない。それは、「デザインとコードの境界線を限りなく溶かし、チーム全員が同じプロダクトの真実を見据えて開発する」という組織的トランスフォーメーションそのものである。
クローズドなエコシステムから脱却し、オープンソースの強靭な歯車を噛み合わせたとき、あなたのチームの開発スピードは文字通り次元が変わる。今すぐ設定ファイルを書き下ろし、リポジトリに最初のパイプラインを通そう。