Design system

Design in every session

How every session knows your design system: design.tsv, the component lookup and the release each product is on.

Last updated November 15, 2026View as Markdown

In the pilot

The design system module is in the pilot: it is on for pilot orgs first. An org admin can tell you whether your org has it.

When your product uses a design system, every session on that product knows it, on every harness. The agent builds with the system's own components and tokens, at the release your product is on, and stops when a part is missing instead of inventing one.

This needs the design module on your org and a product that declares the system it uses. If the design kill switch is on, sessions get no design part.

Declare the system your product uses

A session hears of a system only through the product's declared use.

Open the product's Design system tab

Open your product and choose the Design system tab. Systems it uses lists each declared system.

Declare a system

A maintainer of the product presses Declare a system and picks the system. A retiring system is marked as retiring, with what replaces it.

Say how the product takes it

Choose how it takes the system (registry, package, copy, submodule, workspace, runtime or theme). You can add a theme or brand, and a declared pin, such as 1.2.0.

Which release a session sees

Each session sees one release of each system its product uses, picked in this order:

  1. The release that matches the product's declared pin: react v1.2.0 (pinned).
  2. Else the version EasyCode found in the product's code: react v1.2.0 (found). See Found versions and update tasks.
  3. Else the latest release that is not withdrawn: spec v1.3.0 (latest), or (latest; pin not matched) when a pin matched nothing.
  4. Else the unreleased view: unreleased (no releases).

A session on the design system itself sees unreleased (this system).

What the session is told

At launch, the session gets a short Design system section in its instructions. It names the system and the release, and says whether the system is required ("use only its components and tokens") or preferred. It also says what to do when a part is missing: stop and offer the nearest component, a changed design or a request. A second system adds one line; a retiring one says to add no new uses.

The section points at files rather than repeating them, and it is never cut from the session's context.

The files the runner writes

The runner keeps the design record beside your org map, under the org checkouts root:

  • org/design.tsv: one row per component, token and rule of every release your products use, with the columns system, release, kind, name, status, item and detail.
  • Detail files under design/<system>/<release>/: one <Component>.json per component (props, variants, slots, states, the registry item and install command per library, story links), plus tokens.json and rules.json.
  • The release's render catalogue, when the system has one: each story's markup, class strings, stylesheets, icons and fonts, so a prototype looks like the real thing.

Rows never name a repo folder, so a member who cannot read the system's repos gets the same rows. A running session keeps the release it started with.

Look up a component

Any agent can read org/design.tsv and open a component's detail file. In Claude Code and Codex, the session also has the studio tool studio_design_system: give it the product to get the release, its components and its tokens, or add component to get one component's detail.

Prototype on the system

A prototype in system mode is built from the release's own parts. The agent copies a story's markup for each part and changes only text and a few safe attributes. Page styles may only place things.

Two tools check the work:

  • studio_ds_check resolves and checks a system-mode prototype folder without uploading it.
  • studio_publish runs the same resolver and checker, then publishes.

The resolver writes each part's exact class strings from the release, so a prototype cannot drift from the system. The checker refuses what the system does not have: an invented component, a hand-written class, a page style that restyles a part, a look-alike outside a part, an unnamed visible element, and a control that does nothing.

Prototypes are interactive on mock data: lists filter and sort, forms validate, and menus and dialogs open.

Check on the product's devices

Desktop app only

The device check renders in the desktop app's hidden window.

A product's maintainer or an admin picks its devices in the product's Devices section; without a choice, the default devices apply. Publishing a prototype needs a passed device check. In system mode, each frame renders at every device of the product, each data state renders at the first device, and a click pass presses every control. A control that changes nothing fails as "Dead control" with its id. A release with no render catalogue cannot be checked.

Pass the design gate

A workflow's design gate approves a system-mode prototype only when its check passed on every device. Otherwise it answers "The approved version's check did not pass on every device".

A small UI change can skip the prototype. The task's author presses Mark small on the gate and gives a reason. The gate then shows "Marked small by the author" with the reason, and the approver can accept with no prototype. Unmark small clears it, and so does a request for changes.

When a part is missing

The agent proves the part is missing: no component, no variant and no composition of existing ones. Then it offers three choices: the nearest component, a changed design, or a proposal. A proposed part is drawn with a dashed outline and a Proposed label, using only the release's tokens. To ask the system's team for it, file a request: see Design requests.

Next

Something wrong or missing? Suggest a change

On this page