Skip to main content
Gradial allows teams to generate production-ready CMS pages directly from Figma files or creative briefs. With just a few clicks, you can skip handoffs and reduce production time by over 75%.

​
Overview

The Figma integration enables you to:
  • Generate CMS pages directly from high-fidelity Figma designs
  • Start from creative briefs or wireframes to scaffold CMS content
  • Automatically detect and reuse assets from your DAM
  • Preview live page output from imported designs
This integration eliminates redundant back-and-forth between designers, developers, and content authors by converting designs into live CMS structures.

​
What You Can Do

​
Authentication Methods

Gradial supports three ways to connect Figma: For most teams, OAuth 2.0 is the recommended approach. It provides more granular permission control, better security hygiene, and makes it easier to manage access centrally if team members change. If your organization prefers token-based setup, use a plan access token rather than a personal access token where your Figma plan supports it. Plan access tokens are managed by plan administrators and are not tied to an individual user, so they don’t break when someone leaves the organization. They also support longer expirations (up to 1 year, versus 90 days for personal access tokens) and can be scoped to specific files, folders, teams, or workspaces.

​
How the Integration Fits Together

Before starting setup, it helps to understand how the pieces connect:
  1. Credentials are created in Figma first. For OAuth 2.0 this is a Figma OAuth app; for token-based setup it is a plan access token or personal access token. Either way, this is what authorizes Gradial to connect to your Figma organization and defines the scopes — what Gradial is permitted to do.
  2. A service account is identified (OAuth 2.0). When connecting in Gradial’s settings, you specify a Figma account that all Gradial tasks will be executed on behalf of. With a plan access token, activity is attributed to the token instead, so no service account is needed. This is the account that will appear in Figma’s audit logs for any activity Gradial performs.
  3. The integration is created once at the organization level under Settings → Integrations.
  4. It is then assigned to one or more Environments under Settings → Environments. This makes it available to all Workspaces within those Environments.
  5. Users interact with it through the agent — there is no separate Figma panel. Once the integration is active in an Environment, users simply paste a Figma URL into the agent chat to begin working with a design.

​
Step 1: Create the Figma OAuth App

Your Figma admin creates the OAuth 2.0 app in Figma first. This is what authorizes Gradial to connect to your Figma organization and defines the permissions it has. Complete this step while logged in to Figma as an admin.
  1. Go to Figma Developer Settings and navigate to My apps → Create new app.
  2. Give the app a descriptive name (e.g., Gradial Integration – [Your Company Name]).
  3. Under Redirect URLs, add the following URL exactly as shown:
  1. Enable the required permissions. Gradial requests the following scopes:
FILES & CONTENT
  • file_content:read — Read your design files, pages, and layers
  • file_metadata:read — Access file names, thumbnails, and edit history
  • file_versions:read — View saved versions of your files
COMMENTS
  • file_comments:read — Read comments left on designs
  • file_comments:write — Post and manage comments
DEV RESOURCES
  • file_dev_resources:read — Read developer handoff annotations
  • file_dev_resources:write — Add developer handoff annotations
LIBRARIES
  • library_assets:read — Access published component assets
  • library_content:read — Read shared component libraries
  • team_library_content:read — Access team-wide design libraries
ACCOUNT & PROJECTS
  • current_user:read — Identify the connected Figma account
  • projects:read — List available projects and files
  1. Under Publish, select Private.
  2. Save the app. Figma will display a Client ID and Client Secret — copy both and store them securely immediately.
The client secret is shown only once at creation time. Store it in your secrets manager before closing this screen. If it is lost, you will need to regenerate it and reconnect the integration in Gradial.

​
Step 2: Identify the Account Gradial Will Act On Behalf Of

When you connect Figma in Gradial’s settings, you will specify a Figma account that all Gradial tasks will be executed under. This is the account Gradial uses when reading files, accessing dev resources, and performing any actions in Figma — and it is the account that will appear in Figma’s audit logs for any activity Gradial performs. We strongly recommend using a dedicated service account rather than an individual’s personal Figma account. Here’s why: To set up the service account:
  1. Create a Figma account using a shared team email address — most teams reuse the same service account email they use for other integrations like their ticketing system (e.g., [email protected]). This avoids creating and managing multiple service identities.
  2. Have your Figma admin assign this account a Dev seat. A Dev seat covers everything Gradial needs today, including access to Dev Mode, design files, and developer handoff resources.
  3. Add the service account to the relevant Figma teams or projects so it has access to the files Gradial will need to read.
A Dev seat is sufficient for Gradial’s current needs and is slightly cheaper than a Full seat, while sharing the same API rate limits. A Full seat is ideal if your organization plans to use additional Figma features beyond what Gradial requires. Your Figma admin should keep this in mind when planning seat allocations. See Figma’s pricing page for a full breakdown of seat types.

​
Step 3: Add the Integration in Gradial

With the OAuth app created and your service account ready, a Gradial administrator can now complete the connection.
  1. In Gradial, go to Settings → Integrations.
  2. Find Figma in the list of available integrations and click + Add.
  3. In the Add Figma Integration dialog, enter the Client ID and Client Secret from Step 1.
  4. When prompted to specify the account Gradial will act on behalf of, sign in using the service account credentials set up in Step 2.
  5. Once authorized, the integration will appear under Existing Integrations.
At this point the integration exists at the organization level but is not yet available to any Workspaces. Proceed to Step 4.

​
Step 4: Assign the Integration to an Environment

A single Figma integration can be assigned to multiple Environments. Each Environment you assign it to will make the integration available to all Workspaces within that Environment.
  1. In Gradial, go to Settings → Environments.
  2. Select the Environment you want to enable Figma for.
  3. Locate the Figma integration in the available integrations list and add it to the Environment.
  4. Repeat for any other Environments that need access.
If a Workspace isn’t seeing the Figma integration, check that it has been assigned to the correct Environment here — this is the most common cause.

​
Step 5: Use Figma in the Agent

Once the integration is assigned to an Environment, users in any Workspace within that Environment can start working with Figma designs immediately. There is no separate import screen — just paste a Figma file URL directly into the agent chat. You can provide either a URL to the full Figma file, or a URL scoped to a specific page or node within the file. Using a scoped URL is useful when you want Gradial to reference only a particular frame, component, or section of a design rather than the entire file.
  • Full file URL — Gradial has access to all pages and frames within the file
  • Page or node URL — Gradial focuses only on the specific page or element you’ve linked to, which is helpful for large files or when working with a specific component in isolation
You can get a node-specific URL directly from Figma by right-clicking any frame or component on the canvas and selecting Copy link. Example prompts:
  • “Generate a CMS page from this Figma file: [URL]”
  • “Use this design as the basis for a new landing page: [URL]”
  • “Build out just the hero section from this frame: [URL]”
  • “What components are defined in this page? [URL]”
Gradial will retrieve the design and parse its frames, text, and images into structured CMS content.

​
Setup Instructions: Plan Access Token

Figma plan access tokens are supported using exactly the same setup as personal access tokens — the only difference is which token you paste into Gradial. The overall flow — add the integration, then assign it to Environments — is unchanged. Plan access tokens are available on Figma Organization and Enterprise plans, and only Figma organization administrators can create them. Creating one requires multi-factor authentication on the admin’s Figma account.

​
Step 1: Generate the Plan Access Token in Figma

Your Figma organization admin completes this step.
  1. Go to Figma’s token developer hub.
  2. In the upper-right corner of the table, click Generate REST API token.
  3. On Describe your token, enter a name and description (e.g., Gradial Integration), select an expiration of up to 365 days, then click Next.
  4. On Choose scopes, select the scopes Gradial needs — the same set listed in Step 1 of the OAuth setup — then click Next.
  5. On Choose resources, select either All resources or Only selected resources. If you scope the token, make sure every file, folder, team, or workspace Gradial needs to read is included.
  6. Click Create, then copy the token and store it securely immediately.
The token is shown only once at creation time. Store it in your secrets manager before closing the screen. If it is lost, generate a new token and re-enter it in Gradial.

​
Step 2: Add the Token in Gradial

  1. In Gradial, go to Settings → Integrations, find Figma, and click + Add.
  2. Enter the plan access token and click Connect.
  3. Assign the integration to the relevant Environments under Settings → Environments as described in Step 4 above.
Plan access tokens expire after the period the admin selected (maximum 1 year). Track the expiration date and generate a replacement before it lapses — when the token expires, the integration stops working for every Environment it is assigned to until a new token is entered.
Figma does not support comment-writing endpoints (file_comments:write) with plan access tokens. If your team relies on Gradial posting comments back into Figma, use OAuth 2.0 instead.

​
Setup Instructions: Personal Access Token

If OAuth 2.0 is not required for your environment and your plan does not support plan access tokens, you can connect using a personal access token. The overall flow — add the integration, then assign it to Environments — is the same.
  1. Go to Figma Developer Settings and generate a new personal access token under Personal Access Tokens.
  2. In Gradial, go to Settings → Integrations, find Figma, and click + Add.
  3. Enter your personal access token and click Connect.
  4. Assign the integration to the relevant Environments under Settings → Environments as described in Step 4 above.
Personal access tokens are tied to an individual Figma account and expire after a maximum of 90 days. If that person leaves the organization or their token expires, the integration will stop working for all Environments it is assigned to. For team environments, OAuth 2.0 with a service account is strongly preferred, with a plan access token as the next best option.

​
Figma API Rate Limits

Figma enforces API rate limits that vary by plan tier and seat type. Because Gradial accesses the Figma API using the credentials you connect — a service account, a plan access token, or a personal access token — the limits below apply to all Gradial activity for that connection.
Rate limits are set by Figma and are outside Gradial’s control. If your team runs high volumes of design-to-page workflows, ensure your service account is on a plan and seat type that supports the throughput you need.
Key takeaways:
  • Seat type matters more than plan tier. Dev and Full seats receive significantly higher per-minute limits than View or Collab seats at the same plan level. This is why Step 2 recommends assigning the service account a Dev seat.
  • View/Collab seats are unsuitable for high-volume use. At Professional, Organization, and Enterprise tiers, View/Collab seats are capped at 5–10 requests per minute regardless of tier — far lower than the Dev/Full equivalents.
  • Starter plans are limited across all seat types. Consider upgrading to Professional or higher if you anticipate sustained Gradial usage.
If you hit rate limits, Gradial will surface an error indicating the Figma API is unavailable. Reducing the frequency of design imports or upgrading the service account’s seat type will resolve this.

​
Troubleshooting

Figma file not accessible Ensure the service account has been granted access to the relevant Figma projects and files, and that the OAuth session or token is still active. Redirect URL mismatch error during OAuth Confirm that the redirect URL in your Figma app settings matches exactly: https://app.gradial.com/api/integrations/figma/callback Even a trailing slash difference can cause this error. Client secret was lost before saving Regenerate the client secret in your Figma app settings, then re-enter it in Gradial under Settings → Integrations → Figma. Integration not available in a Workspace The integration must be assigned to the Environment that the Workspace belongs to. Go to Settings → Environments, select the correct Environment, and confirm the Figma integration has been added. Integration stopped working after a team member left If the integration was set up using a personal account rather than a service account, it will need to be reconfigured. Follow the OAuth 2.0 setup steps above using a dedicated service account going forward, or switch to a plan access token, which is not tied to an individual user. Authentication errors after a period of working normally The access token may have expired — personal access tokens last a maximum of 90 days and plan access tokens a maximum of 1 year. Generate a replacement token in Figma and re-enter it in Gradial under Settings → Integrations → Figma. Figma file not accessible when using a plan access token If the token was created with Only selected resources, confirm the file’s team, workspace, or folder is included in the token’s resource allowlist. Otherwise, generate a new token with the correct resources selected.

​
Support

Need help configuring or troubleshooting the integration? Contact your Gradial onboarding lead or email [email protected].