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:
- The release that matches the product's declared pin:
react v1.2.0 (pinned). - Else the version EasyCode found in the product's code:
react v1.2.0 (found). See Found versions and update tasks. - Else the latest release that is not withdrawn:
spec v1.3.0 (latest), or(latest; pin not matched)when a pin matched nothing. - 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 columnssystem,release,kind,name,status,itemanddetail.- Detail files under
design/<system>/<release>/: one<Component>.jsonper component (props, variants, slots, states, the registry item and install command per library, story links), plustokens.jsonandrules.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_checkresolves and checks a system-mode prototype folder without uploading it.studio_publishruns 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