Service Blueprint Generator

A tool for creating service blueprints from spreadsheet data. Load your lanes, phases, and cards from CSV or TSV files and generate an editable Figma diagram or a shareable HTML preview — no coding required.

What it does

Service blueprints map out what happens during a service journey: what the person does, what staff do, what systems do, and what policies apply. This tool lets you define that structure in a spreadsheet and generate a formatted diagram automatically.

Two outputs:

• Figma plugin — generates an editable blueprint directly in your Figma file, with individually moveable cards
• HTML preview — renders in any browser; export as a PNG to share with people who don't have Figma

---

Quick start

HTML preview (no install needed)

1. Open preview/index.html in your browser
2. Upload your structure file and one or more content files
3. Click Render
4. Click Export PNG to save a full-width image

Figma plugin

1. Install dependencies and build:

   npm install
   npm run build

2. In Figma: Plugins → Development → Import plugin from manifest
3. Select dist/manifest.json
4. Run the plugin from the Plugins menu

---

File formats

All files can be CSV or TSV. Column headers are case-insensitive.

Structure file

Defines the lanes (rows) and phases/sub-phases (columns) of the blueprint. Row order determines render order.

type,id,label,parent
lane,applicant,Applicant,
lane,system,System,
lane,policy,Policy,
phase,apply,Apply for Benefits,
subphase,discover,Discover,apply
subphase,submit,Submit Application,apply
phase,review,Review,
subphase,caseworker-review,Caseworker Review,review

Column	Description
type	lane, phase, or subphase
id	Unique identifier (used to link content)
label	Display name shown in the diagram
parent	For subphases: the id of their parent phase

Content file(s)

Each row is one card. You can use multiple content files — they are merged. This is useful for separating content by contributor or topic (e.g. a separate file for policy citations).

lane,subphase,type,text,subtext
applicant,discover,applicant,Search for benefits online,Via agency website
system,submit,system,Generate confirmation number,
system,submit,domain-event,intake.application.submitted,
policy,submit,policy,7 CFR § 273.2(g),Agency must accept any application on the date of first contact.

Column	Description
lane	The id of the lane this card belongs to
subphase	The id of the sub-phase column
type	Card type (see below)
text	Main card text (header)
subtext	Optional secondary text (body)

Multiple rows with the same lane + subphase create multiple cards in that cell, in the order they appear.

Card types file (optional)

Overrides the default card types. If omitted, the built-in types are used.

id,label,headerBg,bodyBg,headerFg,bodyFg,icon
applicant,APPLICANT,#D97C20,#FDECD4,#3D1800,#3D1800,person-single
system,SYSTEM,#137C69,#F1FFFD,#FFFFFF,#0A3A2E,gear

The id column must match the type values used in your content file. The icon column accepts: person-single, person-group, gear, document, lightning, diamond-alert, lightbulb, building, bar-chart, mail, diamond, help.

---

Default card types

Type	Color	Use for
applicant	Orange	Actions taken by the person applying
caseworker	Purple	Actions taken by a caseworker
supervisor	Indigo	Actions taken by a supervisor
system	Green	Automated system processing
domain-event	Teal	Events emitted by the system
communications	Blue	Notices, letters, or messages sent
pain-point	Red	Friction or barriers in the experience
opportunity	Amber	Ideas for improvement
policy	Beige	Regulatory requirements
metrics	Light teal	Performance indicators
question	Gray	Open questions or knowledge gaps
touchpoint	Dark gray	Service channels or touchpoints
note	Yellow	General annotations

---

Starting from unstructured content

If you're working from workshop output, interview notes, or a pile of sticky notes rather than an already-structured spreadsheet, this section is for you.

Step 1 — Define your structure first

Before touching content, decide on your lanes and phases. This is the hardest design decision and everything else follows from it.

Lanes (rows) represent actors or systems: the person receiving the service, front-line staff, back-office staff, systems, policy. Start with 4–6 and add more only if the content demands it.

Phases represent major stages of the journey (e.g. Awareness → Apply → Review → Decision → Appeal). Sub-phases break each phase into finer steps. If you're unsure, start with phases only and add sub-phases once you have real content to fill them.

Write your structure file first, render an empty blueprint, and review it with your team before adding any cards.

Step 2 — Sort your content into cells

Each piece of content (a sticky note, an observation, a policy citation) belongs in one cell: the intersection of a lane and a sub-phase. Work through your raw material and assign each item a lane and subphase value from your structure file.

A card also needs a type — pick the one that best describes what kind of thing it is, not who it belongs to (the lane handles that):

You have...	Use type
Something a person does or decides	applicant
Something a caseworker does	caseworker
An automated system action	system
A notice, letter, or message sent	communications
A regulation or policy that applies	policy
A pain point or barrier you observed	pain-point
An idea for improvement	opportunity
An open question	question
Something you want to annotate	note

Step 3 — Use AI to help structure at scale

If you have a large volume of raw content (e.g. hundreds of sticky notes exported from Miro, or interview transcripts), an AI assistant can help convert it to CSV quickly.

Paste your raw content and prompt it with something like:

I'm building a service blueprint. My lanes are: applicant, caseworker, system, policy. My sub-phases are: discover, apply, submit, review, decision. Convert each item below into a row with columns: lane, subphase, type, text, subtext. Use these card types: applicant, caseworker, system, communications, policy, pain-point, opportunity, question, note. If an item doesn't clearly fit a cell, put it in the note type and flag it.

Review the output carefully — AI will make judgment calls about categorization that may not match your intent. Treat the result as a first draft to edit, not a finished product.

Step 4 — Iterate

Load your files, render the blueprint, and look for:

• Cells that are overloaded (too many cards) — consider splitting the sub-phase
• Cells that are empty across a whole lane — does that lane belong?
• Card types that feel wrong — it's easy to retype a type column value

The CSV format is designed to make this iteration fast. Small edits in a spreadsheet, re-upload, re-render.

---

The examples/ folder contains a complete service blueprint for a benefits application submission flow:

• structure.csv — lanes and phases
• content.csv — system actions, events, and person actions
• content-policy.csv — policy citations as a separate file (demonstrating multi-file loading)

Load all three to see a full blueprint rendered.

---

Development

npm install          # install dependencies
npm run build        # build the Figma plugin to dist/
npm run watch        # rebuild on file changes

Source files:

src/
  config/
    card-types.ts    # default card type colors and labels
    icons.ts         # SVG icon paths
  types.ts           # TypeScript type definitions
  parser.ts          # CSV/TSV parsing
  renderer.ts        # Figma rendering logic
  main.ts            # Figma plugin entry point
  ui.html            # Plugin UI
preview/
  index.html         # Standalone HTML preview (no build needed)
examples/            # Sample CSV files