Design system

Why the system is like this

Everything else on this stand says what the system contains. This page says where it came from, how to use it, and what to do when it does not contain what you need. It is written for three readers: whoever picks this up in a month, the developer who gets it at handoff, and the next session that has to decide where something goes.

Nothing here is a preference. Every value in this system reaches back through a chain of five files to a pixel on a poster, and every rule reaches back to a count on the screens. Where a decision was taste, it says so and names whose.

Five attributes, and what each one costs

The visual language is five pairs of opposites, settled at stage 06. Each carries the line of research it stands on and the borrowed technique it licenses. A pair without both is an invention, and a technique without a pair is a clone at the level of the detail.

Precise, not soft

Design principle 5: density is the feature. Six hours a day means no decorative whitespace, keyboard before mouse. Under it, satisficing under volume is supported by analyst quotes in two practitioner studies.

What it rejected: pill buttons, and the 32px card padding of the reference it took the radius from. That is a marketing page breathing, not a console at 1440 carrying eighteen rows and a pane.

The plate overruled the reference. The reference proposed 2px. Plate J draws zero on every interface element and keeps a radius for physical objects only, so A1 is met more strictly than the reference met it.

Where it is visible A radius of zero, and it is a decision rather than an omission: it is what makes the square terminals of the icon set consistent with everything they sit in. Seven space steps, with two of them carrying the density between them.

Saturation is spent on two closed sets, not decorative

The accent carries latitude, the live strip, where you are in the navigation, and the row being decided with its primary action. The severity ramp carries High, Medium and Low. Both sets are closed and countable, and a fifth use of colour anywhere is a defect rather than a variation.

This attribute was amended in writing rather than stretched. It used to read "saturation is scarce". Severity was readable only by counting bars and the user asked for it to read as colour, and there is no way to grant that inside the old wording: three more coloured elements on every row is exactly the economy the old version refused. The previous text is kept rather than deleted.

What stayed load bearing is that colour has to be countable. The ramp descends in chroma rather than in brightness, because on a dark ground every value has to clear 4.5:1 and loudness cannot carry a ramp. It runs warm to cool and never reaches green: a low severity case is not a resolved one.

Where it is visible Twenty three primitives and twenty seven roles, each with a surface and a pair. The severity bars and the latitude mark are the two closed sets, and the button is where the fourth accent job stands.

Authority by restraint, not by emphasis

The social job, verbatim: "I want it to look like the work of someone who knew what they were doing, so that nobody has to redo it to be sure." Beside it, a study finding that analysts with three or more years want the system to augment their speed rather than reiterate fundamentals.

It is more than typography. It is the same argument the product makes about Clerk: it files a verdict, it does not insist on one. A console that shouts at its operator is a consumer product wearing a uniform.

It gained a ceiling at stage 06 and a defect at stage 08. 600 is the working emphasis and 700 is allowed on a counted value only. The readout is an h1 on 35 screens, so the browser's own 700 reached a heading that is not a counted value, and it took a box comparison against the product to see it.

Where it is visible Three weights and no 500, and the readout, which now declares 400 explicitly because a tag was deciding it.

Depth by tone, not by blur

Design principle 5's second half: no overlay that hides the evidence the analyst is deciding on. And the structure the wireframes settled: a top bar, a connection strip, a list, a detail pane and a notice stack, all live at once on one screen.

Two independent references reached the same rule, which is why this is a discipline rather than a preference. Depth by blur on four layers is how a dense screen turns to soup.

It was carried on a poster and proved in a browser. Three grounds with no blur and no shadow anywhere in the console, and whether three tones separate a queue, a pane and a selected row at 1440 was decided at stage 06 step 6 rather than on the plate.

Where it is visible The fill roles, four usable steps above the page, and the theme check that reports both ramp collapses as declared rather than hiding them.

Counted, not estimated

Voice principle 3: a number names its claim, its scope and its window, count first and never a bare percentage. Under it, verbatim from a practitioner study: an explanation is more meaningful "if I have some context about how that percentage was generated".

What it licenses: monospace as a primary face rather than a garnish for timestamps. Every load bearing value in this product is a count, and proportional digits make a column of counts unreadable.

What it rejects: confidence as a large coloured ring or gauge. Voice principle 3 forbids the bare percentage in words, and it must not come back as a picture.

Where it is visible Two families, chosen on a rendered comparison of four candidates each rather than on the name drawn on the plate. The record and the trend are where the counting shows.

The reflex these five were written against was measured, not assumed. Ten style results came back for a query about a dense operator console and eight were dark plus an electric blue or violet accent, describing themselves in nearly the same words. That is the dangerous kind of reflex: it looks correct for security tooling specifically and it would survive a review. Two of the ten were not that, and both are in the record: one spends its single accent on orange, and the other is warm ivory and is kept as the anti-reference, because a bright field is a glare source at 03:00.

The ground is dark, and since 2026-08-27 the light theme is one control away rather than a named debt. It was decided against the reading research, which favours light and favours it more as the type gets smaller, and against halation, which hits a large minority. What carries it is the rota: 79% of SOCs run 24/7 and a case is opened from a phone at 03:00. Halation then forces three things, and without them dark is done badly: never pure white on pure black, body text at 400 or above, and slightly open tracking on small monospace.

The default did not move, and that is the part worth reading twice. With nothing stored the console is dark and prefers-color-scheme is never read: an operating system that happens to be light is not an argument that reopens a ground this project settled on the rota. What changed is that the analyst can now answer the question for herself, once, and be remembered.

Where a value comes from

No value in this system was chosen here. Each one arrives through five files, and each hop is a file you can open.

1 · the plateA poster, drawn and then read as pixels rather than as a caption. The palette was sampled off the image and checked against the plate's own stylesheet, which agreed at every role.

2 · artifactsDESIGN-artifacts.md. Every value with its origin, its contrast against all three grounds, and the eight plates that were not taken.

3 · the themeStage 06 coloured three real screens by remapping the wireframe variables, at a structural diff asserted byte for byte. The second screen cost one rule and the third cost none.

4 · the kitStage 07 read DESIGN.md out of the running code rather than proposing it, and folded three stylesheets into one, proved by a byte identical screenshot.

5 · tokensdesign/system/tokens.css. Two levels, and every role in both themes side by side with a contrast table computed in the page rather than transcribed.

A reference is not an origin. It says how something is made, not why it is right here. A value carried straight out of a reference would have a reference as its origin, and that is the one thing this chain exists to prevent. The one value in the whole system with no origin says so out loud on Geometry, and it is still open.

How to use it, and there are four doors

Four questions, four places. The fourth is named separately on purpose: somebody assembling a screen for the first time is looking for permission, and meets the prohibition only after having done it their own way.

which component do I take Overview Seventy three of them at three levels, each with a live miniature painted by the same stylesheet the page it leads to documents. Every page carries anatomy, variants, when to use it, rule and anti-rule, and states in both themes. is this composition already solved Patterns Four compositions that already stand on three or more screens, plus the six two screen candidates waiting for a third. Look here before reaching for the components: a composition you assemble yourself when a pattern exists is a fifth answer to a question that has four. what are the rules Architecture Two ladders that both use the word level, what a component may read, how a role is named, why the theme pair is a property of the level rather than an event, and the five things it takes to add a component. what may I not do Usage rules Thirteen prohibitions of composition and context, each with the count or the decision it came from, and each one also a function in design/kit/checks/rules.mjs. Run them against your screen rather than reading them.

Both themes are accepted even though the product ships one. A screen carries no theme code, no toggle and no data-theme attribute: the pair is a property of the token level rather than a feature, and base.css is the one place the page's ground and ink are set, so flipping the theme needs no rule anywhere else. The switch lives in this stand's panel and not in the product, and there is no prefers-color-scheme anywhere in the system, deliberately: the console's ground is a decision about a room at 03:00 rather than about an operating system setting. What that obliges you to do is still real. A component that breaks in the theme nobody ships still breaks, and the person who finds out is the developer at handoff, so a new role and every one of its states is written in both themes at the moment it is founded, and the finished screen is rendered twice.

The order of the four is the order to use them in. Look for a pattern; if there is none, assemble from components; if the component you need does not exist, that is an order for the system and not an exception for your screen. A screen never carries a style of its own.

How to grow it

One rule, and it is the difference between a living system and a folder somebody once tidied.

New appears in design/system/ first and on the screen second. Never the other way round.

Without it, styles are growing on screens again within a week and the system is just another name for a folder. The full section is Contributing to the system on Architecture, with the address for each of the four kinds of new thing: a value, a component, a composition and a rule. The two parts of it that get skipped are named there explicitly, because they are the two that look harmless: the registry entry in the group of its own level, and the @import in its own level group rather than at the end of the file.

What the system does not do yet

The honest list. Every row names what is missing, where it shows, why it was left, and who closes it. A backlog with no owner on a row is a wish.

Loading the backlog.

Source: design/kit/docs/backlog.md. Four of these rows were opened by stage 09 itself, three of them by running the usage rules for the first time and one by an audit reading a file against its own header.