---
title: "Reading these docs"
description: "The page contracts, the status vocabulary, and how to read a token or contrast table without being misled by it."
url: "https://opsinjs.pensievelabs.org/start/reading-these-docs"
source: "https://opsinjs.pensievelabs.org/start/reading-these-docs.md"
section: "Start here"
kind: "guide"
reviewed: "2026-09-20"
reviewer: "content"
aliases: ["how to read these docs", "page contracts", "status badges", "docs conventions"]
---

> Elements written as `<PascalCase … />` below are opsinjs documentation
> components. Their attributes are the content: the values they render are
> generated from `tokens/*.json` and `registry/catalogue.ts` and are
> published separately at https://opsinjs.pensievelabs.org/r/index.json and under the Reference
> section.
> `<StubNotice>` IS THE EXCEPTION, AND IT IS THE ONE TO READ. It is a
> paired element rather than a self-closing one, and the text between
> its opening and closing tags is prose an author wrote, reproduced
> below word for word. That prose is where this page says whether the
> component has been reviewed. Read the children, not only the
> attributes.

<PageTemplate kind="guide" />

## Overview [#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 [#understand-the-status-vocabulary]

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

<StatusLegend />

| Status       | What it promises                                                               |
| ------------ | ------------------------------------------------------------------------------ |
| `planned`    | A specification with no implementation. There is nothing to install.           |
| `shipped`    | Installable source. The API may change in any release, with a changelog entry. |
| `deprecated` | Still installs, with a named replacement and a named removal version.          |

`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](../project/decisions/0025-the-audit-is-author-run.mdx) for what the
audit covered and what it did not.

### For agents [#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](../agents/raw-markdown-api.mdx).
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](../agents/rules-for-agents.mdx).

## Know which outline you are reading [#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](../components/anatomy-of-a-component-page.mdx)
  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 [#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](../foundations/token-architecture.mdx).

<NoDataYet script="scripts/build-tokens.mts" />

## Read a contrast report correctly [#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](../foundations/materials/the-contrast-floor.mdx).

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 [#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 [#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](../health/numbers-units-precision.mdx); plain
language is canonical in
[Plain-English A to Z](../content/plain-english-a-z.mdx). 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](../project/community.mdx) 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](../project/docs-freshness.mdx).

## Next [#next]

* [Anatomy of a component page](../components/anatomy-of-a-component-page.mdx) is
  the component page contract, taught once and never repeated.
* [Rules for agents](../agents/rules-for-agents.mdx) is the machine-facing
  version of this page.
* [Release phases](../project/release-phases.mdx) says what each status
  promises, in the project's own words.