Aider + Figma — Pair-Coding UI from a Context Bundle

Aider is a terminal-based AI pair programmer. It reads files you specify, generates edits as unified diffs, and applies them directly to your codebase. Every change is reviewable before it lands. That diff-first workflow pairs well with token-aware design handoff — you can see exactly whether the generated code is using spacing.16 from the token file or has drifted to a hardcoded 16px.

This guide covers the full Aider + figmascope pipeline: generating the bundle, loading it into an Aider session, using Architect mode for the initial scaffold, and iterating with targeted edit prompts.

Prerequisites

Install Aider if you haven't already:

pip install aider-chat
# or
brew install aider

Aider supports multiple model backends. Examples here use Claude Sonnet via the Anthropic API, but the workflow is identical with OpenAI or local models.

export ANTHROPIC_API_KEY=sk-ant-...
# or OPENAI_API_KEY for GPT-4o

Step 1: Generate the bundle

Head to figmascope.dev, paste your Figma file URL, and click Export Agent Context. The exporter runs in your browser — your Figma personal access token stays in localStorage and never leaves your machine.

Download lands as context-bundle.zip.

Step 2: Unzip into your project

unzip ~/Downloads/context-bundle.zip -d ./design/

ls design/
# CONTEXT.md  _meta.json  components/  screens/  strings.json  tokens.json

Step 3: Launch Aider with bundle files in scope

Pass the bundle files you need on the command line. Aider loads them as read-context — the model can reference them but won't edit them unless you explicitly use /add to promote them to editable files.

aider \
  --read design/CONTEXT.md \
  --read design/tokens.json \
  --read design/strings.json \
  design/screens/home.json \
  src/screens/HomeScreen.kt

The pattern: --read for bundle files (context-only, not editable), positional args for the source files you want Aider to modify. This keeps the bundle clean — Aider's diff machinery won't try to edit tokens.json.

If you want Aider to create a new file rather than edit an existing one, just name the target path that doesn't exist yet. Aider will create it.

Step 4: Add reference PNGs

Aider can include images as context for multimodal models. Use the /add command after launch:

/add design/screens/home.png

The PNG is a 2× render from Figma. With a multimodal model (Claude Sonnet, GPT-4o), Aider includes it as a visual reference. Use it for sanity checks during review — the canonical spec is the JSON, not the image.

Step 5: Architect mode — initial scaffold

Aider's /architect command uses a two-step model: one pass to plan, one pass to implement. This is the right starting point for a full screen, where you want a coherent structure before editing individual pieces.

/architect Implement design/screens/home.json as a Jetpack Compose screen.

Context:
- Read CONTEXT.md for framework constraints and target conventions.
- All spacing, color, and radius values come from tokens.json.
  Map token keys directly: spacing.16 → 16.dp, color.7f5cfe → Color(0xFF7F5CFE).
- Use string keys from strings.json via stringResource() with the fallback field as the literal fallback.
- IR node kinds: stack(vertical)→Column, stack(horizontal)→Row, overlay→Box,
  absolute→Box+Modifier.offset, leaf(text)→Text, leaf(rect)→Box+Modifier.background.
- Do not hardcode any value that has a token equivalent.

Output to: src/screens/HomeScreen.kt

Aider generates a plan first, shows it to you, then produces the diff. Review the plan — if the node mapping looks wrong, correct it before the implementation pass runs.

Step 6: Edit specific files with token references

After the scaffold is in place, use targeted /edit prompts to fix specific issues. This is where Aider's diff workflow shines — each edit is a small, reviewable change rather than a full regeneration.

The card component in HomeScreen.kt uses hardcoded 12dp for corner radius.
Check tokens.json for the correct radius token and replace it.

Aider produces a minimal diff: one or two lines changed, nothing else touched. You can see exactly what moved.

For a spacing audit across the whole file:

Audit every .dp value in src/screens/HomeScreen.kt against the spacing tokens in design/tokens.json.
Produce a diff that replaces any hardcoded value with its token equivalent where one exists.
Leave a // TODO comment for any value that doesn't match a spacing token.

Step 7: Review diffs against the spec

Aider's diff view is the review surface. Before accepting any change, check:

Do added lines reference token keys, not literal values?
Do string literals appear in strings.json, or are they hardcoded UI copy?
Does the node nesting in the generated code match the parent-child order in the IR JSON?

If a diff looks wrong, reject it with n at the prompt and tell Aider what to fix. The short feedback loop — prompt, diff, accept/reject, refine — means you catch drift immediately rather than after a big block of code lands.

Why Aider's diff workflow pairs well with the bundle

Token drift is visible in diffs. If a generated line says color = Color(0xFF7F5CFE) instead of color = tokens.colorPrimary, you see it before it merges. There's no "check it later" — the review happens inline.

Iterative refinement is cheap. You're not regenerating the full screen on every change. Each follow-up prompt produces a targeted diff. The bundle provides the stable context; Aider provides the surgical editing.

The bundle is version-controlled alongside the code. When the design updates, re-export the bundle from figmascope, diff it against the previous version, and ask Aider to apply only the changed nodes. The workflow scales across multiple design iterations without full reimplementation.

Common patterns and pitfalls

Don't add all screens at once. Pass one screen JSON at a time. More context isn't always better — Aider (and the underlying model) performs better with focused context than a dump of every screen in the file.

Use --read for the bundle, not positional args. If you pass tokens.json as a positional arg, Aider might try to edit it. Use --read to mark it read-only context.

Check _meta.json before the first prompt. The warnings array lists fills and effects the exporter couldn't fully resolve. Tell Aider about them upfront so it doesn't approximate silently:

cat design/_meta.json | python3 -c "import sys,json; w=json.load(sys.stdin).get('warnings',[]); print('\n'.join(w))"

Include any warnings in your architect prompt: "Skip hero-background fill — gradient not supported. Leave a TODO comment."

Prefer Aider for surgical, reviewable edits — and use Cursor or Claude Code when you need full-session context across many files. All three workflows start the same way: the main figmascope app handles export in your browser.