Design rules

The rules that don't bend when you touch a screen — pulled from the audits, kept here so they don't drift.

These rules come from CLAUDE.md and the design × engineering audits (docs/08a-audit-brief.md, docs/08b-ux-brief.md). They are short on purpose. Each rule has an argument in another document. If the argument is repeated here, the two copies can drift out of sync.

The environment switcher

The environment switcher in the sidebar (top-left) is the only place where a person chooses an environment. Everywhere else, the environment is read-only context. Examples are "in production · switch environment in the sidebar," --env production in a CLI chip, and the environment column of an audit row. Do not add a second switcher, tabs or a segmented control. Do not add a column that a reader can mistake for a control.

Buttons

Every button must center its label:

display: flex;
align-items: center;
justify-content: center;

The product has no left-aligned button label.

Casing

Use sentence case everywhere. The rubber-stamp "ROLLED BACK" is the one caps exception in the whole system. See Copy voice and casing.

Negative color

Negative color (--color-negative) appears at most once on a screen. Caution uses text alone, never a color fill. See Brand and tokens.

Sidebar counts read Flags 13 / Experiments 5. The signed-in person in every screenshot and mockup is Mia Okafor · MO. Numbers come only from docs/06-canonical-numbers.md. No other source can invent a figure.

Paper gotchas

Paper (file 01M2Q303RK19BADQ6XBRKCD8PK) has a few rules that the team learned the hard way. docs/00-context.md has the full rules:

Do not use margins, display: grid, tables or <span> rich text inside a text node. Paper flattens <span> rich text. Use separate text elements.
Use absolute commands with an explicit L in SVG paths (M38 40 L38 45). Do not use the H/V shorthand.
Text children of an absolutely positioned container can lose position: absolute on their own. Set it explicitly on each child. Verify the result with a screenshot.
When the content of an artboard is final, set the height of the artboard to fit-content. Do not guess a fixed number.

Where these rules come from

Every rule on this page comes from a specific audit finding or product decision. docs/08a-audit-brief.md, docs/08b-ux-brief.md and docs/07d-decisions.md give the reason for each rule. This page lets a reader check a screen against a rule. The reader does not need to read the audit again.