Design System

Colour

Surfaces

• --color-bgpage background
• --color-bg-altelevated / alt surface
• --color-surfacecards / panels
• --color-borderhairlines / dividers

Text

• --color-textbody copy
• --color-text-mutedsecondary / metadata
• --color-text-headingheadings

Brand

• --color-primarypurple — primary / accents
• --color-linkcyan — links / connections
• --color-accentamber — sparing highlight

Status

• --color-successsuccess / active
• --color-infoinfo
• --color-warningwarning
• --color-errorerror / deprecated

Typography

Type scale

• Aa knowledge architecture--text-4xl · hero display
• Aa knowledge architecture--text-3xl · page title
• Aa knowledge architecture--text-2xl · section heading
• Aa knowledge architecture--text-xl · subsection
• Aa knowledge architecture--text-lg · lead / card title
• Aa knowledge architecture--text-base · body
• Aa knowledge architecture--text-sm · secondary / captions
• Aa knowledge architecture--text-xs · labels / metadata

Font families

• --font-display — Space Grotesk — displayGive your project a knowledge architecture
• --font-body — Inter — bodyFiles are nodes, wikilinks are edges, AGENTS.md files are the navigation layer.
• --font-mono — JetBrains Mono — codegit clone …/aDNA.git ~/aDNA && cd ~/aDNA && claude

Font weights

• Regular 400 — --font-weight-regular
• Medium 500 — --font-weight-medium
• Semibold 600 — --font-weight-semibold
• Bold 700 — --font-weight-bold

Spacing

• --space-1
• --space-2
• --space-3
• --space-4
• --space-5
• --space-6
• --space-8
• --space-10
• --space-12
• --space-16

Radius & elevation

Components

Buttons

Badges

Status pills

Callouts

Illustration slots

Illustration on this site is contained: it is permitted in five named slots and nowhere else. Everywhere else — navigation, prose, tables, registry rows, code, form controls, footers — is type and colour only, in both themes. That containment is not only a style rule: keeping artwork out of the interface is part of what keeps contrast verifiable.

A page may not invent a sixth slot. Adding one is an amendment to the decision record that governs this table (ADR-053), not a choice made on the page that wants it.

empty_state

One mark, used at two sizes: inline beside a line that says a field is empty, and as a block heading a result set that matched nothing. Both are live on the vault registry.

Four rules govern applying it to a new page:

1. Write the sentence first. The mark is hidden from assistive technology and carries no meaning of its own, so the visible text beside it has to say the whole thing. Removing every mark must lose exactly nothing.
2. Show it where something is actually missing — never keyed to a vault's stage, class or status. A mark tied to a lifecycle stage reads as a ranking of that stage, and the registry has nothing to rank with: every stage on it is self-declared.
3. Credit the artwork once per page, not once per mark. The credit describes the artwork, and there is one piece of artwork however many times a page draws it.
4. Check both themes. The mark takes its colour from the text beside it, so it follows the theme on its own; a container you put it in does not, and needs its own contrast check.

Diagram construction

A diagram is a figure that carries information: nodes, edges, a funnel, a graph. It is not an illustration — illustration is contained to the five slots above and is about atmosphere; a diagram is about a claim, and is held to whether a reader can read it. These rules are derived from the diagrams this site already ships, so following them produces something that looks like the rest of the site rather than merely something that is allowed.

Stroke and fill

Structural strokes are 1.4–2 user units, and 1.6 is the house default — the weight the funnel bands, the triad edges and the triad nodes all use. Node fills are var(--color-bg) so a node knocks out the edges passing behind it; that is what keeps a graph readable without a halo or a shadow.

Colour comes from currentColor, never from a hex value and never from a theme query. This is the whole dual-theme mechanism: a diagram inherits the text colour of the container it sits in, so it themes for free and cannot fall out of step with the page around it. A diagram that needs a second colour takes it from a --color-* token, and a diagram that needs a third is usually a diagram that is trying to say too much.

Grid and scale

Draw into a viewBox and let the figure scale — 320×320, 320×280, 640×384 and 340×440 are the sizes in use. Keep the composition centred on a round number (160 is the house centre) so a contributor can place a node without solving for it.

The trap is type. Inside a viewBox, font-size="14" is 14 user units, not 14 pixels: at 320px wide a 640-unit figure paints that label at 7px. Every label must clear 12 CSS px as rendered, at 320 · 390 · 1024 · 1440 · 1920, in both themes. Measure it in a browser from the transform matrix — a computed style reports the authored number and is blind to the scale.

Every diagram carries a text equivalent

A diagram is role="img" with aria-labelledby pointing at a <title> and a <desc> inside the SVG. The <title> names the figure; the <desc>is the explanation, not a restatement of the title. The test is whether someone who cannot see the figure gets the same claim from the description — if the description only says what the picture looks like, it has not been written yet.

Add a <figcaption> when the figure needs a caption a sighted reader should also see. Interactive figures need more: the relationship graph ships a keyboard-navigable twin, because a node you can only reach with a pointer is a node some readers cannot reach.

What a diagram may leave out

A figure may show a subset — most useful figures do. What it may not do is let the subset pass for the whole. Every graph a figure omits is a stated category, not a silent omission: say what is not shown, in the description or the caption, in the figure's own voice. A network diagram showing ten vaults out of seventy-four is honest; the same diagram unlabelled is a claim that the network has ten.

The same rule governs data: a diagram encodes nothing its text layer does not also say. If a node's colour means something, the meaning is written down somewhere a reader can reach without the colour.

Voice

These are the rules this site's copy is written to. They are not a list of preferences. Each one exists because a specific sentence here confused a specific reader, or because a measurement said so. Where a rule rests on taste rather than evidence, it says so and you may argue with it.

The one rule the rest serve

Honesty is the aesthetic. Claims move down to what can be verified, never up to what would be impressive. That is not a moral posture, it is the positioning: a standard for trustworthy context that overstates itself has refuted its own argument in the first paragraph.

Two registers, and the order they go in

The site writes plainly, and it sometimes writes a line that compresses an idea. Both are legitimate. The failure is never the compressed line itself — it is that line arriving before the reader knows what the thing is.

Plain before compressed, on every surface, every time. A compressed line may summarise what the reader now knows; it may never be the thing that introduces it. The About page is the worked example: it opens with what aDNA is, spends four sections on named people and named limits, and only then reaches for a line that compresses all of it — which costs the reader nothing, because they already hold every part.

The rule is about order, not ratio. "Cut the memorable lines" is the wrong reading and produces worse writing: flat, forgettable, and no more honest. Move them.

Tense

Write what is true now in the present, and what is not yet true in a tense that says so. Aspirational present tense is a defect, not a flourish — "the network where teams share context" describes something that does not exist yet, in the grammar of something that does, and a reader cannot tell the difference. Write "stewarded today by one person" instead, where the word today is doing real work.

Any sentence describing a surface outside this site carries the date it was checked. A statement about someone else's project is true as of a moment.

One new term per paragraph

At most one unfamiliar term per paragraph, defined where it is first used, linked to its glossary entry. A paragraph that introduces two undefined nouns has introduced neither. The glossary is the single canonical home for a definition: define in place with a clause, then link — do not define the same term twice in two voices, because then there are two definitions.

Defining a term in place makes a sentence longer and raises its reading grade. That trade is taken deliberately: a grade-9 sentence about an undefined noun is not more readable than a grade-11 sentence that defines it. Reading level is a proxy; comprehension is the thing.

Say the limit in the same breath as the claim

Concede and then claim. State the limit as part of the fact. Pre-empt the objection in the reader's own words, and answer "why should I believe you" out loud. A reader who has already been handed the counter-argument has nothing left to catch you at — which is where the credibility comes from, not from an absence of weaknesses.

Disclose where the confusion happens

A true statement placed below the moment a reader needs it is not yet a disclosure. This site has twice shipped a disclosure that existed and was unreachable: the note that its agent personas are AI sat only on the About page while forty-one pages named a persona, and the note that aDNA here does not mean ancient DNA sat on four deep reference pages and none of the first-contact ones. Both were true, and both were three clicks past the reader who needed them. When a rule here says disclose, it means at first encounter, on the surface where the confusion happens.

Things to avoid, each one earned

• "lives" for where context is. Readers took it to mean a hosted destination. Say where the files actually are: on your machine. The rule binds where that ambiguity can occur — a file path like how/missions/ is not a server and nobody has ever mistaken one for the other.
• A compressed phrase as a headline. If a reader has to hold a concept they have not been given, the line is in the wrong place, not the wrong words.
• Counters with no reason to want them. A number on a first screen that means nothing to a newcomer is decoration. Keep the number where a reader has a reason for it, and make its definition reachable.
• Circular definitions. Define the outer term without using the inner one.
• Status labels with no legend, and internal shorthand.

What the reading-level number is, and is not

Copy is measured for reading grade, and the number can tell you two real things: sentences are too long, or the words have too many syllables. It cannot tell you whether a reader understood. A page can score well and be incomprehensible if its nouns are undefined; a page that is mostly a card list scores nonsense, because the measure needs sentences and a list has none.

Never rewrite to move the number. Rewrite because a reader was lost, and let the number confirm it. A paragraph broken into bullets will always score better and will not always read better.

How to know a rewrite is done

1. A stranger reads the first screen without a dictionary.
2. A developer still finds the precision — nothing was made vague to be made simple.
3. Nothing in it can be caught overstating.
4. The measured grade level agrees.

In that order. The fourth is the confirmation, never the goal.

What these rules rest on. They are drawn from readings of this site by simulated first-time visitors — a cheap early-warning instrument, not people. Sessions with human readers are the real test, and where a human reading contradicts a rule above, the reading wins and the rule is amended in public rather than quietly dropped.