> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reasonos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Project design systems

> Use your project's components and tokens, preview design changes on a branch, and make reviewed changes the default for future branches.

A project's design system lives with its code in
`.reasonos/design-system/`. Its README explains how to use the project's
components, tokens, and assets.

## Using the design system with an agent

The native engine receives a pointer to the design-system README through
project instructions; Claude Code receives generated plugin guidance when
the README exists in its workspace. For Codex or Gemini, ask the agent to
read the README. Starting with ReasonOS 1.0.2, they also receive this guidance
automatically.

For a frontend task, a useful instruction is:

> Read this project's design-system README and use its existing components
> and tokens for this change.

The guidance helps the agent find the right source; it is not an enforced
design check. Review the resulting application. Seeing a design system in
the viewer does not prove that an already-running agent loaded it.

<Note>
  After your workspace is updated to ReasonOS 1.0.2, start a new agent session:
  an existing CLI session may retain its previous instructions. Asking the
  agent to read the README always works. Hosted runtime updates are managed
  by ReasonOS. Your handwritten instructions outside the generated block
  remain yours.
</Note>

## What the branch selector shows

The project's **Design** page displays the selected branch's **committed**
design-system files. The default view follows the project's default branch.

Choosing another branch changes which version the viewer reads. It does
not switch a running workspace to another branch, merge files, or display
uncommitted edits.

## Previewing a design change

1. Open a feature branch's workspace.
2. Update the application and its design-system files together. Ask the
   agent to use the project's existing components and tokens.
3. Preview the running application in that workspace.
4. Commit the design-system changes to the feature branch. Select that
   branch on the Design page to inspect its committed version.
5. Review and merge the change into the project's default branch.

Committing the feature branch makes its version available to the viewer;
it does not make it the project's default.

## After merging

New branches created from the updated default branch inherit the merged
design-system files. Existing branches retain their own version until
they incorporate the change through your normal Git workflow.

The Design page's branch selector never performs that merge for you.

For the broader agent workflow, see [Using the Agent](/agents/using-the-agent).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.