Penpotの使い方完全ガイド【インストールから応用まで】

デジタルプロダクト開発において、デザインと開発の連携は常に課題です。デザイナーが作成した美しいデザインが、開発工程で意図せず変更されたり、実装に時間がかかったりする経験はないでしょうか。あるいは、デザインシステムの管理が属人化し、一貫性の維持に苦労する場面もあるかもしれません。

Penpotがない世界では、デザインは画像として共有されがちです。デザイナーはAdobe XDやFigmaでUIを作成し、開発者はそれを基に手動でCSSやHTMLを記述します。このプロセスでは、デザイン変更のたびに手作業での調整が必要です。コミュニケーション不足からデザインと実装の間に認識の齟齬が生まれ、手戻りが発生することもあります。さらに、デザイン資産が特定のベンダーにロックインされ、将来的な移行コストの懸念もつきまといます。

Penpotがある世界では、これらの課題が解消されます。デザインはコードと同じオープンスタンダードで表現されます。デザイナーと開発者は共通のプラットフォームでリアルタイムに協業可能です。デザイン変更は即座にコードに反映される基盤が整います。デザインシステムはコードとして管理され、一貫性と再利用性が向上します。自社サーバーでのホスティングも可能で、データ主権を完全に保持できます。

本記事では、この革新的なツールPenpotの導入から活用までを、開発者の視点から徹底的に解説します。

Penpotとは

Penpotは、オープンソースのデザインプラットフォームです。 Figmaの代替として注目されており、特にデザインとコードの連携に強みを持っています。スケーラブルなデジタルプロダクト開発チーム向けに設計されています。

Penpotはオープンスタンダードを重視しています。 SVG、CSS、HTML、JSONといったウェブ標準技術を直接扱えます。これにより、デザインが「コードとして」表現されるため、開発者にとって非常に理解しやすいのが特徴です。

最大の強みは、デザインインフラを完全に所有できる点にあります。自己ホスティングが可能であり、組織の厳格なコンプライアンス要件にも対応できます。ブラウザベースで利用できるだけでなく、自社サーバーにデプロイも可能です。

リアルタイムコラボレーション機能も充実しています。複数のメンバーが同時にデザイン作業を進められます。大規模なチームでの製品開発を強力にサポートします。

開発者にとって特に魅力的なのは、デザインがコードに直結する点です。 InspectモードでSVG、CSS、HTMLコードにすぐにアクセスできます。これにより、デザインから実装への翻訳プロセスが高速化されます。

さらに、強力なデザイントークン機能も搭載されています。デザインと開発の間で「単一の情報源」を確立できます。これにより、デザインの一貫性を保ち、複雑なデザインシステムの管理が容易になります。

MCP（Multi-directional Code-Design Platform）サーバーは、デザインとコードの双方向ワークフローを実現します。オープンAPIとプラグインシステムも提供されており、ワークスペースをプログラムで拡張できます。自動化、AI駆動のワークフロー、既存ツールとの統合も容易です。

CSS GridやFlex Layoutといった最新のレイアウト機能も備えています。レスポンシブなインターフェースをコードのように設計できます。 Penpotは、フルスタックのデザインプラットフォームとして、製品開発プロセス全体を統合します。

インストール方法

Penpotは自己ホスティングが推奨されています。 Docker Composeを利用することで、簡単に自身の環境にデプロイできます。ここでは、macOS、Linux、Windows共通でDocker Composeを用いたインストール方法を説明します。事前にDocker Desktop（Windows/macOS）またはDocker EngineとDocker Compose（Linux）がインストールされていることを前提とします。

1. Penpotリポジトリのクローン

まず、PenpotのDocker Compose設定ファイルを含むリポジトリをクローンします。任意のディレクトリで以下のコマンドを実行してください。

git clone https://github.com/penpot/penpot.git

2. ディレクトリへの移動

クローンしたPenpotディレクトリに移動します。

cd penpot

3. Penpotインスタンスの起動

Docker Composeを使用してPenpotサービスを起動します。-d オプションを付けることで、バックグラウンドでサービスが実行されます。

docker compose up -d

初回起動時には、必要なDockerイメージがダウンロードされます。これには数分かかる場合があります。すべてのサービスが起動すると、ブラウザでPenpotにアクセスできるようになります。デフォルトでは http://localhost:9001 でアクセス可能です。

4. 起動確認

サービスが正しく起動しているか確認します。

docker compose ps

すべてのサービスが running ステータスであることを確認してください。

5. Penpotの停止

Penpotインスタンスを停止したい場合は、以下のコマンドを実行します。

docker compose down

これにより、Penpotに関連するすべてのDockerコンテナが停止し、削除されます。データを保持したまま停止したい場合は、docker compose stop を使用します。

基本的な使い方

Penpotは主にWeb UIで操作するデザインツールです。しかし、開発者向けの機能やAPIを通じて、コマンドラインからの操作や自動化も可能です。ここでは、開発者がPenpotを使い始める上で知っておきたい基本的な「コマンド」と、その概念を説明します。

1. Penpotインスタンスの起動と停止

自己ホスティング環境では、Penpotサーバーの管理が基本となります。前述のインストール方法で紹介したDocker Composeコマンドは、日常的に使用する重要なコマンドです。

起動:

docker compose up -d

このコマンドで、Penpotサーバーとそれに必要なデータベースなどのサービスがバックグラウンドで起動します。開発中は頻繁に利用することになるでしょう。

停止:

docker compose down

開発を終える際や、サーバーを再起動する際に使用します。コンテナが停止し、関連するネットワークも削除されます。

2. プロジェクト内のデザインアセットをプログラムで取得する

PenpotはデザインをSVG、CSS、HTMLとして扱います。 APIを利用することで、これらのアセットをプログラム的に取得し、開発ワークフローに組み込めます。例えば、プロジェクト内のSVGアイコンを自動でダウンロードするシナリオを考えます。

まず、PenpotのWeb UIでAPIトークンを生成する必要があります。通常、ユーザー設定やプロジェクト設定のセクションにあります。ここでは、例えば YOUR_API_TOKEN と YOUR_PROJECT_ID を使用するものとします。

# 例: Penpotからプロジェクトの全アセット情報を取得
# 実際のAPIエンドポイントはPenpotのAPIドキュメントを参照してください。
# ここでは仮のAPIエンドポイントを使用します。
# 取得したJSONから必要なアセットのURLを抽出し、ダウンロードするスクリプトを記述します。
curl -s -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://your-penpot-instance.com/api/v1/projects/YOUR_PROJECT_ID/assets" \
     | jq '.data[] | select(.type == "svg") | .url' \
     | xargs -I {} curl -s -O "{}"

このコマンドは、jq を使ってJSONレスポンスからSVGアセットのURLを抽出し、xargs で各URLからファイルをダウンロードする例です。実際のAPIレスポンスの構造に合わせて jq のパスを調整してください。

3. デザイントークンをプログラムで取得する

Penpotの強力な機能の一つがデザイントークンです。 APIを通じてトークン定義を取得し、開発プロジェクトで利用できます。例えば、アプリケーションのカラーパレットやフォント設定をPenpotで一元管理し、それをCSS変数として自動生成する基盤を構築できます。

# 例: Penpotからデザイントークンを取得し、JSONファイルとして保存
# 実際のAPIエンドポイントはPenpotのAPIドキュメントを参照してください。
# ここでは仮のAPIエンドポイントを使用します。
PENPOT_API_TOKEN="YOUR_API_TOKEN"
PENPOT_PROJECT_ID="YOUR_PROJECT_ID"
TOKENS_OUTPUT_FILE="design-tokens.json"

curl -s -H "Authorization: Bearer $PENPOT_API_TOKEN" \
     "https://your-penpot-instance.com/api/v1/projects/$PENPOT_PROJECT_ID/design-tokens" \
     -o "$TOKENS_OUTPUT_FILE"

echo "デザイントークンを $TOKENS_OUTPUT_FILE に保存しました。"

このコマンドにより、Penpotで定義されたデザイントークンがJSON形式で出力されます。このJSONファイルを、style-dictionaryなどのツールと連携させることで、CSS変数やSass変数、JavaScriptオブジェクトなど、様々な形式に変換して利用できます。

これらの「コマンド」は、Penpotが単なるデザインツールではなく、開発ワークフローに深く統合できるプラットフォームであることを示しています。 APIを積極的に活用することで、デザインとコードの間の隔たりをさらに小さくできるでしょう。

便利な使い方・応用例 3選

Penpotの真価は、そのオープン性とAPIによる拡張性にあります。ここでは、実際の開発シーンに落とし込んだ応用例を3つ紹介します。これらは、デザインと開発の連携をより密接にし、プロダクト開発の速度を向上させるでしょう。

1. CI/CDパイプラインへのデザインアセット自動組み込み

デザイン変更が頻繁に行われるプロジェクトでは、手動でのアセット更新は手間がかかります。 PenpotのAPIとCI/CDツールを組み合わせることで、このプロセスを自動化できます。例えば、GitHub Actionsを使って、特定のブランチへのマージやタグ付けをトリガーに、Penpotから最新のデザインアセット（SVGアイコン、画像など）をダウンロードし、リポジトリにコミットするシナリオを考えます。

# GitHub Actionsのワークフロー内で実行されるスクリプトの例
# 例として、PenpotからSVGアイコンを含むZIPファイルをダウンロードし、展開する
# 環境変数 PENPOT_API_TOKEN と PENPOT_PROJECT_ID はGitHub Secretsで設定します。
# ASSET_DIR は、プロジェクト内のアイコンを格納するディレクトリパスです。

#!/bin/bash
set -euo pipefail

PENPOT_INSTANCE_URL="https://your-penpot-instance.com" # あなたのPenpotインスタンスURL
ASSET_DIR="src/assets/icons"
TEMP_ZIP="penpot_assets.zip"

echo "Penpotからデザインアセットをダウンロード中..."

# Penpot APIからアセットをZIP形式でダウンロード（仮のAPIエンドポイント）
# 実際のAPIは個々のアセットURLを提供することが多いため、
# 事前にアセットリストを取得し、ループでダウンロードする方が現実的です。
# ここでは、簡略化のため「全アセットをZIPで提供するAPI」を想定します。
curl -s -L -H "Authorization: Bearer $PENPOT_API_TOKEN" \
     "$PENPOT_INSTANCE_URL/api/v1/projects/$PENPOT_PROJECT_ID/export/assets.zip" \
     -o "$TEMP_ZIP"

if [ ! -f "$TEMP_ZIP" ]; then
    echo "エラー: アセットのダウンロードに失敗しました。"
    exit 1
fi

echo "ダウンロード完了。$ASSET_DIR に展開します。"
mkdir -p "$ASSET_DIR"
unzip -o "$TEMP_ZIP" -d "$ASSET_DIR" # -o は既存ファイルを上書き
rm "$TEMP_ZIP"

echo "デザインアセットの自動更新が完了しました。"

# Gitへのコミットとプッシュ（GitHub Actionsのステップとして別途設定）
# git config user.name "github-actions[bot]"
# git config user.email "github-actions[bot]@users.noreply.github.com"
# git add "$ASSET_DIR"
# git commit -m "feat: Update design assets from Penpot [skip ci]" || true # 変更がない場合はエラーにしない
# git push

このスクリプトは、CI/CD環境で実行されることを想定しています。デザインが更新されるたびに、最新のアセットが自動的にコードベースに取り込まれ、常に最新のデザインで開発を進められます。

2. デザイントークンを活用したテーマ切り替え機能の実装

Penpotで管理されているデザイントークンは、アプリケーションのテーマ設定に非常に有効です。例えば、ダークモードとライトモードの切り替えや、ブランドカラーの変更などを、デザイントークンに基づいて実装できます。 Penpot APIで取得したJSON形式のデザイントークンを、style-dictionaryのようなツールでCSS変数などに変換し、フロントエンドアプリケーションに組み込む手順を考えます。

# 開発環境で実行するスクリプトの例
# Penpotからデザイントークンを取得し、CSS変数ファイルを生成します。
# 事前に style-dictionary がインストールされている必要があります (npm install -g style-dictionary)。

#!/bin/bash
set -euo pipefail

PENPOT_API_TOKEN="YOUR_API_TOKEN" # あなたのAPIトークン
PENPOT_PROJECT_ID="YOUR_PROJECT_ID" # あなたのプロジェクトID
PENPOT_INSTANCE_URL="https://your-penpot-instance.com" # あなたのPenpotインスタンスURL
TOKENS_JSON="design-tokens.json"
STYLE_DICTIONARY_CONFIG="style-dictionary-config.json"

echo "Penpotからデザイントークンを取得中..."

# Penpot APIからデザイントークンをJSON形式で取得
curl -s -H "Authorization: Bearer $PENPOT_API_TOKEN" \
     "$PENPOT_INSTANCE_URL/api/v1/projects/$PENPOT_PROJECT_ID/design-tokens" \
     -o "$TOKENS_JSON"

if [ ! -f "$TOKENS_JSON" ]; then
    echo "エラー: デザイントークンのダウンロードに失敗しました。"
    exit 1
fi

echo "デザイントークンを $TOKENS_JSON に保存しました。"

# style-dictionaryの設定ファイルを作成（必要に応じて）
# これは一度作成すればよいです。
cat << EOF > "$STYLE_DICTIONARY_CONFIG"
{
  "source": ["$TOKENS_JSON"],
  "platforms": {
    "css": {
      "transformGroup": "css",
      "buildPath": "build/css/",
      "files": [{
        "destination": "_variables.css",
        "format": "css/variables"
      }]
    },
    "js": {
      "transformGroup": "js",
      "buildPath": "build/js/",
      "files": [{
        "destination": "tokens.js",
        "format": "javascript/es6"
      }]
    }
  }
}
EOF

echo "style-dictionaryでデザイントークンを変換中..."

# style-dictionary を実行してCSS変数やJSオブジェクトを生成
npx style-dictionary --config "$STYLE_DICTIONARY_CONFIG" build

echo "デザイントークンの変換が完了しました。build/css/_variables.css および build/js/tokens.js を確認してください。"

このスクリプトにより、デザイナーがPenpotで更新したカラーコードやフォントサイズが、開発側のCSS変数やJSオブジェクトに自動的に反映されます。これにより、デザインと実装の間で一貫性が保たれ、テーマ変更も容易になります。

3. プラグイン開発によるカスタムワークフローの構築

Penpotはプラグインシステムを提供しており、独自の機能を追加したり、外部ツールと連携したりできます。例えば、選択中のデザイン要素の情報を取得し、それを特定のフォーマットで出力するプラグインや、AIを活用してデザイン要素を生成するプラグインなどを開発できます。プラグインはJavaScriptで記述されるため、Node.js環境での開発が基本となります。

# Penpotプラグイン開発の初期設定例 (Node.js環境を想定)
# 実際のプラグインはPenpotのAPIと連携するJavaScriptファイルとして動作します。
# ここでは、開発環境をセットアップし、簡単なプラグインの骨格を作成する例を示します。

#!/bin/bash
set -euo pipefail

PLUGIN_NAME="my-custom-penpot-plugin"
PLUGIN_DIR="$PLUGIN_NAME"

echo "Penpotプラグイン ($PLUGIN_NAME) の開発環境をセットアップ中..."

mkdir "$PLUGIN_DIR"
cd "$PLUGIN_DIR"

# Node.jsプロジェクトを初期化
npm init -y

# プラグインのメインファイルを作成
cat << EOF > "index.js"
// Penpotプラグインのメインファイル
// Penpotのグローバルな `penpot` オブジェクトを通じてAPIにアクセスします。

penpot.onSelectionChange(async (selection) => {
  if (selection.length > 0) {
    console.log("選択された要素:", selection[0].name);
    // 例: 選択された要素の情報を取得し、何らかの処理を行う
    // const elementData = await penpot.api.getElement(selection[0].id);
    // console.log(elementData);

    // 例: UIにメッセージを表示する
    // penpot.ui.postMessage({ type: 'info', message: '要素が選択されました' });
  }
});

penpot.onMessage(async (message) => {
  if (message.type === 'runPlugin') {
    // プラグインが実行された際の処理
    console.log("プラグインが実行されました！");
    // 例えば、選択要素からコードを生成し、クリップボードにコピーする
    // const selectedElements = await penpot.api.getSelection();
    // const generatedCode = generateCodeFromElements(selectedElements);
    // penpot.ui.copyToClipboard(generatedCode);
  }
});

// プラグインUIを開くための関数
// penpot.ui.show({ width: 300, height: 200, title: 'My Plugin' });
EOF

# プラグイン設定ファイル (manifest.json) の作成例
cat << EOF > "manifest.json"
{
  "name": "$PLUGIN_NAME",
  "id": "com.example.$PLUGIN_NAME",
  "version": "1.0.0",
  "main": "index.js",
  "ui": "ui.html",
  "capabilities": ["selection", "apiAccess"],
  "menu": {
    "text": "My Custom Plugin",
    "command": "runPlugin"
  }
}
EOF

# プラグインのUIファイル (ui.html) の作成例
cat << EOF > "ui.html"
<!DOCTYPE html>
<html>
<head>
  <style>body { font-family: sans-serif; padding: 10px; }</style>
</head>
<body>
  <h1>Hello Penpot Plugin!</h1>
  <p>このプラグインはPenpotを拡張します。</p>
  <script>
    // プラグインUIのスクリプト
    // parent.postMessage({ pluginMessage: { type: 'runPlugin' } }, '*');
  </script>
</body>
</html>
EOF

echo "プラグインの雛形が $PLUGIN_DIR ディレクトリに作成されました。"
echo "次に、Penpotのプラグイン開発者向けドキュメントを参照して、機能を実装してください。"

この例では、プラグインの基本的なファイル構成を示しました。 Penpotのプラグインは、デザインツールの内部APIと連携し、様々な自動化や拡張を実現します。独自のワークフロー要件に合わせて、強力なカスタムツールを作成できるでしょう。

他ツールとの組み合わせ

Penpotはそのオープン性から、様々な開発ツールとの連携が容易です。デザインと開発のブリッジを強化し、シームレスなワークフローを構築するために相性の良いツールを紹介します。

1. GitHub / GitLab (バージョン管理システム)

組み合わせ方: Penpotでエクスポートされたデザインアセット（SVG、CSS、HTML）やデザイントークンを、Gitリポジトリでバージョン管理します。前述のCI/CDパイプラインの例のように、自動で最新のデザインをリポジトリにコミットし、変更履歴を追跡できます。デザインレビューもPull Request上で行うことが可能です。
メリット: デザイン資産の変更履歴を開発コードと同期させ、一貫したバージョン管理を実現します。

2. VS Code (コードエディタ)

組み合わせ方: Penpotで生成されたCSS、HTML、デザイントークンなどのコードは、VS Codeで直接編集できます。Penpotはデザインの「コードベース」を生成するため、開発者は馴染み深いIDEでそのコードを直接操作し、アプリケーションに組み込めます。APIキーを環境変数として管理し、VS CodeのターミナルからPenpot APIを叩くスクリプトを実行することもできます。
メリット: 開発者が使い慣れた環境で、デザインから生成されたコードを効率的に扱えます。

3. Storybook (コンポーネントライブラリ)

組み合わせ方: Penpotで設計したコンポーネントやデザインシステムを、Storybookで実装し、ドキュメント化・可視化します。PenpotのデザイントークンをStorybookのコンポーネントに適用し、デザインシステム全体の一貫性を保ちます。Penpotで作成したUIコンポーネントをStorybookでプレビューし、開発者とデザイナーが共通認識を持てます。
メリット: デザインシステムをコードとして管理し、コンポーネントの再利用性を高めます。デザイナーと開発者の間の認識齟齬を防ぎます。

4. Jira / Asana (プロジェクト管理ツール)

組み合わせ方: PenpotのAPIやウェブフックを利用して、デザインの変更や承認ステータスをJiraやAsanaのタスクと連携させます。例えば、Penpotでデザインが「承認済み」になったら、Jiraのタスクステータスを自動で「開発中」に更新するといった連携が考えられます。
メリット: デザインの進捗状況をプロジェクト管理ツールと同期させ、開発チーム全体の透明性を向上させます。

これらのツールとPenpotを組み合わせることで、デザインと開発のワークフローがよりスムーズになり、プロダクト開発全体の生産性が向上します。

よくある設定・カスタマイズ

Penpotは自己ホスティングが可能であるため、Docker Composeの設定ファイルを編集することで、様々なカスタマイズが可能です。ここでは、特に開発者が知っておくべき設定やカスタマイズの例を紹介します。

1. 環境変数の設定 (`.env` ファイル)

PenpotのDocker Composeは、.env ファイルを使用して環境変数を管理します。このファイルに設定を記述することで、ポート番号、管理者情報、データベース接続などを変更できます。 penpot ディレクトリ直下の .env ファイルを編集または新規作成します。

# penpot/.env の例

# Penpotインスタンスの公開URI。外部からアクセスする場合に設定します。
# 例: PENPOT_PUBLIC_URI="https://your-penpot-domain.com"
PENPOT_PUBLIC_URI="http://localhost:9001"

# 管理者ユーザーのメールアドレスとパスワード
# これらは初回起動時に管理者アカウントを作成するために使用されます。
PENPOT_ADMIN_EMAIL="admin@example.com"
PENPOT_ADMIN_PASSWORD="your-secure-password" # 強固なパスワードを設定してください

# データベース設定 (PostgreSQL)
# 通常はデフォルトのままで問題ありません。
# PENPOT_DB_HOST="db"
# PENPOT_DB_PORT="5432"
# PENPOT_DB_USER="penpot"
# PENPOT_DB_PASSWORD="penpot_password"
# PENPOT_DB_NAME="penpot"

# その他の設定例
# Penpotのログレベルを設定
# PENPOT_LOG_LEVEL="info" # debug, info, warn, error など

.env ファイルを変更した場合は、Penpotサービスを再起動する必要があります。

docker compose down
docker compose up -d

2. ポート番号の変更 (`docker-compose.yaml`)

デフォルトではPenpotはポート 9001 で動作します。このポートを変更したい場合は、penpot/docker-compose.yaml ファイルを編集します。frontend サービスのマッピング部分を変更します。

# penpot/docker-compose.yaml の一部抜粋

services:
  frontend:
    # ...
    ports:
      # ホスト側のポート:コンテナ側のポート
      - "80:3000" # 例: ホストの80番ポートでアクセスしたい場合
      # - "9001:3000" # デフォルト設定
    # ...

上記例では、ホスト側の 80 番ポートでPenpotにアクセスできるようになります。変更後も同様に docker compose down -> docker compose up -d で再起動が必要です。

3. APIキーの管理と利用

PenpotのAPIを利用するには、APIキー（トークン）が必要です。これはPenpotのWeb UI内で生成・管理します。

Penpotにログイン: 管理者アカウントでPenpotインスタンスにアクセスします。
ユーザー設定へ移動: プロフィールアイコンをクリックし、「Settings」（設定）または「API Tokens」（APIトークン）のような項目を探します。
新しいトークンを生成: 「Generate New Token」などのボタンをクリックし、トークンの名前（例えば CI/CD_Automation）を設定して生成します。
トークンをコピー: 生成されたトークンは一度しか表示されないため、必ずコピーして安全な場所に保存してください。

このAPIトークンは、前述の応用例で示したように、Authorization: Bearer YOUR_API_TOKEN ヘッダーとしてHTTPリクエストに含めて使用します。本番環境では、APIトークンを環境変数やシークレット管理サービスに格納し、直接コードに埋め込まないようにすることが重要です。

4. プラグインのインストールと開発環境

Penpotはプラグインによる拡張が可能です。公式のPenpot Hubからプラグインをインストールできるほか、自分でプラグインを開発して利用することもできます。

プラグインのインストール: PenpotのWeb UIから「Plugins」セクションにアクセスし、Penpot Hubから利用したいプラグインを探してインストールします。
カスタムプラグインの開発: 前述の応用例で示したように、Node.js環境でJavaScript/TypeScriptを用いてプラグインを開発します。開発したプラグインは、ローカルでテストした後、Penpotインスタンスにデプロイします。具体的なデプロイ方法はPenpotのプラグイン開発者向けドキュメントを参照してください。通常、プラグインのファイルを特定のディレクトリに配置したり、PenpotのUIからアップロードしたりする形になります。

これらの設定やカスタマイズを理解することで、Penpotを自身の開発ワークフローや組織の要件に合わせて最適化できます。

今日からできる実行プラン

Penpotの導入は、デザインと開発の連携を強化するための大きな一歩です。今日からPenpotを使い始めるための3ステップ実行プランを紹介します。

ステップ1: Penpotインスタンスを立ち上げる

まずは、自身の環境でPenpotが動作することを確認しましょう。 Dockerがインストールされていることを前提とします。

Penpotリポジトリをクローン:

git clone https://github.com/penpot/penpot.git
cd penpot

Penpotを起動:
```
docker compose up -d
```
アクセス確認: ブラウザで http://localhost:9001 にアクセスし、Penpotのログイン画面が表示されることを確認します。初回アクセス時には、.env ファイルで設定した管理者情報（PENPOT_ADMIN_EMAIL, PENPOT_ADMIN_PASSWORD）でログインしてください。

このステップで、Penpotの自己ホスティング環境が手に入ります。もしポートが競合する場合は、docker-compose.yaml を編集してポート番号を変更してください。

ステップ2: サンプルプロジェクトを作成し、基本操作を試す

PenpotのUIに慣れるため、簡単なプロジェクトを作成してみましょう。

新しいプロジェクトの作成: Penpotのダッシュボードから「New project」を選択し、任意の名前でプロジェクトを作成します。
アートボードの追加: プロジェクト内で新しいファイルを作成し、アートボードを追加します。
基本的なUI要素の配置: 長方形やテキスト、アイコンなどの基本的なUI要素を配置し、色やフォントを変更してみます。
コンポーネントの作成: 配置した要素をコンポーネント化し、再利用性を体験します。
Inspectモードの確認: デザイン要素を選択し、右側のサイドバーにある「Inspect」タブを開きます。そこで表示されるSVG、CSS、HTMLコードを確認し、デザインがコードとして表現されていることを実感してください。

このステップで、Penpotのデザイナー向けUIと、コードとの連携の基礎を理解できます。リアルタイムコラボレーションを試すために、もし可能であれば同僚と同時に同じファイルを開いてみてください。

ステップ3: Penpot APIを試す簡単なスクリプトを作成する

開発者としてPenpotの真価を体験するために、APIを叩く簡単なスクリプトを作成してみましょう。

APIトークンの生成: ステップ2で作成したPenpotインスタンスにログインし、ユーザー設定からAPIトークンを生成し、控えておきます。
プロジェクトIDの確認: 作成したプロジェクトのURLからプロジェクトID（例: http://localhost:9001/#/project/PROJECT_ID_HERE）を控えておきます。

デザイントークン取得スクリプトの実行: 以下のコマンドをターミナルで実行し、デザイントークンがJSONとして出力されることを確認します。YOUR_API_TOKEN と YOUR_PROJECT_ID は、先ほど控えた値に置き換えてください。

# `jq` がインストールされていることを確認してください (brew install jq / apt install jq)
PENPOT_API_TOKEN="YOUR_API_TOKEN"
PENPOT_PROJECT_ID="YOUR_PROJECT_ID"
TOKENS_OUTPUT_FILE="my-penpot-tokens.json"

curl -s -H "Authorization: Bearer $PENPOT_API_TOKEN" \
     "http://localhost:9001/api/v1/projects/$PENPOT_PROJECT_ID/design-tokens" \
     -o "$TOKENS_OUTPUT_FILE"

echo "デザイントークンを $TOKENS_OUTPUT_FILE に保存しました。"
cat "$TOKENS_OUTPUT_FILE" | jq .

このステップで、Penpotが提供するデザインデータをプログラム的に利用できることを体感できます。ここからさらに、CI/CD連携やカスタムプラグイン開発へと発展させていくことが可能です。

Penpotを今日から活用し、デザインと開発の新しいワークフローを構築しましょう。

Penpotの使い方完全ガイド【インストールから応用まで】

Penpotの使い方完全ガイド【インストールから応用まで】

Penpotとは

インストール方法

1. Penpotリポジトリのクローン

2. ディレクトリへの移動

3. Penpotインスタンスの起動

4. 起動確認

5. Penpotの停止

基本的な使い方

1. Penpotインスタンスの起動と停止

2. プロジェクト内のデザインアセットをプログラムで取得する

3. デザイントークンをプログラムで取得する

便利な使い方・応用例 3選

1. CI/CDパイプラインへのデザインアセット自動組み込み

2. デザイントークンを活用したテーマ切り替え機能の実装

3. プラグイン開発によるカスタムワークフローの構築

他ツールとの組み合わせ

1. GitHub / GitLab (バージョン管理システム)

2. VS Code (コードエディタ)

3. Storybook (コンポーネントライブラリ)

4. Jira / Asana (プロジェクト管理ツール)

よくある設定・カスタマイズ

1. 環境変数の設定 (.env ファイル)

2. ポート番号の変更 (docker-compose.yaml)

3. APIキーの管理と利用

4. プラグインのインストールと開発環境

今日からできる実行プラン

ステップ1: Penpotインスタンスを立ち上げる

ステップ2: サンプルプロジェクトを作成し、基本操作を試す

ステップ3: Penpot APIを試す簡単なスクリプトを作成する

参考文献

1. 環境変数の設定 (`.env` ファイル)

2. ポート番号の変更 (`docker-compose.yaml`)