Import your design system

What you're configuring — the three pointers

Every design system, however it's imported, boils down to three pointers into your codebase. The browser importer infers them for you; the desktop tray and CLI take them as flags; the published YAML carries them as fields:

• Styling — your globals.css, tailwind.config.*, design-token JSON, or whatever carries your colours, spacing, and theme variables.
• Components — the directory or package entry that exports the components you want available on the canvas (React components for React projects, Vue components for Vue projects).
• Frame — optional but often what separates "styled" from "unstyled". A wrapper component that mirrors your real <App>'s provider stack (<ThemeProvider>, query client, route mocks, etc.) and pulls in any global stylesheet your entry doesn't import, so components render in the same context they would in production. Point it at an existing module, or — in the browser importer — let Statecraft author one for you when the context is scattered across your app shell.

Continuous publishing from your machine

The browser importer publishes once per refinement round. If you're iterating on a component library locally and want every save to bounce to the canvas in ~2 seconds — without re-importing — install the desktop tray app. The tray runs a daemon that watches your repo, rebundles on every save, and uploads to Statecraft.

Open the wizard from any of three places: the menubar dropdown (Add a design system…), the Design systems panel in Settings, or the first-run onboarding banner. The wizard:

1. Pick the repo root, the workspace, a slug (lower-case kebab, 3–32 chars — used as the import name in canvas JSX), and an optional display name.
2. Pick the main file that exports your components (usually src/index.ts). Four shortcut chips (src/index.ts, src/index.tsx, src/index.js, index.ts) pre-fill the path so you can confirm with a click. Optionally expand Add a wrapper component for a default-export wrapper that provides theme, query-client, and route mocks.
3. Click Add design system. The daemon writes a statecraft.yaml manifest in your repo (the single source of truth for the build — entry, framework, install, Tailwind, etc.), records a thin pointer to it in .statecraft/live.json, registers the design system on the server with kind: live, and starts watching. The first build can take a minute on first install. The Design systems panel shows live status (Building / Live / Failed) for every registered DS. Edit statecraft.yaml and save anytime to change build config — the daemon rebuilds.

Once the first bundle is uploaded, your machine isn't load-bearing — collaborators keep rendering the last-published bundle even with your daemon offline. Build failures (TypeScript errors, missing imports) surface in the Design systems panel as a red row with a classified hint plus a prompt to edit statecraft.yaml and save. The bundle pointer is intentionally untouched on failure, so teammates keep rendering the last-good bundle while you fix the error.

From the CLI

The same registration is statecraft import --repo-root . --framework react --slug acme-ui --entry ./src/index.ts — useful in scripts, on machines without the desktop app, or when you want to script the whole onboarding. --repo-root and --framework are both required (no silent defaults); on a TTY without them you'll be prompted, off-TTY the CLI errors pointing at the missing flag.

When run interactively, import also asks four short questions about how to install your component dependencies (where to run install, which package manager, whether to skip install) — confirm the defaults or override. After registration succeeds, the CLI prints the path to _design-systems/_status.md so you can watch the first-build progress.

Add --wait to block until the first build reaches a terminal verdict; the CLI exits with 0 / 1 / 124 for clean / failed / timeout — the right shape for scripts and coding agents. statecraft live list shows every kind: live design system registered on this machine.

To change install, bundler, or engine config later, edit the committed statecraft.yaml and save — the daemon rebuilds. There is no live update verb; the manifest is the edit surface. statecraft live build --slug acme-ui manually nudges a rebuild without modifying source. statecraft live status --slug acme-ui (also --wait-capable) queries the current build verdict. statecraft live rm --slug acme-ui removes a registration without deleting the design system from the server (the editor UI keeps ownership of deletes so a stray CLI run can't drop a teammate's work).

React or Vue

Statecraft supports both. Each design system declares framework: react or framework: vue in its YAML and is filtered against the project's framework when a designer creates a project — Vue DSes for Vue projects, React DSes for React projects. For Vue, pass --framework vue on statecraft import and point --entry at a .ts barrel that imports your .vue SFCs (or directly at a .vue file).

Styling pipelines

Tell Statecraft once how your library produces styles and the daemon wires the matching plugin into its Vite toolchain. Every option is a per-DS flag (or YAML field) — never auto-detected, because past guessing rabbit-holed users in monorepo subpackages.

• Tailwind v3 or v4. Pass --tailwind v3 --tailwind-css ./path/globals.css --tailwind-config ./path/tailwind.config.ts (or --tailwind v4 --tailwind-css ./path/globals.css) on import. The daemon adds @tailwindcss/vite (v4) or wires the PostCSS plugin (v3) into the scratch build.
• Build-time CSS-in-JS — eight engines covered: vanilla-extract, linaria (via @wyw-in-js/vite), pigment-css, stylex, compiled, macaron, windi-css, panda. Pass --css-engine vanilla-extract (or whichever you use) on import and the daemon installs the matching plugin into the scratch toolchain. For StyleX and Windi the daemon also auto-imports the engine's virtual CSS module (virtual:stylex.css / virtual:windi.css) into the bundle entry. Panda additionally needs --panda-config ./panda.config.ts for its pre-build codegen step plus --css-engine-import ./src/styles/index.css pointing at your @layer directive CSS file (Panda has no canonical default path).
• UnoCSS uses its own dedicated unocss.build: YAML block — pass --unocss-config ./uno.config.ts on import, optionally --unocss-preset uno --unocss-preset icons and --unocss-globals-css ./src/styles/globals.css. The daemon adds unocss to the scratch, wires the Vite plugin before react(), and auto-imports virtual:uno.css.
• Hybrid runtime/extract — kuma-ui. Default mode runtime-injects (works out of the box); static-extract mode is opt-in via --css-engine-import.
• Runtime CSS-in-JS — emotion, styled-components, stitches, goober, jss, theme-ui, fela, plus Compiled (its babel plugin compiles to a runtime). All work without a plugin chain — the host singletons them across every iframe via the importmap. Declaring them via --css-engine only changes how Statecraft reports a 0 KB CSS bundle (from "warning" to "expected").
• Plain CSS / SCSS / CSS Modules / Less / Stylus work out of the box — Vite handles them natively, no engine entry needed.

Populating the components catalog

Once the build is green — the Design systems panel shows Live · published for that row, or _status.md reports Status: OK — there's one more step before your components are fully usable in the canvas: populate components: in the published YAML.

Both scope: (the list of names usable in templates) and components: (the palette catalog) are hand-authored. Statecraft writes the bundle's named exports to _design-systems/<slug>.exports.txt in the sync folder as a copy-from list, but neither field is auto-populated — the runtime treats scope: as the single source of truth, and the palette can only render rich entries (snippet, props, category) that a human supplied. We can't fabricate those — the right snippet for <Card> usually has children, your Button's variant values are project-specific, the category groupings reflect your team's mental model.

While components: is empty, the editor flags it loudly: _status.md shows Status: WARNING — palette empty with the list of scope entries that have no matching catalog block, the toolbar's component palette renders an empty-state listing the bundled exports, and _reference.md shows the same warning under each affected DS heading. CSS-only / Tailwind-only design systems can legitimately ship without a components: block, so this is a warning rather than a failure — but pairing a populated scope: with empty components: is almost always an authoring half-step.

Open <sync-folder>/<workspace>/_design-systems/<slug>.yaml and add a components: block. Each entry should match a name in scope::

scope:
  - Button
  - Card
  - FormInput

components:
  - label: Button
    tagName: Button
    category: Form
    snippet: '<Button variant="solid">Click</Button>'
    props:
      - name: variant
        type: string
        label: Variant
        options:
          - { label: Solid, value: solid }
          - { label: Ghost, value: ghost }

  - label: Card
    tagName: Card
    category: Layout
    snippet: |
      <Card>
        <p>...</p>
      </Card>

  - label: Form input
    tagName: FormInput
    category: Form
    snippet: '<FormInput placeholder="Email" />'

The Core gallery starters (shadcn, radix-ui, ant-design, mui) are good references for richer schemas — install any of them from the gallery and open the row on the Design Systems page to see the full catalog YAML.

From a private repo

For libraries kept in a private repo where you don't want a public bundle, install the desktop tray (or the standalone statecraft CLI) and run statecraft import against the repo root. The daemon watches the working tree, rebundles on every save, and uploads the JS+CSS pair to Statecraft storage — no public hosting or HTTPS URL needed. Collaborators render the last-published bundle even when your machine is offline.

Monorepo / pnpm-catalog setups: pass --install-cwd, --install-command, or --package-manager at import time. The optional frameComponent field names a provider wrapper the bundle should re-export (<ThemeProvider>, route mocks); the iframe wraps every rendered state in it. Build failures surface in the workspace's _design-systems/_status.md with a classified hint.

The npm-package source kind in detail

The npm package starter (mentioned above) is a design-system source kind that takes a package name and an exact version — no bundle, no daemon, no CI:

name: Chakra UI
source:
  npm: "@chakra-ui/react"
  version: "2.8.2"

scope:
  - Button
  - Box
  - Stack

providers:
  - import: ChakraProvider

styleCache:
  kind: emotion

Packages resolve through esm.sh at render time — there's no build step in Statecraft. The package needs to be ESM-compatible and work with the React version Statecraft ships. Good for public libraries you don't need a custom build of; for anything custom or private, use statecraft import.

Things that just work — no config needed

A few categories of components routinely surprise people with whether they'll render. Most of them are handled automatically:

Modals, popovers, and tooltips. Statecraft renders each state inside its own sandboxed iframe — and the design system runs inside that frame. So components that portal to document.body — modals, dialogs, popovers, dropdown menus, tooltips, toasts — render normally: their portal lands in the frame's own body, not the editor. Headless UI, Radix, MUI, and Ant Design overlays all work, each contained to its own state frame, and a library can never leak styles or overlays into the editor chrome or into another state.

Routing components. Many real components reach for the app's router — a Next <Link>, a react-router <Link to="/profile">, a wouter useLocation. In Statecraft there's no real router to navigate (each state is a static snapshot), but those components still need something above them to read context from. The canvas mounts inert no-op providers automatically so they render without crashing:

• react-router-dom v6+ — wrapped in a <MemoryRouter>. <Link>, useLocation, useNavigate, useParams all work; clicks don't actually navigate.
• wouter — wrapped in an in-memory <Router>. Same story: hooks resolve, links render, nothing navigates.
• next/link, next/navigation, next/router — redirected to inert shims (the real Next.js packages only work inside next dev / next build). <Link> renders as an <a>; useRouter, usePathname, useSearchParams return "no current route". redirect() and notFound() throw a clear error.

No design-system configuration needed — just import and use. The one case that does need configuration is @tanstack/react-router: declare its <RouterProvider> via your DS YAML's providers: chain (or the bundle's frame component) so tanstack hooks resolve.

When loading fails

When loading fails, the canvas shows a resolver error in place of the preview. The most common causes are covered in the YAML reference's "Common esm.sh errors" section. For kind: live design systems, _design-systems/_status.md is the canonical "did the last build work?" check — read it before assuming anything's deeper than a YAML typo.