Skip to main content
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.
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.

​
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.