Design system
Three surfaces share one stylesheet of design tokens, design/prototest-tokens.css: the ProtoTrace viewer, the HTML report and these docs. There are no copies.
| Surface | How it gets the tokens |
|---|---|
| ProtoTrace viewer | imports the file directly |
| HTML report sink | embeds the file into every report it writes |
| Documentation | imports the file at the top of its theme |
Every swatch on this page is drawn from that file, so this page is also a live check that the tokens render the way this page describes them.
Two surfaces
The same tokens resolve differently on two surfaces, chosen with data-theme on <html>:
- Technical paper, the light surface. It is the default for these docs.
- Execution blueprint, the dark surface. It is the default for the viewer and the report.
Switch the theme of this site to see the blueprint values.
--bg--surface--surface-2--hover--surface-sunkenColour carries meaning only:
--blueprint--success--warning--danger--violet--mutedDocumentation panels
A panel's role determines its presentation. The shared frame supplies its border, header spacing and source line.
| Role | Presentation |
|---|---|
| Explanatory figure | Follows the reader's theme; uses the document's reading scale for notes and explanations |
| Code | Uses the sunken blueprint surface, the monospace scale and a shared copy control |
| Recorded product preview | Retains the viewer's blueprint surface and compact row layout; names its source archive |
Documentation prose uses the reader scale (1rem). The compact token scale remains appropriate for code, ids and authentic product controls. Headings, spacing, colours and radii continue to come from the existing tokens.
The execution vocabulary
These tokens describe a test run rather than a page. Anything that draws a ProtoTest execution uses them, so a phase, an outcome or an entry kind looks the same everywhere. The samples below sit on the blueprint surface, where the viewer and the report draw them.
Phases
Each test runs through up to four phases, in this order:
Outcomes
An outcome is always a dot and a word, never colour alone:
Entry types
Each trace entry belongs to one of four families. The chip's label names the specific kind; the colour only separates the families.
An unknown entry kind, such as your own billing.webhook.deliver operation, renders as an action. It looks like a built-in call, so your integration's operations are as visible as ProtoTest's.
Typography
| Face | Used for |
|---|---|
| Space Grotesk | Headings and the wordmark |
| Manrope | Everything a person reads |
| JetBrains Mono | Data: durations, ids, kinds, routes, attribute values, code |
--text-display--text-heading--text-title--text-strong--text-body--text-meta--text-microNothing is set below 10px.
Spacing, radii and motion
Padding, gaps and margins use the scale, never raw pixels. The only exception is a hairline of 1 or 2px.
| Token | Value | Used for |
|---|---|---|
--space-1 | 4px | the gap inside a chip |
--space-2 | 6px | between a label and its value |
--space-3 | 8px | inside a control |
--space-4 | 12px | between rows in a list |
--space-5 | 16px | inside a panel |
--space-6 | 22px | between a panel's sections |
--space-7 | 32px | between page sections |
A radius names what a thing is, so pick by role:
| Token | Value | Used for |
|---|---|---|
--radius-hairline | 2px | small markers and bars |
--radius-chip | 4px | chips |
--radius-control | 7px | buttons and inputs |
--radius-panel | 10px | panels |
--radius-overlay | 14px | dialogs and sheets |
--radius-pill | 999px | filter chips |
- Elevation: a single shadow,
--elevation-overlay, used only by things that float. Panels have a border and no shadow. - Motion:
--motion-fastfor state changes,--motion-slowfor layout changes. Both drop to zero when the reader asks the operating system to reduce motion.
The mark
There is one mark geometry, and it is never redrawn or simplified. The surface decides its colours
through --brand-mark-body and --brand-mark-check, so pages that inline the SVG get the right mark on
either theme without swapping files.
A favicon is an image, so it can't read the page's theme. The viewer's and the report's favicons carry
their own prefers-color-scheme rule and follow the operating system instead.
Using the tokens yourself
If you write your own report sink or render trace data somewhere else, start from the same file rather than copying colours out of it. This is a complete document:
<!doctype html>
<html lang="en" data-theme="dark">
<head>
<link rel="stylesheet" href="prototest-tokens.css" />
</head>
<body>
<span class="outcome" style="color: var(--outcome-failed)">Failed</span>
<i style="background: var(--phase-execution)"></i>
</body>
</html>
Embed the file's contents instead of linking it when the output has to stand alone, which is what the HTML report sink does.
The viewer enforces this with a style lint that runs in its build. It rejects raw colours, spacing off the scale, and radii that are not tokens. The HTML report's tests check that it embeds the shared file rather than a palette of its own.