Blueprints for engineers
Engineers · Blueprints

Reading and working with Blueprints

You already know how to build software. This guide covers Sketch’s own vocabulary and UI for requirements: Blueprints, FRs, pins, proposals, redlines, the Backlog and releases.

01 · Orientation

What is Sketch?

Sketch is where Thanx turns an idea into a shipped feature, on three connected surfaces: Blueprints (requirements), Sketches (prototypes, as HTML or React) and Components (the design-system catalog).

Numbered Blueprint sidebar beside requirement cards with priority and Backlog labels.✥
A Blueprint – numbered sections down the sidebar, each holding a list of FRs.
Live updates prototype with the Sketch version selector above its configuration screen.✥
A Sketch – a real, interactive prototype with its own version history.
Feedback settings requirements beside their pinned prototype design pane.✥
The connection – a section’s pinned design beside the FRs that refer to it.

A Blueprint section pins – attaches – one version of a design, and the functional requirements (FRs) inside that section refer to elements within it. This guide covers Blueprints; the prototype viewer is in Sketches for engineers, and designer workflow is in Sketch for designers.

How they fit togetherThe pin lives on the section, not the FR. Either half can exist alone: a section with no pin is valid, and so is a prototype nobody has pinned yet.
02 · Requirements

Reading a Blueprint

A Blueprint reads top-down: sections group functional requirements (FRs) like chapters, and each FR is one testable statement. An FR carries a priority and a decision story.

Checkout phone collection requirement cards with priority and audience labels and Open Questions below.✥
A section – FR cards with priority, experience and an Open Questions block.
Unpinned section header with a Pin a design button above an Email Health requirement card.✥
No design yet – a section with nothing pinned shows a full-width “Pin a design” row.
Email Health requirement cards showing Defer on one card and Backlog on another.✥
Backlog – a deferred FR wears its label; one click on Defer sends an FR to the Backlog.
Decision story entry with Zach Goldstein's decision and a link to its original conversation.✥
Decision story – who decided what and why, linked to the original conversation.
Background and context markdown with Why now, Voice of customer, engineering groundwork, and goal.✥
Context sections – plain markdown for background or out-of-scope notes instead of FRs.
Overview priority and experience totals above Deferred work and Bring into scope.✥
Overview – totals by priority and experience, plus a Deferred work breakdown.
Two section typesA section is either a requirement list (holds FRs) or a context section (markdown only, no priority, Defer or Open Questions).
03 · Design

Reading a Prototype

A pinned prototype is one exact version of one variant (one design approach within a Sketch), not a screenshot and not “latest”. It renders inline in the section’s design pane, and a newer upload never moves the pin by itself. A pin can carry up to 10 tabs, one per prototype state. A node with tabs opens on the first. The All states menu lists every state the prototype declares.

Pinned design pane with its prototype version header, order rating statistics, and chart.✥
Design pane – the pinned version renders next to its section’s functional requirements (FRs).
Design pane header with a row of state tabs above the prototype, the first tab selected.✥
Pinned states – one tab per state above the prototype, opening on the first.
All states menu open over the design pane, listing the prototype's states with step, preset and screen tags.✥
All states – every state the prototype declares, beyond the pinned tabs.

For the viewer, versions and stages, screens and design assets, see The viewer and Versions and stages in Sketches for engineers. Finalize and the adoptable export are in Adoptable files.

04 · Collaboration

Discussion

Comments live at two levels: a section comment, or a Discussion tab scoped to one functional requirement (FR). Either can be posted as a Redline – queued as a proposed rewrite instead of a plain note. The composer is a split Comment button whose menu holds “Post as redline”, and an existing comment can be promoted to a redline afterwards (see Making changes).

Type @ in any comment box – section, requirement or proposal review – to mention someone. They get a bell notification and a Slack DM, and the mention shows as their name everywhere the comment appears. A new comment on a requirement also notifies everyone who commented on it before, as a reply would.

Open Questions above the section comment composer and its Post as redline menu.✥
Section comments – Open Questions sit above the comment box, whose Comment menu offers Post as redline.
Requirement discussion thread with staff comments and a highlighted Redline comment.✥
FR discussion – a plain comment and a Redline-tagged one in the same thread.
Requirement comment composer reading Thanks, @, with a picker listing people by name.✥
@mentions – any Blueprint comment box can mention someone.
Global Comments panel with search, Active and Archived tabs, and a requirement comment group.✥
Comments panel – every open comment across the Blueprint in one place, grouped by FR.
05 · Design references

Design references

A section can hold more than one pin (an attached design). A functional requirement (FR) can also carry implementation references – pointers to one exact element in the pinned version. When a pin moves to a newer version, Sketch replays each reference against it and marks any that no longer land on exactly one element as broken.

Pinned design header with its pinned version and Pin out of date warning.✥
Pin out of date – the section points at an older version than the prototype’s latest.
More actions menu with Update pins and Show all broken references actions.✥
More actions – Update pins for stale designs and Show all broken references for broken pointers.
Update pins dialog listing sections and their stale and latest prototype versions.✥
Update pins – a PM or designer moves stale pins forward from here.
Broken references banner and its exit and rerun controls above an Out of date reference tile.✥
Show all broken references – filters the deck to the affected FRs, each broken tile marked Out of date.
Reference update progress dialog with checked count, progress bar, elapsed time, and fixed count.✥
Repair – a progress dialog re-runs the references against the new version.
Choose what readers see dialog with a state library on the left, a live preview on the right and tab chips below.✥
Choose states – a library on the left, a live preview on the right, tabs below.
A tab chip's popover with the tab name, its state, and a Change control.✥
Tab settings – name and state. Requirements link from their cards.
Shown in pill open on a requirement card, a checklist of the node's tabs with two ticked.✥
Shown in – the tabs that show the FR; Edit states opens the checklist of every tab.
The Shown in checklist open on a requirement card.✥
Tabs on this node – tick the tabs that show this requirement.
A requirement card with a dashed Not shown pill and its panel naming who marked it, with Undo.✥
Not shown – an FR with nothing to picture, with who marked it and Undo.
Stale pin vs. broken referenceA stale pin only means design moved on. A broken reference (“Out of date” on the reference tile) means the pointer your code depends on no longer lands on a single element, so it is worth a look.
  • Pin states. Pinning a design also pins what readers see. Choose up to 10 of the prototype’s page states; each becomes a tab in the node’s design pane.
  • Choose. Add a design opens a library of the prototype’s states, grouped into sections. Hover a state to preview it, click to add it as a tab. A section named like the node comes first: Add all N as tabs. Drag tabs to reorder. A pin with no tabs shows the default view.
  • Shown in. Each FR card has a Shown in · N pill. Open it to see the tabs that show this requirement: click a row to switch the pane to that tab. Edit states (or Add more… when no tab is linked) opens a checklist of the node's tabs: tick the ones that show this requirement, then press Done. Add more… there opens the pin states dialog to add tabs for this requirement.
  • Not shown. A rule with nothing to picture, such as an out-of-scope error, can be marked Nothing to show in edit mode. Its pill reads Not shown, and its panel is headed Not shown in the prototype, with who marked it (Edit states opens Undo). Linking a tab clears the mark.
  • Stale tabs. If a newer version drops a pinned state, its tab reads Not in <version> and offers Pick a replacement. sketch upload warns when it drops a pinned state.

To read references from a terminal or an agent, use sketch blueprint reference or the blueprint_requirement_references tool. A reference captured on a tab remembers that tab’s state and replays it first. Selecting an element and copying it for Claude is covered in Implementation references. From a terminal, sketch states <sketch> <variant> lists a version’s states, and blueprint add-preview, edit-preview and proposal pin-design-slot take --page-state. Agents use prototype_page_states and page_states on the pin tools.

06 · Editing

Making changes

Changes reach a Blueprint by several routes, and only some of them touch the live tree.

Pending edits banner beside an open panel listing a changed requirement title and Revert.✥
Pending edits – the banner holds the save actions; its side panel lists each edit with a Revert.
Proposals column listing open proposals, each row with a review summary and one marked as waiting on your review.✥
Proposals – a review summary on each row, and your pending reviews marked.
Proposal review banner with Mint, Request peer review and a reviewer pill reading Approved 1 of 2.✥
Proposal review – Mint, Request peer review and the reviewer pill.
Describe what changes dialog with a text box and a button for each of a refinement and a material change.✥
Mint – one text box and a button per level, with the stored severity primary.
Reviewer picker open with a Choose reviewers select, removable chips and a list of Sketch users.✥
Request peer review – a searchable select of Sketch users.
Reviewer panel with three reviewers showing pending, approved and changes requested, plus a note and Re-request and Remove controls.✥
Reviewer panel – each reviewer’s status and note, with Re-request and Remove.
A Slack decision thread where Aaron asks @Sketch to draft a proposal; the Sketch app replies Drafted P1: Split report CSV export with the proposal link, then Updated P1 after a follow-up decision.✥
@Sketch in a thread – it drafts the proposal and replies with its link; a later mention updates the same proposal.
  • The Blueprint page edits the live version inline: a functional requirement (FR)’s title, details, priority and Defer label. Each edit waits in the Pending edits list until you save it from the banner above the deck: “Refine existing requirements” (minor version), “Change scope materially” (major version) or “Save (no version change)”. The side panel has a Revert per row.
  • A proposal is a draft change, shared with every collaborator and reviewable and discardable before it is live. Batched Redline comments (comments tagged to become proposed rewrites, applied with /redline), and structural drafts go here.
  • Slack: mention @Sketch in a decision thread and it drafts a proposal. It finds the Blueprint (a slug in the mention, else the channel’s linked one), reads the thread, and replies with the proposal link. A later mention in the same thread updates that proposal. It never mints, and never creates a Blueprint. You need a Sketch account to invoke it. One draft runs per thread at a time.
  • MCP (Model Context Protocol) drafts into proposals and never edits the live tree directly. A proposal goes live only through an explicit blueprint_mint_proposal call; the one direct write is blueprint_update, which changes only the name, description and metadata.
  • The CLI still writes to the live tree by default. Only sketch blueprint apply-edits and move-requirement can target a proposal: --as-proposal creates a new one, --proposal <reference> adds to an existing one. add-requirement, update-requirement and delete-requirement always write live. Commands are in The CLI.

Severity. Whoever drafts a proposal sets its severity, minor or major, and it is stored on the proposal. /blueprint, /redline and the Slack bot set it. From a terminal, sketch blueprint proposal set-severity or --severity; over MCP, blueprint_set_proposal_severity.

Peer review. Request peer review names reviewers from the Sketch user list; each gets a Slack DM. A reviewer approves or requests changes, with an optional note, in the web UI only. The banner shows one reviewer pill (avatars, “Approved 1 of 2”, “Changes requested”). Open it for each reviewer’s status and note, Re-request and Remove. Review is advisory: anyone can mint at any time, and approving never mints. From a terminal, sketch blueprint proposal request-review --reviewer <email> and proposal reviewers; over MCP, blueprint_request_proposal_review (needs the blueprints scope).

Minting is one dialogMint opens Describe what changes: a text box and one button per level, Refinement change (5.0 → 5.1) or Material change (5.0 → 6.0). A click mints at once. The proposal’s stored severity makes its button the primary one. An empty box mints a refinement; a material change needs a description. Discard proposal sits at the far right.

To see what changed, blueprint_diff compares two versions and blueprint_pending_changes diffs the live tree against its last accepted state. Shapes are in the Appendix.

07 · Notifications

Notifications

The bell, last in the Blueprint top bar and in the main navigation bar, shows everything that involves you, whatever your Slack settings. Tabs split it into All, Review, Your proposals, Comments and Watching. On All, Waiting on you pins review requests, changes requested on your proposals and @mentions; each says what clears it, and clears when you act there or Dismiss it. Clicking a row opens its target and marks it read. Hide read, on by default and remembered for you in this browser, shows only unread rows, Waiting on you included; turn it off to see your history. Mark all read leaves waiting items unread. The gear opens Notification settings, the same table as your profile: Icon, Event and Slack.

Sketch can direct-message you about a Blueprint or a sketch. The Watch button in the top bar (the Slack mark, with a green dot while you watch) opens one panel: watch or unwatch, then pick Daily digest or Real time for changes. Comments are always real time.

The same panel holds your account-wide Slack toggles. After your first comment on a Blueprint, a prompt also offers to watch it. Changelogs go to watchers as DMs, not to a channel. A Blueprint’s Slack channel, set on the title slide, gets a bookmark when it is linked. You can request a one-time link announcement; release posts go to that channel only when Slack Channel Releases is on. Review DMs always arrive, whatever your Watch settings: a reviewer someone named, or an author whose reviewer answered. So do @mention DMs. Reply DMs are on unless you turn them off. Turning off Redlines on things I watch keeps redlines on Blueprints you watch out of both the bell and Slack.

Slack can also draft proposals: mention @Sketch in a decision thread. See Making changes.

Notifications bell open from the Blueprint top bar on Review, with a re-requested review and what clears it.✥
The bell – last in the Blueprint top bar.
Notification settings with Icon, Event and Slack columns: Always on for review requests, reviews on your proposals and @mentions, then switches including Redlines on things I watch.✥
Notification settings – everything shows under the bell; choose what reaches Slack.
Slack Watch button with a green dot in the Blueprint top bar.✥
Watch button – the Slack mark between Comments and the version picker. A green dot means you are watching.
Watch this Blueprint panel with Daily digest and Real time choices, Comments always real time, and the Global Slack settings heading.✥
Watch panel – Blueprint cadence, always-real-time comments, and the Global Slack settings heading. Open the full image for the toggles.
Slack channel metadata field on the Blueprint title slide, linked to p-thanx-mcp.✥
Slack channel – the channel link is metadata set on the title slide.
08 · Lifecycle

Lifecycle

A requirement moves through Backlog, a release cycle, testing and a numbered release.

Owner and status. Every Blueprint has an owner (its creator, until you change it) and a status: Draft, Ready, Active or Archived. Set both on the title slide. Changes are live, never mint a version and never appear in a changelog. The status pill sits in the left rail; the Blueprints list shows status and owner on each card and filters by either. Its search matches names, descriptions, starters and contributors, and combines with status, a time window, sort and two people pickers: Owner (who originally started the Blueprint, not its current owner) and Contributor (who minted a version or authored a proposal). The address bar keeps the view, so the link shares it. My Blueprints means owned by you. Archived hides a Blueprint from the default list; pick another status to bring it back. Owner is a label, not a permission. From a terminal, sketch blueprint update --owner <email> --status <status> and list --status --owner. archive and unarchive are gone; use update --status archived.

Title slide with the Blueprint status select open, listing Draft, Ready, Active and Archived.✥
Status and owner – set on the title slide, live with no mint.
Blueprints list searching for recoveryai, with the Owner picker open on Originally started by, Contributor, Last updated and Sort, and a status chip and owner avatar on each card.✥
Blueprints list – status, owner, search and people filters in the sidebar.
More actions menu with Add global redline, Make test plan, copy commands, and Update pins.✥
More actions – Add global redline, Make test plan, Copy changelog, Update pins and more.
Test plan form with name, section checkboxes, and all or unreleased requirement scope.✥
Make test plan – name it and scope it to the sections you touched.
Test plan checklist with progress totals, grading controls, Create release, and End test plan.✥
Grading – Pass, Fail, Not Building and Cannot Test, saved on click.
Release result listing Released, Skipped Backlogged, and Carried forward requirements.✥
Release result – what shipped, what was skipped as Backlogged, what carried forward.
Release and scope panel showing Released, In flight, and Backlog filters beside Versions.✥
Scope panel – Released, In flight and Backlog counts, each with a Filter.
Released requirement cards with green release labels and Un-release controls.✥
Released – a released card shows its release and an Un-release control.
  • Backlog is a label on a requirement (deferred_to). Backlogged work sits outside every cycle. The Overview slide’s Deferred work list has a Bring into scope action; each move is one version.
  • Testing: Make test plan is in the ⋯ More actions menu (it reads Test plans once the Blueprint has one). Name it, pick sections, then grade each requirement Pass, Fail, Not Building or Cannot Test. Backlogged requirements are never added to a plan.
  • Releases: Create release in test mode records the Pass-graded requirements as Release N and ends the plan. Backlogged ones are skipped and named in the result.
  • Locks: a released requirement cannot be edited or deleted until you Un-release it on its card. The same lock blocks deleting its section and restoring an older version.
  • Release cycle: the in-flight work is derived, never stored. Creating a release starts the next cycle, and anything unreleased and not in the Backlog carries into it.
Hide what you do not needThe top bar has toggles to hide released and deferred requirements, so a long Blueprint shows only the work in flight.
09 · Access

Connecting

Blueprints are reachable from Claude over MCP and, read-only, from Keystone. Connecting, tokens and the rest of the MCP tools are in MCP and Keystone; the CLI is in The CLI.

Blueprint tools

  • Read: blueprint_list, blueprint_show, blueprint_comments, blueprint_versions, blueprint_diff, blueprint_pending_changes, blueprint_requirement_history, blueprint_requirement_references.
  • Proposals: blueprint_list_proposals, blueprint_get_proposal, blueprint_create_proposal, blueprint_apply_to_proposal, blueprint_apply_comments_to_proposal, blueprint_mint_preview, blueprint_mint_proposal, blueprint_archive_proposal, blueprint_set_proposal_severity, blueprint_request_proposal_review.
  • Pins and metadata: blueprint_pin_proposal_design_slot, blueprint_unpin_proposal_design_slot, blueprint_update. blueprint_update takes owner and status; blueprint_list and blueprint_show return them. blueprint_show also returns each pin’s page_states and not_shown_requirements (read-only), and the pin tools take page_states.

Token roles. A personal token created with the Blueprint drafter role reads anything and writes only Blueprint proposals; it cannot comment or mint. Full access is the default. See MCP and Keystone.

Keystone

Keystone is the read-only proxy other Thanx tooling uses to query internal systems. Blueprints and prototypes are there as sketch_* tools, such as sketch_get_blueprint and sketch_list_blueprint_proposals.

10 · Reference

Glossary

Sketch
The platform as a whole: Blueprints (requirements), Sketches (prototypes) and Components, connected by design pins.
Blueprint
A structured requirements document: a tree of sections, each holding FRs or, for a context section, plain markdown.
FR
Functional requirement – a single, atomic, testable statement inside a section.
Proposal
A draft set of changes to a Blueprint, shared with every collaborator and reviewable before it is live.
Mint
Turning a proposal into a new live Blueprint version: a minor version for refined requirements, a major one for a material scope change.
Version
A minted snapshot of a Blueprint, labelled major.minor; a new Blueprint starts at the unnumbered Initial (0.0). Prototype versions are separate; see Versions and stages.
Stage
Where a prototype version stands: a private Draft, Iterating (published versions before a Finalize) or Finalized (N.0, with its N.x iterations). Defined in Sketches for engineers.
Variant
One competing design approach within a Sketch, each independently versioned.
Pin / design slot
The link from a section’s design pane to one exact prototype version. Reads “Pin out of date” when the prototype has a newer one.
Implementation reference
An FR’s pointer to one exact element inside its section’s pinned version. Broken (“Out of date”) when a newer pin no longer resolves it to a single element.
Redline
A comment tagged to become a proposed rewrite, applied in bulk with /redline.
Context section
A section that renders plain markdown for background or out-of-scope notes and holds no FRs.
Backlog
The label (deferred_to) on a requirement set aside for later. Backlogged work belongs to no release cycle and is never added to a test plan.
Release
A numbered record (Release 01, 02, …) of the Pass-graded requirements in a test plan. Releasing locks those requirements until you Un-release them.
Release cycle
The set of work a Blueprint is trying to ship in one go. Derived, not stored: unreleased, non-Backlog requirements. Creating a release starts the next cycle.
Test plan
A named check-off list over the sections you choose, graded Pass, Fail, Not Building or Cannot Test.
Owner
The person a Blueprint is labelled with, its creator until changed. A label, not a permission.
Status
Draft, Ready, Active or Archived. Set on the title slide, live, and never a new version.
Peer review
Named reviewers approve or request changes on a proposal. Advisory: anyone can still mint.
Pinned state (tab)
One of up to 10 prototype page states a pin shows as a tab in the node’s design pane.
Shown in
The pill on an FR card listing the pinned tabs it is linked to, or Not shown when it has nothing to picture.
Watch
A Slack DM subscription for a Blueprint or sketch. The Watch panel sets its change cadence and your global Slack toggles; comments are always real time.
11 · Reference

Appendix: Blueprint tool reference

Behaviour behind Making changes and Connecting. Useful when you are calling these tools, not required reading otherwise.

For notification delivery and Blueprint channel metadata, see Notifications: changelogs go to watchers as DMs; channel release posts require Slack Channel Releases.

Rich vs. thin fetches

blueprint_show defaults to thin: the node tree and requirements, plus each node’s pinned previews and open questions with note counts (never note text), but no requirement details prose until you pass detail (“full”, one identifier or node id, or an array of them). blueprint_diff and blueprint_pending_changes return a change log, not a full tree.

Diffs

blueprint_diff takes slug with from and to version labels, or since (a duration such as 7d, or an ISO date). It defaults to since the last major version. blueprint_pending_changes takes only slug.

History and references

blueprint_requirement_history takes slug and an identifier (or an array of them) and returns each decision story. blueprint_requirement_references takes slug and one FR identifier and lists its implementation-reference attachments.

Proposal flow

blueprint_create_proposal → blueprint_apply_to_proposal (each requirement change carries a why or a full provenance) → optionally blueprint_set_proposal_severity → blueprint_mint_preview, which returns the live digest → blueprint_mint_proposal, which needs that digest and should run only on an explicit request.