# remediation agent unable to read figma component specs error - how to fix it

## TL;DR

Give the agent a spec source that is not Figma's UI: use the Figma API with a file key and access token from the operator, or fall back to the design system's coded tokens. Agents cannot log into Figma and click around. One line of why: the agent needs structured spec data (colors, spacing, type), and screen-scraping the Figma UI is not a plan.

## The error, verbatim

```text
RemediationAgentError: unable to read Figma component specs
    tried: figma.com file URL (login wall), no API credentials configured
    needed: button component specs (padding, colors, type scale)

```

## Fix it step by step

### Step 1: Reproduce the access failure

```bash
node agent/remediate.js --spec figma | rg -i 'figma|login|credential' | head -5
```

Expected: The agent cannot reach the specs.

### Step 2: Check for API credentials

```bash
env | rg -i 'figma' | sed 's/=.*/=.../' 
```

Expected: Shows whether a Figma access token is configured (value redacted).

### Step 3: Wire the Figma API

```bash
rg -n 'figma|spec' agent/remediate.js | head -10
```

Expected: Add: fetch file nodes via the Figma API with the operator-provided token, cache the specs.

### Step 4: Re-run remediation

```bash
node agent/remediate.js --spec figma | tail -4
```

Expected: Agent reads component specs from the API and patches to spec.

### Step 5: Add a regression probe

```bash
node agent/run-audit.js --smoke | tail -3
```

Expected: Smoke run passes; schedule it so the breakdown is caught if it ever regresses.

## When to use this skill

- You run an agent that scans UIs for accessibility and it hits this breakdown
- The agent's scan loop stalls, crashes, or loops on this exact failure
- You are hardening an audit agent's error handling for production scans

## When NOT to use this skill

- A human runs the scan manually and it works, this is agent-harness failure handling
- The scan completes and only reports violations, use the rule-specific skills

## Compatibility

Remediation agent with Figma API access (file key plus access token, operator-provided). Coded design tokens are the fallback. Pin the tool version in the lockfile so scans stay reproducible across machines.

## Variant phrasings

### agent cannot access figma

Same block, same API wiring.

### figma login wall agent

Practitioner phrasing for the UI-scraping dead end.

### the breakdown hits other routes too

Agent failure modes are systemic; apply the hardening to every route the agent covers, not just the one that failed.

## Why it happens

Remediation patches for visual issues (contrast, spacing, type) need the design spec, and teams point agents at Figma file URLs. Agents cannot pass Figma's login, and the file UI is not machine-readable anyway. The Figma API exposes files, components, and styles as JSON with an access token the operator provisions once. Without it, the fallback is the coded design tokens (the CSS variables or theme file), which are often sufficient and always accessible. Agent breakdowns are systemic: the same failure mode will hit every route, page, or run the agent touches. Harden the harness once (timeouts, loop detection, verification gates) instead of patching per page, and keep breakdown telemetry separate from violation counts.

## Edge cases

- The access token is operator-provisioned, the agent must never ask the user to paste credentials into a chat.
- Cache spec fetches, Figma API has rate limits and specs change slowly.
- Coded tokens beat Figma specs for the agent: they are the actual values the app uses.
- Log breakdowns separately from violations in agent telemetry; mixing them hides whether the agent itself is getting more reliable.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_0j8nMIc3WJ0oYdh8CjzwtA