For years, design-to-code AI has been the headline. Now consider reversing the direction: an AI coding agent working directly on an editable Figma component library.

Figma's remote MCP server can write real Figma nodes through its use_figma tool. This is different from importing a screenshot or converting HTML into unconnected shapes. It can create or update components, variants and variables, and it can use existing library content. But possible is not the same as reliable: will an agent reuse the right foundations, avoid duplicates and honor component contracts?

In this tutorial, we'll establish a small controlled test and audit the output. The aim isn't to produce the prettiest alert. It's to see whether a design system can supply enforceable constraints to an agent.

What you'll build

A StatusBanner Figma component family with three variants:

• Intent=Success, a confirmation with a success icon and title/message slots.
• Intent=Warning, cautionary guidance.
• Intent=Error, validation or failure feedback.

The component family should include real Figma components and a component set, not three independently drawn lookalikes, plus Auto Layout, existing semantic color variables, and a reusable icon instance where available.

The challenge: an existing test library owns the tokens and foundational components. The agent must inspect and reuse them rather than inventing arbitrary colors or duplicate icons.

Success criteria

1. Three actual variants belong to a StatusBanner component set.
2. Each variant uses horizontal Auto Layout; text content can grow without overlap.
3. Fills and text colors use existing semantic variables, not detached literals.
4. The icon, if provided as an approved component, is reused as an instance.
5. No new variable or icon family is created without approval.
6. The output is visually usable, and the agent reports missing dependencies rather than fabricating them.

These are proposed acceptance criteria for this tutorial, not findings from a completed run.

Prerequisites and access

• Figma: a Professional, Education, Organization or Enterprise plan with access to canvas writing, plus edit permission for the target file. Writing outside drafts requires a Full seat. The write feature is in beta and free during the beta period; Figma says it will become usage-based paid functionality later.
• Agent: Claude Code, with its official Figma plugin, or another supported MCP client. This article demonstrates Claude Code.
• Server: the remote Figma MCP server at https://mcp.figma.com/mcp. The local/desktop MCP server does not support writing to the canvas.
• Safety: a duplicated or disposable Figma Design file, never a production library on the first run.
• Test fixture: a local test file with sample semantic variables and an approved icon component. Naming conventions below are examples, not Figma defaults.

Official requirements: Figma: Write to canvas, Remote installation, Figma MCP FAQ.

1. Make a disposable Figma test library

Create a new Figma Design file named Agentic DS Lab, StatusBanner or duplicate a small, existing library. Use a page named Foundations and a page named Agent Experiments. Keep the experiment isolated from published components.

Create or confirm these semantic color variables in a local collection. Assign realistic values in your file; the values below are merely a reproducible fixture, not recommended brand colors:

Add one real Figma component called Icon/Status if you have an appropriate icon system. If your library uses different names, keep your names and update the contract below. We want to measure reuse, not force a fictional system.

Set a reasonable default width for a banner (for example, 360px) and plan to check its resizing behavior at 280px and 480px. Use text content long enough to wrap on narrower widths.

Important: the fixture itself is not proof that the agent used variables. After generation, inspect the resulting bindings in Figma.

2. Install and authenticate Figma's remote MCP integration

Figma recommends the official Claude Code plugin because it provides MCP connection settings and Figma skills, including figma-use.

# Run in your terminal with Claude Code installed.
claude plugin install figma@claude-plugins-official

Restart Claude Code. Inside Claude Code, run:

/plugin

Select the installed Figma plugin, connect and authenticate, and grant access in your browser. Verify its connection before proceeding.

If plugin installation is unavailable, Figma documents manual remote-server setup:

claude mcp add --transport http figma https://mcp.figma.com/mcp

Then restart Claude Code and use /mcp to authenticate. Manual server configuration does not install the Figma skills. For this experiment, prefer the official plugin or install the skills separately as documented.

Do not use http://127.0.0.1:3845/mcp for this tutorial: that is the desktop MCP server, which cannot write to canvas.

Source: Figma: Remote MCP server installation.

3. Write a machine-readable component contract

Create a folder for the experiment:

mkdir -p figma-agent-lab
cd figma-agent-lab

Create status-banner.contract.json:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "experiment": "status-banner-native-figma",
  "targetFile": "PASTE_FIGMA_FILE_URL_HERE",
  "targetPage": "Agent Experiments",
  "componentSet": "StatusBanner",
  "variantProperty": "Intent",
  "variants": ["Success", "Warning", "Error"],
  "layout": {
    "direction": "HORIZONTAL",
    "padding": { "horizontal": 16, "vertical": 12 },
    "gap": 12,
    "textWraps": true
  },
  "tokenMapping": {
    "Success": {
      "background": "color/feedback/success/background",
      "foreground": "color/feedback/success/foreground"
    },
    "Warning": {
      "background": "color/feedback/warning/background",
      "foreground": "color/feedback/warning/foreground"
    },
    "Error": {
      "background": "color/feedback/error/background",
      "foreground": "color/feedback/error/foreground"
    }
  },
  "reuse": {
    "preferredIconComponent": "Icon/Status",
    "createNewColorVariables": false,
    "createDuplicateIcons": false
  },
  "humanApprovalRequiredFor": [
    "missing-tokens",
    "new-global-components",
    "changes-outside-target-page"
  ]
}

The JSON is our experiment contract, not an official MCP API schema. The $schema property is descriptive here; the file is not itself validated against a published schema unless you create one. An agent reads it as instructions. It does not become automatically enforceable merely because it's JSON.

4. Add a repeatable agent skill (optional but recommended)

Figma documents custom skills as a way to package repeatable instructions. In this experiment, create .claude/skills/build-ds-component/SKILL.md inside your working project:

---
name: build-ds-component
description: Build a native Figma Design component in a test file, reusing existing design-system components and variables, with a post-write audit.
compatibility: Requires the Figma remote MCP server, official figma-use skill, and edit access to the target file.
---

# Build a Design-System Component

## When to use
Use when creating or updating native Figma components in the designated experiment file.

## Instructions
1. Load and follow Figma's `figma-use` skill before using `use_figma`.
2. Read the experiment contract and linked Figma file.
3. Inspect existing pages, component families, variables and available icon components.
4. Report exact variable/component matches and anything missing.
5. Do not create missing global variables or shared icon families without approval.
6. Create only on the `Agent Experiments` page. Do not modify existing library definitions.
7. Prefer existing component instances and bound semantic variables to visual lookalikes.
8. Create native components and a native variant set, using Auto Layout.
9. Inspect the resulting node types, property names, variable bindings and layout settings.
10. If an operation partially fails, inspect the file before retrying; do not create duplicates.
11. Produce an audit report with evidence, unverified items and exact node IDs.

## Edge cases
- Missing semantic variables: stop and ask for a mapping; never silently substitute literals.
- Missing approved icon: explain the limitation and await approval or use a no-icon variant.
- Existing `StatusBanner` component set: stop before overwriting; propose a safe alternative.
- Unsupported action: report it; do not replace native components with HTML imports or screenshots.

The first step is important: Figma identifies figma-use as the foundational skill for the use_figma tool. The custom skill doesn't replace it.

Reference: Figma: Create skills for the MCP server.

5. Run the actual creation prompt

In Figma, open the disposable test file, copy its URL, and replace PASTE_FIGMA_FILE_URL_HERE in the JSON contract. Then run Claude Code from your figma-agent-lab directory.

Paste this prompt:

Use the official Figma remote MCP integration and its figma-use skill.

Goal: Create a real native Figma `StatusBanner` component set in this file:
PASTE_FIGMA_FILE_URL_HERE

Read `status-banner.contract.json` and the build-ds-component skill first.

PHASE A, INSPECT, NO WRITES:
- Enumerate matching local components and semantic variables in the file.
- Confirm the `Agent Experiments` page exists.
- Check for any existing StatusBanner component set.
- List missing or ambiguous dependencies and stop if a required token is absent.
- Show the exact intended changes and ask for my approval.

PHASE B, WRITE AFTER APPROVAL:
- Use `use_figma` to create a native component set with Intent=Success,
  Intent=Warning and Intent=Error variants.
- Use horizontal Auto Layout with the specified padding and gap.
- Bind approved semantic variables to fills and text where supported.
- Reuse the approved icon component as a true instance, if available.
- Make title and description text editable and resize gracefully.
- Do not create a screenshot, HTML import, detached visual clone, new global
  token, or duplicate icon family.
- Do not change existing shared components.

PHASE C, VERIFY:
- Inspect node types, component-set membership, variant properties,
  auto-layout settings, variable bindings and instance references.
- Test or report the limits of width resizing at 280px and 480px.
- Give me the Figma URL and node IDs.
- Return an honest audit: PASS, FAIL or NOT VERIFIED per criterion.
- If something is unsupported, stop and explain rather than claiming success.

Why an inspection phase? A single unconstrained command can create duplicates or invent assets to satisfy the visual brief. We want the agent to discover the system before modifying it. It's slower, but it makes the experiment meaningful.

6. Understand what the agent is doing

Figma documents use_figma as a tool that runs Figma Plugin API code in the target file. For example, the underlying Figma Plugin API exposes native component creation:

// Illustrative Figma Plugin API operations, NOT a standalone script
// and NOT the syntax of a direct MCP tool call.
const banner = figma.createComponent();
banner.name = "StatusBanner / Intent=Success";
banner.layoutMode = "HORIZONTAL";
banner.itemSpacing = 12;
banner.paddingLeft = 16;
banner.paddingRight = 16;
banner.paddingTop = 12;
banner.paddingBottom = 12;

// Real production work must also create child nodes, load fonts,
// bind variables, build the component set, and verify the output.

This snippet demonstrates the class of native operations available. It deliberately isn't presented as a complete, tested plugin implementation; the remote agent/skill handles the actual operations. The use_figma tool is not the same thing as running the above TypeScript in a terminal.

Plugin API references: createComponent, Working with variables, setBoundVariable.

7. Audit the result in Figma

Do not judge success from a screenshot alone. Open the file and inspect the created object hierarchy. At minimum, verify:

If you cannot inspect a property programmatically, mark it NOT VERIFIED until checked manually. A screenshot is supporting evidence, never proof of variable binding.

Ask the agent to export an audit report as status-banner-audit.json using this format:

{
  "experiment": "status-banner-native-figma",
  "figmaFileUrl": "PASTE_RESULT_URL_HERE",
  "checks": {
    "nativeStructure": "NOT_VERIFIED",
    "variants": "NOT_VERIFIED",
    "autoLayout": "NOT_VERIFIED",
    "variableBindings": "NOT_VERIFIED",
    "iconReuse": "NOT_VERIFIED",
    "noUnauthorizedDuplicates": "NOT_VERIFIED",
    "resizeBehavior": "NOT_VERIFIED",
    "scopeSafety": "NOT_VERIFIED"
  },
  "evidence": [],
  "notes": "Replace statuses only after actual inspection and attach evidence."
}

This is an intentionally blank report template, not a result. If a check is partially met, record FAIL with a clear explanation rather than treating partial compliance as PASS.

8. Score the audit with a dependency-free script

Save this as audit.mjs. It validates that your audit file has exactly the expected statuses, prints a score, and refuses to call the experiment successful while anything remains unverified. The script checks the report, not Figma itself; it cannot independently prove that an agent's report is truthful.

import { readFileSync } from "node:fs";

const path = process.argv[2] ?? "status-banner-audit.json";
const report = JSON.parse(readFileSync(path, "utf8"));
const required = [
  "nativeStructure",
  "variants",
  "autoLayout",
  "variableBindings",
  "iconReuse",
  "noUnauthorizedDuplicates",
  "resizeBehavior",
  "scopeSafety"
];
const allowed = new Set(["PASS", "FAIL", "NOT_VERIFIED"]);

for (const key of required) {
  if (!allowed.has(report.checks?.[key])) {
    throw new Error(`Missing or invalid status: ${key}`);
  }
}

const statuses = required.map(key => report.checks[key]);
const passed = statuses.filter(s => s === "PASS").length;
const failed = statuses.filter(s => s === "FAIL").length;
const unknown = statuses.filter(s => s === "NOT_VERIFIED").length;

console.table(required.map(key => ({ check: key, status: report.checks[key] })));
console.log(`Passed ${passed}/${required.length}; failed ${failed}; unverified ${unknown}`);

if (failed || unknown) {
  console.error("Experiment is NOT verified as fully compliant.");
  process.exitCode = 1;
} else {
  console.log("Report claims all checks passed. Independently review its evidence.");
}

Run:

node audit.mjs status-banner-audit.json

Interpretation: 8/8 means your documented checks passed; it is not a scientific benchmark of model reliability. To make stronger claims, repeat the task on clean copies, save prompts and logs, and independently inspect each run.

9. Turn the experiment into a meaningful comparison

For a better follow-up, run two variants of the experiment on separate clean file copies:

• Run A, minimal context: only provide the visual description and target file.
• Run B, structured context: provide the full contract, library inspection instructions, and skill.

Keep model, task scope and allowed tools the same. Record whether the agent used actual components and variables, number of unauthorized duplicates, human interventions, elapsed time and the final audit. Note that the setups intentionally differ in instructions and context; this is an exploratory comparison, not a controlled causal study.

Capture screenshots of both files, the node trees and the binding panels. Record the generation process if you plan to post a demonstration. Do not publish a fabricated before/after image.

Results log, to fill in after testing

10. Failure modes worth publishing

Even if the experiment fails, it can teach us something useful.

The agent draws three attractive cards rather than a component set. It optimized for appearance instead of semantics. Inspect the node hierarchy and tighten the requirement for a COMPONENT_SET.

Colors look right but are not variable-bound. Matching a hex code isn't using the design system. Require binding verification.

It creates new success tokens instead of using the originals. The system context or naming is ambiguous, or the agent ignored a rule. Stop and inspect, rather than accepting the duplicate as success.

It creates an icon shape rather than reusing an icon component. Check the component reference and whether it had access to the approved library.

It fails on authentication or write permissions. Check that you're using the remote server, have edit access and meet the current seat requirements. Don't misinterpret an access issue as a model limitation.

It cannot confidently verify a result. That's useful evidence about tooling and observability. Mark the check NOT_VERIFIED.

11. What this means for design systems

The interesting question isn't whether an agent can draw a banner. Many tools can generate a visually convincing banner.

The bigger question is whether our design systems are structured well enough for software agents to make safe, inspectable contributions:

• Can an agent discover the canonical component and its constraints?
• Can it distinguish token values from token bindings?
• Can it avoid producing duplicate system primitives?
• Can it report provenance and support human review?
• Can the team detect drift before publishing changes?

The introduction of native canvas writes turns those questions into practical engineering and design-governance problems. It doesn't eliminate the need for designers; it changes which parts of the work are worth automating and which decisions need review.

The challenge: try this on a duplicate of your design system. Don't just ask whether the result looks good. Ask whether it actually belongs in the system.

Primary sources and further reading

1. Figma: Write to canvas. Feature capabilities, access requirements and write workflow.
2. Figma: Remote MCP server installation. Official Claude Code plugin, manual fallback and authentication.
3. Figma: Tools and prompts. The use_figma capabilities and why native writes differ from HTML import.
4. Figma: MCP FAQs. The use_figma and figma-use roles.
5. Figma: Create skills for the MCP server. Custom skill format and safe testing practices.
6. Figma: Structure your file for better code. Components, variables, naming and layout guidance.
7. Figma Plugin API: createComponent. Real native component creation.
8. Figma Plugin API: Working with variables. Variable binding semantics.

Experiment status

As of November 3, 2026. Figma's ability to write native components, component variants, variables, frames and Auto Layout through its remote MCP server is documented by Figma. The StatusBanner experiment above has not been run by the author, and no results are claimed. What you have just read is a reproducible experiment protocol, not a report of completed testing. Record actual results before publishing a demonstration or claiming success.

Confirm current beta access, client support and pricing before relying on this tutorial. We will add real screenshots, tested results and a link to the experimental Figma file once the runs are complete.