Code2Des Page Import — How to Use

The script imports all static application pages under the configured folder by default, or only selected routes. For each page it uploads DOM evidence, a screenshot, and image assets, then waits for Page Import completion. It supports localhost routes because capture runs on your machine. It does not generate Figma layers or run organization or library jobs.

Setup

Copy the complete script/code2des-page-import/ folder, including .env.example, into your frontend repository root as code2des-page-import/.

Use Node.js 22 or later and install the script dependencies:

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

Chrome is used by default. To use Playwright Chromium instead, run npx playwright install chromium and set PLAYWRIGHT_CHANNEL=bundled.

Add these package scripts:

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

Start your frontend using its development command, then copy code2des-page-import/.env.example to code2des-page-import/.env. Configure:

Setting	Value
GUINNESS_API_URL	Your backend environment, optionally ending in /api/v1
GUINNESS_USER_TOKEN	Current user bearer token with write access to the target project
GUINNESS_ORGANIZATION_ID	Target organization ID
GUINNESS_PROJECT_ID	Target project ID
PAGE_IMPORT_BASE_URL	Running application base URL, including its port
PAGE_IMPORT_PAGES_PATH	Folder relative to the frontend root, e.g. src/app/proto-pages
PAGE_IMPORT_ROUTES_FILE	Optional JSON array or newline list of concrete routes, replacing folder discovery

Keep .env and generated output out of version control. Local test credentials are only for your local environment.

Capture and import

Set the default source in code2des-page-import/.env:

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

# Preview the full route list without capture or upload
npm run guinness:code2des-page-import -- --list

# Default: import every static page under PAGE_IMPORT_PAGES_PATH
npm run guinness:code2des-page-import

# Selected routes only (overrides folder discovery)
npm run guinness:code2des-page-import -- --pages /proto-pages/faq/cm_ftr_faq01,/des2code/AC_RGST01

# Override the folder for this run
npm run guinness:code2des-page-import -- --pages-path src/app/proto-pages/faq

Discovery supports Next.js App Router (src/app or app). Nested folder imports preserve their full route prefix. Route groups are omitted from URLs; private folders, parallel slots, and intercepting routes are excluded. Dynamic templates such as [id] are skipped with a warning. Supply concrete dynamic routes through --pages or --routes-file routes.json (for example ["/products/123", "/products/456"]). A routes file also supports non-Next.js projects. Leaving the folder unset discovers the entire app directory. Legacy PAGE_IMPORT_URL is a base-URL fallback; use --url to select a single page.

# Optional: capture and inspect locally without uploading
npm run guinness:code2des-page-import -- --dry-run

# Import a desktop page
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

# Import a separate mobile capture of the same route
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

Pages run sequentially, with a new Page Import ID per page. Every invocation creates a unique run-* directory with numbered page directories and a batch-report.json updated after each page. Successful pages have status: "1" in their individual import-report.json. Failures are recorded and the remaining pages continue; any failed page makes the command exit nonzero. HTTP error pages are rejected. A rerun creates fresh imports rather than resuming. --dry-run captures all selected pages without uploading; --list only prints URLs. --ready-selector and --settle-ms can wait for client-rendered content.

Capture excludes fully clipped/transparent subtrees and offscreen fixed overlays, preserves below-fold content, and includes visible pseudo-element background images. Each run captures the initial page state; it does not discover navigation or interaction states. CSS/JavaScript source files are not uploaded. Images over 3 MB and videos are skipped; individual evidence/screenshot objects are limited to 20 MB and the full bundle to 50 MB. Inspect warnings and screenshots for omissions or clipping.

Use the capture in Figma

1. Open the updated Guinness plugin in a saved Figma file and sign in.
2. Select the same backend environment, organization, and project used by the script.
3. Open Code2Des → Existing imports, then Refresh imports.
4. Select the completed pages. Names, URLs, viewport sizes, and creation dates distinguish captures; Load more retrieves older imports.
5. Select Generate. The plugin uses the saved captures and adds editable frames through the normal Code2Des flow, without fetching the localhost URLs again.

Up to 500 pages can be generated in one batch. Desktop/mobile captures remain separate selections. Local imports do not appear in a plugin connected to a deployed environment. Pending or failed imports are not listed; check the script result and retry a failed upload as a new run.

See Code2Des for Figma placement and font handling. Design-system generation is a separate plugin action.