Skip to content

Guinness Figma Plugin — Setup Guide

Summary

The Guinness Figma plugin connects the current Figma file to a Guinness organization and project. The panel carries one tab per conversion direction — WF → Design, Design → WF, Code → Design, Code → WF — plus an Account tab holding identity and the workspace they all share. This guide explains how to build and load the development plugin, connect it to an environment, and complete the initial workspace setup.

What you need

  • The Figma desktop application and permission to load development plugins.
  • Access to the guinness-figma-plugin source repository.
  • Node.js and npm.
  • A Guinness account with access to the required organization and project.
  • A Figma personal access token for your own account, so server-side generation can read the files you can open.
  • Network access to the selected Guinness environment.
  • For Code2Des, network access to the environment's S3 origin so presigned images can be downloaded.

Warning

Do not put a user password, access token, or other secret in .env. The plugin obtains its user token through the sign-in form. .env contains only build-time endpoint configuration.

Install the source dependencies

From the plugin repository:

cd guinness-figma-plugin
npm install
cp .env.example .env

The .env file is ignored by Git. Confirm that it remains untracked before sharing or committing other changes.

Configure the environment

Set these values in .env:

Variable Required Purpose
VITE_BACKEND_BASE Yes Backend URL including its deployment stage, without /api/v1 or a trailing slash. It is embedded in the plugin UI.
VITE_DEBUG_API_LOGGING No Set to true while diagnosing API requests; otherwise use false.
WF2DES_BACKEND_DOMAIN Yes Backend origin only—scheme and host, with a port only when needed. It is written into Figma's network allowlist.
WF2DES_S3_DOMAIN Code2Des S3 origin only used by the presigned image URLs. It is written into Figma's network allowlist.

VITE_BACKEND_BASE includes the API Gateway stage, while WF2DES_BACKEND_DOMAIN must not include a path. For example, the current dev configuration is:

VITE_BACKEND_BASE=https://d5tms1w7bl.execute-api.ap-northeast-1.amazonaws.com/dev
VITE_DEBUG_API_LOGGING=false
WF2DES_BACKEND_DOMAIN=https://d5tms1w7bl.execute-api.ap-northeast-1.amazonaws.com
WF2DES_S3_DOMAIN=https://dev-guinness-backend.s3.ap-northeast-1.amazonaws.com

Check basic connectivity before building:

curl https://d5tms1w7bl.execute-api.ap-northeast-1.amazonaws.com/dev/api/v1/ping

The expected response is pong.

Build the plugin

Create a complete one-shot build:

npm run build

The build type-checks the source and generates dist/plugin.js, dist/index.html, and dist/manifest.json. For active development, use:

npm run dev

This watches both plugin bundles, but environment and manifest changes still require a fresh build and plugin reload.

Important

Environment values are embedded at build time. Editing .env does not update an already-built plugin. Run npm run build again whenever an endpoint, domain, port, or debug setting changes.

Load it in Figma

  1. Open the Figma desktop application and a Figma design file.
  2. Choose Plugins → Development → Import plugin from manifest….
  3. Select guinness-figma-plugin/dist/manifest.json.
  4. Run Guinness from the Development plugins list.

After rebuilding, close the existing plugin panel and run the development plugin again. Re-import the manifest when its network domains changed. If Figma continues using an older configuration, remove the development plugin entry and import the generated manifest again.

Sign in and select a workspace

Signing in replaces the sign-in form with the tab strip. The workspace every tab runs against is set on the Account tab and read back from the header bar.

  1. Enter your Guinness account email and password, then select Sign in.
  2. Open the Account tab.
  3. Confirm that Workspace → Organization shows the expected organization. It is assigned by the signed-in account and cannot be changed in the plugin.
  4. Select the project that should own generated records and imported assets. The same project can be switched from the header bar, which stays visible on every tab.
  5. Confirm the Figma file value.
  6. Under Figma access, paste a Figma personal access token and select Save token.

Generation reads the source frame from Figma on the server using your own Figma token, so it can only reach files you can already open. Create the token in Figma under Settings → Security → Personal access tokens. The stored token is write-only: the plugin reports whether a token is registered and when it was last validated, never the value. The section can only check a token once a project is selected, so complete step 4 first.

For a published private organization plugin, the Figma file key is detected automatically. A locally imported development plugin may not receive figma.fileKey; in that case, paste the key from the Figma file URL into Figma file:

https://www.figma.com/design/<figma-file-key>/<file-name>
                             ^^^^^^^^^^^^^^^^

The session, selected project, active tab, and development file-key override are stored in Figma client storage and restored when the plugin is reopened. Sign out before changing accounts or using a shared machine.

The panel's tabs

Each conversion direction is its own tab, and one tab is open at a time:

Tab What it converts What it needs to start
WF → Design Builds a hi-fi design from a wireframe frame. One wireframe frame selected on the canvas.
Design → WF Builds a wireframe from a design frame. One design frame selected on the canvas.
Code → Design Captures a live page and rebuilds it as a native design. A public page URL, or a completed page import in the selected project.
Code → WF Captures a live page and rebuilds it as a wireframe. A completed page import in the selected project.
Account Not a conversion. Signed-in account, interface language, Figma access token, and the shared workspace. —

Two tabs can expect opposite inputs from the same canvas—WF → Design wants a wireframe frame where Design → WF wants a design frame—so confirm the open tab before selecting a frame and generating.

Logs sits below the active tab and keeps its entries across a tab switch, so a failed run can be read after moving on.

Verify the setup

The setup is ready when:

  • The tab strip appears with WF → Design, Design → WF, Code → Design, Code → WF, and Account.
  • The header shows the intended project and the open file's key.
  • Account → Workspace shows the intended organization and project rather than a local smoke project.
  • Account shows the intended signed-in email, and Figma access reports a registered token.
  • No API or network-domain error appears in Logs.
  • The Code → Design tab can list completed imports or import a public page.
  • A generated Code → Design result displays its captured images rather than empty placeholders.

Continue with Code2Des — How to Use to import and generate a page.

Troubleshooting

Sign in keeps loading Check VITE_BACKEND_BASE. A stale tunnel port, an accidental line break in .env, or a missing API Gateway stage can leave the request waiting on the wrong address. Verify /api/v1/ping, correct .env, rebuild, and reload the plugin.

A local organization is still displayed The old bundle or its persisted local session is still active. Sign out from Account, rebuild, close the panel, and re-import dist/manifest.json.

Invalid credentials Confirm the complete account email and use the current password. Do not include an email: or password: label when copying credentials. Never paste a password into documentation or chat.

No projects are available The account is authenticated but has no visible project in its organization. Ask an administrator to grant project access, then sign out from Account and back in.

Figma access reports no token, or generation cannot read the source file Server-side generation uses your own Figma token, so a missing or revoked token leaves it unable to open the file. Select a project, then register a current personal access token under Account → Figma access.

Images are missing or Figma reports a blocked domain Confirm that WF2DES_S3_DOMAIN matches the origin in the backend's presigned URLs. Rebuild and re-import the manifest after changing it.

An environment change has no effect Inspect dist/manifest.json and confirm its networkAccess.allowedDomains, then search dist/index.html for the staged backend URL. If either is stale, rebuild before reopening the plugin.

Security notes

  • Never commit .env, account passwords, tokens, or captured authentication responses.
  • Sign out to remove the saved Guinness session from Figma client storage.
  • Presigned Code2Des image URLs are temporary and should not be copied into documentation.