Design References
The Designs page of a project: the links it keeps to Figma files, wireframes, prototypes, screenshots, API contracts and diagrams, attached to the whole project or to one component.
By the end of this page you will have linked a project's designs where everyone finds them, know every field a design reference carries and what reads each one downstream, and know how a reference is attached to a component, changed and removed.
A design reference is a link the project keeps to one of its designs: a Figma file, a wireframe, a prototype, a screenshot, an API contract, a sequence diagram, an entity diagram or a document. The link is the record and the file stays where the designer keeps it. Developers and testers open the reference before they build or check a screen, the client signs off against it, and Heimdall names it when it drafts a story for the screen it shows.
A reference hangs off the whole project or off one of its components, so the web app's screens sit beside the web app and the API contract beside the API. Epics, stories, requirements, use cases and test cases will take references of their own as those modules land.
Before you begin
| You want to | You need |
|---|---|
| Open the Designs page | design-reference:view-any on the project. Every staff role has it; a client guest has it through their project membership. |
| Add a reference | design-reference:create, through your role on the project or your team role, or to own the team. Business analysts have it by default. |
| Edit a reference | design-reference:update. |
| Delete a reference | design-reference:delete. |
The page lives under a project: open the project and choose Designs in the sidebar.
Read the designs
The page shows one card per reference, in the project's order:
| On the card | What it shows |
|---|---|
| Kind badge | What the link points at, as a coloured badge: Figma, wireframe, prototype, screenshot, API contract, sequence diagram, entity diagram, document or other. |
| Title and host | The reference's title, which opens the detail flyout, and the host the address points at. |
| Attached to | Whole project or the component the design belongs to, the version when one is recorded, and how long ago the reference changed. |
| Open Design | Opens the design in a new tab, exactly where the designer keeps it. |
| Card menu | View Reference, Edit Reference, Activity, Delete Reference. |
Above the cards, narrow the page with the search box (words in the title, the address or the version), the kind filter and the component filter. The filters travel in the page address; Clear Filters on the empty state drops them all.
A client guest sees every reference of their project: the designs are what the client reviews and signs off against.
Add a reference
- Press Add Reference.
- Type the Title as the team refers to the design, and paste the Address where it lives.
- Under What It Is, pick the Kind and, when the design belongs to one component, choose it under Attached To; leave it empty for a design that covers the whole project. Record the Version the designer labels it with.
- Write the Notes: what to look at and why, which frames are signed off, which are still exploring.
- Press Add Reference.
The card appears at once, you are recorded as the person who added it, and
design_reference.created goes out to every endpoint subscribed to it.
The link is the record
Nothing is uploaded. The design stays in Figma, in the wiki, in the contract repository, wherever the designer keeps it; the reference says what it is, which version is current and what to look at. Attachments and an in-app viewer for API contracts follow with the attachments block.
Open a reference
Press a card's title, or View Reference in its menu, to open the detail flyout: the kind badge, the title and the full address, Open Design, what it is Attached To, the Version, who Added it, the Notes and the created and updated stamps. From the flyout, Edit, Activity and Delete are one press away.
A link such as /projects/<project>/designs?show=<id> opens the page with that reference's flyout
already open; notifications and Heimdall's buttons use it.
Edit a reference
- Press Edit Reference in the card menu, or Edit in the flyout.
- Change what you need: the address when the design moved, the version when a new one is current, the component it is attached to when it was filed wrongly.
- Press Save Changes.
Every change travels as design_reference.updated with its old and new values; moving a reference
between the project and a component shows as the attachment changing. An edit that changes nothing
announces nothing.
Delete a reference
Delete Reference in the card menu or Delete in the flyout removes the link with its activity history after a confirmation; there is no undo. The design itself stays where the designer keeps it. When a component is deleted, its references are moved onto the whole project rather than lost.
All the fields
What happens next
- Every add, edit and delete is written to the reference's activity history with who did it and where from.
- The
design_reference.created,design_reference.updatedanddesign_reference.deletedevents go out to every endpoint subscribed to them. - Stories, requirements, use cases and test cases will carry references of their own as those modules land, and an uploaded API contract will open in an in-app viewer with the attachments block.
Heimdall on this page
Heimdall reads the references through the same tools the MCP server offers and carries the open project as its context.
Linking designs is a person's work: an agent over MCP reads the references to build against the design and never rewrites the links.
From the API and MCP
Design References API
List, get, add, change and delete design references over REST.
list_design_references and get_design_reference
The two MCP tools that read a project's design references as the token sees them.
Permissions
| Action | Permission |
|---|---|
| See the references | design-reference:view-any, a client guest included |
| Open a reference | design-reference:view |
| Add a reference | design-reference:create, or owning the team |
| Edit a reference | design-reference:update, through a project role or a team role |
| Delete a reference | design-reference:delete |
Frequently asked
Related
- Components — what a reference may be attached to
- The project overview — the project the designs belong to
- Status reference — the nine kinds
design_reference.*webhook events
How is this guide?
Last updated on
Data Dictionary
The Data Entities tab of a project's Dictionary pages: the things the project keeps records of, their fields, owners, personal data, retention and review status.
Repositories
The Repositories tab of a project's Code pages: the Git repositories the code lives in, with provider, owner, name, default branch, privacy and component; registering, editing, disconnecting and deleting them.