CanICode

0.12.3 verified Fri May 01 auth: no javascript

CanICode v0.12.3 is a CLI and MCP server that lints Figma designs for AI code-generation readiness. It runs 16 deterministic rules (no AI cost) across 6 categories (Pixel Critical, Responsive, Code Quality, Token Management, Interaction, Semantic) and automatically fixes issues via Figma API, enabling a roundtrip workflow. Requires Node.js >=22. Differentiators: rule scores are ablation-validated with 94% pixel accuracy using 5× fewer tokens than raw JSON, and the calibration pipeline uses pixel-level comparison (visual-compare) against community fixtures. Supports both capture-only (gotchas) and write-to-Figma (roundtrip) modes. Released frequently (every few weeks) under active development.

Common errors

error Error: Cannot find module 'canicode' ↓

cause Installed as global but used as local import without adding to package.json or running from wrong directory.

fix

Run 'npm install canicode' in your project and ensure node_modules contains it.

error TypeError: analyzer.analyzeFile is not a function ↓

cause Using outdated version <0.11.0 that did not export 'Analyzer' class.

fix

Update to v0.11.0+ with 'npm install canicode@latest'.

error Figma API error: 403 Forbidden ↓

cause Insufficient Figma token permissions (read-only token used for write operations).

fix

Generate a new personal access token with 'write' scope in Figma account settings.

Warnings

breaking v0.12.0 removed the '--api' flag from 'analyze' subcommand. Use 'FIGMA_TOKEN' env var or config file instead. ↓

fix Set FIGMA_TOKEN environment variable or use 'canicode init --token' to configure.

breaking v0.12.0 split 'canicode init' into interactive setup and separate 'token-refresh' command. The old non-interactive 'init --token' is removed. ↓

fix Run 'canicode init' interactively or use 'canicode token-refresh <token>' separately.

deprecated v0.11.0 deprecated direct export of 'RuleScore' type; use canonical types from '@canicode/types' if needed. ↓

fix Import from '@canicode/types' instead of 'canicode' for type-only imports.

gotcha The roundtrip writes to Figma may produce '📝 annotated the scene node' markers; this is correct behavior when writing to instance children. It does not mean failure. ↓

fix Review the annotation format; use 'allowDefinitionWrite' opt-in to propagate to component definitions.

Install

npm install canicode

yarn add canicode

pnpm add canicode

Imports

default
wrong
```
const canicode = require('canicode')
```
correct
```
import canicode from 'canicode'
```
ESM-only package; requires Node >=22. No default export in current API; prefer named CLI usage.
Analyzer
wrong
```
import Analyzer from 'canicode/Analyzer'
```
correct
```
import { Analyzer } from 'canicode'
```
Named export for programmatic analysis. TypeScript types are bundled.
Roundtrip
wrong
```
import { Roundtrip } from 'canicode/roundtrip'
```
correct
```
import { Roundtrip } from 'canicode'
```
Named export for the roundtrip (write-to-Figma) workflow. Introduced in v0.11.0.

Quickstart

Shows programmatic usage to analyze a Figma file and print grade, rule results, and gotchas.

#!/usr/bin/env node
import { Analyzer } from 'canicode';

const figmaToken = process.env.FIGMA_TOKEN ?? '';
const fileKey = process.env.FIGMA_FILE_KEY ?? '';

const analyzer = new Analyzer({ token: figmaToken });

async function main() {
  const result = await analyzer.analyzeFile(fileKey);
  console.log('Overall grade:', result.grade);
  console.log('Rule results:', JSON.stringify(result.rules, null, 2));
  console.log('Gotchas:', result.gotchas);
}

main().catch(console.error);