DOCUMENTATION

A shared design.
A local workflow.

Connect the project’s design source to your coding agent through instructions, references, MCP tools, visual editing and validation. Studio is one part of this workflow.

Start with the Canon skill

Install the entry skill for your coding agent, whether you already have a shadcn/ui project or are starting a new one:

npx canon-ds@latest setup

Select your agent and installation scope in the installer, then reload its session if needed. In Codex, invoke $canon; in other agents, select the installed skill or ask to use the Canon skill.

Existing shadcn/ui project

Open the application folder in your coding agent and ask:

Use the Canon skill to connect this shadcn/ui project. Preserve its components and theme. Do not rebuild the app.

The agent inspects the installed library, adopts it without reseeding the theme, and prepares design references, MCP and Studio. If Canon is already connected, it reuses that connection. Your application remains the source of truth.

New project

Use the Canon skill to build a local todo app in a new folder, with shadcn/ui.

The agent creates the framework app, installs and connects shadcn/ui and Canon, implements the requested flows and verifies the result. You can then refine the shared design in Studio.

setup copies the entry skill included in that Canon version into your chosen agent and scope. It does not initialize a library or change your app. The copy survives npm cache cleanup. Run setup again to update it; installed skills do not update automatically.

For a scripted installation, use npx canon-ds@latest setup --agent codex --yes in the target folder, or add --global for all projects. --root <directory> selects a different existing folder. --yes requires an explicit agent. See npx canon-ds@latest setup --help.

The entry skill guides your agent. After connecting a project, Canon generates a separate design-system skill and references specific to that project. Installing the npm package alone does not install the entry skill into your agent.

Prefer manual setup?

Use Node.js 22.18 or newer and your project’s existing package manager. Canon 0.2.1 or newer provides live library context through MCP.

npm install --save-dev canon-ds
npx canon --version
npx canon adopt
npx canon adopt --apply
npx canon studio --port 0 --open

--save-dev (or -D) adds Canon to development dependencies. Your deployed app uses its own component source and theme. Adoption preserves an existing shadcn library; follow the library guide for a new application.

npx canon setup

The design harness.

A harness is the environment around an agent that supplies context, instructions, tools and feedback. Canon provides these pieces for the design of an application.

In library mode, the installed component source and theme are authoritative. Canon inventories that source, generates design references, installs instructions in the repository, exposes MCP tools, offers visual editing through Studio, and checks supported style violations.

Canon is not an autonomous coding agent or a hosted runtime. Your coding agent composes the application; your framework serves it. Instructions and checks help consistency but do not guarantee compliance.

From setup to shipping.

1. Create or choose an app. Canon works inside a framework project. Use adopt for an installed shadcn/ui library, or init --lib shadcn to initialize and seed a library.
2. Inspect and connect. Review the adoption plan before applying. Canon reads the installed component inventory, theme variables and supported variants.
3. Install agent context. Initialization/adoption normally builds references and installs managed instructions, skills, rules and MCP configuration. Where supported, --no-hooks skips adding the optional Claude edit hook.
4. Start the agent with the design. Read AGENTS.md and DESIGN.compact.md, then retrieve relevant details through MCP or DESIGN.md. A client may require enabling its project MCP server.
5. Build the actual product. The agent reuses installed components and implements routes, data and behavior. An overview example is not a generated product screen.
6. Refine in Studio. Inspect the real components, adjust supported styles and theme tokens, and compare light/dark and mobile/desktop drafts.
7. Save. Shared source and generated references update. Your app picks up source changes through its normal reload or build. After external source edits, run canon sync.
8. Validate. Run canon lint and canon check, review findings, run the application’s tests and inspect it in the browser. Deploy through your application’s existing workflow.

What Canon writes.

These are the installed project references and integrations. Their content depends on the active design mode and project inventory.

Generated DESIGN files, the design-system skill and Cursor rule are Canon-managed outputs. Put project-specific instructions outside the managed AGENTS.md/CLAUDE.md block. Source paths and theme filenames are discovered from your project; they are not always components/ui and app/globals.css.

Agent instruction example

Read AGENTS.md and DESIGN.compact.md.
Use Canon MCP to retrieve the relevant design rules and components.
Reuse the installed components and shared theme.
Implement application behavior in the app.
Review lint findings and verify the running UI.

This is a suggested prompt, not a verbatim generated file. Canon supplies the project-specific references during setup.

Feedback, with clear limits.

canon lint reports supported style violations. canon check checks build consistency and runs lint. The optional Claude edit hook reports lint feedback after supported edit events; it does not prevent an agent from writing code.

MCP gives compatible clients access to tools such as design_rules, list_components, get_component, search and lint_code. In library mode, these tools read the installed component source and declared theme variables on each request. They do not return Canon’s native catalog. Application patterns are not inventoried by the library adapter; component source remains authoritative for dynamic props and behavior.

Upstream library classes can trigger lint findings. Review them against the installed source rather than blindly rewriting the library. Canon does not replace functional tests, accessibility checks or browser verification, and it does not deploy your application.

Your existing library,
in Studio.

Available now: shadcn/ui. More library adapters are planned. They are not supported yet; this guide documents the currently available adapter.

Already using shadcn/ui?

Adoption inventories installed components and preserves the existing theme. Review the plan before applying it.

npx canon adopt
npx canon adopt --apply
npx canon studio --port 0 --open

Run this from a supported shadcn/ui project with its configuration and components installed. Canon does not turn every component in the upstream catalog into an installed component.

Starting a new library

First create your application with your chosen framework. Then initialize the library from that app's root:

npx canon init "My product" --lib shadcn
npx canon studio --port 0 --open

This runs the library's setup when needed, installs a core selection of components, and applies the Canon preset to the theme. Use adopt to preserve an existing theme. Initialization deliberately seeds a theme.

Add a component

npx canon add accordion
npx canon sync

In library mode, installation uses the library's own CLI. Canon then updates its inventory and generated references.

Change a style.
Keep a shared source.

Theme and typography

Theme shows components together in an overview so you can see shared changes in context. Edit declared theme variables for light and dark modes. Typography displays type samples and the project's available font configuration; samples are presentation examples, not an installed Typography component.

Find the right theme control

Only tokens found in your theme appear. The preview appearance switch selects light or dark for inspection; editing one appearance does not automatically replace the other. A token changes elements that actually reference it. Component variants and instance overrides can take precedence.

Installing as a development tool

npm install --save-dev canon-ds adds Canon to devDependencies in your package.json. -D is the shorter form. Canon runs while developing; the deployed app uses the saved component source and theme CSS.

Components

Select an installed component, switch between interaction and inspection in the preview chrome, and choose a base, variant, or exported part in the inspector. Hover highlighting helps identify the selected source.

The preview compiles your actual React source with draft edits in memory. Composed examples supply content and props; their shared appearance comes from the installed components and project theme.

Draft, then save

1. Change a supported property or theme token.
2. Review the component and its use in Theme, including light and dark modes.
3. Choose Save to write supported changes to the project files.

Reset discards the unsaved draft. Saved source changes reach your app through its normal reload or next build. Canon does not deploy the application.

Restore shadcn defaults

Open the arrow beside Reset and select Full reset. Canon prepares the current official defaults for the style and base color in components.json. Review the affected components, then confirm Restore defaults. It restores supported shared component styles and declared light/dark theme colors and radius, while preserving application logic, project fonts and custom tokens.

A backup is saved under .canon/backups/library-reset/. Preparation and cancellation do not change files; edits made after preparation block the reset. This needs internet access and uses current upstream defaults, not a historical version snapshot. Unsupported configurations are reported before any write.

What can be edited?

Declared theme variables, supported CVA base and variant classes, defaults, and supported static part class literals. Dynamic expressions, application behavior, and unsupported source shapes stay read-only. The inspector reports these limits; not every prop of a component is a style control.

If the source changes while you edit, a conflict prevents silently overwriting it. Reload the source and reapply the intended changes.

Design context,
where you build.

Initialization and adoption generate design references and install supported agent configuration. Your agent can discover components and read focused design information through MCP or the generated files.

npx canon sync
npx canon mcp

sync rebuilds references after external source edits. mcp is a stdio server started by an agent client, not a browser page.

If the current agent session has not loaded the MCP configuration, reload the client. The skill can continue from the generated references and actual source while MCP is unavailable; it should report which path it used.

A useful instruction

Use the installed design system and shared components for this project. Read the generated Canon design references before changing the UI. Reuse existing tokens and variants, and verify the result in the running application.

Canon supplies design context and style checks. Your agent still implements page composition, data, routes, application behavior, and tests.

Prefer Canon's
own catalog?

Native mode stores design definitions as JSON and generates CSS, React wrappers, documentation, and agent references. It is a separate workflow from editing installed shadcn/ui source.

npx canon init "My product"
npx canon studio --port 0 --open

Integrate the generated CSS into the app using its framework's normal CSS imports. Use canon sync after changes made outside Studio.

Explore the native catalog →

Read the native workflow guide →

Connect from the public catalog

The public catalog is static. Its connection procedure imports the native catalog into your project; it does not adopt your existing shadcn library.

npx canon connect https://marcosdocanto.github.io/canon/CONNECT.md
npx canon studio --port 0 --open

The everyday commands.

Use --root and --design where supported to target a different project or configured design directory. Check each command's help before scripting it.

Built in the open.

Source code, issues, and pull requests live on GitHub. The package is distributed as canon-ds on npm under the MIT license.

See the 0.2 migration guide and changelog for the transition.

Contribute

Start with the contribution guide. Include reproducible steps for bugs, and review changes to shared component styles in the real Studio.

Prepare a release

The maintainer release guide covers package checks, GitHub Pages, and npm publishing. A local site build does not publish an npm package.

npm run test:ci
npm run release:check
npm run build:site

This documentation describes the current source. Compare it with your installed version before depending on a newly added feature.