For token-free analysis, use the canicode MCP server with the official Figma MCP, or the /canicode skill in Claude Code.

Token priority:

1. --token flag (one-time override)
2. FIGMA_TOKEN env var (CI/CD)
3. ~/.canicode/config.json (canicode init)

canicode analyze <url> --preset strict

Override rule scores, severity, node exclusions, and global settings:

canicode analyze <url> --config ./my-config.json

{
  "excludeNodeNames": ["chatbot", "ad-banner", "wip"],
  "gridBase": 4,
  "rules": {
    "no-auto-layout": { "score": -15, "severity": "blocking" },
    "default-name": { "enabled": false }
  }
}

See examples/config.json | docs/CUSTOMIZATION.md | Run canicode docs config

Add project-specific checks with declarative pattern matching:

canicode analyze <url> --custom-rules ./my-rules.json

[
  {
    "id": "icon-not-component",
    "category": "component",
    "severity": "blocking",
    "score": -10,
    "match": {
      "type": ["FRAME", "GROUP"],
      "maxWidth": 48,
      "maxHeight": 48,
      "hasChildren": true,
      "nameContains": "icon"
    },
    "message": "\"{name}\" is an icon but not a component",
    "why": "Icons that are not components cannot be reused consistently.",
    "impact": "Developers will hardcode icon SVGs instead of using a shared component.",
    "fix": "Convert this icon to a component and publish it to the design system library."
  }
]

Conditions use AND logic — all must match for the rule to fire. Available conditions: type, notType, nameContains, nameNotContains, namePattern, minWidth, maxWidth, minHeight, maxHeight, hasAutoLayout, hasChildren, minChildren, maxChildren, isComponent, isInstance, hasComponentId, isVisible, hasFills, hasStrokes, hasEffects, minDepth, maxDepth.

Combine with config overrides:

canicode analyze <url> --config ./config.json --custom-rules ./rules.json

Tip: Ask any LLM "Write a canicode custom rule that checks X" with the conditions above — it can generate the JSON for you.

See examples/custom-rules.json | docs/CUSTOMIZATION.md

Final Score = (Density Score × 0.7) + (Diversity Score × 0.3)

Density Score  = 100 - (weighted issue count / node count) × 100
Diversity Score = (1 - unique violated rules / total rules in category) × 100

Severity weights issues — a single blocking issue counts 3x more than a suggestion. Scores are calculated per category and combined into an overall grade (S/A+/A/B+/B/C+/C/D/F).

Weights and rule scores are validated through a 4-agent calibration pipeline. See docs/CALIBRATION.md for details.

The canicode-mcp server exposes two tools: analyze and list-rules.

Route A — Figma MCP relay (no token):

Claude Code → Figma MCP get_metadata → XML node tree
Claude Code → canicode MCP analyze(designData: XML) → result

Route B — REST API direct (token):

Claude Code → canicode MCP analyze(input: URL) → internal fetch → result

Route A requires two MCP servers (figma + canicode). Route B requires one + a saved token.

The analyze tool accepts designData (XML/JSON from Figma MCP) or input (Figma URL / fixture path). When both are provided, designData takes priority.

Save Figma file data as JSON for offline analysis:

canicode save-fixture https://www.figma.com/design/ABC123/MyDesign

Rule scores are validated against actual code conversion difficulty via a calibration pipeline. This runs inside Claude Code using /calibrate-loop — not exposed as a CLI command.

The pipeline uses 4 subagents:

1. Runner — Analyzes a fixture and extracts issue data
2. Converter — Converts flagged Figma nodes to code via Figma MCP
3. Critic — Reviews proposed score adjustments
4. Arbitrator — Makes final decisions and commits changes

git clone https://github.com/let-sunny/canicode.git
cd canicode
pnpm install
pnpm build

pnpm dev        # watch mode
pnpm test       # run tests
pnpm lint       # type check