Mantine Architect

Generates production-ready Mantine v7 components from Figma designs using a 3-stage AI workflow (Plan → Act → Reflect), validated by Storybook and Playwright.

What it does

Point it at a Figma node. It:

Plans — queries Figma for exact design tokens, maps every variant, flags architectural conflicts (custom widgets Mantine already covers, absolute layouts that must become flow, WCAG contrast failures), and posts conflict comments back to Figma so designers see them inline.
Acts — generates four production files: <Name>.tsx, <Name>.module.css, <Name>.stories.tsx, <Name>.spec.ts.
Reflects — runs 11 automated quality gates (token compliance, PostCSS rules, Storybook autodocs, Playwright tests, visual snapshots, portal CSS scope) and fixes any failures before exiting.

Each stage runs as a separate Claude Code invocation. Stage 1 has Figma MCP access; Stage 2+3 receives only the approved plan — no re-querying Figma.

Model sharding keeps costs low: Stage 1 is always Sonnet (spatial inference + constitutional reasoning). Stage 2+3 is routed automatically — Haiku for simple components with no conflicts and a plan under 12 KB, Sonnet for anything with architectural conflicts or a complex plan. Conflict comments posted to Figma are also rewritten by a Haiku pass into assertive architect prose before posting.

For the full rules, patterns, and gotchas see CLAUDE.md.

Prerequisites

Requirement	Notes
Node.js 20+	Used by Claude Code CLI and the MCP server
Claude Code CLI	`npm install -g @anthropic-ai/claude-code`
Anthropic API key	console.anthropic.com → API keys
Figma personal access token	figma.com → Settings → Security → Personal access tokens

Setup

1. Clone and install

git clone git@github.com:sentient-studio/mantine-architect.git
cd mantine-architect
npm install

2. Install Playwright browsers

npx playwright install chromium

3. Set environment variables

The scripts resolve FIGMA_ACCESS_TOKEN from the environment. The Anthropic key is used by the Claude Code CLI internally.

export FIGMA_ACCESS_TOKEN="figd_your_token_here"
export ANTHROPIC_API_KEY="sk-ant-your_key_here"

Or add them to your shell profile (~/.zshrc, ~/.bash_profile).

Workflows

There are three ways to use Mantine Architect: conversational via the MCP server, single-component via the shell script, and parallel batch via the batch launcher.

Workflow 1 — MCP server (conversational, Claude Desktop)

The MCP server wraps the pipeline so you can drive it in conversation from Claude Desktop.

Build the server

cd mantine-architect-mcp
npm install
npm run build
cd ..

Add to Claude Desktop config

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mantine-architect": {
      "command": "node",
      "args": ["/path/to/mantine-architect/mantine-architect-mcp/dist/index.js"],
      "env": {
        "MANTINE_SCRIPTS_DIR": "/path/to/mantine-architect/scripts",
        "MANTINE_WORK_DIR":    "/path/to/mantine-architect",
        "FIGMA_ACCESS_TOKEN":  "figd_your_token_here",
        "ANTHROPIC_API_KEY":   "sk-ant-your_key_here"
      }
    }
  }
}

Restart Claude Desktop. The server exposes five tools:

Tool	Description
`mantine_plan`	Stage 1 — query Figma, produce architectural plan. ~5–10 min. Returns instantly on cache hit (<24 h).
`mantine_generate`	Stage 2+3 — write TSX/CSS/stories/spec. Skips Stage 1 if a plan exists. ~15–20 min.
`mantine_status`	Poll a running job — returns state, timestamps, recent log tail.
`mantine_get_plan`	Read the full plan markdown after `mantine_plan` completes.
`mantine_get_files`	Read all 4 generated files after `mantine_generate` completes.

Example conversation

You:    Generate a Select component from https://figma.com/design/abc/Test?node-id=78-1313

Claude: [calls mantine_plan] → job started, ~8 min

You:    Status?

Claude: [calls mantine_status] → complete. Calls mantine_get_plan.
        Plan found 3 variants, 1 ADAPT conflict (fixed width → responsive).
        Conflict comment posted to Figma. Shall I generate?

You:    Go ahead

Claude: [calls mantine_generate] → job started, ~18 min

Claude: [calls mantine_get_files] → complete. Here are the 4 files.
        All 11 quality gates passed.

Workflow 2 — Single component (shell script)

# Stage 1: plan only — review before generating
./scripts/dispatch-agent.sh MyComponent "https://figma.com/design/..." --plan-only

# Review the plan
cat logs/plan-MyComponent-<timestamp>.md

# Stage 2+3: generate (uses the plan from Stage 1)
./scripts/dispatch-agent.sh MyComponent "https://figma.com/design/..." --stage2

# Or run both stages in one shot (skips the review gate)
./scripts/dispatch-agent.sh MyComponent "https://figma.com/design/..." --auto-approve

Logs are written to logs/:

File	Stage
`logs/generate-<Name>-<ts>.log`	Stage 1 agent output
`logs/plan-<Name>-<ts>.md`	Extracted plan document
`logs/generate-<Name>-<ts>-stage23.log`	Stage 2+3 agent output

Workflow 3 — Batch (parallel Stage 1 for multiple components)

# Edit components.txt — one ComponentName,FigmaURL per line
./scripts/batch-generate.sh components.txt

Runs Stage 1 for all components in parallel, then opens an interactive review loop. The model used for Stage 2+3 is selected per-component based on plan complexity:

✅ Select   0🔴 1🟡 2🔵  ·  component set  ·  5 ambiguities  ·  14K
✅ Modal    1🔴 0🟡 1🔵  ·  single node    ·  8 ambiguities  ·  16K  ← REVIEW REQUIRED

[1/2]  Select  0🔴 1🟡 2🔵
   Launch Stage 2? [y/n/q]

[2/2]  Modal  1🔴 0🟡 1🔵  ← REVIEW REQUIRED
   Open full plan? [Y/n]
   Launch Stage 2? [y/n/q]

Stage 2+3 is never launched automatically from batch — each component requires explicit approval after reviewing its plan.

Quality gates

Run manually with:

./scripts/quality-gate.sh <ComponentName> [--skip-deps]

Also runs automatically as a pre-commit hook on any staged component files.

#	Gate	What it checks
1	Token Compliance	No hex codes, raw RGB, or bare `px` in CSS
2	File Integrity	All 4 files exist and are non-empty
3	PostCSS Standard	`rem()` spacing, `@mixin hover`, no bare `:hover`
4	Storybook Autodocs	`tags: ['autodocs']` present in story meta
5	Tracker Update	Component row present in `03-figma-links/components.md`
6	data-* Attributes	State props forwarded via `data-*` attributes
7	Size Variant Coverage	`data-size` in TSX, Sizes story, and spec (when `size` prop present)
8	Test Coverage	At least one test case in spec file
9	Dependency Audit	No missing packages or npm vulnerabilities
10	Visual Snapshot	`toHaveScreenshot` assertion present in spec
11	Portal CSS Variable Scope	Component-scoped CSS vars not leaked into portal classes

Model sharding

The pipeline uses different Claude models for different tasks to balance quality and cost:

Stage	Model	Rationale
Stage 1 (Plan)	`claude-sonnet-4-6`	Spatial inference, constitutional conflict detection, Figma MCP reasoning
Stage 2+3 — simple	`claude-haiku-4-5-20251001`	0🔴 0🟡 conflicts + plan < 12 KB — code gen from a complete spec is retrieval, not reasoning
Stage 2+3 — complex	`claude-sonnet-4-6`	Any BLOCK/ADAPT conflict or plan ≥ 12 KB — complexity warrants full reasoning
Stage 2+3 — escalation Step 1	`claude-sonnet-4-6`	`--escalate` flag: fresh Sonnet run after the 3-iteration self-healing cycle fails
Stage 2+3 — escalation Step 2	`claude-opus-4-5`	Break-glass only — fires if escalation Step 1 also fails; ~15× Haiku cost
PUSHBACK validation	python3 (no LLM)	Schema check, field validation, severity/category enum guard
PUSHBACK prose	`claude-haiku-4-5-20251001`	Rewrites dry `detail` fields into assertive architect persona before posting to Figma

The selected model is printed at Stage 2+3 launch:

Model: claude-haiku-4-5-20251001  (0🔴 0🟡 · 9K — routed to Haiku)
Model: claude-sonnet-4-6          (2🟡 conflicts — requires Sonnet)

Set SKIP_PUSHBACK_PROSE_REWRITE=1 to bypass the Haiku prose pass (CI / tests).

Escalation (`--escalate`)

When the normal 3-iteration self-healing cycle fails, escalation is a manual two-step escape hatch:

./scripts/dispatch-agent.sh Modal 'https://figma.com/design/...' --escalate

Step 1 retries with a fresh Sonnet context. If Step 1 also fails, Step 2 uses Opus. Escalation is never triggered automatically — Opus is break-glass only.

Running tests

# Start Storybook (required for Playwright)
npm run storybook

# Run Playwright tests in a second terminal
npm run test:playwright

# Playwright UI mode
npm run test:playwright:ui

Project structure

00-setup/           — Agent prompts and style guide (stage1-prompt.md, stage23-prompt.md,
                      AGENT-CLAUDE.md, style_guide.md)
01-golden-examples/ — Canonical reference components (Button, Card, TextInput, etc.)
02-generated/       — AI-generated components (one folder per component)
03-figma-links/     — components.md tracker (Figma URL → status)
.storybook/         — Storybook config
scripts/            — dispatch-agent.sh, batch-generate.sh, quality-gate.sh,
                      figma-pushback.sh, dependency-audit.sh
mantine-architect-mcp/ — MCP server source (TypeScript)
logs/               — Per-run logs and plan files

Tech stack

Layer	Package	Version
UI library	`@mantine/core`	^7
Icons	`@tabler/icons-react`	^3
Storybook	`@storybook/react-vite`	^8
Testing	`@playwright/test`	^1.51
A11y testing	`@axe-core/playwright`	^4.11
CSS pipeline	`postcss-preset-mantine`	—

Name		Name	Last commit message	Last commit date
Latest commit History 41 Commits
.claude		.claude
.storybook		.storybook
00-setup		00-setup
01-golden-examples		01-golden-examples
02-generated		02-generated
03-figma-links		03-figma-links
logs		logs
mantine-architect-mcp		mantine-architect-mcp
playroom		playroom
scripts		scripts
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
components.txt		components.txt
package.json		package.json
playroom.config.js		playroom.config.js
playwright.config.ts		playwright.config.ts
postcss.config.cjs		postcss.config.cjs
tsconfig.json		tsconfig.json
vitest.config.js		vitest.config.js

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Mantine Architect

What it does

Prerequisites

Setup

1. Clone and install

2. Install Playwright browsers

3. Set environment variables

Workflows

Workflow 1 — MCP server (conversational, Claude Desktop)

Build the server

Add to Claude Desktop config

Example conversation

Workflow 2 — Single component (shell script)

Workflow 3 — Batch (parallel Stage 1 for multiple components)

Quality gates

Model sharding

Escalation (`--escalate`)

Running tests

Project structure

Tech stack

Further reading

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

Mantine Architect

What it does

Prerequisites

Setup

1. Clone and install

2. Install Playwright browsers

3. Set environment variables

Workflows

Workflow 1 — MCP server (conversational, Claude Desktop)

Build the server

Add to Claude Desktop config

Example conversation

Workflow 2 — Single component (shell script)

Workflow 3 — Batch (parallel Stage 1 for multiple components)

Quality gates

Model sharding

Escalation (--escalate)

Running tests

Project structure

Tech stack

Further reading

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Escalation (`--escalate`)