Using the canvas
The canvas shows the selected page on a surface you can zoom and pan like a design tool. A page can explicitly declare multiple artboards, each with its own dimensions and inputs. Click an artboard’s label to select it. Size, preview controls, Actions, and drawing tools apply to that artboard. In a docs lens, a page’s docs fill the canvas instead; see Docs on the canvas. This page covers each part of it.
Scenarios are alternatives: the scenario switcher changes which scenario of the page
is showing. Storybook stories also remain alternatives. They do not create
artboards. A page without an artboards declaration shows one preview; docs
show one viewport. Inputs and annotations stay independent while selecting
between declared artboards. Screenshots, references, and handoffs include
every artboard. The existing sidebar, top bar, toolbar, and view controls keep
their layout.
With several artboards, only the selected artboard runs its preview; click a label or another artboard to select it. The others show a background image of the preview, rendered once per build and kept between sessions, so reopening a page shows them at once. Background images are rendered at the zoom you look at them, so zooming in shows a soft image until the sharper one arrives. Artboards large enough to read show a static copy of the page instead, with sharp text at any zoom but no scripts; click one to select it and run its preview. A single artboard keeps running. The multi-artboard surface requires WebGPU in Chrome or Electron.
When you leave a ready artboard, Workbench keeps an image of its current state, including what you typed, opened or scrolled to. That image stays visible at every zoom at its captured artboard size until you return to the running preview. It has one captured resolution, so it can look soft when enlarged. After a build it stays visible with Stale in the label. Restart the artboard to begin with a fresh document. These images last for the current canvas session. Workbench can evict an image to make room while its app remains ready to capture again; released images are protected from budget eviction. If capture is unavailable or fails, the artboard shows its background image; returning to a warm document still restores its state. Changing an artboard’s size hides an image captured at different dimensions and shows the background render at the new size. The saved image is retained, so resizing a released artboard does not delete its saved state.
Artboards you use, by clicking or typing in them, keep their application state; selecting one only to look at it does not. Up to eight keep it: using a ninth releases the one you used longest ago and says so. A released artboard shows a kept image of what you did. Release in the selected artboard’s label does the same on request: it keeps an image of what you did and ends its document. Restart starts a fresh document and resets application state. Returning to an artboard that kept its state preserves its inputs, scroll position and application state. An image marked Stale cannot supply screenshots or handoffs for a released artboard; restart it before capturing again. Artboards that Workbench ended automatically to make room can be started afresh for review when their saved image is out of date. If the image budget is full or the canvas cannot display the captured image, Release reports the problem and keeps the app running. Restart a released artboard to discard its saved image and make room. If using a ninth artboard cannot release the oldest, the existing eight keep their state. The new app stays warm but is not pinned; try again after capture or display recovers.
When you pick another page, the sidebar marks it immediately. The previous artboard stays visible for up to 200 ms, keeping its own label and reference. If the requested page becomes ready sooner, it appears immediately without a loader. If it takes longer, the old view is hidden and Loading preview… appears until the replacement is ready. Scenarios and lenses use the same grace period. The outgoing preview is not interactive during the transition; screenshots and handoffs wait for the requested page to finish loading. A failure ends the transition and shows the error. Rapid picks follow the latest destination. This keeps fast switches visually continuous without delaying ready content. Labels use the page’s name and the selected story or scenario. Declared artboards include their own names while loading. During a Storybook lookup, the tab names the destination page; the story name joins it once resolved. The grid belongs to the main canvas. Each embedded preview fills its artboard without adding another canvas grid or inner frame shadow.
For a component with no surrounding page, mark its origin-aligned root with
data-wb-fit-content and remove page padding, viewport minimum heights, and
backgrounds. With Fit or Resizable supported, its artboard follows the content’s
natural bounds, including after live input edits.
Layout
| Part | Where | Does |
|---|---|---|
| Sidebar | The Workbench view in VS Code’s activity bar, or the left edge of a standalone browser window | The space switcher, the collection list, the page list, and search |
| Space switcher | Top of the sidebar | The space showing, and the others to switch to. In VS Code it’s always there, for Add a space…; in a browser, only with more than one space. See Several spaces. |
| Collection list | Sidebar, under the heading Collections | The space’s collections |
| Page list | Sidebar | The chosen collection’s groups, pages, and scenarios |
| Search | Bottom of the sidebar | Filters every collection’s pages, groups, and scenarios |
| Top bar | Top of the canvas | The breadcrumb with the scenario switcher, lenses, size, actions, reload, source, reference, and more |
| Artboard | Middle | The page, labeled with its name and size by the artboard label |
| Toolbar | Floating at the bottom | Annotation tools, undo, clear, screenshot, and handoff |
| View controls | Floating at the bottom right | Recenter view, zoom out, the zoom level and its menu, and zoom in |
Inside VS Code, the sidebar is where a file tree usually goes, in your editor’s theme, and the canvas tab doesn’t repeat it.
The sidebar
- The collection list, headed Collections, is at the top. Pick a collection to show its pages in the page list and open its first page. When the page showing already belongs to that collection, it stays.
- Groups in the page list hold related pages. Select a group to expand it and open its first page. Selecting the group of the page showing, or a group’s arrow, expands or collapses it.
- Pages with two or more scenarios expand to show them. Pick a scenario to show it; the first is the page as authored. Selecting the page itself shows its first scenario, and selecting it again while it is showing collapses it. A Markdown page has nothing listed under it.
- Search, the field at the bottom (Search pages…), filters every collection’s pages, groups, and scenarios as you type, and groups the results by collection.
- TypeScript previews and Markdown pages defined in
*.workbench.tsfiles appear in the collections their titles name, beside the pages listed inworkbench.yaml.
In VS Code, the page list is one stop in the tab order. Up and Down move through its groups, pages, and scenarios, Right expands a group or page, Left collapses it, Home and End jump to the first and last, and Enter or Space shows the focused page or scenario. The problems list, above the page list, shows problems importing a catalog or TypeScript previews.
In a standalone browser, ⌘K or Ctrl+K jumps to search. Drag the sidebar’s edge to resize it, focus the edge and use the arrow keys, or double-click it to reset the width. The width is remembered.
The top bar
| Control | Does |
|---|---|
| Breadcrumb: space | The space’s mark and name, before the page. Select it to switch to another space. Shown when there is more than one space. |
| Breadcrumb: page and scenario | The page’s name, then the scenario showing. The scenario is the scenario switcher: select it to pick another scenario. On a Storybook lens, it picks a story of the current title instead. Shown when there is more than one to choose from. |
| Lens switcher | Switches between the page’s docs lenses, the authored page, and each implementation the page has, in that order. Shown when the page has two or more lenses. A page with docs opens on its first docs lens, one for each renderer of its examples. The authored lens defaults to Design, or Preview for a TypeScript preview. Every label is customizable. |
| Size switcher | Fit, Laptop, Mobile, and Resizable. See Artboard sizes. Disabled in a docs lens, because the docs fill the canvas. |
| Actions (pointer icon and switch) | Lets links navigate and forms submit in the page. Off by default. In a Workbench preview, links open the previews they’re mapped to and everything else is recorded under Actions; see Links and navigation. Through a lens whose page is served by something other than the workbench, such as a URL or Storybook lens, it is always on and can’t be switched. See Links and actions. |
| Reload | Reloads the current page. |
Open the source (</>) |
Lists the design file and the page’s code pointers, and opens one in the editor. For a TypeScript preview, it lists the preview definition and its source file; for a page with docs, its design file, then Docs, its Markdown, then each docs lens’s example source. On a Markdown page, Docs is the first row. A path that isn’t on this machine is listed but can’t be opened. |
| Copy reference | Copies a short text reference to the current view. See Copy a reference. |
| Open on its own | Opens the current page in your browser, outside the workbench. |
| Preview controls | Opens the inputs, Reset scenario, action log, and documentation of a TypeScript preview. Shown once the preview is ready. See Preview data, mocks, and actions. |
| More | Configure pages and Download design-system ZIP, which exports the whole current space across its collections and pages. Shown when the workbench server is running. |
When the canvas is narrow, Reload, Open the source, Copy reference, Open on its own, and Preview controls fold into More rather than overlapping.
Your choices of lens, size, and actions are remembered across pages and sessions. A page that doesn’t support a remembered choice uses its own default: the Design lens, a Markdown page’s own docs lens, or the first size it supports.
Artboard sizes
The size switcher sets the artboard’s size:
| Button | Size | Notes |
|---|---|---|
| Fit | The available canvas | Follows the canvas as you resize the editor. |
| Laptop | 1512 × 982 | A 14-inch MacBook Pro. |
| Mobile | 393 × 852 | An iPhone 15 Pro. |
| Resizable | 1024 × 768 to start, at least 320 × 320 | Drag the artboard’s left, right, or bottom edge, or a bottom corner. The last size is kept. |
The page always lays out at the artboard’s real size. An artboard larger than the canvas is zoomed out to fit, never squeezed, so a 1512-pixel layout is still 1512 pixels wide to the page. Screenshots are always taken at the artboard’s real size, whatever the zoom.
A page’s sizes decide which sizes are
enabled.
Zoom and pan
The canvas behaves like Figma’s:
| Input | Does |
|---|---|
| ⌘ or Ctrl + scroll wheel, or pinch | Zoom at the pointer |
| Scroll wheel on the canvas around the artboard, or Shift + wheel there | Pan. Over the page, the wheel scrolls the page. |
| Space + drag, or middle-button drag | Pan, anywhere on the canvas |
⌘ or Ctrl + = (or +), and ⌘ or Ctrl + − |
Zoom in and out, in powers of two |
| ⌘ or Ctrl + 0, or Shift 0 | Zoom to 100% |
| Shift 1 | Zoom to fit |
The view controls have Zoom out and Zoom in buttons on either side of the current level. Select the level for a menu with the same commands plus 50% and 200%. Recenter view, beside the zoom buttons, brings the artboard back to the middle of the canvas without changing the zoom level or the page’s scroll position.
Until you zoom or pan by hand, the artboard stays fitted: changing size or resizing the editor fits it again. Fitting never magnifies past 100%.
These shortcuts work while a page has focus, because the workbench reads them inside the pages it serves, and through Storybook’s key channel for a Storybook lens. A page from another origin, such as a URL lens, keeps its own scroll wheel.
Docs on the canvas
The canvas has two modes, and the lens decides which. In the default canvas mode, the page is on an artboard. In a docs lens, the canvas is in its docs mode: there is no artboard, the page’s docs fill the canvas, at most 960 pixels wide and centered, and the wheel scrolls them like a page in a browser. The size switcher stays visible but is disabled. Switching back to the design lens restores the artboard at its size. Zoom, annotations, screenshots, and handoffs work in a docs lens too; see On the canvas.
Keyboard and clipboard in the editor
Inside VS Code, pages behave like pages:
- Typing, caret movement, selection, copy, cut, paste, select all, and undo stay in the focused field or page.
- Editor shortcuts, such as the Command Palette or switching tabs, reach VS Code, including multi-key chords.
- Right-clicking a design page opens VS Code’s context menu with the page’s selected text.
- Select all works in a field, a note, or the page, but not over the top bar or the toolbar.
Pages from another origin, such as a URL lens, can’t receive the editor’s menu or clipboard integration. Storybook doesn’t forward keys while an input in the story is focused. Use Open on its own when you need full native behavior.
Keyboard shortcuts
Workbench adds no VS Code keybindings; these keys work inside the canvas and the sidebar. Use Ctrl where a shortcut shows ⌘ on Windows and Linux.
Canvas keys
| Keys | Does |
|---|---|
⌘ = or ⌘ + |
Zoom in |
⌘ − |
Zoom out |
| ⌘ 0, or Shift 0 | Zoom to 100% |
| Shift 1 | Zoom to fit |
| Space + drag | Pan |
| Escape | Close an open menu |
Shift 0 and Shift 1 don’t apply while you type in a field or a note.
Annotation keys
| Keys | Does |
|---|---|
| Escape | Leave the drawing tool for Select; with Select, deselect the annotation; while typing a note, finish it |
| ⌘ Z | Undo the last annotation, unless a field, a note, or the page has focus |
| Delete or Backspace | Remove the selected annotation |
| Arrow keys, Shift + arrow keys | Nudge the selected annotation 1 or 8 pixels |
| Shift while drawing | Keep arrows and lines at 45° steps, and rectangles and circles square |
| Shift while dragging a corner handle | Keep a rectangle or circle square |
| Double-click a note or comment | Edit its text, with Select |
Sidebar keys
| Keys | Where | Does |
|---|---|---|
| ⌘ K | Standalone browser | Jump to search |
| Escape | In search | Clear it |
| Down | In search, in VS Code | Move to the first result in the page list |
| Up, Down, Home, End | In the page list, in VS Code | Move between groups, pages, and scenarios |
| Right, Left | In the page list, in VS Code | Expand or collapse a group or page; Left on a page or scenario inside one moves to it |
| Enter or Space | On a page or scenario | Show it |
| Left, Right, Shift + Left or Right | On the sidebar’s edge, in a standalone browser | Resize the sidebar by 8 or 32 pixels |
Links and the address
The current view is recorded in the address’s hash, so reloading or opening a copied link lands on the same page, scenario, size, and lens:
#pages/sign-in.html:error@1512~staging
└ src └ scenario └ width └ lens
| Part | Values | Left out when |
|---|---|---|
| src | The page’s src |
Never |
:scenario |
A scenario id, or on a Storybook lens the part of the story’s id after -- |
The first scenario is showing, or the page has no scenarios |
!example |
In a docs lens, an example’s ID; the docs open scrolled to that example | No example is named, or the lens isn’t a docs lens |
@width |
fit, 1512, 393, or resizable |
In a docs lens, which has no width. Elsewhere the workbench always writes it, though a link you type may omit it |
~lens |
An implementation name, or design for the authored lens of a page with docs |
The page’s default lens is showing: its first docs lens (a Markdown page’s lens), or the authored lens of a page without docs |
The src is always the page’s src, also in a docs lens of a page with a
design. See Addresses for examples of addresses in a
docs lens.
After a page loads, the address is rewritten to describe exactly what is showing.
To get a link:
- Workbench: Copy Canvas URL copies the workbench’s address.
- Workbench: Open Canvas in Browser opens it in your browser.
- In a standalone browser, copy the address bar.
The workbench only listens on 127.0.0.1, so a link works on your machine
while the workbench is running. The port is the first free one from 3579, so
with several windows or spaces open, a saved link may point at another space
after a restart; the hash part stays valid. Share a
reference or a screenshot with other people instead.
Copy a reference
Copy reference identifies every artboard and the selection, with each page’s label, design file, scenario or story, size, and lens. Paste it into a conversation to point an agent or a colleague at the canvas. It doesn’t take a screenshot or include annotations. For those, use a handoff.
Agents can also read the same reference without a paste. Every open canvas
tells the Workbench server which artboards it shows, and
GET /_workbench/view on the server returns the reference from the canvas
you changed most recently. Projects with agent hooks set up can give
it to Claude Code and Codex with every prompt, and to MCP clients through a
current_view tool. A project with a .canonic folder gets the server’s
address in .canonic/.workbench/server.json; add that folder to
.gitignore.
Configure pages
More › Configure pages edits the collections and their pages in a form:
- Add, remove, and rename collections, and set their icons.
- Add a group to a collection with Add group, from the collection’s row or its details. A new group starts with one untitled page, since a group needs at least one; groups don’t nest. Rename and remove groups, and add pages to them.
- Add and remove pages, and edit their labels and source paths.
- Choose each page’s supported sizes.
Saving rewrites only the collections block of workbench.yaml, and the
sidebar refreshes. Scenarios, implementation mappings, and code pointers in that
block are preserved. Everything outside it, including comments, is left alone;
comments inside it are removed. The form edits workbench.yaml only, so
collections that workbench.local.yaml overrides on your machine keep showing
the local version. Editing the YAML directly always works too; see the
reference.
Using a standalone browser
The canvas also works in a regular browser:
- From VS Code, run Workbench: Open Canvas in Browser. The extension still serves the page, so handoffs and opening files in the editor work too.
- Without VS Code, run the server yourself. See Running without VS Code. Everything works except handoffs, opening files in the editor, and start commands.
In a browser, the sidebar is on the left of the page, browser shortcuts and menus work normally, and the camera downloads screenshots. Problems importing a catalog or TypeScript previews are listed only in VS Code’s sidebar.