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

CapabilityDescription
CMS page generationConvert full-page Figma layouts into editable CMS pages
Creative brief parsingUse wireframes or annotated frames to scaffold content
Asset reuse detectionIdentify and reuse existing assets from your DAM
Preview supportRender real-time previews of pages based on Figma files

​
Authentication Methods

Gradial supports two ways to connect Figma:
MethodBest For
OAuth 2.0 (recommended)Teams and organizations — provides scoped, revocable access tied to a dedicated service account
Personal Access TokenIndividual users or quick setup — simpler but tied to a personal account
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.

​
How the Integration Fits Together

Before starting setup, it helps to understand how the pieces connect:
  1. A Figma OAuth app is created first. 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. When connecting in Gradial’s settings, you specify a Figma account that all Gradial tasks will be executed on behalf of. 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:
https://app.gradial.com/api/integrations/figma/
  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:
ConsiderationService AccountPersonal Account
Audit & loggingAll Gradial activity is clearly attributable to a system account, keeping personal activity separateActivity is mixed with the individual’s own work, making audits harder to interpret
LongevityIntegration stays active regardless of team changesIf the person leaves or loses their seat, the integration breaks for all Environments
Access controlPermissions are managed centrally and intentionallyPermissions may change unexpectedly based on the individual’s role
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.
Gradial may require a Full seat in the future as additional capabilities are introduced. 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: Personal Access Token

If OAuth 2.0 is not required for your environment, 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. 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.

​
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/ 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.

​
Support

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