Reading these docs

Overview

Every page on this site is written to a fixed outline determined by its kind, and the build fails if a page invents a heading or omits a required one. That sounds bureaucratic and is in fact the main reason the site is usable: once you have read one component page you can navigate all sixty without looking, and an agent can parse them without a heuristic.

This page teaches the conventions once. It is the shortest way to make the rest of the site predictable.

Understand the status vocabulary

Three values, and they mean the same thing on the page, in the catalogue JSON and in llms.txt.

status appears only on a kind: component page, and every one of them reads shipped. No other page carries the field, because on a page about colour or consent it was describing the prose rather than anything you could install. The legend above counts registry/catalogue.ts live, so trust it over any number typed into a sentence.

Every opsinjs component has been audited against WCAG 2.2 AA by its own authors, not by an independent reviewer, and no component has had a clinical review. shipped means the source installs and passed that author-run audit; it does not mean an independent accessibility review or a clinical review has happened. Nothing here is for a production health surface until a clinician signs it. See ADR 0025 for what the audit covered and what it did not.

For agents

Three rules, and they are the difference between this site being useful to you and being dangerous.

1. Read the page's status; it is the whole answer. At planned there is no implementation, and the page exists so that you do not have to guess: the API on it is a specification under review. Do not emit an implementation of it, do not import from it, and do not tell a user it is available. Those pages carry a data-opsinjs-not-implemented marker and a visually-hidden sentence saying so, in both the HTML and the .md twin, and the marker is absent from shipped. At shipped there is real code and a real install command, and the honest caveats to pass on are that the API may change in any release, that the accessibility audit was run by the authors and not independently reviewed, and that clinical review has not happened.
2. Every page has a markdown twin. Append .md to any documentation URL and you get the processed markdown. That is JSX resolved into text, not raw MDX. The corpus is also published as llms.txt with per-pillar shards. See Raw markdown API.
3. Never invent a number. Thresholds, reference ranges, contrast ratios and token values are supplied or generated, never remembered. If a value is not on the page, the honest answer is that it is not published yet.

The full contract, including the machine-readable schemas, is in Rules for agents.

Know which outline you are reading

A page's kind fixes its headings. The five you will meet most often:

• component is a lean, status-gated anatomy of at most fourteen sections, held to a thousand words. <StubNotice> opens it with the review floor and the open questions. At planned you get when not to use it, the clinical contract, the anatomy, the proposed API and the accessibility bar; the sections that need a build to be truthful are omitted, not left empty. Those are usage, examples and the props table. At shipped those sections appear, generated from the code, and anything whose source has still not been measured says so rather than printing a number. Anatomy of a component page teaches the whole contract once.
• health covers what this means, the rule, why (with evidence), applying it, the components that implement it, what it does not cover, and when it was last reviewed.
• foundation covers overview, how it works, using it, tokens, accessibility impact and related.
• recipe covers a task, the parts, the build, the copy, the checks and variations.
• guide covers overview, the tasks, verify it worked, troubleshooting and next. The page you are reading now.

Read a token table correctly

Token tables have three columns for a reason. Token is the name you use. What it controls is the property it is expected to drive. Used by is the list of components that consume it. That column turns a list into a decision aid, because it tells you the blast radius of changing one.

Two habits will keep you out of trouble:

• Never copy the resolved value out of the table into your code. The value is generated from the token source and will change. The name is the contract; the value is an implementation detail that happens to be printed.
• Check the tier. Primitives are the raw ramp, semantic tokens are the meaningful names, and component tokens are the per-component overrides. Components reference semantic tokens and never primitives, and so should you. See Token architecture.

Read a contrast report correctly

Contrast tables on this site print two numbers per pair, and they are not interchangeable.

• WCAG 2.2 contrast ratio is the legally-referenced figure, ranging from 1:1 to 21:1. It is what conformance is measured against today.
• APCA Lc is a perceptual lightness contrast value from the draft WCAG 3 work. It models polarity, so light-on-dark and dark-on-light are not treated as the same problem, and it correlates better with legibility at small sizes.

opsinjs publishes both because they disagree, and where they disagree the honest thing is to show it rather than pick the flattering one. The published floor and what happens when a pair fails it are in The contrast floor.

Every number in a contrast report is measured in CI from the token source. None of them is typed by an author, and a regression fails the build.

Verify it worked

You can read this site fluently if you can answer these without looking:

1. What does each status entitle you to? planned: a specification, and no code, no working install command and no import path. shipped: code you can install, an API that may move under you in any release, an author-run WCAG 2.2 AA audit rather than an independent accessibility review, and no clinical review behind it.
2. Where does a number in a table come from? A generator, named on the page. If a table renders the <NoDataYet> placeholder, its source is empty and the page is telling you so rather than inventing a value.
3. How do you get any page as markdown? Append .md to the URL.

Troubleshooting

A section you expected is missing from a component page. It is gated by status, or it is one of the five a shipped page may leave out. A section that would need a build to be truthful is omitted at planned rather than rendered empty, because an empty heading reads as a documentation gap and an omitted one reads as what it is.

A table shows a placeholder instead of data. That is the <NoDataYet> placeholder, and it names the script that will fill it. It is deliberately loud; a silently empty table is how documentation starts lying.

Two pages seem to contradict each other. One of them is canonical, and both say which. Numeric formatting is canonical in Numbers, units and precision; plain language is canonical in Plain-English A to Z. If you find a genuine contradiction that is not covered by a canonicality declaration, that is a bug. Report it as a docs issue; Community says where.

A page you found through search has an old review date. Review dates are published rather than hidden precisely so you can weigh them. See Docs freshness.

Next

• Anatomy of a component page is the component page contract, taught once and never repeated.
• Rules for agents is the machine-facing version of this page.
• Release phases says what each status promises, in the project's own words.