Design Decision Recorder

A Figma plugin that lets your team capture why a design looks the way it does — pinned to the actual element on the canvas. Designers, developers, QA, PMs, and BAs can all add their reasoning, and the file becomes its own source of truth.

What it does

• Capture decisions on any selected element — role, status, title, and the rationale (with built-in writing templates so nobody stares at a blank box).
• Browse and search every decision in the file. Click a row to jump straight to the element on the canvas.
• Link decisions to each other and view the whole network at a glance in the Graph tab.
• Auto-maintained “🗂 Design Decisions” page inside your file, kept up to date without polluting version history.
• Travels with the file. No external server, no API key, no account.

Why this and not a Notion doc

A Notion link rots. A Slack thread gets buried. A Figma comment is hard to find six weeks later. Decisions belong on the element they describe, in the same tool the team is already in.

Install (5 minutes, no coding needed)

You'll do this once on your computer. After that, the plugin lives in Figma — you just open it and use it like any other plugin.

Step 1 — Make sure Node.js is installed

Node.js is a free piece of software that lets your computer run the install command. Most people don't have it by default, so let's check first.

1. Open a terminal:
   • Mac: Press Cmd + Space, type Terminal, hit Enter.
   • Windows: Press the Win key, type PowerShell, hit Enter.
2. Type the following and press Enter:

   node --version

3. If you see something like v20.10.0 — you're good. Skip to Step 2.
4. If you see "command not found" or "not recognized" — go to nodejs.org, click the big LTS download button for your operating system, run the installer, and accept all the defaults. Then close and re-open the terminal and try node --version again.

Step 2 — Run the install command

In the same terminal window, copy-paste this and hit Enter:

npx @neilsarjal09/design-decision-recorder install

The very first time you may see a prompt like "Ok to proceed? (y)" — type y and hit Enter.

When it finishes, you'll see a message like:

Open Figma → Plugins → Development → Import plugin from manifest…
Pick this file:

  /Users/yourname/Documents/DesignDecisionRecorder/manifest.json

Copy that file path — you'll need it in the next step. Leave the terminal open.

Step 3 — Import the plugin into Figma

Important: You need the Figma desktop app, not the browser version. The browser doesn't have the "Import from manifest" option. Download Figma desktop if you don't have it.

1. Open the Figma desktop app and open any file.
2. In the top menu, click Plugins → Development → Import plugin from manifest…
3. A file picker opens. Navigate to the path you copied (or paste the path into the picker's address bar) and select manifest.json. Click Open.

You'll see a small confirmation. The plugin is now permanently saved on this computer.

Step 4 — Run it

In Figma, go to Plugins → Development → Design Decision Recorder. A panel opens. Select any element on your canvas, switch to the Capture tab, and start recording decisions.

Updating to a newer version

When a new version is released, run the same command with --force so it overwrites the old files:

npx @neilsarjal09/design-decision-recorder install --force

You don't need to re-import in Figma. Next time you open the plugin, the new version is already there.

Putting the files somewhere else

If you'd rather not use ~/Documents/DesignDecisionRecorder/, point it at a folder of your choice:

npx @neilsarjal09/design-decision-recorder install --path ~/figma-plugins/ddr

Day-to-day usage

1. Capture a decision. Select an element on the canvas, open the plugin, switch to the Capture tab, fill out the form, hit Save. The decision is now bound to that element.
2. Find a decision. Browse tab — type into the search box or use the role / status / paradigm filters. Click a row to jump straight to the element on the canvas.
3. See the full log. A page called 🗂 Design Decisions is automatically maintained in your file with every decision listed.
4. Visualise the network. Graph tab shows every decision as a node and every link between them as a line — click a node to jump to it.
5. Recover a deleted log page. Settings → Rebuild decisions page.

What you can record

• Roles — Designer, Developer, QA, PM, BA, Other.
• Statuses — Proposed, Approved, Rejected, Revisited, Superseded.
• Paradigms — Component, Layout, Interaction, Accessibility, Information Architecture, Motion, Visual style, Content. Each comes with a writing template based on real design-system decision docs. You can also create your own custom paradigms in Settings, and they'll be available to everyone working in the file.
• Jira ticket (optional) — link the decision to a Jira ID for cross-referencing.
• Linked decisions — connect this decision to other decisions in the file, Obsidian-style.
• Walkthrough recording (optional) — attach a Loom / Drive / YouTube link explaining the decision.

Every role and status has its own colour, so the on-canvas log stays scannable at a glance.

For developers building from source

npm install
npm run build

Then in Figma desktop, Plugins → Development → Import plugin from manifest… and pick the manifest.json in this project's root. For a hot-reloading dev loop:

npm run watch

Roadmap

• Transcript ingestion — paste a meeting transcript, get extracted candidate decisions to confirm.
• Semantic search — find decisions by meaning, not just keywords.
• MCP / Claude Skill companion — read exported JSON across files for cross-project decision reporting.

License

MIT