PenpotのCSS変数（CSS Custom Properties）完全連携術：デザインシステムのトークンをコードへダイレクトに反映させる方法
デザインとコードの乖離は、すべてのフロントエンドエンジニアとプロダクトデザイナーが一度は直面する悪夢だ。「FigmaのHEXコードをコピーしてTailwindの設定に貼り付け、SCSSの変数に落とし込む…」この手動の同期作業に、一体どれだけのエンジニアリングリソースが溶かされてきたことか。
オープンソースのプロトタイピングツール「Penpot」の真価は、単なるFigmaのオープンソース代替ではない。その内部アーキテクチャの根底にはSVGとCSSのネイティブな親和性があり、「デザインシステムをそのままCSS変数（CSS Custom Properties）としてコードベースに直結させる」ための完璧な素地が備わっている。
今回は、テックリードの視点から、Penpotのデザイントークンをプロダクションコードへダイレクトに流し込み、デザイン変更を秒速で反映させる究極のワークフローを構築する方法を解説する。
—
1. なぜPenpotなのか？ デザインとコードの「言語」を統一する思想
多くのデザインツールは、独自のJSON構造や閉じたプロパティを持っており、それを開発者が使える形に変換するには何かしらの仲介（プラグインや外部サービス）が必要だった。
しかし、Penpotは最初からCSSの概念（Flexbox, CSS Grid, SVG, そしてCSS変数）をそのままキャンバスの操作系に落とし込んでいる。つまり、デザイナーがPenpot上でトークンを定義するということは、実質的に「CSSの設計図を書いているのと同じ」なのだ。
この思想を極限まで活かし、デザイン変更がCI/CDパイプラインやローカルのHMR（Hot Module Replacement）を通じて、一瞬でプロダクションのUIに反映されるパイプラインを構築する。
—
2. チームの生産性を爆発させるPenpotショートカット＆神設定
まずは、デザインシステムの土台を作るデザイナーと、それをコードに落とし込むエンジニアが共通して知っておくべき、作業効率を最大化するプラクティスから入る。
開発スピードを加速させるキーボードショートカット
Penpotの操作をキーボードに指を定着させることで、コンポーネント構造の構築速度が3倍になる。
- `Shift + A` : Auto Layout（Flexbox）の適用（CSSのdisplay: flexを一発で構築）
- `Cmd/Ctrl + Shift + K` : コンポーネント化（Atomic Designのパーツ化）
- `Alt/Option + ホバー` : CSSインスペクターの精密数値確認（Margin/Paddingの即座の把握）
- `Cmd/Ctrl + /` : コマンドパレット呼び出し（迷ったらこれ。全機能をキーボードから実行）
チーム共有のための「厳格な命名規則（Naming Convention）」ルール
CSS変数として出力する以上、Penpot内のトークン名はそのままコードの変数名になる。場当たり的な命名は負債を生む。以下の階層構造（BEMライクなアプローチ）をチーム全体で強制すること。
1. グローバルトークン（プリミティブ）: 色のパレットやベースの数値
- 例: `–color-blue-500`, `–spacing-4`
2. セマンティックトークン（エイリアス）: 役割を持たせた変数
- 例: `–color-primary`, `–color-background-base`, `–spacing-layout-md`
3. コンポーネントトークン: 特定のコンポーネントにスコープされた変数
- 例: `–button-bg-hover`
—
3. Penpotトークンをコードへ直結させる：実用設定ファイルのベストプラクティス
Penpotで定義したカラーやタイポグラフィを、ビルドプロセスに組み込むための設定ファイルを定義する。ここでは、W3C Design Tokens Format準拠の構造を想定し、JSON/YAMLを用いたモダンな連携パイプラインを構築する。
① トークン定義ファイル（`design-tokens.json`）
PenpotのAPIやエクスポート機能を介して同期、あるいはチームでソースオブトゥルース（信頼できる唯一の情報源）として管理するJSONの構造例だ。
{
“color”: {
“primitive”: {
“blue”: {
“500”: { “value”: “#0D9488”, “type”: “color”, “$description”: “Primary Brand Teal” },
“600”: { “value”: “#0F766E”, “type”: “color”, “$description”: “Primary Brand Teal Dark” }
},
“neutral”: {
“900”: { “value”: “#0F172A”, “type”: “color”, “$description”: “Slate 900” },
“100”: { “value”: “#F8FAFC”, “type”: “color”, “$description”: “Slate 50” }
}
},
“semantic”: {
“background”: {
“default”: { “value”: “{color.primitive.neutral.100}”, “type”: “color” },
“inverse”: { “value”: “{color.primitive.neutral.900}”, “type”: “color” }
},
“action”: {
“primary”: { “value”: “{color.primitive.blue.500}”, “type”: “color” },
“primaryHover”: { “value”: “{color.primitive.blue.600}”, “type”: “color” }
}
}
},
“spacing”: {
“sm”: { “value”: “8px”, “type”: “dimension” },
“md”: { “value”: “16px”, “type”: “dimension” },
“lg”: { “value”: “24px”, “type”: “dimension” }
}
}
② トークンをCSS変数に変換するビルドスクリプト（Node.js / Style Dictionary活用）
上記のJSONを、実際のプロダクションで読み込める純粋なCSS変数（`:root`）にコンパイルする設定ファイル（`config.json` for Style Dictionary）のベストプラクティス。
{
“source”: [“tokens/design-tokens.json”],
“platforms”: {
“css”: {
“transformGroup”: “css”,
“buildPath”: “src/styles/”,
“files”: [
{
“destination”: “_tokens.css”,
“format”: “css/variables”,
“options”: {
“outputReferences”: true,
“selector”: “:root”
}
}
]
}
}
}
この設定によって出力される `src/styles/_tokens.css` がこれだ：
/
- Do not edit directly
- Generated on: 202X.XX.XX
- This file is synchronized directly with Penpot Design System.
/
:root {
–color-primitive-blue-500: #0D9488;
–color-primitive-blue-600: #0F766E;
–color-primitive-neutral-900: #0F172A;
–color-primitive-neutral-100: #F8FAFC;
–color-semantic-background-default: var(–color-primitive-neutral-100);
–color-semantic-background-inverse: var(–color-primitive-neutral-900);
–color-semantic-action-primary: var(–color-primitive-blue-500);
–color-semantic-action-primary-hover: var(–color-primitive-blue-600);
–spacing-sm: 8px;
–spacing-md: 16px;
–spacing-lg: 24px;
}
これをアプリケーションのエントリーポイント（`main.ts`や`App.tsx`、グローバルCSS）でインポートするだけで、すべてのコンポーネントからこの変数群にアクセス可能になる。
—
4. デザイナーとエンジニアをつなぐ実戦的ワークフロー
ここまでの仕組みをチームに定着させるための、具体的な運用フローを定義する。
[ Penpot (Design System) ]
│
▼ (Webhook / CLI / Export)
[ Design Tokens JSON ]
│
▼ (Style Dictionary Build)
[ _tokens.css (CSS Variables) ]
│
▼ (HMR / Bundler)
[ Frontend App (React / Vue / Svelte) ]
1. デザインの変更: デザイナーがPenpot上でトークン（カラーやスペーシング）をアップデートする。
2. トークンの同期: Penpotのエクスポート機能、またはサードパーティのPenpot連携スクリプト（CLI）を用いて、Gitリポジトリ上の `design-tokens.json` を更新する（GitHub Actionsによる自動化も推奨）。
3. 自動ビルド: プルリクエストの作成時やビルド時にStyle Dictionaryが走り、`_tokens.css` が自動生成される。
4. 即時反映: フロントエンドエンジニアがコード側で変数を書き換える必要は一切なく、常に最新のデザインシステムがコードに同期される。
—
5. テックリードからの総括：ツールの境界線を消し去れ
UI/UXの現場において、デザインとコードの間に「翻訳作業」が存在しているうちは、真の俊敏性（Agility）を手に入れることはできない。
Penpotを単なる「絵を描くツール」として使うのはもったいない。その背後にあるCSSのセマンティクスを理解し、今回紹介したCSS変数との完全連携パイプラインを構築することで、「デザイナーがデザインを変えた瞬間、プロダクションの画面の色が変わる」という、エンジニアリングのロマンと実利を兼ね備えた開発環境が手に入る。
さあ、今すぐプロジェクトのスタイル定義を見直し、手動でのHEXコードのコピー＆ペーストという不毛な作業に終止符を打とう。プロダクトの品質とチームの速度は、この基盤構築の美しさによってのみ飛躍的に向上するのだから。