Design System

Seven tokens set all the colors of the page. Click a swatch to copy its value. Use the switch above to select the authored oklch() notation or the hex notation that a Figma color field accepts. The page copies the value that it shows.

Each entity shows its family color only in small elements: the card rule, the label, and the hover accent. A family color is not a page background. The four families have one lightness and one chroma (L 0.42, C 0.13). Only the hue is different. Hex notation cannot show this relation. This is the primary reason the tokens are written in OKLCH.

Rust is only for the Source family. Error chrome has the same hue, but it has its own token. Thus the two colors can change independently, and one is never used to mean the other. Links and buttons keep the blue color on hover. The underline becomes stronger.

The build computes these ratios from the tokens. The ratios are measured, not asserted. The check includes each family and each state. Before the OKLCH conversion, the check could read only hex values, and eleven of these tokens could not be measured.

Family and state hues are used only for labels, rules, and other non-text UI. For these elements, the AA threshold is 3:1. These hues are not used for body text. The three text pairs at the top must be more than 4.5:1.

Three cards are dark in the two themes: the entity card on a link such as The MOC, the citation card on a bracketed [N], and the authorship panel in the frontispiece. The card is dark in the light theme. Thus the card shows as an object on the page, not as a hole in the page. The component is on Part V.

The label and the rule below the title use the family hue of the entity, with more lightness for the card. The ochre and the rust of the cream page are too dark for the dark card. Each accent has a twin with half the chroma (--hovercard-divider-*) for the rule. The twin is the same hue with a smaller effect.

Agent Mode sets Plex Mono on an almost-black background. It has no accent of its own. The root element has data-theme="dark". Thus headings use the same --color-blue as the site, in its dark-theme value. One blue is used in the two themes.

There are two families and one question to select between them: do you read this thing, or does this thing operate the page? Signifier is a serif with sharp stress and a true italic. It sets the content: titles, deks, body text, headings, and quotes. Söhne is a grotesque with no editorial opinion. It sets the apparatus: navigation, labels, buttons, breadcrumbs, badges, and form feedback. Klim made the two families. IBM Plex Mono is a third register, not a third voice. It shows that a machine speaks. It occurs only in Agent Mode, in code, and in token values such as the values on this page.

Because of this separation, the page can have much chrome, and the chrome does not compete with the content. The two families also do not compete on weight. The register shows which family you read. Thus hierarchy in each family comes only from size and style. For the same reason, MC does not set headings in bold.

This shows all the styles above, together. This is the real article chrome. The components and the classes are the same components and classes that a tool page or a competency page renders. This includes the Goudy versal, the small-caps lead-in, the hanging indents, and the bracketed citation markers. The page shows what the site ships, not an approximation.

Hover on a marker to see the citation card. The references are on Part V.

Intervals that occur frequently have semantic names: --space-{from}-to-{to}. You adjust a rhythm one time, and all pages change together.

A radius shows the type of the object. Thus this table gives each radius by its function, not as a sequence of numbers. Select the radius whose function is correct. Do not select a radius because its number looks correct. Shadows and gradients are not permitted. The corner is the only soft effect in the system.

The homepage can show a diagnostic overlay at /?grid=1. The overlay is a tool for authors, not chrome for readers. It checks the shared content box, the margin rails, the 8px baseline, and the 24px major rhythm.

• Figures nest. The edges of a figure align with the grid, flush on the content column. The internal tracks come from the content of the figure, not from the page grid. Nested subdivisions have one internal rule, and the boundary is documented.
• Declare spans. Put hero copy, exhibit groups, cards, and header chrome on named tier spans where possible.
• Name grid breaks. The hero engraving, full-bleed NavCard rows, and source rivers can break the content grid only if their CSS names the exception and the edge where the grid starts again.
• Protect expressive type. Display text can keep optical values. Systems that occur frequently, such as cards, captions, FAQ, CTA rows, and newsletter blocks, must use the 8px/24px rhythm.
• Keep color semantic. Family colors are signals for entities. A monochrome treatment is a proposal, not the default system.

• Article. Breadcrumbs, a display-italic title, a dek, a measured column, and a contents rail. Tool pages and competency pages use this shape.
• Index. A title, a dek, and a grid of nav cards in alphabetical sequence. The tools, sources, and people pages use this shape.
• Landing. Exhibits show the product at a smaller scale. The windows show real pages, not mockups.

There is no shared button primitive. These are the buttons that render on a launch surface, each with the class that draws it. An audit compared each button class in src/styles with its consumers. The legacy .btn family does not ship, thus it is not shown: see Part VII.

The first two buttons were the same design, made two times independently. From 2026-07-26, they agree on corner, fill, press, and hover. The unification of the hover found a bug: the shared value was --color-blue-dark, a fixed dark navy in the two themes. In the dark theme, this made a dark navy button below almost-black label text. Now the hover mixes the fill in the direction of --color-ink. This makes the button darker on cream and lighter in the dark theme. The difference that remains is the waiting state, and that difference is real — see Part VII.

One component, four families. The rule below the title and the label use --family-accent. The data-family attribute of the card sets this value. No other part of the card changes. Titles keep their canonical case. The card is chrome, not a copy editor.

The frontispiece of each article is a real CardFrame with tone="brand". The frame uses --color-blue and --color-background, not the fixed navy of the card-era artwork. Thus the frame changes with the theme. The hero is a mask with one ink, not a raster image, for the same reason. The proportion is locked at 5:7.

Sizes: Large 280×392, Medium 200×280, Small 160×224. The ratio does not change. A card that is not 5:7 is not this card. The frame can show a Roman numeral for its index in a pack. The article frontispiece shows no numeral.

These are not tooltips. Each card is a link. You can move the pointer into the card and follow it. Thus the card is a popover. The card stays open while the pointer is inside it. Hover on The MOC to see the entity card. Hover on the marker in the article above to see the citation card. The colors are on Part I.

Only once you have the outcomes do you work out the competencies — sort them through the Competency Stack, which separates the role-specific from the company-fit abilities.

The card is an enhancement, not the only route. The link navigates without the card. The dek is also in a visually-hidden description. Thus keyboard users and screen-reader users get the same summary.

Each tool page has the Human / Agent toggle. The page is written two times: one time for you, one time for your agent. On the site, the toggle is a fixed control at the bottom right. Here, the toggle is in the page flow.

One style is used on each reading surface that 0.3 ships. A bracketed marker is at the point of the claim. The marker points at a numbered reference at the foot of the page. The two halves are below, adjacent. This adjacency shows their relation.

The entry is in Chicago notes form, author-first. The name is in speech sequence, not in bibliography sequence. The first reference to a work is full. Later references are short. There are four types, with the short form last:

• Put a space before the bracket. Write abilities [1], not abilities[1].
• Mid-sentence position is correct. Put the marker at the claim, not at the end of the sentence. Do not change it.
• The marker becomes rust on hover. This is the only link on the site that can do this. This is not an exception to the rule on Part VII; it is an instance of the rule. Rust shows a Source, and a citation points at a source.
• The number is a link, not a label. The ↩ symbol moves you back to your sentence. If you cannot go back from a citation, you lose your position on the page.
• Author-first, not inverted. Write Walter Isaacson, “…”, not Isaacson, Walter. MC does not sort by surname. Thus inversion gives no help and is less clear.
• Put the URL last, with no text after it. A period after the URL goes into the href and breaks the link. A URL in the middle of an entry is not parsed and shows as dead text. check-citation-form finds the two errors.
• An entry can ship incomplete. Write the entry as far as the source permits, then stop. The lint gives a warning; it does not block. A gate that demands an unknown date teaches authors to invent a date.

This is frozen history, listed so that nobody writes a new instance: the card corpus sets Chicago superscripts adjacent to the punctuation (“the framework.²”). All routes that rendered them were removed from 0.3. ^N^ is only in content/packs/**.

With prefers-reduced-motion, travel is removed. Only the fades that help comprehension stay. The demos above become a crossfade.

Each entry below occurred in this design system. Each entry has a date and a link to the decision that closed it. The list is not confession. Each entry names a failure class. If you can name a class, you can build a check for it.

1. A name that describes a slot gets spent

   --color-accent-secondary means “the second color, use it when you need one.” Thus it was used. By 2026-07-25 it did five functions at the same time: the Source family, error states, CTA/button/nav hover, a maturity rung, and the fail badge of this page. The audit found 33 direct consumers.

   Closed The token was renamed, not aliased. An alias invites new consumers. Rust is now --family-bib and means Source. Errors have --color-error. The ladder has its own tokens. 2026-07-25-rust-reserved-for-sources

2. A retirement that only covered half the surface

   On 2026-06-10, the one-register-per-role rule removed rust from the link register — but only for prose links, and the token name did not change. 45 days later, rust was still possible as a button, CTA, and nav hover. The rule was written, but no check enforced it.

   Closed Each button, CTA, and nav hover now keeps blue and makes the underline stronger.

3. A button system with no consumers

   .btn and its four variants are documented as the button system of MC. Their only consumer in the app is ShareButton, which renders on /pack/*, a card-era route removed from 0.3. On each launch surface, the count is zero. The buttons that ship — .nl-signup-btn and .home-cta — are the same design, made two times, with different radii and different hovers.

   Closed Corner, fill, press, and hover were unified on 2026-07-25/26. The unification found a bug immediately. The shared hover value, --color-blue-dark, is a fixed dark navy in the two themes. In dark mode, it made a dark navy fill below almost-black label text, at approximately 1:1. Because there were two implementations of one button, nobody examined one of them as the button. The difference that remains is real: only the newsletter button waits, and Part V now shows that state instead of a description of it.

4. A breakpoint that is not one of the breakpoints

   The tier system has four boundaries: 600, 960, 1440, 1920. --space-page-gutter steps at 1024, which is not one of them. Thus the Desktop tier changes its page gutter in the middle of the tier, and the Grid table above gave one value for each tier that the token does not ship. The cost is measurable. Make this page wider from 1023px to 1024px, and the content column becomes narrower, from 715px to 636px. The gutter increases 32→72 faster than the viewport increases.

   Open The Gutter column is now computed from the token at the two ends of each tier, not written by hand. Thus the split reports itself. To move 1024 to 960 is a layout decision with effects far past this page. The decision is named here, not made silently.

5. A style documented for surfaces that were cut

   Until 2026-07-25, this page taught two citation styles: IEEE brackets for article surfaces, and Chicago superscripts for “card surfaces.” But all routes that render a superscript were removed from 0.3, and ^N^ occurs only in content/packs/**. The reader got a selection between a live convention and a dead convention, and no mark showed which was which.

   Closed The section gives the one live style and names the other style as frozen history. The failure class is larger than citations: a reference page gets its scope from the version it was written for, and a route removal does not change the prose that documents the route.

6. A ladder with no readers

   --competency-level-1/2/3 document a maturity ladder, and competency-page.css still carries 1 declaration that consume the first rung. Competencies currently carrying a maturity_rubric: 0. The colors are documented, styled, and rendered on zero pages.

   Open The build computes that count from the corpus. Thus this entry cannot become stale in the way that prose can. The consumer count is now adjacent to each token on this page. A token that nothing renders reports this itself.

7. A state that failed its own check

   --color-flag shipped as #B8860B: 2.81:1 against the page, below AA. It had no dark override. Thus the dark theme got a value designed for cream. The contrast table did not sample it. That is the only reason it stayed.

   Closed The token now uses the L/C convention of the palette at the flag hue. It has a dark twin. It is in the contrast table, which now samples each family and each state, not four selected pairs.

8. A split running through a set

   Two of the four family tokens were written in hex and two in oklch() — an effect of time, not of intent. The effect was not cosmetic. The families have one lightness and one chroma, and only the hue is different. Hex notation cannot show this relation. A rule cannot stay strong when the members of its own set do not agree.

   Closed 64 tokens were converted to OKLCH. The conversion was verified as lossless in three ways: through the numbers, through the authored string, and through browser pixels before and after. 2026-07-25-oklch-is-the-authored-notation

9. A checker that could not check

   contrastRatio() accepted only hex. Thus eleven tokens could not show in the contrast table — in the section whose claim is “measured, not asserted.” The gap was silent. The table rendered, passed, and omitted the tokens.

   Closed The function now resolves each notation. A filter that hides outputs must be verified in two directions: the bad case is gone, and the correct population is present.

A rule without its forbidden pair is only a preference. Each row below shows the violation adjacent to the correct setting. The violation has a line through it and has the size it would have on the site.

• Never

  Hierarchy by bold

  Correct

  Hierarchy by register

• Never

  A link that hovers to rust

  Correct

  Hue holds; the underline strengthens

• Never

  Rust as a generic accent

  Correct

  Rust marks a Source, and nothing else

• Never

  Söhne’s job, set in Signifier

  Correct

  Apparatus is Söhne