# Design in every session

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

> **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](/design-system/found-versions-and-updates).
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](/design-system/design-requests).

## Next

- [The design system record](/design-system/the-record)
- [Start a session](/guides/start-a-session)
- [Studio: share and review](/guides/studio-share-and-review)
