Documentation
Get Workbench
Workbench docsGetting started

Getting started

This guide takes you from installing the extension to a working canvas with design pages, a page state, and a preview of a component from your code. It takes about five minutes.

1. Install the extension

In VS Code, search for Canonic Workbench in the Extensions view and click Install, or install it from the Visual Studio Marketplace.

Cursor, Windsurf, and other VS Code forks don’t use the Visual Studio Marketplace. For them, download the .vsix for your computer from the latest Workbench release:

Computer File
Mac with Apple silicon canonic-workbench-darwin-arm64.vsix
Mac with Intel canonic-workbench-darwin-x64.vsix
Windows canonic-workbench-win32-x64.vsix
Windows on Arm canonic-workbench-win32-arm64.vsix
Linux canonic-workbench-linux-x64.vsix
Linux on Arm canonic-workbench-linux-arm64.vsix

Install it from the terminal:

code --install-extension canonic-workbench-darwin-arm64.vsix

Or open the Extensions view, choose … › Install from VSIX…, and pick the file. Forks have the same menu, and their own command-line tool, such as cursor --install-extension.

Each file bundles the runtime its platform needs for screenshots and TypeScript previews, so there is nothing else to install. VS Code 1.123 or later is required. Screenshots need macOS 13 or later, Windows, or Linux with a display; see The screenshot helper.

The release builds are unsigned. Desktop macOS is the most exercised platform; Windows and Linux builds have not been validated as thoroughly.

If VS Code was already open on a project, run Developer: Reload Window after installing, so running windows pick up the extension. To update or remove it later, see Updating and Uninstalling.

2. Write workbench.yaml

Create workbench.yaml at the root of your project. Every src is a path from that root. Workbench looks for the file at the top of each folder open in VS Code, so in a monorepo either put it at the repository root, or open the folder that contains it; see Projects in a subfolder.

name: Acme

collections:
  - name: Pages
    icon: file-text
    items:
      - label: Sign in
        src: pages/sign-in.html
        states:
          - id: default
            label: Default
          - id: error
            label: Wrong password

  - name: Components
    icon: component
    items:
      - label: Button
        src: components/button.html
  • name titles the sidebar in a standalone browser and names design-system exports.
  • Each entry under collections is a collection, a button in the sidebar’s collection list. icon is any Lucide icon name, written in kebab-case.
  • Each entry under items is a page: a label and the HTML file to show. A src ending in .md is a Markdown page instead: docs with live examples of your components. Any page can also have docs, with docs.
  • states lists variations of one page. The first is the page as written.

The configuration reference lists every key.

3. Make the page answer to its state

Declaring a state in the YAML adds it under its page in the page list. The page decides what that state looks like. The simplest way is CSS keyed off an attribute the workbench sets on <html>:

<!-- pages/sign-in.html -->
<style>
  .alert { display: none; }
  html[data-wb-state="error"] .alert { display: block; }
</style>

<p class="alert">That password isn't right.</p>

There are two other ways, covered in Pages and states. You don’t add any script tags: the extension injects what a page needs when it serves it.

4. Open the canvas

Open the project folder in VS Code. When a folder contains workbench.yaml, the Workbench icon appears in the activity bar. Its view, the sidebar, shows your collections and pages where a file tree usually goes.

Pick a page, or run Workbench: Open Canvas from the Command Palette. The canvas opens in an editor tab and shows the page on an artboard at a real device width.

Try these:

  • Pick Wrong password under Sign in to switch state.
  • Use the size switcher in the top bar for Laptop, Mobile, a Resizable artboard, or Fit.
  • Draw on the page with the annotation tools in the toolbar at the bottom, then select Copy handoff. The screenshot with your annotations is saved and a prompt describing every annotation is copied to your clipboard, ready to paste to an agent.

Workbench also lists any TypeScript previews and Markdown pages defined in *.workbench.ts and *.workbench.tsx files, once you trust the workspace. Step 6 adds a preview.

In VS Code, saving workbench.yaml or workbench.local.yaml rebuilds the sidebar and refreshes the canvas. Workbench: Refresh Pages does the same on demand. In a standalone browser, reload the page.

5. Ignore the files that belong to one machine

Add these to .gitignore:

workbench.local.yaml
.canonic/.handoffs/
  • workbench.local.yaml holds overrides for your machine, such as a dev server’s port or where another repository is checked out. See Local overrides.
  • .canonic/.handoffs/ holds the screenshots that handoffs save.

Workbench writes nothing else into the project unless you save Configure pages, which rewrites workbench.yaml. See Files and network access.

6. Preview a component from your code

Design pages show what a page should look like. A TypeScript preview renders the real component from your source, in named states. Next to a React src/Button.tsx that exports Button, add src/Button.workbench.ts:

import { definePreview } from '@canonic2/workbench';

export default definePreview({
  id: 'components/button',
  title: 'Components/Button',
  adapter: 'react',
  source: { entry: './Button.tsx', export: 'Button' },
  inputs: { label: 'Continue', disabled: false },
  states: {
    default: {},
    disabled: { inputs: { disabled: true } },
  },
});

Run Workbench: Refresh Pages. A second Button appears under Components, with Default and Disabled states, rendered with your project’s own React. Workbench supplies @canonic2/workbench when it compiles the file; to type-check it, run npm install --save-dev @canonic2/workbench (see Types). Other frameworks work the same way; each has its own guide: React, React Native Web, Vue, HTML, and Astro. For anything else, see Custom adapters.

Removing Workbench from a project

Delete workbench.yaml and workbench.local.yaml, along with any .workbench.ts and .workbench.tsx files, workbench.config.ts, and workbench-env.d.ts you added, and the .canonic/.handoffs/ folder. Your pages contain nothing Workbench-specific beyond optional state attributes and CSS, which are inert without it. To remove the extension itself, see Uninstalling.

Next steps

View Markdown on GitHub ↗