Tidy for Figma

What is Tidy?

Tidy is the design-system context layer for AI work. It combines a Figma plugin, local Tidy API, and MCP server so tools like Claude Code, Cursor, Windsurf, and Claude Desktop can ask useful questions about your system instead of guessing from screenshots or pasted notes.

The goal is simple: turn your design system into something an AI assistant can query, inspect, and use.

The short version

Tidy is distributed to Master yearly members through two private repositories:

1. rominak/tidy is the core product: Figma plugin, local Tidy API, Tidy MCP server, CLI, audits, and generated design-system data.
2. rominak/qmd-tidy-mcp is the optional companion bridge for Master yearly members who also use QMD and want one assistant tool that merges Tidy context with QMD corpus matches.

This is similar in spirit to Figma Console MCP: the assistant gets structured design context instead of only visual guesses. The difference is that Tidy is focused on design-system health, naming, token discipline, component hygiene, and project memory. QMD is optional.

What it gives the assistant

Tidy is useful when the assistant needs to answer questions like:

• Which variables exist, and which ones look duplicated?
• Does this component follow our naming rules?
• Which components are missing descriptions?
• Where is token drift showing up?
• What changed in the design system, and why?
• Which rule should this new component follow?

Without Tidy, the assistant can only work from whatever you paste into the prompt. With Tidy, the assistant can ask for structured context when it needs it.

How the system works

Figma file
  ↓
Tidy Figma plugin
  ↓
Local Tidy API
  ├─ Tidy MCP server → Claude Code / Cursor / Windsurf / Claude Desktop
  └─ optional qmd-tidy-mcp → Tidy context + QMD matches

The Figma plugin is the design-side bridge. It reads component, variable, and audit data from the file.

The Tidy MCP server is the assistant-side bridge for core design-system operations. The optional QMD bridge adds a clean system_context tool so your AI tool can ask one design-system question and receive both structured Tidy context and matching project notes from QMD.

Capabilities

Design-system audit

• Component naming checks
• Variable naming checks
• Missing description detection
• Component hygiene review
• Library consistency checks

Structured context for AI

• Component and variable summaries
• Design-system health signals
• Project-specific rules and decisions
• Optional QMD matches from your local documentation corpus

Better AI output

• Fewer invented token names
• Fewer generic component suggestions
• More accurate design-system reviews
• Prompts that can reference the actual system instead of abstract rules

When to use it

Use Tidy when you want AI to work with your real design system, not a generic idea of one.

Good use cases:

• Auditing a Figma library before a release
• Preparing a component cleanup pass
• Reviewing token naming before syncing to code
• Giving Claude Code or Cursor context before generating UI
• Asking why a token, component, or rule changed
• Creating a design-system health report

Do not use it as a replacement for Figma’s own Dev Mode MCP. Use the official Figma MCP when the assistant needs to read selected frames or implementation details. Use Tidy when the assistant needs design-system structure, governance, audits, and memory.

Requirements

• Node.js 18+
• Figma desktop app
• Tidy Figma plugin installed locally
• Tidy local API running
• An MCP-compatible client: Claude Code, Cursor, Windsurf, Claude Desktop, or another client that supports local MCP servers

Optional QMD bridge:

• QMD CLI available in your PATH
• Master yearly access to the private qmd-tidy-mcp companion repository

Setup

1. Install the Tidy Figma plugin

Clone the Tidy repository and install dependencies:

git clone git@github.com:rominak/tidy.git
cd tidy
npm install
npm run build

In Figma:

1. Open Plugins > Development > Import plugin from manifest.
2. Select manifest.json from the Tidy folder.
3. Open your design-system file.
4. Run the Tidy plugin.

Keep the plugin running when you want live Figma context.

2. Start the local Tidy API

Tidy exposes local design-system context through a local API. The MCP bridge expects it at:

npm run api

http://localhost:9251

If your local API uses a different port, set TIDY_API_URL in the MCP config.

3. Add the core Tidy MCP server

For Claude Code:

claude mcp add tidy -s user -- node /absolute/path/to/tidy/dist/index.js

This is the core MCP server for Tidy.

4. Optional: install the QMD Tidy MCP bridge

Install the QMD Tidy MCP bridge only if you also use QMD and want assistant answers that combine Tidy graph context with QMD corpus matches.

git clone git@github.com:rominak/qmd-tidy-mcp.git
cd qmd-tidy-mcp
npm install
npm run build

Then add it to your MCP client config:

{
  "mcpServers": {
    "qmd-tidy": {
      "command": "node",
      "args": ["/absolute/path/to/qmd-tidy-mcp/dist/index.js"],
      "env": {
        "TIDY_API_URL": "http://localhost:9251",
        "QMD_BIN": "qmd"
      }
    }
  }
}

Restart your MCP client after saving the config.

Test it

Once the plugin and local API are running, ask your assistant:

Use Tidy to summarize the current design-system status.

If the optional QMD bridge is installed, ask:

Use system_context to explain what our design system says about danger/error naming.

Or:

Use system_context to find token drift and summarize the highest priority cleanup work.

If everything is connected, the assistant should either call the core Tidy tools or call system_context when the QMD bridge is installed.

Tool reference

system_context

The optional qmd-tidy-mcp repository adds system_context, which returns structured design-system context from Tidy, QMD search results, or both.

Argument	Type	Required	Default	Notes
query	string	yes	-	Natural-language design-system question
scope	"both" | "corpus" | "graph"	no	"both"	Which context layer to query
collection	string	no	all	Optional QMD collection scope
limit	number	no	5	Max QMD results, capped at 25

Example:

{
  "query": "which components are missing useful descriptions?",
  "scope": "both",
  "limit": 5
}

Distribution recommendation

For now, distribute Tidy as two private GitHub repositories:

• rominak/tidy for the Figma plugin, local API, audits, and design-system tooling.
• rominak/qmd-tidy-mcp for the Master yearly MCP bridge.

This keeps the plugin and the MCP bridge cleanly separated. Master yearly members can receive GitHub access, clone the repos, and follow the setup instructions above.

Later, the MCP bridge can move to an npx install:

{
  "mcpServers": {
    "qmd-tidy": {
      "command": "npx",
      "args": ["-y", "qmd-tidy-mcp"],
      "env": {
        "TIDY_API_URL": "http://localhost:9251",
        "QMD_BIN": "qmd"
      }
    }
  }
}

That will be easier for Master yearly members, but GitHub is the better first distribution path while the product is still changing.

Troubleshooting

The assistant does not see system_context

Restart your MCP client after editing the config. Most clients only load MCP servers on startup.

The graph context is empty

Check that the Tidy plugin and local API are running. The MCP bridge can start even if Tidy is unavailable, but it will return a warning instead of graph data.

QMD results are missing

Make sure qmd works in your terminal. If it is not in your PATH, set QMD_BIN to the absolute path.

Figma data looks stale

Re-run the Tidy plugin in the active Figma file and refresh the local API context before asking the assistant again.

Best for

• Design-system teams with large Figma libraries
• Teams preparing AI-assisted component documentation
• Designers who want Cursor or Claude Code to understand their real system
• Master yearly members who want local, private design-system context instead of a hosted black box