コンテンツにスキップ

Code2Des Page Import — 使い方

既定では設定したフォルダー内の静的ページをすべて取り込みます。特定の URL だけを選択することもできます。各画面の DOM 情報、スクリーンショット、画像を取得・アップロードし、Page Import の完了を待ちます。取得は手元の端末で行うため localhost にも対応します。Figma レイヤー生成、整理、ライブラリ生成は実行しません。

セットアップ

script/code2des-page-import/ フォルダー全体を .env.example も含めてフロントエンドのリポジトリ直下に code2des-page-import/ としてコピーします。

Node.js 22 以降を使用し、依存パッケージをインストールします。

npm install --save-dev @playwright/test sharp undici

既定では Chrome を使用します。Playwright Chromium を使う場合は npx playwright install chromium を実行し、PLAYWRIGHT_CHANNEL=bundled を設定します。

package.json に追加します。

{
  "scripts": {
    "guinness:code2des-page-import": "node code2des-page-import/import.mjs",
    "test:guinness-code2des-page-import": "node --test code2des-page-import/__tests__/*.test.mjs"
  }
}

フロントエンドを開発コマンドで起動し、code2des-page-import/.env.example を code2des-page-import/.env にコピーして設定します。

設定 値
GUINNESS_API_URL 接続先バックエンド（末尾 /api/v1 も可）
GUINNESS_USER_TOKEN 対象プロジェクトへの書き込み権限を持つ有効なユーザートークン
GUINNESS_ORGANIZATION_ID 対象の組織 ID
GUINNESS_PROJECT_ID 対象のプロジェクト ID
PAGE_IMPORT_BASE_URL ポート番号を含むアプリのベース URL
PAGE_IMPORT_PAGES_PATH フロントエンド直下からの相対パス（例: src/app/proto-pages）
PAGE_IMPORT_ROUTES_FILE 任意の JSON 配列または1行1ルートのファイル。フォルダー探索の代わりに使用

.env と生成物はコミットしないでください。ローカルテスト用の認証情報はローカル環境専用です。

取得とインポート

code2des-page-import/.env で既定の対象を設定します。

PAGE_IMPORT_BASE_URL=http://127.0.0.1:3000
PAGE_IMPORT_PAGES_PATH=src/app/proto-pages

# 取得・アップロードせず URL 一覧だけを確認
npm run guinness:code2des-page-import -- --list

# 既定: 設定フォルダー内の全静的ページを取り込む
npm run guinness:code2des-page-import

# 指定した画面のみ（フォルダー探索より優先）
npm run guinness:code2des-page-import -- --pages /proto-pages/faq/cm_ftr_faq01,/des2code/AC_RGST01

# 今回だけ対象フォルダーを変更
npm run guinness:code2des-page-import -- --pages-path src/app/proto-pages/faq

Next.js App Router の src/app または app を探索します。サブフォルダー指定時も URL の親パスを保持します。ルートグループは URL から除き、private フォルダー、parallel slot、intercepting route は対象外です。[id] などの動的テンプレートは警告付きでスキップします。具体的な URL を --pages または --routes-file routes.json（例: ["/products/123", "/products/456"]）で指定してください。ルートファイルは他のフレームワークにも使えます。フォルダー未設定時はアプリ全体が対象です。旧 PAGE_IMPORT_URL はベース URL の代替設定です。1ページ指定には --url を使います。

# アップロードせず取得結果だけを確認
npm run guinness:code2des-page-import -- --dry-run

# デスクトップ画面
npm run guinness:code2des-page-import -- \
  --url http://127.0.0.1:3000/example \
  --name "Example desktop" --width 1440 --height 900 \
  --output-dir code2des-page-import/output/example-desktop

# 同じ URL のモバイル画面を別途取得
npm run guinness:code2des-page-import -- \
  --url http://127.0.0.1:3000/example \
  --name "Example mobile" --width 390 --height 900 \
  --output-dir code2des-page-import/output/example-mobile

画面を順番に処理し、画面ごとに新しい Page Import ID を作成します。実行ごとに一意の run-* フォルダーを作り、番号別の画面フォルダーと、各画面の処理後に更新する batch-report.json を保存します。成功した画面の import-report.json には status: "1" が記録されます。失敗を記録して残りの処理を続け、1件でも失敗すると終了コードが非ゼロになります。HTTP エラーページは取り込みません。再実行は再開ではなく新規取り込みです。--dry-run は全選択ページをアップロードせず取得し、--list は URL 一覧だけを表示します。描画待ちには --ready-selector と --settle-ms を指定できます。

完全にクリップされた要素、透明な要素とその子孫、画面外の固定オーバーレイは除外します。スクロール先の通常コンテンツと、表示中の疑似要素の背景画像は取得します。初期表示の静的な取得のみで、画面遷移や操作状態の探索は行いません。CSS/JavaScript のソースは送信しません。3 MB を超える画像と動画は除外し、情報・スクリーンショットは1オブジェクト20 MB、全体50 MBが上限です。警告と画像で欠落や切り取りを確認してください。

Figma で使用する

  1. 保存済みの Figma ファイルで更新版 Guinness プラグインを開き、サインインします。
  2. スクリプトと同じバックエンド環境・組織・プロジェクトを選びます。
  3. Code2Des → 取り込み済み（Existing imports）で取り込みを更新（Refresh imports）を選びます。
  4. 完了済みの画面を選択します。名前、URL、サイズ、作成日時で区別でき、さらに読み込む（Load more）で過去の取得を表示できます。
  5. 生成（Generate）を選びます。保存したデータを使用し、通常の Code2Des フローで編集可能なフレームを追加します。localhost の URL は再取得しません。

1バッチ最大500画面です。デスクトップ版とモバイル版は別々に選択できます。ローカルで取り込んだ画面はデプロイ先環境に接続したプラグインには表示されません。処理中・失敗した取得も表示されないため、実行結果を確認し、アップロード失敗時は新規実行で再試行してください。

配置とフォントの扱いは Code2Des を参照してください。デザインシステム生成は別の操作です。