figma-taxonomy-gen

CLI tool that extracts interactive UI elements from Figma designs and generates an opinionated Amplitude event taxonomy.

Documentation: arcbaslow.github.io/figma-taxonomy-gen

Problem: Every team building a tracking plan goes through the same cycle — designer creates screens, PM manually writes a spreadsheet, analyst maps events, developer implements tracking, nobody keeps it in sync. This tool closes the gap between "design is done" and "tracking plan exists."

What it does

Figma file → Extract interactive elements → Apply naming conventions → Output taxonomy

1. Fetches your Figma file via the REST API (or reads a local JSON fixture)
2. Walks the node tree and identifies interactive elements (buttons, inputs, toggles, tabs, cards, modals, etc.)
3. Builds a screen map from the page/frame hierarchy
4. Generates events using configurable naming conventions ({screen}_{element}_{action})
5. Applies property rules (e.g., all *_fail events get error_description)
6. Outputs to Excel, Amplitude CSV, JSON Schema, and Markdown

Installation

# With uv (recommended)
uv pip install figma-taxonomy-gen

# Or with pip
pip install figma-taxonomy-gen

From source

git clone https://github.com/arcbaslow/figma-taxonomy-gen
cd figma-taxonomy-gen
uv sync

Quick start

From a Figma file

export FIGMA_TOKEN="your-figma-personal-access-token"
figma-taxonomy extract https://figma.com/file/ABC123/MyApp

From a local fixture (no token needed)

figma-taxonomy extract --fixture tests/fixtures/banking_app.json

Output

By default, four files are generated in ./output/:

CLI reference

# Basic extraction
figma-taxonomy extract https://figma.com/file/ABC123/MyApp

# Custom output directory
figma-taxonomy extract https://figma.com/file/ABC123/MyApp --output ./my-output

# Specific formats only
figma-taxonomy extract ... --format excel,csv

# Specific page only
figma-taxonomy extract ... --page "Onboarding"

# Custom config
figma-taxonomy extract ... --config ./my-config.yaml

# Skip API cache
figma-taxonomy extract ... --no-cache

# Detect drift between a stored taxonomy and the current Figma file
figma-taxonomy validate ./output/taxonomy.json --figma https://figma.com/file/ABC123/MyApp

# Validate against a fixture; exit non-zero if drift detected (for CI)
figma-taxonomy validate ./output/taxonomy.json --fixture ./figma.json --exit-code

Drift detection

Once you've committed a taxonomy.json to your repo, run validate to check whether the design has changed since. It matches events by Figma node_id (so renames are detected as renames, not add+remove), and reports:

• Added — interactive elements that exist in Figma but not in the stored taxonomy
• Removed — events in the stored taxonomy that no longer correspond to any Figma node
• Renamed — same node, different event name (e.g., after a component was renamed)
• Property changes — properties added or removed on an existing event

Wire this into CI with --exit-code to fail the build when designs and the tracking plan drift apart.

AI enrichment (optional)

With --ai, the tool sends one prompt per flow to Claude and merges suggested properties into the generated events. Good for things like enum values derived from component variants, contextual identifiers, and state flags that rule-based generation can't infer.

uv pip install 'figma-taxonomy-gen[ai]'
export ANTHROPIC_API_KEY="sk-ant-..."
figma-taxonomy extract --fixture tests/fixtures/banking_app.json --ai

Before calling the API, the CLI prints an estimated cost and prompts for confirmation (use --yes to skip the prompt in scripts). Haiku is the default; override via ai.model in the config to use Sonnet for complex screens.

Cost estimate for the banking-app fixture (6 flows, Haiku): ~$0.001. A real 30-50 screen fintech app typically lands between $0.01 and $0.10.

MCP server

The tool ships an MCP server so Claude Desktop / claude.ai can call its functions directly. Three tools are exposed:

Install and run:

uv pip install 'figma-taxonomy-gen[mcp]'
figma-taxonomy-mcp

In Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "figma-taxonomy": {
      "command": "figma-taxonomy-mcp",
      "env": { "FIGMA_TOKEN": "your-figma-pat" }
    }
  }
}

Pushing to Amplitude (Enterprise)

If you're on an Amplitude plan that exposes the Taxonomy API:

export AMPLITUDE_API_KEY="..."
export AMPLITUDE_SECRET_KEY="..."
figma-taxonomy push ./output/taxonomy.json            # real push
figma-taxonomy push ./output/taxonomy.json --dry-run  # preview only

Diffing two taxonomy files

figma-taxonomy diff ./v1/taxonomy.json ./v2/taxonomy.json --exit-code

Useful for reviewing taxonomy changes in PRs before they're pushed to Amplitude.

CI: drift detection on pull requests

A composite action is included so you can fail PRs when the Figma design and the committed taxonomy go out of sync. Drop this into .github/workflows/taxonomy-drift.yml in your app repository:

name: Taxonomy drift check
on:
  pull_request:
    paths:
      - "tracking/taxonomy.json"

jobs:
  drift:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: arcbaslow/figma-taxonomy-gen/.github/actions/drift-check@v0.4.0
        with:
          taxonomy-path: tracking/taxonomy.json
          figma-url: https://figma.com/design/ABC123/MyApp
          figma-token: ${{ secrets.FIGMA_TOKEN }}

The job exits non-zero with a human-readable diff when events are added, removed, renamed, or when properties change.

Configuration

Create a taxonomy.config.yaml to customize naming conventions:

app:
  type: fintech
  name: "MyApp"

naming:
  style: snake_case
  pattern: "{screen}_{element}_{action}"
  max_event_length: 64

  actions:
    button: "clicked"
    input: "entered"
    toggle: "toggled"
    tab: "viewed"
    screen: "pageview"

  screen_name:
    strip_prefixes: true
    strip_suffixes: ["- Default", "- Light", "- Dark"]

output:
  formats: ["excel", "csv", "json", "markdown"]
  directory: "./output"

See taxonomy.config.yaml for the full default config with all options.

How element detection works

The tool uses a three-layer strategy to identify interactive elements:

1. Name patterns — Matches component names against known patterns (button, input, toggle, dropdown, etc.)
2. Prototype interactions — Any node with a Figma interaction (click, hover, drag) is automatically interactive
3. Component types — Only COMPONENT, COMPONENT_SET, and INSTANCE nodes are considered

Non-interactive elements (icons, dividers, loaders, placeholders) are automatically excluded.

Naming convention

Events follow the {screen}_{element}_{action} pattern:

Screen names are cleaned automatically (numbered prefixes stripped, variant suffixes collapsed).

Property rules

Configure automatic property assignment based on event name patterns:

property_rules:
  - match: "*_clicked"
    add:
      - name: "element_text"
        type: "string"
  - match: "*_fail"
    add:
      - name: "error_description"
        type: "string"

Global properties (like screen_name, platform) are added to every event.

Development

git clone https://github.com/arcbaslow/figma-taxonomy-gen
cd figma-taxonomy-gen
uv sync

# Run tests
uv run pytest -v

# Run CLI
uv run figma-taxonomy extract --fixture tests/fixtures/banking_app.json

Roadmap

• v0.1 — Core extraction pipeline, CLI, 4 output formats
• v0.2 — Full config support, validate command (taxonomy drift detection)
• v0.3 — AI enrichment via Claude (property inference from screen context)
• v0.4 — MCP server for Claude Desktop, Amplitude API push, diff command
• v1.0 — CI workflows, drop-in drift-check action, MkDocs site, PyPI publish (ready to tag)

License

MIT