Design system

A design system tells the agent how your product should look, so a change to the interface comes back in your brand and not as generic output. You write it once as plain text in Markdown. It applies to every run of the project, and you can also set one for your whole organization.

When to use it

Use it when your tickets change what users see: pages, forms, buttons, emails. Without it the agent chooses colors, fonts and spacing on its own. With it, the agent follows yours.

Two levels

• Organization. One master text for the whole install, in Settings → Organization design system. Every project that follows it gets it.
• Project. A text for one project, and optionally a file in its repository (for example docs/DESIGN.md) that is read at run time, so the design system can live beside the code and change with it.

For a run, the agent receives them in this order: the organization text (unless the project turns it off), then the project text, then the repository file. Where they disagree, the project wins over the organization, and the prompt says so.

Set it up

1. For the whole organization: open Settings → Organization design system, paste your text and save.
2. For a project: pick the project, then open Settings → Design system. Write the text, and optionally enter a Repository file path. The page shows whether the file was found, and how many characters of the combined text will be used.
3. Turn off Also follow the organization design system for a project that has its own brand.

What the agent does with it

When the combined text is not empty, the plan, implement, review and fix steps get a "Design system" section. It tells the agent that the design system applies to every user-facing change, to use the tokens, components and patterns it names, and never to invent colors, fonts, spacing or component styles when the design system names one.

• If a ticket contradicts the design system, the agent follows the ticket and says so in its summary.
• The reviewer treats a clear violation as a finding, so it goes through the normal fix round.
• With no design system, nothing about the prompts changes.

Limits

Each part (organization, project, repository file) is cut at 20,000 characters, and the whole at 40,000. A part that is cut gets a visible note at the end, so you and the agent can see it. Keep it short and concrete: the agent reads the whole text on every run. The repository file must stay inside the project's checkout.

What is sent, and what it uses

The design system is part of the prompts, so it goes to your model provider with the rest of a run, like your project instructions. Do not put secrets in it. The run log records that a design system was applied and how many characters each part had, never the text.

It adds its length to each prompt it is part of, so a long design system uses more model work on every run. A page of rules is a small part of a typical run.

An example

# Acme Design System

## Brand

- Primary blue is `#1F4FD8`. Use it for the main action on a page and for links. Never use it as
  a background for large areas.
- Text is `#14213D` on white. Muted text is `#5B6578`. Errors are `#B42318`.

## Typography

- Inter for everything. Headings are 600 weight, body is 400. No other typefaces.
- Sizes come from the scale 12, 14, 16, 20, 28, 40 pixels.

## Spacing and layout

- Spacing is a multiple of 4 pixels. Cards have 16 pixels of padding and 8 pixel corners.
- Content is at most 1200 pixels wide.

## Components

- Use `Button`, `Card`, `Table` and `Dialog` from `src/ui`. Do not write your own buttons.
- Buttons use Title Case. One primary button per page.

## Never

- No gradients, no drop shadows heavier than the one on `Card`, no emoji in the interface.
- Do not add a new color. If a design needs one, say so in the summary instead.

To keep it in your repository, put the same file at docs/DESIGN.md and enter that path as the Repository file.