Skip to content
Docs0.9GitHubInstall

Building on itDesign rules

Design rules

The look the web client and the iPhone app keep, for contributors who change a screen or add one.

This page is for contributors who touch the apps’ interface. It states the rules the existing screens follow, with the tokens that carry them.

The interface is monochrome: ink on paper, hairlines, and squared corners. Colour on screen always means something.

Surface File
Web tokens web/src/styles/tokens.css
Web primitives web/src/styles/quiet.css
iPhone tokens and primitives ios/App/Sources/Views/Quiet.swift

The two sets use the same names and the same values. Change a value in both, and use a token in place of a literal. Where the two apps behave differently, the iPhone app is the reference and the web client follows.

Token Use
--color-paper The page
--color-paper-2 Raised surfaces: the dock, row marks, inset blocks, the owner’s prompts
--color-paper-3 Selected and pressed
--color-ink Headings, values, an unread row’s title
--color-ink-2 An unread row’s second line
--color-muted Meta, times, section labels, a read row’s title
--color-rule Hairlines
--color-rule-2 Outlines and pending steps

Dark is neutral carbon and light is white paper, with the same structure. The theme follows the system unless the owner picks one.

The accent is ink: --color-accent is --color-ink, so a primary button is ink with paper text. Depth comes from the three paper steps and from hairlines.

Chroma on screen means one of these:

Hue Means
A state tone What an agent is doing
A project’s colour Which project a row or card belongs to. There are 12, the same on every surface.
The app colour The one the owner chose in Settings

Thinking, provider marks, and code highlighting have hues of their own, described below or set in tokens.css. A new element that wants colour to stand out gets size, weight, or position instead.

The four tones are the terminal chooser’s status colours, and they mean the same everywhere:

Token State Glyph
--tone-live Running A filled dot, breathing gently
--tone-ready Ready for the next prompt A ring
--tone-ask A question is open A diamond
--tone-alarm An approval is needed A triangle
--tone-quiet Unknown, starting, or exited A small muted dot; an arc that turns while starting
  • Every state has its own shape, so it reads without colour.
  • In a row of counts, only the states that need the owner keep their tone. The rest are muted.
  • Red is --tone-alarm. It means an approval or a failure, and is never decoration or a primary button.
  • Thinking has its own violet, --tone-think, which sets an agent’s thinking apart from what it says.

A plugin’s page never sends a colour. It names a tone (ask, alarm, ok, accent, muted) and the app picks the value. See Plugin UI.

Each provider’s mark is its owner’s trademark, shown only to name the provider and drawn in its owner’s colours. Never redraw one. The web client’s and the iPhone app’s copies match path for path, and a test checks it.

  • Sans for every word. On the web that is IBM Plex Sans; the iPhone app uses the system’s text styles, so every size follows Dynamic Type.
  • Mono only for figures, times, code, commands, and paths. On the web that is JetBrains Mono.
  • Numbers in counts and times are tabular.
  • An unread row’s title is ink, and a read one’s is muted.

The web scale, from tokens.css:

Token Size Used for
--text-xs 0.75rem Meta, chips, counts
--text-sm 0.8125rem Section labels, a row’s second line, labels
--text-body 0.9375rem A row’s title
--text-lg 1rem Headings
--text-xl to --text-3xl 1.125rem to 1.5rem Larger text

Line height is 1.55, and --measure is 780px.

Token Value For
--radius-tag 4px Tags
--radius-control 6px Buttons, fields, chips, inset blocks
--radius-card 8px Cards
--rule-hair 1px Every border and divider

--radius-round is for circles, such as a row’s mark and a chat’s picture.

A section starts with a muted label over a hairline.

Spacing steps are --space-3xs (2px) through --space-2xl (64px): 2, 4, 8, 12, 16, 24, 40, 64. Controls are 32px tall, or 28px small.

Lists use fixed row metrics so titles line up down a screen: a 36px leading mark with a 12px gap on the web, 40 points on the iPhone, and the state glyph at the mark’s corner.

A list row follows one pattern on every screen:

  • A leading mark: a monochrome symbol for the provider, the Master, or a project, or the chat’s own picture, in a neutral circle.
  • The agent’s state as its glyph at the mark’s corner.
  • A title, with an optional second line.
  • Meta and times at the trailing edge, in mono where they are figures.
Token Value
--dur-micro 100ms
--q-dur 150ms, ease-out: the quiet look’s transitions, such as a glyph changing tone
--dur-short 180ms
--dur-long 360ms

The running dot’s breath is the only motion that never stops, and it never fades far enough to read as another colour. On the iPhone it holds still with Reduce Motion, and a changed state cross-fades.

  • Check quiet.css and Quiet.swift for a primitive that already does it: section labels, counts, chips, rows, state glyphs, and marks are all there.
  • Build the same change on both apps, with the same names.
  • Look at it in light and dark.
  • If it shows state, use the glyph and its tone. If it doesn’t, it has no hue.