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.
Where the values live
Section titled “Where the values live”| 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.
Colour
Section titled “Colour”Surfaces and ink
Section titled “Surfaces and ink”| 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.
What colour may mean
Section titled “What colour may mean”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.
State tones
Section titled “State tones”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.
Provider marks
Section titled “Provider marks”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.
Radii and rules
Section titled “Radii and rules”| 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.
Motion
Section titled “Motion”| 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.
Before you add something
Section titled “Before you add something”- Check
quiet.cssandQuiet.swiftfor 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.