{
  "name": "opsinjs-docs",
  "version": "0.0.0",
  "generator": "opsinjs-docs",
  "docsVersion": "0.0.0",
  "generatedAt": "2026-11-11T08:11:34.392Z",
  "site": "https://opsinjs.pensievelabs.org",
  "implemented": true,
  "implementedCount": 60,
  "notice": "60 opsinjs components are implemented, each has been audited against WCAG 2.2 AA by its authors, none of them has had an independent accessibility review or a clinical review, so none of them is for a production health surface. Every other entry is a specification or a reserved name, not code. Check `implemented` on the roster row, or `meta.opsinjs.implemented` on the item, before you assume a component exists, and never generate code against a proposed API.",
  "homepage": "https://opsinjs.pensievelabs.org",
  "format": "processed-markdown",
  "characters": 1530233,
  "total": 123,
  "included": 123,
  "omitted": 0,
  "sections": [
    {
      "id": "index",
      "title": "Introduction and guides",
      "description": "What opsinjs is and who it is for, then getting started, Next.js, theming, styling, the registry, agents and how to read these docs.",
      "pages": 11,
      "pagesInCorpus": 11
    },
    {
      "id": "foundations",
      "title": "Foundations",
      "description": "Accessibility, colour, typography, space, shape, motion, materials, icons, imagery, data visualisation, states and writing.",
      "pages": 14,
      "pagesInCorpus": 14
    },
    {
      "id": "components",
      "title": "Components",
      "description": "Every component in the catalogue. Each entry's `status`, and `implemented` in /r/index.json, say whether it installs; none has had an independent accessibility review or a clinical review.",
      "pages": 61,
      "pagesInCorpus": 61
    },
    {
      "id": "health",
      "title": "Health",
      "description": "The doctrine layer: the two colour axes, alerts, numbers and units, reference ranges, trends, high-stakes moments, consent and privacy, and the safety review.",
      "pages": 9,
      "pagesInCorpus": 9
    },
    {
      "id": "patterns",
      "title": "Patterns",
      "description": "Multi-screen sequences a health product keeps rebuilding, such as disclosing a result, logging daily or escalating an alert, plus forms.",
      "pages": 12,
      "pagesInCorpus": 12
    },
    {
      "id": "reference",
      "title": "Reference",
      "description": "The generated list of every token, CSS variable, data attribute, key binding, contrast pair and type, plus error codes and the glossaries.",
      "pages": 11,
      "pagesInCorpus": 11
    },
    {
      "id": "contribute",
      "title": "Contribute",
      "description": "A plain-language guide to contributing with Claude Code: setting up, every step with an example prompt, three worked examples and what not to do.",
      "pages": 5,
      "pagesInCorpus": 5
    }
  ],
  "shards": [
    {
      "id": "components",
      "title": "Components",
      "url": "https://opsinjs.pensievelabs.org/llms-components.txt",
      "sections": [
        "components"
      ]
    },
    {
      "id": "health",
      "title": "Health doctrine",
      "url": "https://opsinjs.pensievelabs.org/llms-health.txt",
      "sections": [
        "health"
      ]
    },
    {
      "id": "foundations",
      "title": "Foundations",
      "url": "https://opsinjs.pensievelabs.org/llms-foundations.txt",
      "sections": [
        "foundations"
      ]
    },
    {
      "id": "reference",
      "title": "Generated reference",
      "url": "https://opsinjs.pensievelabs.org/llms-reference.txt",
      "sections": [
        "reference"
      ]
    }
  ],
  "componentCounts": {
    "shipped": 60
  },
  "corpusComponentCounts": {
    "shipped": 60
  },
  "conventions": {
    "markdownTwin": "Append `.md` to any documentation URL to get that page's processed markdown.",
    "registryCatalog": "https://opsinjs.pensievelabs.org/r/registry.json",
    "registryRoster": "https://opsinjs.pensievelabs.org/r/index.json",
    "search": "https://opsinjs.pensievelabs.org/api/search?query=<term>&tag=<section>",
    "implemented": "`implemented` on a page record answers for the thing that page documents: a component id, or a screen specimen. It is ABSENT, not `false`, on a page that documents neither. A guide, a doctrine page or a token reference is not an unbuilt anything. Absent therefore means \"the question does not apply here\", and `false` means \"this named thing has no code\".",
    "counts": "`componentCounts` tallies the component pages in this response. `corpusComponentCounts` tallies every component page in the corpus. Neither sums to `included` or to `total`, because a release phase is only carried by a `kind: component` page. Read the second one for any question about opsinjs; read the first for any question about this file."
  },
  "pages": [
    {
      "url": "https://opsinjs.pensievelabs.org/docs",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs.md",
      "slug": [],
      "section": "Introduction and guides",
      "title": "Introduction",
      "description": "A React design system for consumer health apps, made of components that show people their own numbers and rules that keep those numbers honest.",
      "kind": "guide",
      "aliases": [
        "what is opsinjs",
        "opsinjs overview",
        "production ready",
        "licence",
        "security"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "opsinjs is for teams building screens where a person reads their own health data, such as wellness apps, remote-monitoring companions, patient portals and at-home test readouts. That reader is not a clinician, and is often anxious, on a phone and reading an unfamiliar number.\n\nIt is not for clinician-facing EHR screens, regulated device software or a charting library.\n\n## What it decides for you [#what-it-decides-for-you]\n\n| Decision                                           | Where it is fixed                               |\n| -------------------------------------------------- | ----------------------------------------------- |\n| What a colour may mean, and the four status levels | [Two colour axes](./health/two-colour-axes.mdx) |\n| How a number, a unit and a precision render        | [Numbers and units](./health/numbers.mdx)       |\n| How many urgent surfaces a screen may carry        | [Alerts](./health/alerts.mdx)                   |\n| The contrast floor every token pair must clear     | [Materials](./foundations/materials.mdx)        |\n| Which words are banned from patient-facing copy    | [Writing](./foundations/writing.mdx)            |\n\n## What it refuses to decide [#what-it-refuses-to-decide]\n\nopsinjs is a presentation layer. It never triages, diagnoses or advises.\n\n* **Ranges and thresholds.** Your product's clinical owner supplies them. A component only draws a value against one.\n* **Status.** Your product assigns it. No component derives a status from a value.\n* **Clinical wording.** opsinjs bans words and shapes sentences. It never writes the sentence that says what a result means.\n* **Data.** No fetching, caching, schema or unit conversion.\n* **Regulatory status.** opsinjs is not a medical device and confers no regulatory status on your product.\n\n[Health](./health/index.mdx) has the full safety position.\n\n## State of the system [#state-of-the-system]\n\nAll sixty components are `shipped`, which means the source installs and renders. Every one has been audited against WCAG 2.2 AA by its own authors. That audit is not an independent review, and no component has had a clinical review. Nothing here is for a production health surface until a clinician signs it. A `shipped` API may change in any release, and each change carries a changelog entry.\n\n## How it ships [#how-it-ships]\n\nopsinjs is a shadcn registry. The CLI copies source into your repository, and you own it.\n\n| What              | Where                                                                           |\n| ----------------- | ------------------------------------------------------------------------------- |\n| A component       | `npx shadcn@latest add @opsinjs/<name>`, served from `/r/<name>.json`           |\n| The token layer   | A theme item at `/r/themes/opsinjs-default.json`                                |\n| The catalogue     | `/r/registry.json` and `/r/index.json`                                          |\n| Docs for machines | `/llms.txt` and a `.md` twin of every page. See [Agents and LLMs](./agents.mdx) |\n| An npm package    | None is published. Five are proposed as specifications                          |\n\nComponents use Base UI and Lucide, and need React 19 or later and Tailwind CSS v4. [Registry](./registry.mdx) says what an item holds.\n\n## Licence, security and community [#licence-security-and-community]\n\nThe code is MIT and the guidance prose is CC BY 4.0, so you can quote a rule in a clinical safety case with attribution. The canonical repository is [github.com/prashantonomy/opsinjs](https://github.com/prashantonomy/opsinjs). Report a vulnerability through its [private reporting form](https://github.com/prashantonomy/opsinjs/security/advisories/new), never in a public issue. There is no security email address. A risk that someone misreads their own health data goes in a public issue as a [safety concern](https://github.com/prashantonomy/opsinjs/issues/new?template=safety-concern.yml), and a question goes to [Discussions](https://github.com/prashantonomy/opsinjs/discussions).\n\nThe canonical host is `opsinjs.pensievelabs.org`. This project never asks for a token or a credential, so anything that does is an impersonation.\n\n## Next steps [#next-steps]\n\n* [Getting started](./getting-started.mdx): register the namespace and render a first component.\n* [Next.js](./nextjs.mdx): the stylesheet, the root layout and the client boundary.\n* [Theming](./theming.mdx): the token tiers, presets and dark mode.\n* [Health](./health/index.mdx): the rules, useful even without the code.\n* [Components](./components/index.mdx): all sixty, each with its clinical contract.\n\nThe [showcase](/showcase) has whole apps built from the components, and the [playground](/playground) tries themes, contrast and status."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/agents",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/agents.md",
      "slug": [
        "agents"
      ],
      "section": "Introduction and guides",
      "title": "Agents and LLMs",
      "description": "The stable machine surfaces, the rules for generating safe health UI, and how to connect an agent",
      "kind": "guide",
      "aliases": [
        "llm",
        "ai agent",
        "llms.txt",
        "markdown twin",
        "mcp",
        "skill",
        "agent rules",
        "system prompt"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "Every page and every component id answers at a stable address, so an agent can look a fact up instead of guessing it.\n\n## Machine surfaces [#machine-surfaces]\n\n| Path                                                                                       | What it is                                                                                                                     |\n| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |\n| [`/llms.txt`](/llms.txt)                                                                   | Index of every page, with absolute URLs and each component's `status`. Start here                                              |\n| [`/llms-full.txt`](/llms-full.txt)                                                         | The whole corpus, size-capped. A `## Truncated` block at the end names any page it drops                                       |\n| `/llms-components.txt`, `/llms-health.txt`, `/llms-foundations.txt`, `/llms-reference.txt` | Topic shards. Each carries its sections whole                                                                                  |\n| `<page URL>.md`                                                                            | The markdown twin of any page. The documentation index is `/docs.md`                                                           |\n| [`/r/index.json`](/r/index.json)                                                           | The roster: every component id with `status`, `implemented`, category and aliases                                              |\n| [`/r/registry.json`](/r/registry.json)                                                     | The shadcn-spec catalogue, which the shadcn MCP server reads                                                                   |\n| `/r/<name>.json`                                                                           | One registry item, carrying its source and `meta.opsinjs.implemented`                                                          |\n| [`/r/docs.json`](/r/docs.json)                                                             | The corpus as one versioned, size-capped JSON file for offline use. `included` and `omitted` say whether it carries every page |\n\nPage HTML, class names, heading anchors and `/view` preview routes are not a contract, so link to a page rather than a fragment.\n\n## The markdown twin [#the-markdown-twin]\n\nAppend `.md` to any page URL. Documentation components stay as tags whose attributes are the content, such as `<ComponentPreview name=\"range-bar\" />`, and the values they draw are published at `/r/index.json` and in [Reference](./reference/index.mdx). A component twin carries `status` and `implemented` in its frontmatter. Every twin sends the docs version in an `x-opsinjs-docs-version` header, which a saved file loses, so store it beside any cached copy.\n\n## Rules for agents [#rules-for-agents]\n\n1. **Tokens, not values.** Never emit a hex, `rgb()`, pixel radius or millisecond duration. Use a token or a utility that resolves to one.\n2. **Status, not colour.** Set a level (`steady`, `watch`, `attention`, `urgent`) and let the system choose the colour. Never render a status without its word.\n3. **One axis per element.** Category and status never colour the same element. See [Two colour axes](./health/two-colour-axes.mdx).\n4. **Never invent a component, prop or variant.** Read `/r/index.json` and the installed source. If an id is not in the catalogue, say so and stop. For a `planned` id, describe the specification and emit no import. No id is planned today.\n5. **Never assume a registry.** Check `components.json` for `@opsinjs` before emitting `add @opsinjs/<name>`, and offer the one-line addition first.\n6. **Never invent a number.** No threshold, reference range, contrast ratio or bundle size unless a generated source you read supplied it.\n7. **Never decide a threshold.** Whether a reading is high belongs to the product's clinical logic, not to opsinjs and not to you. See [Reference ranges](./health/reference-ranges.mdx).\n8. **Never soften a clinical message.** \"Nothing to worry about\" is a different clinical claim, not friendlier copy for `watch`.\n9. **Never generate an accessibility claim** such as \"meets WCAG AA\" in code, a comment or a commit message.\n10. **Say what `shipped` costs.** Every id is `shipped`. Its API may change in any release, its WCAG 2.2 AA audit was run by its own authors, and it has had no independent accessibility review and no clinical review. Nothing here is for a production health surface.\n11. **Install source, never import a package.** No opsinjs package is published, so `@opsinjs/react` never resolves.\n12. **Cite the page you used.**\n\n```tsx\n// Right: the level is data, the word and the colour are the system's business.\n<StatusPill status=\"watch\" describes=\"HbA1c result\" />\n\n// Wrong: a colour decision, an invented prop, and no word.\n<StatusPill color=\"#f59e0b\" />\n```\n\n## Connect an agent [#connect-an-agent]\n\nRegister the namespace in `components.json`:\n\n```json title=\"components.json\"\n{\n  \"registries\": {\n    \"@opsinjs\": \"https://opsinjs.pensievelabs.org/r/{name}.json\"\n  }\n}\n```\n\n**MCP.** opsinjs has no MCP server of its own. The shadcn MCP server reads this registry and supplies inventory, not judgement. Substitute `cursor`, `vscode`, `codex` or `opencode` for your client.\n\n```bash\nnpx shadcn@latest mcp init --client claude\n```\n\n**Skill.** The skill at `skills/opsinjs/` in the repository holds `SKILL.md`, four rule files and an eval set. `npx skills add prashantonomy/opsinjs` installs it, or you can paste the rules above into your system prompt. The skill cannot judge clinical correctness, and its presence is no evidence of a clinical review.\n\n## Evals [#evals]\n\n`skills/opsinjs/evals/evals.json` holds 22 tasks that score the docs, not a model. Each asks a question an agent would ask and asserts what the answering page must and must not say. `pnpm run evals` scores them against a pass mark of 0.9. Scores are advisory and are not shown on this site yet.\n\n<NoDataYet script=\"scripts/run-evals.mts\" />"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/changelog",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/changelog.md",
      "slug": [
        "changelog"
      ],
      "section": "Introduction and guides",
      "title": "Changelog",
      "description": "What changed in each release, newest first, and the versioning and deprecation rules every release follows",
      "kind": "guide",
      "aliases": [
        "releases",
        "release notes",
        "semver",
        "breaking change policy",
        "what is next"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "Breaking changes lead each entry. A changed presentation default, such as a status word, a default rounding or a unit, leads it on its own line labelled `SAFETY`, because a consumer who copied a file receives the change only when they copy it again. opsinjs owns no clinical threshold, and no entry reads as though it does. A feed is at [`/rss.xml`](/rss.xml).\n\n<Todo>\n  Sixty components were built after 0.0.0 and no entry records them. Every catalogue row still reads `since: unreleased`, so the version number to file that entry under is the decision blocking it.\n</Todo>\n\n## 11 November 2026 [#11-november-2026]\n\nFive interaction motions, each on a spring the motion tokens already kept for that job, and all set out on [Motion](./foundations/motion.mdx). A button sinks under a press and settles back as you let go, and so do a button-shaped link and the close controls on a dialog, a sheet and a toast. A linked card or metric tile sinks a little less and never springs, because it can hold a reading. The switch thumb squashes while you hold it and travels when you let go, a tick draws itself and a radio dot grows from the centre. The chosen segment of a segmented control is one puck that glides to your next choice. The tab indicator glides too, where it used to jump, because its transition named the wrong property. Popovers, menus, selects, comboboxes and tooltips unfold from the control that opened them and come into focus, where menus, selects and comboboxes used to appear in a single frame. A toast rises from its edge, follows a finger that swipes it, springs back if let go early and leaves the way it was thrown, and a toast docked to the top now swipes up rather than down. Under reduced motion every one of them still changes state, with no travel, squash, scale or blur. Value, RangeBar and ScoreDial still never animate. None of it has had an accessibility review. This entry carries no version number.\n\n## 10 November 2026 [#10-november-2026]\n\n[StatusPill](./components/status-pill.mdx) is an enamel plate, lit from above, with a semibold word. Its colours are new, and they are not the status ramp: Steady is emerald, Watch is gold, Needs attention is burnt orange and Urgent is crimson, each at the lightness where its hue reads as itself, and the same in both themes. The word is white on the three deep plates and deep brown on the gold one. The four plates are new tokens in `tokens/color.json`, such as `--opsin-status-urgent-plate`, and the build refuses a plate whose word falls below the body-text floor. On paper the pill still prints as the level's tint with its ink. The words, the glyphs, the sizes and the props are unchanged. None of it has had an accessibility review or a clinical review. This entry carries no version number.\n\n## 8 November 2026 [#8-november-2026]\n\nThe accent is yours to choose now. There are three [accent themes](./foundations/accent.mdx), each with the same nine accents: normal keeps the ink action and spends the accent on what is selected, vibes makes the accent the action at full chroma, and stryk is high contrast, applied on its own whenever a reader's system asks for more contrast. Set them with `data-accent-theme` and `data-accent`, or install a theme item such as `opsinjs-vibes-volt`. In the default theme a switch that is on, a ticked box, a chosen radio, a slider's range, a progress fill and a chosen scale point are cobalt rather than ink. A quiet button and a card's quiet action are set in the accent ink and are no longer underlined; only a link inside running text keeps its underline. Every accent pair is measured, and the build refuses one below its floor. None of it has had an accessibility review.\n\nSix components were redrawn, and none of them claims anything new. [RangeBar](./components/range-bar.mdx) is a glass gauge: the range is a lit section inside a glass tube, and the reading is a frosted cursor that rides the tube with an index line in the level's colour; [RangeLegend](./components/range-legend.mdx) draws each tone as a miniature of that piece. [ScoreDial](./components/score-dial.mdx) is an instrument, with a bezel, a ruled face, the scale's two ends and a needle on a hub. [GoalRing](./components/goal-ring.mdx) sits on a plate and now draws in its category colour, which a class naming a missing utility had turned to black. [StatusPill](./components/status-pill.mdx) draws its glyph in the level's line colour, solid for the two upper levels, inside a softer capsule. [AlertBanner](./components/alert-banner.mdx) is a sheet tinted by its level, with the recommended action filled in the level's own ink. Button labels are centred on the lowercase band a reader sees as the text, rather than sitting a pixel and a half low.\n\nPage titles no longer end in the site name. A browser tab or a search result shows the page's own title, such as \"Button\", because search engines already print the site name above every result. The home page title reads \"opsinjs: a design system for consumer health apps\". The landing page footer links to [Pensieve Labs](https://pensievelabs.org/) and to its open source hub, and every page now names Pensieve Labs as the publisher in its structured data. Several component descriptions were shortened to fit a search result, with no change to what they claim. This entry carries no version number.\n\nThe system has a new look, and it changes no claim any component makes. The primary action is ink, a near-black capsule by day and a near-white one by night, so the two colour axes are the only colour that carries weight on a product screen. One brand blue is left, and it is spent as light: the focus ring, the mark beside an eyebrow and the bloom behind this site. Cards keep their opaque fill and gain a larger squircle corner, a soft drop and a decorative edge, while controls keep their 3:1 boundary. Buttons, chips and segmented controls are capsules, and a quiet button is underlined so it still reads as a control. The squircle token reads `superellipse(2)` now, because the `superellipse(4)` it held drew a nearly square corner. Product titles are set at 800, body text sits on a 24px line, and the [RangeBar](./components/range-bar.mdx) reading is a ringed disc, as the opsinjs mark draws it. This site sets Inter heavy and tracked in, with a floating glass sidebar. None of it has had an accessibility review or a clinical review.\n\n## 13 October 2026 [#13-october-2026]\n\nEach screen on the [showcase](/showcase) now opens on its own at `/showcase/<slug>`. The screen fills the window and nothing is drawn round it except a small bar in the top right corner, which switches between light and dark and between phone, tablet and desktop sizes without reloading the screen, so whatever you typed into it stays. On a window narrower than 1024px the screen starts below the bar, so the bar never covers it. The results screen has a page there too, so both cards open the same way. The essay that used to stand at `/showcase/diabetes-medicines-app` is gone, and the address now opens the app itself. The two component defects it recorded are tracked as issues [#16](https://github.com/prashantonomy/opsinjs/issues/16) and [#17](https://github.com/prashantonomy/opsinjs/issues/17). The bar also carries a link back to the showcase, for a reader who arrived from search. A screen framed on a documentation page also fills its frame edge to edge now, with no grey margin round it. This entry carries no version number.\n\nThe showcase has a third screen, the [patient record portal](/showcase/patient-record-portal): a patient's own view of the record their hospitals write, with who can see it, who has looked at it, the people they trust, a share a doctor opens once and an emergency card a paramedic can read. It is built from twenty-four components and lays itself out for a phone, a tablet and a desktop window, following the reader's text size as well as the window's width. Everything in it is invented, it explains nothing it shows, and like every screen on the showcase it has had no clinical review.\n\n## 12 October 2026 [#12-october-2026]\n\nThe site has a landing page at `/`, with links to the documentation and to GitHub, and the documentation moved under `/docs`: this page is now `/docs/changelog`, and the index twin is `/docs.md`. Every address from the last three weeks, such as `/components/button`, redirects permanently to its `/docs` twin, and so does its `.md` twin. The registry under `/r` did not move. The development warnings in `lib/opsinjs.ts` now link to `/docs` pages; a copy installed earlier prints the old addresses, which still resolve. This entry carries no version number.\n\nThe landing page also links to the [showcase](/showcase), which now shows a card for each whole screen opsinjs has built from its own components: the diabetes medicines app and the results screen. Both are opsinjs's own work with invented figures, and neither has had a clinical review. The bar an entry from another team has to clear is unchanged.\n\n## 8 October 2026 [#8-october-2026]\n\nThe documentation site was restructured into six sections modelled on Blueprint's docs: opsinjs, Foundations, Components, Health, Patterns and Reference. It has about 115 pages where there were 400, and each old URL redirects to the page that absorbed it. If a stored address stops answering, find the page again in [`/llms.txt`](/llms.txt). This entry carries no version number.\n\nThe GitHub repository became public the same day. Every page now links to its source with \"Edit this page\", the sidebar and the footer link to the repository, and issues, discussions and private vulnerability reporting are open. The site also sends security headers with every response, including a Content-Security-Policy that admits nothing from another origin.\n\nA seventh sidebar section, [Contribute](./contribute/index.mdx), is a plain-language guide for clinicians and health scientists who want to contribute with Claude Code: setting up, every step with an example prompt, three worked examples and what not to do.\n\n## 2 September 2026 [#2-september-2026]\n\nVersion 0.0.0 was the scaffold. It shipped a documentation site, a token layer, twenty-four component specifications at `planned`, eight decision records and the machine surfaces, which were the `.md` twins, `/llms.txt`, the `/r` catalogue and an offline bundle. It contained no components and published nothing to npm.\n\n## Versioning [#versioning]\n\nopsinjs follows semantic versioning, and the versioned surface is wider than the JavaScript API, because you own the source and your styles and tests reach into the markup. Five surfaces are covered:\n\n1. The exported API: components, hooks, functions, types, and their prop names, types and defaults.\n2. The rendered DOM: structure, nesting order, roles and accessible names.\n3. The `data-*` attributes listed in [Data attributes](./reference/generated/data-attributes.mdx).\n4. The CSS custom properties listed in [CSS variables](./reference/generated/css-variables.mdx).\n5. The registry contract: item names, the URLs they are served from and the files each installs.\n\nRemoving or renaming any of these, or changing the condition that produces it, is a major version. Exact token values are not covered, though a token's meaning and its contrast floor are. Nor are class names, CSS variables without the `--opsin-` prefix, anything marked `@internal`, or this site's own chrome.\n\nBefore 1.0, a minor release may break something, with a changelog entry and a migration note, and a patch never deliberately does. Token names are not stable yet, but token meanings are. A `shipped` component's API may change in any release, with a changelog entry rather than a deprecation cycle. Nothing in a copied file records its version, so run `shadcn add` in its own commit naming the item and the date.\n\n## Deprecation [#deprecation]\n\nNothing is removed without being deprecated first. A deprecated component, prop or token keeps working for at least one minor release before 1.0 and a full major after it. Its entry names the replacement, the version that deprecated it and the version that removes it. Treat it as absent for new work. Nothing has been deprecated yet.\n\n<NoDataYet what=\"The deprecation list\" script=\"scripts/build-registry.mts\">\n  No script projects deprecations out of `registry/catalogue.ts` yet.\n</NoDataYet>\n\n## What is next [#what-is-next]\n\nThere is no dated roadmap. Open items, in no order:\n\n* An independent accessibility review. The WCAG 2.2 AA audit so far was run by the components' own authors.\n* A clinical review. No component has had one, so nothing here is for a production health surface.\n* ESLint and Stylelint rules that enforce the two colour axes and tokens in your own project. They are planned, not built.\n* Source data for the [keyboard reference](./reference/generated/keyboard.mdx) and for bundle sizes.\n* Internationalisation, deferred rather than blocked. Unit systems such as mmol/L and mg/dL already ship.\n\nNot planned at all: clinician-facing components, a charting library, a general form library, an opsinjs CLI and native mobile."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/getting-started",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/getting-started.md",
      "slug": [
        "getting-started"
      ],
      "section": "Introduction and guides",
      "title": "Getting started",
      "description": "Register the @opsinjs namespace, install the token layer and render your first component, then adapt the steps to your framework.",
      "kind": "guide",
      "aliases": [
        "quick start",
        "installation",
        "components.json",
        "framework support",
        "browser support",
        "troubleshooting"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "The shadcn CLI copies opsinjs into your project as source, and there is no npm package. Paths below are for Next.js, and the table at the end lists what differs elsewhere.\n\n## Prerequisites [#prerequisites]\n\n* React 19 or later. React 18 is not supported.\n* Tailwind CSS v4. There is no v3 path.\n* A current Node LTS for the CLI.\n* Control over stylesheet order.\n\n## Initialise shadcn [#initialise-shadcn]\n\n<CodeBlockTabs defaultValue=\"npm\" groupId=\"package-manager\">\n  <CodeBlockTabsList>\n    <CodeBlockTabsTrigger value=\"npm\">\n      npm\n    </CodeBlockTabsTrigger>\n\n    <CodeBlockTabsTrigger value=\"pnpm\">\n      pnpm\n    </CodeBlockTabsTrigger>\n\n    <CodeBlockTabsTrigger value=\"yarn\">\n      yarn\n    </CodeBlockTabsTrigger>\n\n    <CodeBlockTabsTrigger value=\"bun\">\n      bun\n    </CodeBlockTabsTrigger>\n  </CodeBlockTabsList>\n\n  <CodeBlockTab value=\"npm\">\n    ```bash\n    npx shadcn@latest init\n    ```\n  </CodeBlockTab>\n\n  <CodeBlockTab value=\"pnpm\">\n    ```bash\n    pnpm dlx shadcn@latest init\n    ```\n  </CodeBlockTab>\n\n  <CodeBlockTab value=\"yarn\">\n    ```bash\n    yarn dlx shadcn@latest init\n    ```\n  </CodeBlockTab>\n\n  <CodeBlockTab value=\"bun\">\n    ```bash\n    bun x shadcn@latest init\n    ```\n  </CodeBlockTab>\n</CodeBlockTabs>\n\n`init` writes `components.json` and `lib/utils.ts`, whose `cn` helper every opsinjs component imports. The registry does not ship that file.\n\n## Register the namespace [#register-the-namespace]\n\nAdd one entry to `components.json`.\n\n```json title=\"components.json\"\n{\n  \"registries\": {\n    \"@opsinjs\": \"https://opsinjs.pensievelabs.org/r/{name}.json\"\n  }\n}\n```\n\nThe CLI substitutes `{name}`. `opsinjs.pensievelabs.org` is the only canonical host, so anything else serving `@opsinjs` is not this project. Keep the other fields `init` wrote, with `tailwind.cssVariables` set to `true` and `iconLibrary` to `lucide`.\n\n## Install the token layer [#install-the-token-layer]\n\nThe tokens are a separate theme item. The CLI writes their light and `.dark` values into the stylesheet named by the `tailwind.css` field.\n\n<CodeBlockTabs defaultValue=\"npm\" groupId=\"package-manager\">\n  <CodeBlockTabsList>\n    <CodeBlockTabsTrigger value=\"npm\">\n      npm\n    </CodeBlockTabsTrigger>\n\n    <CodeBlockTabsTrigger value=\"pnpm\">\n      pnpm\n    </CodeBlockTabsTrigger>\n\n    <CodeBlockTabsTrigger value=\"yarn\">\n      yarn\n    </CodeBlockTabsTrigger>\n\n    <CodeBlockTabsTrigger value=\"bun\">\n      bun\n    </CodeBlockTabsTrigger>\n  </CodeBlockTabsList>\n\n  <CodeBlockTab value=\"npm\">\n    ```bash\n    npx shadcn@latest add https://opsinjs.pensievelabs.org/r/themes/opsinjs-default.json\n    ```\n  </CodeBlockTab>\n\n  <CodeBlockTab value=\"pnpm\">\n    ```bash\n    pnpm dlx shadcn@latest add https://opsinjs.pensievelabs.org/r/themes/opsinjs-default.json\n    ```\n  </CodeBlockTab>\n\n  <CodeBlockTab value=\"yarn\">\n    ```bash\n    yarn dlx shadcn@latest add https://opsinjs.pensievelabs.org/r/themes/opsinjs-default.json\n    ```\n  </CodeBlockTab>\n\n  <CodeBlockTab value=\"bun\">\n    ```bash\n    bun x shadcn@latest add https://opsinjs.pensievelabs.org/r/themes/opsinjs-default.json\n    ```\n  </CodeBlockTab>\n</CodeBlockTabs>\n\nOrder is load-bearing: Tailwind, the token layer, an `@source` line for the folder components land in, then your overrides. Getting it wrong is quiet, because components lay out correctly in the wrong colours.\n\n```css title=\"app/globals.css\"\n@import \"tailwindcss\";\n\n/* The :root and .dark blocks the theme item writes. */\n\n@source \"../components/ui/**/*.{ts,tsx}\";\n\n/* Your own overrides last, so they win. */\n```\n\n## Add a component [#add-a-component]\n\n<CodeBlockTabs defaultValue=\"npm\" groupId=\"package-manager\">\n  <CodeBlockTabsList>\n    <CodeBlockTabsTrigger value=\"npm\">\n      npm\n    </CodeBlockTabsTrigger>\n\n    <CodeBlockTabsTrigger value=\"pnpm\">\n      pnpm\n    </CodeBlockTabsTrigger>\n\n    <CodeBlockTabsTrigger value=\"yarn\">\n      yarn\n    </CodeBlockTabsTrigger>\n\n    <CodeBlockTabsTrigger value=\"bun\">\n      bun\n    </CodeBlockTabsTrigger>\n  </CodeBlockTabsList>\n\n  <CodeBlockTab value=\"npm\">\n    ```bash\n    npx shadcn@latest add @opsinjs/status-pill\n    ```\n  </CodeBlockTab>\n\n  <CodeBlockTab value=\"pnpm\">\n    ```bash\n    pnpm dlx shadcn@latest add @opsinjs/status-pill\n    ```\n  </CodeBlockTab>\n\n  <CodeBlockTab value=\"yarn\">\n    ```bash\n    yarn dlx shadcn@latest add @opsinjs/status-pill\n    ```\n  </CodeBlockTab>\n\n  <CodeBlockTab value=\"bun\">\n    ```bash\n    bun x shadcn@latest add @opsinjs/status-pill\n    ```\n  </CodeBlockTab>\n</CodeBlockTabs>\n\nIt adds `lucide-react` to `package.json`, writes no CSS, and writes three files:\n\n```text\n<aliases.ui>/status-pill.tsx    the component, yours to edit\n<aliases.lib>/opsinjs.ts        units, categories and error codes every component reads\n<aliases.lib>/status.ts         the four clinical levels, their words and their glyphs\n```\n\nIn a default project they land in `components/ui/` and `lib/`. Commit them on their own, so a later `--diff` has something to compare against.\n\n## Render it [#render-it]\n\n```tsx title=\"app/page.tsx\"\nimport { StatusPill } from \"@/components/ui/status-pill\"\n\nexport default function Page() {\n  return <StatusPill status=\"watch\" describes=\"Blood pressure\" />\n}\n```\n\n`status` is required, because your product assigns it and opsinjs never derives one. `describes` is what a screen reader announces the level as being about. [StatusPill](./components/status-pill.mdx) has the full contract.\n\nCheck that the pill is styled, that its background reads an `--opsin-status-*` custom property, and that in greyscale it still names its level in words and by icon.\n\n<Todo>\n  Nobody has walked this path end to end against the published registry. No registry item serves the `@theme inline` mappings behind utilities the components use, such as `gap-opsin-2` and `text-opsin-body`, so a fresh project does not generate those utilities yet.\n</Todo>\n\n## Other frameworks [#other-frameworks]\n\n| Setup                              | What differs                                                                                                                                                    |\n| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| [Next.js](./nextjs.mdx) App Router | The reference install                                                                                                                                           |\n| Vite                               | Client only. Declare `@/` in both `vite.config.ts` and `tsconfig.json`. Import `src/index.css` once, at the entry point                                         |\n| React Router framework mode        | Export `app/app.css` from the root route's `links`, so error routes get it too. Upgrade Remix to React Router 7 first                                           |\n| TanStack Start                     | Vite rules apply. Load `src/styles.css` in the root route's document shell                                                                                      |\n| Astro                              | Import `src/styles/global.css` from your layout. Display components need no hydration directive. An interactive component must share an island with its trigger |\n| Manual, no CLI                     | Fetch `/r/<name>.json`, write each file in `files` to its target, install its `dependencies` and add the `cn` helper yourself                                   |\n| Monorepo                           | Run the CLI with `--cwd apps/web`. Every consuming app needs its own `components.json`, its own aliases and its own `@source` lines                             |\n\nNo row has a recorded end-to-end test, and the TanStack Start and Astro rows come from each framework's architecture, not from a build. Create React App and React Native are not targeted, and there is no Vue or Svelte build, though the tokens are plain CSS and work anywhere.\n\n<NoDataYet script=\"scripts/build-reference.mts\" />\n\n## Browser support [#browser-support]\n\nThe floor opsinjs commits to testing is Safari and iOS Safari 16.4, plus the current and previous major versions of Chrome, Edge and Firefox. Backdrop blur, `corner-shape`, Display P3 colour and `linear()` springs are enhancements. They degrade to an opaque surface, circular corners, the sRGB value the contrast floor is measured against, and the browser's default easing.\n\n<Todo>\n  Not one of the sixty components has been tested against any browser, at the floor or above it.\n</Todo>\n\n## Troubleshooting [#troubleshooting]\n\n**The CLI reports an unknown registry.** `components.json` has no `registries` entry for `@opsinjs`, or its key is missing the `@`. The URL must include `{name}`.\n\n**Every copied file fails on `@/lib/utils`.** `shadcn init` was never run. Run it, or add the `cn` helper at the path `aliases.utils` names.\n\n**The component renders unstyled.** Tailwind is not scanning the folder you copied into. Add an `@source` line, with a path relative to the CSS file.\n\n**Colours are wrong or empty.** The token layer is missing or loads before Tailwind, or `tailwind.css` names a stylesheet your app does not import.\n\n## Next steps [#next-steps]\n\n* Using Next.js? Read [Next.js](./nextjs.mdx).\n* Changing colours or type? Read [Theming](./theming.mdx).\n* Coming from shadcn/ui? Read [Migrating from shadcn/ui](./migrating.mdx).\n* Showing a health value? Read [Health](./health/index.mdx) first."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/migrating",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/migrating.md",
      "slug": [
        "migrating"
      ],
      "section": "Introduction and guides",
      "title": "Migrating from shadcn/ui",
      "description": "What maps one to one from shadcn/ui, what changes, and the order to move things in.",
      "kind": "guide",
      "aliases": [
        "shadcn migration",
        "asChild to render",
        "token mapping"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "The registry mechanism, code ownership, `cn()` and Tailwind all carry over, and both registries install side by side under their own namespaces. Three things change.\n\n* **Radix becomes Base UI**, so `asChild` becomes `render`. See [Styling](./styling.mdx).\n* **`variant` splits in two.** `category` says what a reading is about and `status` says how urgent it is, and they never mix. See [Two colour axes](./health/two-colour-axes.mdx).\n* **`destructive` has no equivalent**, because nothing about a person's reading is destructive.\n\n## Components [#components]\n\n| shadcn/ui                                                | opsinjs                                                                                                                                                                                                      | Note                                                                       |\n| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |\n| `Alert`                                                  | [AlertBanner](./components/alert-banner.mdx)                                                                                                                                                                 | Takes `status`, not `variant`                                              |\n| `Badge`                                                  | [StatusPill](./components/status-pill.mdx)                                                                                                                                                                   | Status only. A neutral label is [Badge](./components/badge.mdx)            |\n| `Card`, `Dialog`, `Sheet`, `Skeleton`, `Button`, `Toast` | [Card](./components/card.mdx), [Dialog](./components/dialog.mdx), [Sheet](./components/sheet.mdx), [Skeleton](./components/skeleton.mdx), [Button](./components/button.mdx), [Toast](./components/toast.mdx) | Same role                                                                  |\n| `Form` and `FormField`                                   | [Field](./components/field.mdx)                                                                                                                                                                              | Library-agnostic. See [Forms](./patterns/forms.mdx)                        |\n| `Progress`                                               | [Progress](./components/progress.mdx)                                                                                                                                                                        | Same role. [RangeBar](./components/range-bar.mdx) is a different component |\n\n## Props and attributes [#props-and-attributes]\n\n| shadcn/ui                                     | opsinjs                                                           |\n| --------------------------------------------- | ----------------------------------------------------------------- |\n| `asChild` and a single child                  | `render={<element />}`                                            |\n| `variant=\"destructive\"`                       | `status=\"urgent\"`, only where a clinical status genuinely applies |\n| `variant=\"secondary\"` as a category tint      | `category=\"sleep\"`                                                |\n| `data-state=\"open\"` and `data-state=\"closed\"` | `data-open` and `data-closed`                                     |\n| Entry and exit animation on `data-state`      | `data-starting-style` and `data-ending-style`                     |\n\n## Tokens [#tokens]\n\nopsinjs components use shadcn role utilities such as `bg-card` and `border-border`, so your role variables still reach them. To adopt the opsinjs values, point each role at its token.\n\n| shadcn/ui role                  | Point it at                                                      |\n| ------------------------------- | ---------------------------------------------------------------- |\n| `--background`, `--foreground`  | `--opsin-chrome-background`, `--opsin-chrome-foreground`         |\n| `--muted`, `--muted-foreground` | `--opsin-chrome-muted`, `--opsin-chrome-muted-foreground`        |\n| `--border`                      | `--opsin-chrome-border`                                          |\n| `--destructive`                 | Nothing. `--opsin-status-urgent-*` is for a clinical status only |\n\n`--opsin-status-<level>-*` and `--opsin-category-<name>-*` have no shadcn counterpart. Names may change before 1.0, and [Tokens](./reference/generated/tokens.mdx) lists every one.\n\n## Order of work [#order-of-work]\n\n1. Add the `@opsinjs` entry and the token layer from [Getting started](./getting-started.mdx), keeping shadcn/ui installed.\n2. Re-check contrast, because your shadcn values were never measured against the opsinjs floor. See [Theming](./theming.mdx).\n3. Migrate screens that show a health value first, a whole screen at a time.\n4. Rewrite each `variant` by hand as identity or severity. One that meant both was a bug.\n5. Move overlays as a group, because Radix and Base UI focus management can fight on one screen.\n6. Commit the files `shadcn add` writes in their own commit. Nothing in a copied file says which system it came from.\n\n## Pitfalls [#pitfalls]\n\n* **Keeping `variant` beside `status` on your own wrappers.** That is how the axes get mixed.\n* **Running two theme providers.** opsinjs adds none, because its theme is a class on `<html>`.\n* **Porting `globals.css` wholesale.** The import order differs, and it is load-bearing.\n* **Swapping `asChild` for `render` by find and replace.** `render` takes an element, so the result type-checks and renders one element too many.\n* **Expecting `--radius` to set the shape.** opsinjs derives a radius ladder and uses `corner-shape` where supported. See [Shape](./foundations/shape.mdx)."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/nextjs",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/nextjs.md",
      "slug": [
        "nextjs"
      ],
      "section": "Introduction and guides",
      "title": "Next.js",
      "description": "The stylesheet, root layout, dark mode and client boundary for opsinjs in a Next.js App Router project.",
      "kind": "guide",
      "aliases": [
        "app router setup",
        "use client",
        "rsc boundary",
        "server components",
        "pages router"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "The App Router is the reference target, and opsinjs is developed against it. Run [Getting started](./getting-started.mdx) with `rsc` set to `true` in `components.json`, so the CLI keeps `\"use client\"` where it is needed.\n\n## Stylesheet [#stylesheet]\n\n`app/globals.css` holds four things, in this order.\n\n1. `@import \"tailwindcss\"`.\n2. The opsinjs token layer. If it loads before Tailwind, Tailwind's preflight can overwrite parts of it.\n3. An `@source` line for every folder holding copied components, relative to the CSS file.\n4. Your overrides, in your own `@theme` block. Editing the token layer itself turns the next upgrade into a manual merge.\n\n## Root layout [#root-layout]\n\nThere is no opsinjs provider. Light and dark are a class on `<html>`, and the tokens resolve from it with no JavaScript.\n\n```tsx title=\"app/layout.tsx\"\nimport \"./globals.css\"\n\nexport default function RootLayout({\n  children,\n}: {\n  children: React.ReactNode\n}) {\n  return (\n    <html lang=\"en\" suppressHydrationWarning>\n      <body>{children}</body>\n    </html>\n  )\n}\n```\n\n* **Set `lang`.** Screen readers choose a pronunciation dictionary from it, so numbers and units are read in the right language.\n* **`suppressHydrationWarning`** lets a theme script set the class before React hydrates without a mismatch warning. It covers `<html>` only, which is the one place it belongs.\n\n## Dark mode and first paint [#dark-mode-and-first-paint]\n\nSet the theme class before first paint with a plain inline `<script>` in `<head>`. `next/script` with `beforeInteractive` runs after the Next client runtime loads, which is too late. Any theme library that sets a class on the root element also works.\n\n## Server and client components [#server-and-client-components]\n\n`\"use client\"` marks a boundary, not a file. Everything a client module imports becomes client code, so keep the directive on the interactive leaf and never on a page or a layout.\n\n**Server components.** 33 of the 60 carry no directive and ship no JavaScript of their own, including [ResultCard](./components/result-card.mdx), [RangeBar](./components/range-bar.mdx), [StatusPill](./components/status-pill.mdx), [Value](./components/value.mdx) and [TrendSparkline](./components/trend-sparkline.mdx). [Button](./components/button.mdx), [Field](./components/field.mdx) and [Progress](./components/progress.mdx) stay on the server too, but the Base UI parts they compose carry their own directive and hydrate as small islands.\n\n**Client components.** The other 27 hold state, a listener or a portal, and carry `\"use client\"`: [Accordion](./components/accordion.mdx), [Avatar](./components/avatar.mdx), [BodyMap](./components/body-map.mdx), [Checkbox](./components/checkbox.mdx), [Combobox](./components/combobox.mdx), [ConsentSheet](./components/consent-sheet.mdx), [Dialog](./components/dialog.mdx), [LogSheet](./components/log-sheet.mdx), [Menu](./components/menu.mdx), [NumberField](./components/number-field.mdx), [Popover](./components/popover.mdx), [Questionnaire](./components/questionnaire.mdx), [RadioGroup](./components/radio-group.mdx), [ReadingInput](./components/reading-input.mdx), [ScaleInput](./components/scale-input.mdx), [ScrollArea](./components/scroll-area.mdx), [SegmentedControl](./components/segmented-control.mdx), [Select](./components/select.mdx), [Sheet](./components/sheet.mdx), [Slider](./components/slider.mdx), [Switch](./components/switch.mdx), [SymptomPicker](./components/symptom-picker.mdx), [TabBar](./components/tab-bar.mdx), [Tabs](./components/tabs.mdx), [Term](./components/term.mdx), [Toast](./components/toast.mdx) and [Tooltip](./components/tooltip.mdx).\n\n* Pass server content into a client component as `children` to keep it out of the client bundle.\n* A function cannot cross the boundary, so an event handler needs a client component.\n* Import each component from its own module, never from a barrel file.\n* Never branch rendering on `typeof window`, because it produces different markup on each side.\n\n## Times and hydration [#times-and-hydration]\n\n[RelativeTime](./components/relative-time.mdx), [MetricTile](./components/metric-tile.mdx), [TimelineEntry](./components/timeline-entry.mdx), [DoseTracker](./components/dose-tracker.mdx) and ResultCard never read the clock, so each takes a required `now`. Read the clock once where the screen renders, with `new Date().toISOString()`, and pass the same value to every component, so no two timestamps disagree across a minute boundary.\n\n## Pages Router [#pages-router]\n\nThe Pages Router has no server components, so the split above does not apply. Import the stylesheet in `pages/_app.tsx` and set the theme class in `pages/_document.tsx`."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/principles",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/principles.md",
      "slug": [
        "principles"
      ],
      "section": "Introduction and guides",
      "title": "Design principles",
      "description": "Five prohibitions that settle design arguments in opsinjs, and what a designer decides for themselves",
      "kind": "guide",
      "aliases": [
        "design principles",
        "for designers",
        "designer onboarding",
        "design handoff"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "Each principle names something opsinjs will not do, so a proposal can be checked against it. When two proposals conflict, the one that breaks a principle higher on this page loses. That order is opinion, not evidence.\n\n## One element, one axis [#one-element-one-axis]\n\nColour carries two separate meanings. Category says which part of your health something is about, and status says how much attention it needs. One element takes colour from one axis, never both. An urgent heart tile takes its status from the surface and its category from a glyph or a label. Rule A11Y008 fails `pnpm check` on any registry element that carries both. See [Two colour axes](./health/two-colour-axes.mdx).\n\n## Never colour alone [#never-colour-alone]\n\nEvery status is carried by a word, a distinct glyph and a colour together, and the word is never left out. Colour fails first, in greyscale print, sunlight, screenshots and screen readers. Rule A11Y001 fails a registry file that paints a status without a word and a glyph beside it.\n\n## Say what is not known [#say-what-is-not-known]\n\nMissing, stale, estimated and partial data are states with their own rendering, never a blank or a zero. A screen that shows nothing where a number should be reads as a steady reading. [States](./foundations/states.mdx) lists the data states every data-bearing component renders.\n\n## Tokens, not values [#tokens-not-values]\n\nNo component, example or generated file contains a literal colour, radius, duration or spacing value. Everything resolves through a token and every token through a scale, which is what makes a theme possible and contrast measurable. Rules A11Y005 and A11Y006 fail `pnpm check` on a hex colour, a raw `oklch()` or a Tailwind palette class under `registry/`. The lint rules that would check your own project are planned, not built.\n\n## Do not practise medicine [#do-not-practise-medicine]\n\nopsinjs decides how a number is presented, never what it means. Thresholds, reference ranges, triage, escalation and clinical wording belong to your product and its clinical governance. Any surface that could be read as a judgement says whose judgement it is.\n\n## For designers [#for-designers]\n\nFixed for you:\n\n* What a colour may mean.\n* The four status levels, with their words, icons and tone.\n* The measured contrast floor.\n* The six rungs of the material ladder.\n* Motion, which never signals urgency.\n\nYours to decide: which measurement matters most, which category a metric belongs to, the copy, density within the space scale, and brand.\n\nDesign at 200% text as a second artboard. Treat WCAG 2.2 SC 2.5.8 target size as the floor, not the goal. Order every reading as label, value, unit, status, time, so a screen reader announces the subject before the alarm.\n\nBefore handing a screen over, check that:\n\n1. Every status distinction survives greyscale.\n2. There is at most one urgent surface. See [Alerts](./health/alerts.mdx).\n3. The word \"normal\" does not appear. See [Reference ranges](./health/reference-ranges.mdx).\n4. Every number has a timestamp.\n5. Someone can name the source of every threshold.\n\nThere is no Figma library, kit or plugin yet, and the DTCG token export is specified rather than published. Your route into the system is these docs and the rendered previews."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/reading-the-docs",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/reading-the-docs.md",
      "slug": [
        "reading-the-docs"
      ],
      "section": "Introduction and guides",
      "title": "Reading the docs",
      "description": "How the site is arranged, how a component page is laid out, and what its notices promise",
      "kind": "guide",
      "aliases": [
        "how to read these docs",
        "what shipped means",
        "docs chrome",
        "product theme"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "Every component page has the same sections in the same order.\n\n## Navigation [#navigation]\n\nThe sidebar has seven sections: opsinjs (the guides), Foundations, Components, Health, Patterns, Reference and Contribute. Only the section you are in is expanded, and the page you are on lists its own headings beneath it. There is no table of contents on the right and no breadcrumb.\n\nCmd+K opens search on a Mac, and Ctrl+K opens it on Windows and Linux. The Search row in the sidebar opens it too, and the Theme row switches between light, dark and system.\n\n## Component pages [#component-pages]\n\n| Section          | What it holds                                                                                                  |\n| ---------------- | -------------------------------------------------------------------------------------------------------------- |\n| Review notice    | The review state, then at most three open safety questions                                                     |\n| Usage            | The install command, the import and a minimal use                                                              |\n| Examples         | The default preview first, then named examples                                                                 |\n| When to use it   | Cases for and against. Every case against names an alternative                                                 |\n| Clinical meaning | Health components only. What the component asserts, what it must never be read as, and who owns the thresholds |\n| Accessibility    | What was checked and what was not, then the keyboard table and the contrast report                             |\n| Props interface  | The generated props table, then data attributes where the component documents them                             |\n\n## Previews [#previews]\n\nEach preview renders in an iframe under the product theme, with switches for theme, density, text size and status. Text size changes the real font size, so at 200% the layout reflows.\n\nThe docs chrome differs from the product theme on purpose, because density suits a developer at a desk and fails a patient holding a phone. The product theme is roomier, uses the reader's system font and keeps 44px touch targets, so take screenshots from a preview, not the page around it.\n\n## Release phases [#release-phases]\n\n| Phase        | It is                                | Its API                                                      |\n| ------------ | ------------------------------------ | ------------------------------------------------------------ |\n| `planned`    | A written specification with no code | A sketch. Do not code against it                             |\n| `shipped`    | Installable source in the registry   | May change in any release, with a changelog entry            |\n| `deprecated` | Installable source on its way out    | Frozen, with a named replacement and a named removal version |\n\nEvery component is `shipped`. That means the source installs and renders, and it never means reviewed. The review notice reads \"Audited against WCAG 2.2 AA. Clinical review pending.\" The authors of the components ran that audit, so it is not an independent review, and no component has had a clinical review. Nothing here is for a production health surface.\n\nThese phases describe software, while the clinical status levels describe a person's data.\n\n## Honesty markers [#honesty-markers]\n\n| Marker        | It reads                 | What it means                                                               |\n| ------------- | ------------------------ | --------------------------------------------------------------------------- |\n| `NotBuiltYet` | \"is not built yet\"       | No code is behind this id, so nothing renders                               |\n| `NoDataYet`   | \"has not been generated\" | A generated table has no source data yet. It names the script that fills it |\n| `Todo`        | \"Not written yet\"        | A known gap, counted by the build and still open                            |\n\n## Generated tables [#generated-tables]\n\nProps tables, token tables and contrast reports are generated from the source, and CI fails when one drifts from it. Copy a token's name, never its printed value. A contrast report gives two figures per pair. The WCAG 2.2 ratio is what conformance is measured against, and APCA Lc is a perceptual figure from the draft WCAG 3 work. Both are shown because they sometimes disagree."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/registry",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/registry.md",
      "slug": [
        "registry"
      ],
      "section": "Introduction and guides",
      "title": "Registry",
      "description": "opsinjs ships as a shadcn-spec registry of source you copy and own, not as an npm package you depend on.",
      "kind": "guide",
      "aliases": [
        "distribution",
        "shadcn registry",
        "@opsinjs",
        "self host",
        "npm packages"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "`npx shadcn add` writes a component's source into your repository. The registry follows shadcn's specification without extending it, so the shadcn CLI and its MCP server need no adapter.\n\n<Callout>\n  All 60 catalogue ids are `shipped`, so each installs and renders. None has had an independent accessibility review or any clinical review, and none is for a production health surface. Nothing is released yet.\n</Callout>\n\n## What you get and what it costs [#what-you-get-and-what-it-costs]\n\n| You get                                                                                               | You pay                                                              |\n| ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |\n| Readable source, such as [RangeBar](./components/range-bar.mdx)'s answer to a missing reference range | Updates never arrive on their own                                    |\n| No peer dependencies and no lockfile conflicts                                                        | Maintenance and security fixes, with no `npm audit` for copied files |\n| Changes made by editing a file                                                                        | Copies of one component drift apart silently                         |\n\n## What is served [#what-is-served]\n\n| Path                                 | Contents                                                                |\n| ------------------------------------ | ----------------------------------------------------------------------- |\n| [/r/registry.json](/r/registry.json) | Every item, without file contents. The CLI and MCP server read it first |\n| `/r/<name>.json`                     | One item, with its files inlined                                        |\n| `/r/styles/<style>/<name>.json`      | The same item at a named style                                          |\n| `/r/themes/<preset>.json`            | A theme, with `cssVars` and no files                                    |\n| [/r/index.json](/r/index.json)       | Status, category, aliases and the review notice for each id             |\n\nThe catalog and its items follow shadcn's schemas. An item's `name` is also its catalogue id, docs path and file name, and its `description` is plain English for a patient. Fields shadcn lacks, such as `implemented`, `status` and `since`, sit under `meta.opsinjs`, so items validate anywhere. A component is a `registry:ui` item that also carries `lib/opsinjs.ts` and `lib/status.ts`.\n\n## Namespace and commands [#namespace-and-commands]\n\n```json title=\"components.json\"\n{\n  \"registries\": {\n    \"@opsinjs\": \"https://opsinjs.pensievelabs.org/r/{name}.json\"\n  }\n}\n```\n\n`{name}` is required. Add the block even when you install by full URL, because 21 items name their siblings as `@opsinjs/<name>` in `registryDependencies`, and the CLI cannot follow them without it. A namespace is a local alias, not a reservation, so read the URL of any namespace you did not write.\n\n| Command                                                | Use                                           |\n| ------------------------------------------------------ | --------------------------------------------- |\n| `npx shadcn@latest add @opsinjs/result-card`           | Install an item and its registry dependencies |\n| `npx shadcn@latest add @opsinjs/result-card --dry-run` | List the files it would write                 |\n| `npx shadcn@latest view @opsinjs/result-card`          | Read the source before you accept it          |\n| `npx shadcn@latest add @opsinjs/result-card --diff`    | Compare your copy with the current upstream   |\n| `npx shadcn@latest search @opsinjs -q \"range\"`         | Search names, titles and descriptions         |\n\nNever run `add --all` against opsinjs, and never `--overwrite` before reading `--diff`. There is no `opsinjs` CLI, and the `check-theme` and `doctor` commands are proposed, not built.\n\n## Taking upgrades [#taking-upgrades]\n\nThere is no `npm update`, and nothing in a copied file records its version.\n\n1. Run `add` in its own commit, naming the item and the date. That commit is the only record of what you took.\n2. Read the [changelog](./changelog.mdx), then run `add --diff` to see what would change.\n3. Decide per hunk. Overwrite an unedited file, re-apply light edits on top, and three-way merge heavy ones against your install commit, for example with `git merge-file --diff3 mine.tsx base.tsx theirs.tsx`.\n4. Upgrade the token layer with the components, then re-run your tests, your contrast checks and a greyscale check.\n\nNo upgrade has been exercised yet, because nothing has been released. Prefer composition to editing, because a wrapper never conflicts.\n\n## Running your own registry [#running-your-own-registry]\n\nPublishing components beside opsinjs needs no fork. A registry is a flat `registry.json` plus one JSON file per item at a URL matching `{name}`, and `shadcn build` writes the item files. Pick a namespace nobody else will want, such as `@acme-health`, and reference opsinjs items by full URL or a configured namespace, never a bare name.\n\nFork the repository only to change tokens, generators or doctrine. First change its name, namespace, preset prefix and site URL. Never edit generated output, and run `pnpm run generate && pnpm run contrast && pnpm run check` after every upstream merge. Forking the status vocabulary or the clinical doctrine needs clinical sign-off.\n\n## Proposed packages [#proposed-packages]\n\nFive npm packages are proposed as specifications, and none is published. The repository's `packages/` folder holds only a README, and the registry stays the way opsinjs is distributed.\n\n| Package                 | Proposed to hold                                                                                                              |\n| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------- |\n| `@opsinjs/color`        | OKLCH, gamut mapping, APCA, WCAG 2.2 and `deriveTheme()`, for a contrast check in CI. The maths already lives in `lib/color/` |\n| `@opsinjs/motion`       | Spring solving and `linear()` generation                                                                                      |\n| `@opsinjs/react`        | The components as a dependency, for teams that cannot vendor source. Whether to publish it is undecided                       |\n| `@opsinjs/preset`       | The `@theme inline` mappings                                                                                                  |\n| `@opsinjs/tailwind.css` | The token stylesheet as a versioned import                                                                                    |"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/styling",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/styling.md",
      "slug": [
        "styling"
      ],
      "section": "Introduction and guides",
      "title": "Styling",
      "description": "Style a component you own through className, its data attributes and the render slot, without breaking the theme or the colour axes.",
      "kind": "guide",
      "aliases": [
        "className override",
        "cn function",
        "state attributes",
        "render prop",
        "asChild",
        "lint rules"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "Installed components are source you own, so you can edit them, but each edit is yours to merge at every upgrade. Try these hooks first, and fix the token in [Theming](./theming.mdx) when several components look wrong the same way.\n\n## className and style [#classname-and-style]\n\nEvery component takes `className` and merges it onto its root with `cn()`, which is `clsx` plus `tailwind-merge`. Your class comes last, so it wins a conflict:\n\n```ts\nimport { cn } from \"@/lib/utils\"\n\ncn(\"px-4 py-2\", isWide && \"px-8\")\n// \"py-2 px-8\"\n```\n\n* `className` styles only the root of what receives it, such as `Card` or `Card.Header`. Reach anything else through its `data-slot`.\n* When you wrap a component, forward `className` last, or the default overwrites the caller's.\n* The registry does not ship `cn`, so yours is the one `shadcn init` wrote. Its stock `tailwind-merge` treats `text-opsin-*` type steps as colours, so `cn(\"text-opsin-body\", \"text-foreground\")` keeps only the later class. Write the colour as `[color:var(--foreground)]`, as the components do.\n* Most components take a closed set of props with no `style`. [Button](./components/button.mdx) and [Link](./components/link.mdx) forward their native element's attributes, `style` included.\n* Never hardcode a colour such as `bg-[#e11d48]` or a size such as `text-[13px]`, never reach for `!important`, and never style into a component's internals by descendant selector.\n\n## Data attributes [#data-attributes]\n\nAttributes are the styling and testing contract, so renaming one is a breaking change. opsinjs stamps a closed set of four:\n\n| Attribute            | On                                                     | Value                                                            |\n| -------------------- | ------------------------------------------------------ | ---------------------------------------------------------------- |\n| `data-slot`          | Every part of every component                          | The part, such as `result-card-header`                           |\n| `data-status`        | An element whose colour, icon or word carries a status | `steady`, `watch`, `attention`, `urgent` or `unknown`            |\n| `data-category`      | An element tinted from the category axis               | One of the six categories                                        |\n| `data-opsinjs-value` | An element showing a measurement                       | The unrounded number, without its unit, so never export it alone |\n\n```css\n[data-open] { /* the popup is open */ }\n[data-status=\"urgent\"] { /* the value's clinical status */ }\n```\n\nComponents built on Base UI add its state attributes, such as `data-open`, `data-disabled` and `data-starting-style`. These are present or absent, so `[data-open]` matches and `[data-open=\"true\"]` does not.\n\n* Style a state through its attribute, not a class you toggle.\n* Never set `data-status` yourself to force a colour, because that puts a clinical claim in the DOM that nothing backs.\n* Never invent `data-opsinjs-*` attributes. Use your own prefix.\n* No `data-state` attribute exists, so a selector against it matches nothing.\n\n## The render slot [#the-render-slot]\n\nFour components take `render`, an element rendered in place of their own. Link, [Card](./components/card.mdx) and [MetricTile](./components/metric-tile.mdx) take your router's link so navigation stays client-side, and `Field.Control` in [Field](./components/field.mdx) takes a control opsinjs does not ship, such as `<textarea rows={3} />`. Link's own `href`, `data-slot` and attributes win over the router element's, and the two class lists are joined.\n\n```tsx\nimport NextLink from \"next/link\"\nimport { Link } from \"@/components/ui/link\"\n\n<Link href=\"/results\" emphasis=\"action\" render={<NextLink href=\"/results\" />}>\n  See your results\n</Link>\n```\n\nButton takes no `render`, `href` or `as`, because a control that goes somewhere is a Link. `render` is the nearest thing to shadcn/ui's `asChild`, and it is untested against Next and React Router links.\n\n## Naming [#naming]\n\n| Thing                            | Convention                          | Example                         |\n| -------------------------------- | ----------------------------------- | ------------------------------- |\n| Component id, file and docs path | kebab-case                          | `result-card`                   |\n| Component                        | PascalCase                          | `ResultCard`                    |\n| Props interface                  | `<Component>Props`                  | `ResultCardProps`               |\n| Prop                             | camelCase, booleans positive        | `disabled`, not `isDisabled`    |\n| Custom property                  | `--opsin-`, then axis, member, role | `--opsin-status-urgent-surface` |\n\nProse is British and code is American. Never name anything `normal`, never use `error` for a clinical state, and never add a catch-all `variant` prop, which ends up carrying both axes.\n\n## TypeScript [#typescript]\n\nEvery component exports a `<Component>Props` interface, from which its page's API table is generated. The axis types ship with every component in `lib/opsinjs.ts`:\n\n```ts\nimport { type ClinicalStatus, type HealthCategory } from \"@/lib/opsinjs\"\n```\n\n`ClinicalStatus` holds the four levels and `HealthCategory` the six categories. `unknown` is a separate `UnknownStatus`, the absence of a verdict rather than a fifth level, and `ClinicalStatusOrUnknown` joins the two. Type a wrapper with `Pick` and `Omit` on the exported interface, and never widen `status` to `string`.\n\n## Lint rules [#lint-rules]\n\n<NotBuiltYet what=\"The opsinjs lint tooling\">\n  `eslint-plugin-opsinjs` and `stylelint-plugin-opsinjs` are proposed as specifications. Neither is built or published.\n</NotBuiltYet>\n\nUntil they exist, review by hand for a colour literal or arbitrary colour value, both axes on one element, a status token in a category role, a banned word such as \"normal\" in copy, and a component variable set on `:root`. In a fork, `pnpm run check:a11y` catches several of these, but only in the component sources under `registry/`, never in your application."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/theming",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/theming.md",
      "slug": [
        "theming"
      ],
      "section": "Introduction and guides",
      "title": "Theming",
      "description": "Retheme opsinjs through its semantic tokens, and leave the status and category palettes that carry meaning as they are.",
      "kind": "guide",
      "aliases": [
        "theme",
        "retheme",
        "token tiers",
        "brand colour",
        "dark theme",
        "@theme inline"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "opsinjs draws every colour, radius, space step and duration from CSS custom properties, most of them generated from `tokens/*.json`. Change the token rather than the component, and every component follows.\n\n## Three tiers [#three-tiers]\n\n| Tier      | Looks like                                                   | Read by                           |\n| --------- | ------------------------------------------------------------ | --------------------------------- |\n| Primitive | `--opsin-neutral-500`, `--opsin-status-watch-500`            | The semantic tier only            |\n| Semantic  | `--primary`, `--card-foreground`, `--opsin-status-watch-ink` | Components and your code          |\n| Component | `--rb-label-half` on [RangeBar](./components/range-bar.mdx)  | One component, listed on its page |\n\nReferences point one way, from component to semantic to primitive. A primitive or a literal colour still renders, and silently drops out of every theme and contrast measurement. Status and category ramps have the slots `-surface`, `-line`, `-ink` and `-accent`, and an accent never carries meaning alone. Surface roles such as `--background` and `--card` resolve through `--opsin-chrome-*`. [Tokens](./reference/generated/tokens.mdx) lists every token.\n\n## A theme from your brand colour [#a-theme-from-your-brand-colour]\n\nEnter your brand's primary action colour in the [theme generator](/playground/theme). It derives an 11-step ramp in your browser, measures each step against white and near-black text with the build's contrast code, and gives you the ramp as `--brand-50` to `--brand-950`. It is a preview, because the engine that also clamps chroma per hue, adds a Display-P3 value and assigns roles by measurement is not published.\n\nSet the roles in your own stylesheet, imported after the opsinjs one:\n\n```css title=\"app/globals.css\"\n:root {\n  --primary: oklch(0.52 0.14 262);\n  --primary-foreground: oklch(0.99 0 0);\n}\n\n.dark {\n  --primary: oklch(0.72 0.12 262);\n  --primary-foreground: oklch(0.17 0.01 262);\n}\n```\n\nIn the default accent theme `--primary` is ink, the darkest neutral by day and the lightest by night, so a filled control carries no hue; the vibes and stryk themes make it the accent, and [Accent](./foundations/accent.mdx) lists every role. A theme sets `--primary`, `--primary-foreground`, `--ring` and the surface roles, never the status ramps, the category ramps or the contrast floor. Radius and space steps change only in `tokens/*.json`. Only one colour owns `--primary`, and a brand hue near a status hue stays off any surface that reports a result.\n\n## Presets and preset codes [#presets-and-preset-codes]\n\nA preset is a whole theme as one `registry:theme` item, with `cssVars` for light and dark and no files. `opsinjs-default` is the generated token layer. Each [accent theme](./foundations/accent.mdx) and accent is a preset that layers on it, named `opsinjs-<theme>-<accent>`, so `opsinjs-stryk-graphite` is the high-contrast preset.\n\n<CodeBlockTabs defaultValue=\"npm\" groupId=\"package-manager\">\n  <CodeBlockTabsList>\n    <CodeBlockTabsTrigger value=\"npm\">\n      npm\n    </CodeBlockTabsTrigger>\n\n    <CodeBlockTabsTrigger value=\"pnpm\">\n      pnpm\n    </CodeBlockTabsTrigger>\n\n    <CodeBlockTabsTrigger value=\"yarn\">\n      yarn\n    </CodeBlockTabsTrigger>\n\n    <CodeBlockTabsTrigger value=\"bun\">\n      bun\n    </CodeBlockTabsTrigger>\n  </CodeBlockTabsList>\n\n  <CodeBlockTab value=\"npm\">\n    ```bash\n    npx shadcn@latest add https://opsinjs.pensievelabs.org/r/themes/opsinjs-default.json\n    ```\n  </CodeBlockTab>\n\n  <CodeBlockTab value=\"pnpm\">\n    ```bash\n    pnpm dlx shadcn@latest add https://opsinjs.pensievelabs.org/r/themes/opsinjs-default.json\n    ```\n  </CodeBlockTab>\n\n  <CodeBlockTab value=\"yarn\">\n    ```bash\n    yarn dlx shadcn@latest add https://opsinjs.pensievelabs.org/r/themes/opsinjs-default.json\n    ```\n  </CodeBlockTab>\n\n  <CodeBlockTab value=\"bun\">\n    ```bash\n    bun x shadcn@latest add https://opsinjs.pensievelabs.org/r/themes/opsinjs-default.json\n    ```\n  </CodeBlockTab>\n</CodeBlockTabs>\n\n<Todo>\n  A large-type preset is specified and not built.\n</Todo>\n\nPreset names begin `opsinjs-` so they cannot collide with shadcn styles such as `lyra`. Prefix yours with your organisation. An encoder for short `opsinjs-*` codes is planned, not built. A shadcn preset code is opaque, so run `npx shadcn@latest preset decode <code>` before `npx shadcn@latest apply <code> --only theme`.\n\n## Status and category palettes [#status-and-category-palettes]\n\n1. The ramps `steady`, `watch`, `attention`, `urgent` and `unknown` are closed, because components, the registry, these docs and agents share the ids.\n2. Never add a fifth status level. Carry nuance in words.\n3. If a mandated clinical colour standard or a failing ramp forces a change, edit `tokens/color.json` in a fork, keep the urgency order, re-measure both themes and record it in your accessibility statement.\n4. A fork may add or retune a category. Keep a new hue at least 30° from the status hues 27, 45, 82 and 178, and test it under colour-blindness simulation. Retuning a shipped one is a versioned change.\n5. A category paints accent, line and ink, never a card fill, since a category tint and a status tint at one step look alike.\n6. Never name a token for a verdict, such as `--acme-normal`.\n\nNo element carries both axes, and status always has a word. See [Two colour axes](./health/two-colour-axes.mdx).\n\n## Dark mode [#dark-mode]\n\nDark mode is a `dark` class on `<html>`, and opsinjs ships no provider. Use at most one library that sets the class, add `suppressHydrationWarning` to `<html>`, and keep its script blocking to prevent a flash. Default to light, and offer light, dark and system. [Next.js](./nextjs.mdx) has the layout.\n\nDeclare every token you add under both `:root` and `.dark`, set `color-scheme` so native controls follow, and pin `@custom-variant dark (&:where(.dark, .dark *));` last.\n\n## Tailwind v4 and CSS variables [#tailwind-v4-and-css-variables]\n\nMap each custom property to a utility with `@theme inline`:\n\n```css\n@theme inline {\n  --color-status-watch-surface: var(--opsin-status-watch-surface);\n}\n```\n\nPlain `@theme` copies the value at build time, so `.dark`, Display-P3, the preference queries, `data-density` and `data-text-size` stop reaching the utility, silently. No registry item serves these mappings yet, the theme item included, so declare the ones your components use. opsinjs maps a bare `status-<level>` to the line role and a bare `category-<id>` to the accent.\n\nWithout Tailwind, read `var(--opsin-status-watch-surface)` directly, and keep `var()` references, not resolved values, in CSS-in-JS.\n\n## Validating contrast [#validating-contrast]\n\nPublished contrast figures describe the shipped tokens, so a changed token needs your own measurement. Check pairs at [/playground/contrast](/playground/contrast), or post them:\n\n```bash\ncurl -s https://opsinjs.pensievelabs.org/api/contrast \\\n  -H \"content-type: application/json\" \\\n  -d '{\"fg\":\"oklch(0.99 0 0)\",\"bg\":\"oklch(0.52 0.14 262)\",\"size\":\"body\"}'\n```\n\n`size` is `body`, `large` or `non-text`. The reply has APCA and WCAG 2.2 figures and a `pass`, `conditional` or `fail` verdict.\n\n* Measure both themes, because dark is derived and failures gather there.\n* Check by eye, in greyscale too, that levels still read in order and no category passes for a status.\n* A `check-theme` CI command is proposed for `@opsinjs/color`, which is not published, and `pnpm run contrast` measures only a fork's own tokens.\n* Check that `--opsin-tokens-generated` holds a hash and `--opsin-status-urgent-line` did not move.\n\n## Design handoff [#design-handoff]\n\nKeep `tokens/*.json` upstream of any design library, with roles as aliases of ramps and only `light` and `dark` modes. Display-P3, the `linear()` springs and opaque material fallbacks do not survive into design tools. A DTCG export is planned, not built."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/foundations",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/foundations.md",
      "slug": [
        "foundations"
      ],
      "section": "Foundations",
      "title": "Foundations",
      "description": "The token families and system-wide rules every opsinjs component obeys, one page each.",
      "kind": "foundation",
      "aliases": [],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "Foundations decide once what a colour, a size, a corner or a state means, so every component gives the same answer. Each page states the rules a component follows, and each token family ends in a table generated from `tokens/*.json`. Change a value in [Theming](../theming.mdx), and see every token in one list in [Tokens](../reference/generated/tokens.mdx).\n\n| Page                                           | What it covers                                                                                   |\n| ---------------------------------------------- | ------------------------------------------------------------------------------------------------ |\n| [Accessibility](./accessibility.mdx)           | WCAG 2.2 AA, what components guarantee, and the limits of an author-run audit                    |\n| [Colour](./colour.mdx)                         | Category and status as two axes, the derivation engine and the contrast floor the build measures |\n| [Typography](./typography.mdx)                 | The platform UI font, a type scale named for jobs, and the reader's own text size                |\n| [Space and layout](./space.mdx)                | The 4px spacing scale, the 44pt touch floor, responsive modes and the page shell                 |\n| [Shape](./shape.mdx)                           | The radius ladder, concentric nesting and squircle corners                                       |\n| [Motion](./motion.mdx)                         | Springs as tokens, motion chosen by its job, and reduced motion                                  |\n| [Materials](./materials.mdx)                   | The surface ladder, its rung names, and the contrast floor for translucent rungs                 |\n| [Iconography](./iconography.mdx)               | One icon library, and glyphs that never carry status on their own                                |\n| [Imagery](./imagery.mdx)                       | Illustration, photography, skin-tone representation, avatars and body diagrams                   |\n| [Data visualisation](./data-visualisation.mdx) | Chart colour, chart anatomy and accessible charts                                                |\n| [States](./states.mdx)                         | Interaction states, and the loading, empty, error, stale and partial data states                 |\n| [Writing](./writing.mdx)                       | Voice and tone, health literacy, and the words for status, alerts and errors                     |"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/foundations/accent",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/foundations/accent.md",
      "slug": [
        "foundations",
        "accent"
      ],
      "section": "Foundations",
      "title": "Accent",
      "description": "Three accent themes, normal, vibes and stryk, each with the same nine accents for action, selection, focus and accent text, and never for a result.",
      "kind": "foundation",
      "aliases": [
        "accent colour",
        "accent theme",
        "theme colour",
        "high contrast theme",
        "stryk",
        "vibes",
        "data-accent",
        "data-accent-theme"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "opsinjs has three kinds of colour. Status says how much attention something needs and category says what kind of measurement it is; both are fixed, and [Colour](./colour.mdx) owns them. The accent is the product's own colour, and it is the one you choose. An accent theme decides how loudly it is spent, and an accent decides its hue.\n\n<ComponentPreview name=\"accent-themes-a-settings-card\" kind=\"example\" minHeight=\"400\" />\n\nChange the theme and the accent with the picker above any preview. The choice follows you to every preview and every [showcase](/showcase) screen on this site.\n\n## Three themes [#three-themes]\n\n| Theme               | The filled action                                              | The selected state | Floors   | Default accent |\n| ------------------- | -------------------------------------------------------------- | ------------------ | -------- | -------------- |\n| Normal, the default | Ink, a near-black capsule by day and a near-white one by night | The accent         | Standard | Cobalt         |\n| Vibes               | The accent at full chroma, casting a glow                      | The accent         | Standard | Volt           |\n| Stryk               | The accent, deep by day and light by night                     | The accent         | Enhanced | Graphite       |\n\n**Normal** keeps the ink and paper look and spends the accent as light: what is selected, what has focus, and a quiet action set in words.\n\n**Vibes** makes the accent the action. Deep accents carry a white label. Volt, jade and sky are bright and carry an ink label, with an ink rim by day where the fill alone would not separate from the page; by night a deep fill takes a light rim for the same reason.\n\n**Stryk** is high contrast. The page is pure white or pure black, every boundary and edge is full ink, shadows and translucency go, and the focus ring widens to 3px. Every label clears WCAG 2.2 AAA, 7:1, and APCA Lc 85, and every boundary and ring clears 4.5:1 and Lc 60. **Stryk applies whenever the reader's system asks for more contrast**, whatever theme the product chose, and keeps the accent they picked.\n\n## Nine accents [#nine-accents]\n\nEvery theme defines the same nine, so changing the theme never changes the accent.\n\n| Accent   | Hue                         |\n| -------- | --------------------------- |\n| Cobalt   | 250                         |\n| Sky      | 212                         |\n| Jade     | 152                         |\n| Volt     | 122                         |\n| Rose     | 354                         |\n| Orchid   | 326                         |\n| Violet   | 300                         |\n| Iris     | 278                         |\n| Graphite | none, the monochrome accent |\n\n<ComponentPreview name=\"accent-themes-the-palette\" kind=\"example\" align=\"start\" minHeight=\"620\" />\n\n## Choosing one [#choosing-one]\n\nSet the theme and the accent on `<html>`. With neither, a page renders normal and cobalt.\n\n```html\n<html data-accent-theme=\"vibes\" data-accent=\"volt\">\n```\n\nAny element can start a scope of its own, and `.dark` may sit on the same element, above it or inside it. Set both attributes on one element: a theme on one element and an accent on another do not combine.\n\nEach pairing is also a theme item that layers on the default one:\n\n<CodeBlockTabs defaultValue=\"npm\" groupId=\"package-manager\">\n  <CodeBlockTabsList>\n    <CodeBlockTabsTrigger value=\"npm\">\n      npm\n    </CodeBlockTabsTrigger>\n\n    <CodeBlockTabsTrigger value=\"pnpm\">\n      pnpm\n    </CodeBlockTabsTrigger>\n\n    <CodeBlockTabsTrigger value=\"yarn\">\n      yarn\n    </CodeBlockTabsTrigger>\n\n    <CodeBlockTabsTrigger value=\"bun\">\n      bun\n    </CodeBlockTabsTrigger>\n  </CodeBlockTabsList>\n\n  <CodeBlockTab value=\"npm\">\n    ```bash\n    npx shadcn@latest add https://opsinjs.pensievelabs.org/r/themes/opsinjs-default.json\n    npx shadcn@latest add https://opsinjs.pensievelabs.org/r/themes/opsinjs-vibes-volt.json\n    ```\n  </CodeBlockTab>\n\n  <CodeBlockTab value=\"pnpm\">\n    ```bash\n    pnpm dlx shadcn@latest add https://opsinjs.pensievelabs.org/r/themes/opsinjs-default.json\n    pnpm dlx shadcn@latest add https://opsinjs.pensievelabs.org/r/themes/opsinjs-vibes-volt.json\n    ```\n  </CodeBlockTab>\n\n  <CodeBlockTab value=\"yarn\">\n    ```bash\n    yarn dlx shadcn@latest add https://opsinjs.pensievelabs.org/r/themes/opsinjs-default.json\n    yarn dlx shadcn@latest add https://opsinjs.pensievelabs.org/r/themes/opsinjs-vibes-volt.json\n    ```\n  </CodeBlockTab>\n\n  <CodeBlockTab value=\"bun\">\n    ```bash\n    bun x shadcn@latest add https://opsinjs.pensievelabs.org/r/themes/opsinjs-default.json\n    bun x shadcn@latest add https://opsinjs.pensievelabs.org/r/themes/opsinjs-vibes-volt.json\n    ```\n  </CodeBlockTab>\n</CodeBlockTabs>\n\nA theme item sets `:root` and `.dark` only, so it fixes one pairing. Switching at runtime needs the attribute blocks in `app/tokens.generated.css`.\n\n## Roles [#roles]\n\n| Role                                | Token                                         | Read by                                                                                                                                                                                                                                          |\n| ----------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `--primary`, `--primary-foreground` | `--opsin-accent-action`, `-action-foreground` | [Button](../components/button.mdx) `primary`                                                                                                                                                                                                     |\n| `--state-primary-hover`, `-press`   | `--opsin-accent-action-hover`, `-press`       | The same, under a pointer and pressed                                                                                                                                                                                                            |\n| `--brand`, `--brand-foreground`     | `--opsin-accent-fill`, `-fill-foreground`     | [Switch](../components/switch.mdx), [Checkbox](../components/checkbox.mdx), [RadioGroup](../components/radio-group.mdx), [Slider](../components/slider.mdx), [Progress](../components/progress.mdx), [ScaleInput](../components/scale-input.mdx) |\n| `--primary-edge`, `--brand-edge`    | `-action-edge`, `-fill-edge`                  | The rim a bright fill needs, transparent otherwise                                                                                                                                                                                               |\n| `--brand-ink`                       | `--opsin-accent-ink`                          | Button `quiet`, a card's quiet action, the [Tabs](../components/tabs.mdx) indicator                                                                                                                                                              |\n| `--ring`                            | `--opsin-accent-ring`                         | Every focus ring                                                                                                                                                                                                                                 |\n| `--brand-glow`                      | `--opsin-accent-glow`                         | The light a vibes action throws                                                                                                                                                                                                                  |\n\n## Rules [#rules]\n\n1. An accent never fills a surface that reports a result and never carries a status or a category. On a status surface, such as an [AlertBanner](../components/alert-banner.mdx), a control takes that level's own ink instead.\n2. Every accent hue keeps at least 25 degrees from the status hues 27, 45, 82 and 178, so red, orange, amber and the steady teal stay with status. Graphite has no hue.\n3. Every pair is measured. `scripts/build-tokens.mts` refuses to write an accent below its floor, so a failing accent fails the build, and [Accent contrast](../reference/generated/accents.mdx) publishes every figure.\n4. A control drawn as words is set in the accent ink and never underlined. An underline marks a link inside running text.\n5. A custom accent is a fork of `tokens/accent.json`, measured the same way, never a colour set in a component.\n\n<Todo>\n  Stryk has not been used by a reader with low vision, and no accent theme has been checked by eye under forced colours, where the platform replaces every accent with its own pair.\n</Todo>"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/foundations/accessibility",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/foundations/accessibility.md",
      "slug": [
        "foundations",
        "accessibility"
      ],
      "section": "Foundations",
      "title": "Accessibility",
      "description": "WCAG 2.2 AA, what every component guarantees, what your product still owns, and the limits of an author-run audit.",
      "kind": "foundation",
      "aliases": [
        "a11y",
        "wcag 2.2",
        "vpat"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "The target is WCAG 2.2 Level AA. The authors of the sixty components audited every one against it, in a source pass and a rendered pass, and fixed what they found. That is not an independent review, and no clinician has reviewed any component. opsinjs makes no conformance claim, and nothing here is for a production health surface.\n\n## What components guarantee [#what-components-guarantee]\n\n* **Status is never colour alone.** A visible word and an icon whose shape differs per level sit beside every status colour.\n* **Targets are at least 44 by 44 CSS pixels** at every density.\n* **Keyboard patterns come from Base UI,** and only a modal surface traps focus.\n* **Motion and translucency degrade per token** when the reader asks for less.\n* **A number must never be clipped.** The value and its unit wrap instead.\n\n## What your product owns [#what-your-product-owns]\n\n* **Names and words.** Label every icon-only button and field, and write headings, link text and a text equivalent for every chart. See [Writing](./writing.mdx).\n* **Order and focus.** Tab and screen readers follow the DOM. Place focus after a delete or a submit, and add a skip link and landmarks.\n* **Clinical meaning.** opsinjs renders \"Needs attention\". Which reading earns it is your product's clinical decision.\n* **Timing, sessions and sign-in**, under SC 2.2.1 and SC 3.3.8.\n* **Anything you colour, animate or make translucent yourself.**\n\n## Contrast [#contrast]\n\n`pnpm run contrast` measures every published token pair in both themes as a WCAG 2.2 ratio and an APCA Lc. Failing pairs are shown, not filtered, and `contrast:verify` fails the nightly job when a token edit moves a figure. The floor is on [Colour](./colour.mdx), and every figure is in the [contrast reference](../reference/generated/contrast.mdx).\n\nCheck any pair you invent at [/playground/contrast](/playground/contrast), and text over a translucent rung, whose figure assumes its opaque fallback.\n\n## Colour independence [#colour-independence]\n\nThe words are Steady, Watch, Needs attention, Urgent and Not known, and the `data-status` ids are `steady`, `watch`, `attention`, `urgent` and `unknown`. Under deuteranopia `steady` and `attention` collapse to one tone, so the word and icon carry the difference. Check in greyscale and at [/playground/status](/playground/status). Category colour never shares an element with status. See [Two colour axes](../health/two-colour-axes.mdx).\n\n## Keyboard and focus [#keyboard-and-focus]\n\nA composite widget such as a menu is one <Kbd>Tab</Kbd> stop, and arrow keys, <Kbd>Home</Kbd> and <Kbd>End</Kbd> move inside it. <Kbd>Esc</Kbd> dismisses the topmost surface and returns focus to its trigger. Positive `tabindex` is banned. The focus ring sits outside the element, so keep it clear of `overflow: hidden` and sticky bottom bars (SC 2.4.11).\n\n## Screen readers [#screen-readers]\n\nA value change is announced politely and a safety change assertively, with no third level. [AlertBanner](../components/alert-banner.mdx) uses `aria-live=\"polite\"` at `attention` and `role=\"alert\"` at `urgent`. Announce a sentence (\"Blood pressure, 138 over 84, above your usual range\"), never a bare number, and put the status word in the accessible name.\n\n## Target size [#target-size]\n\n`--opsin-target-minimum` is `2.75rem`, 44 pixels at the default root size, so it grows with the reader's text. That is the AAA figure (SC 2.5.5). AA asks for 24 (SC 2.5.8). `--opsin-target-separation` (`0.5rem`) spaces targets drawn smaller than 44 pixels. Never put delete beside save. Pair [Slider](../components/slider.mdx) with [ReadingInput](../components/reading-input.mdx), and give every drag a single-pointer alternative.\n\n## Text resizing and zoom [#text-resizing-and-zoom]\n\nText scales to 200% through the root font size, and layouts reflow at 400% zoom in a 1280 pixel window (SC 1.4.10). Fixed pixel heights, `overflow: hidden` and `user-scalable=no` usually break them.\n\n<SafetyCallout severity=\"urgent\" evidence=\"opinion\">\n  A truncated health value is a defect of the same class as a wrong one, because the reader cannot tell the two apart.\n</SafetyCallout>\n\n## User preferences [#user-preferences]\n\n* **`prefers-reduced-motion`.** Durations collapse to `1ms` and springs to their declared fallbacks. The state change still happens.\n* **`prefers-reduced-transparency`.** Translucent rungs turn opaque, and nothing moves.\n* **`prefers-contrast: more`.** Only [Surface](../components/surface.mdx) and [DisclaimerNote](../components/disclaimer-note.mdx) respond. The token layer has no answer.\n* **`forced-colors: active`.** Surface, [Field](../components/field.mdx), [RangeBar](../components/range-bar.mdx), [ScoreDial](../components/score-dial.mdx) and others answer it in their own files.\n\nAnimation outside the tokens must read `matchMedia('(prefers-reduced-motion: reduce)')` itself, and urgency is never carried by motion. See [Motion](./motion.mdx).\n\n<Todo>\n  Implement `prefers-contrast: more` in the token layer, give every control a visible boundary under `forced-colors`, and measure the escalated theme in `scripts/check-contrast.mts`.\n</Todo>\n\n## Cognitive accessibility [#cognitive-accessibility]\n\nAsk for one decision per screen, and name the primary action's outcome instead of \"Continue\". Put the answer before the explanation, and keep the reader's input through an error. [Toast](../components/toast.mdx) dismisses itself after five seconds by default, so anything the reader must act on belongs in an AlertBanner. This guidance is our opinion, untested by user research.\n\n## Print [#print]\n\nThe product stylesheet prints both themes as ink on white, Surface keeps its outline, and [RelativeTime](../components/relative-time.mdx) prints an absolute time. A printed value still needs its unit, when it was taken, its status word and any disclaimer. Paper cannot be updated, so a provisional value must say so on the printout.\n\n## Testing your integration [#testing-your-integration]\n\nopsinjs has no test suite of its own. `pnpm run check:a11y` reads component source on every pull request, and a nightly browser pass checks hit area and 200% text. Assert on roles, accessible names, `data-*` attributes and visible text, which semver covers, and never on class names or DOM nesting.\n\nTest with an automated engine, the keyboard alone, 200% text, 400% zoom, greyscale, each preference and a screen reader, iOS VoiceOver and Android TalkBack first. Use empty, stale, out-of-range and implausible data. Finally, read the screen aloud to an outsider and ask what they would do next.\n\n## Conformance documents [#conformance-documents]\n\nopsinjs makes no conformance claim at any level and publishes no conformance report. An Accessibility Conformance Report would list every one of the 55 WCAG 2.2 Level A and AA criteria as Not Evaluated, because that column records an independent evaluation and none has happened. Your product needs its own statement and report.\n\n<NoDataYet what=\"The conformance evaluation record\" script=\"scripts/build-registry.mts\">\n  No catalogue row records an independent review, so there is no evaluation table to publish.\n</NoDataYet>\n\n## Known gaps [#known-gaps]\n\n* No screen reader has been used on any component, and no disabled people have tested one.\n* Forced colours are untested on a real Windows contrast theme, and print on a real printer.\n* Text spacing (SC 1.4.12) is unaddressed.\n* No shared announcement helper ships.\n\n<NoDataYet script=\"scripts/capture-registry.mts\" what=\"A measured result for any rendered component\">\n  The rendered audit was done by hand. The scripts that would capture a figure need Playwright, run only nightly and publish no figure.\n</NoDataYet>"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/foundations/colour",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/foundations/colour.md",
      "slug": [
        "foundations",
        "colour"
      ],
      "section": "Foundations",
      "title": "Colour",
      "description": "Two colour axes, one derivation engine, and a contrast floor measured on every declared pair in both themes.",
      "kind": "foundation",
      "aliases": [
        "color system",
        "palette",
        "oklch",
        "colour engine",
        "APCA",
        "display-p3",
        "color blind",
        "color tokens"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "The [colour browser](/colors) shows every colour token as your device resolves it.\n\n## Two axes [#two-axes]\n\nCategory colour says what kind of measurement something is: `sleep`, `heart`, `activity`, `nutrition`, `mind` or `labs`. Status colour says how urgent it is: `steady`, `watch`, `attention` or `urgent`, plus `unknown`, which means no verdict rather than a fifth level. An element takes colour from one axis, never both, and a status always carries a word and an icon too. Your product assigns every status from ranges and thresholds it owns, and [Two colour axes](../health/two-colour-axes.mdx) has the full rule.\n\n## Roles [#roles]\n\nClinical tokens are named `--opsin-<axis>-<name>-<role>`.\n\n| Role      | What it is                                      | Contrast obligation                        |\n| --------- | ----------------------------------------------- | ------------------------------------------ |\n| `surface` | The tinted fill behind content                  | The background half of each pair           |\n| `line`    | A boundary, icon stroke or chart mark           | Non-text, against its own surface          |\n| `ink`     | Text and icons that carry words                 | Text, against its own surface and the page |\n| `accent`  | An identity fill, such as a bar or a legend dot | None. Never text, never the only boundary  |\n\nA contrast guarantee attaches to a pair, never to a colour.\n\n* Use a whole pair or neither half. A status word on a neutral card is `ink`, never `line`.\n* Never put one axis's `ink` on the other axis's `surface`.\n* Only status tints a surface. A category paints a line, a word or an accent, and has no surface utility.\n* Use a role, never a ramp step or a raw `oklch()`. Hover and pressed colours are derived from the role, not shipped as tokens. See [States](./states.mdx).\n* The bare Tailwind name differs by axis: `bg-status-urgent` is the line and `bg-category-heart` is the accent.\n\nNeutral UI uses the shadcn chrome roles, such as `--background`, `--card` and `--border`.\n\n## Ink and the brand light [#ink-and-the-brand-light]\n\nThe two axes are the only colour that means anything, so nothing else on a product screen competes with them.\n\n* The primary action is ink. `--primary` is the darkest neutral by day and the lightest by night, so a filled control carries no hue.\n* One hue is left in the chrome, the brand light `--opsin-chrome-brand`, at hue 250 between `labs` and `sleep`. It is spent as light: the focus ring, the mark beside an eyebrow, the bar beside the current page and the bloom behind this site. It never fills anything that reports a result and never colours a word a reader has to read.\n* `--border` and `--input` are the 3:1 boundary of a control. `--edge` is the decorative line around a sheet that is not a control, a card or a table, which its drop lifts off the page.\n\n## Derivation engine [#derivation-engine]\n\nGive the engine one brand colour. It keeps the hue, lays it on the fixed lightness ladder every ramp shares, clamps chroma into sRGB step by step without moving lightness or hue, and assigns roles by measurement. If no step clears the floor, it says so rather than ship a failing theme. Derive your own in [Theming](../theming.mdx) or the [theme generator](/playground/theme).\n\n<Todo>\n  The maths lives in `lib/color/` as an app internal, with no published API your own CI can gate on. The theme generator is the only supported entry point.\n</Todo>\n\n## Contrast [#contrast]\n\nWCAG 2.2 is the obligation and APCA is the design tool. `scripts/check-contrast.mts` measures every declared pair in light and dark with both models.\n\n| What the pair carries                                                | WCAG 2.2 | APCA Lc |\n| -------------------------------------------------------------------- | -------- | ------- |\n| Body text, labels and UI copy                                        | 4.5:1    | 75      |\n| Large text, 24px or 18.66px bold                                     | 3:1      | 60      |\n| A meaningful line, such as a status rule, chart stroke or focus ring | 3:1      | 45      |\n| Disabled or decorative, carrying no information                      | None     | None    |\n\nAPCA is a draft, so opsinjs pins its own thresholds. Lc 90 on a health value a person may act on is our judgement rather than a standard, and the build does not gate it.\n\n* Gated pairs fail the nightly run when a change drives one below its floor. Text, `ink` and the neutral boundaries are gated.\n* Advisory pairs, such as an `accent` fill, are published but not gated.\n* Exempt pairs sit outside the floor's scope.\n\nAnything outside the declared set is unmeasured, including text over an image or a translucent surface and faded text such as `text-foreground/70`. [Contrast](../reference/generated/contrast.mdx) lists every measured pair, and the [contrast oracle](/playground/contrast) checks any other.\n\n<ContrastReport scope=\"status\" />\n\n<Todo>\n  In dark, the card border clears WCAG 3:1, but no neutral step lets a 1px hairline reach APCA Lc 45 on the near-black page.\n</Todo>\n\n## Colour blindness [#colour-blindness]\n\nThe status axis keeps the familiar green to red order, although red-green is the most common colour vision deficiency. Keeping it is a judgement, not a finding.\n\nThe four levels collapse under simulation and in greyscale, so every status carries a visible word, a distinct glyph per level, and a fixed order wherever several levels appear together. There is no colour-blind palette or mode. Desaturate a screenshot and read it.\n\n## Display P3 [#display-p3]\n\nsRGB is what every reader gets, and every figure is measured on it. A P3 step adds chroma at the same lightness and hue, so contrast barely moves.\n\nGuard it with `@media (color-gamut: p3)`. The form `@supports (color-gamut: p3)` is always false, because `color-gamut` is a media feature. The generated stylesheet still uses the `@supports` form, so no reader receives P3 values yet.\n\n<NoDataYet what=\"A measurement of the escalated P3 values\" script=\"scripts/check-contrast.mts\">\n  `scripts/check-contrast.mts` never reads the P3 values, so the published figures describe sRGB only.\n</NoDataYet>\n\n## Dark mode [#dark-mode]\n\nLight is the default. Dark is re-derived from the same ladder, not inverted, and keeps every hue, the order of the status levels and the same contrast floor.\n\nSurfaces gain chroma and inks lose it. The background is near-black rather than black, a raised surface gets lighter instead of casting a shadow, and the root declares `color-scheme`. Test dark on a phone at low brightness.\n\n<Todo>\n  The dark `watch` and `attention` surfaces share ladder step 950 and measure roughly Lc 0 against each other. The line, the word and the icon tell them apart.\n</Todo>\n\n## Tokens [#tokens]\n\n<TokenTable scope=\"color\" />"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/foundations/data-visualisation",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/foundations/data-visualisation.md",
      "slug": [
        "foundations",
        "data-visualisation"
      ],
      "section": "Foundations",
      "title": "Data visualisation",
      "description": "Chart colour that respects the two colour axes, a fixed y-axis, and the table twin every chart needs.",
      "kind": "foundation",
      "aliases": [
        "charts",
        "graphs",
        "table twin"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "opsinjs is not a charting library. [TrendSparkline](../components/trend-sparkline.mdx) shows change over time, [RangeBar](../components/range-bar.mdx) one value against a reference range and [ScoreDial](../components/score-dial.mdx) a composite score. Apply these rules to any plotting library.\n\n## Chart colour [#chart-colour]\n\nChart colour follows the [two colour axes](../health/two-colour-axes.mdx), and neither axis may tell series apart.\n\n* **No series in a status colour.** It asserts urgency about the whole dataset and spends the colour kept for escalation ([Alerts](../health/alerts.mdx)).\n* **No series in a category colour either.** As thin lines the accents look alike.\n* **A flagged reading's status goes in words**, as a [StatusPill](../components/status-pill.mdx) beside the chart.\n* **Reference bands are neutral**, labelled and sourced, never green ([Reference ranges](../health/reference-ranges.mdx)).\n* **Colour comes third**, after direct labels and a dash, marker or thickness difference, so a greyscale print still parses.\n* **Pin series one to colour one**, and stop at about five series.\n* **A diverging ramp needs a labelled midpoint** set by the product's clinical governance rather than the mean of the visible data.\n\n<NotBuiltYet what=\"The third ramp\">\n  `tokens/color.json` declares no chart ramp, so no `--opsin-chart-*` property exists. TrendSparkline strokes its line with the category `-line` role in the meantime.\n</NotBuiltYet>\n\nBelow, only each caption's StatusPill carries status.\n\n<ComponentPreview name=\"trend-sparkline-a-band-and-a-marked-reading\" kind=\"example\" align=\"start\" />\n\n## Axes [#axes]\n\n* **Fix the y-axis per metric**, with its units and precision ([Numbers and units](../health/numbers.mdx)). Never fit it to the visible data.\n* **Start at zero where zero means something**, such as steps, and always for bars and areas. Otherwise span the clinically relevant range and state that range beside the chart.\n* **A new window never rescales the y-axis**, and nothing animates.\n* **Gaps stay gaps** ([States](./states.mdx)). TrendSparkline takes one as an entry with `value: null`.\n* **Place readings by time taken**, not by index.\n* **Label the last value directly**, and give the axis its unit.\n* **No dual y-axes or projections.**\n* **Draw no trend from too few points.** The product sets the minimum ([Trends and uncertainty](../health/trends.mdx)), so TrendSparkline's `minimumPoints` has no default.\n\n<NotBuiltYet what=\"A chart that renders every part named here\">\n  TrendSparkline draws one series and an optional band, with no axes and no interaction.\n</NotBuiltYet>\n\n## Table twin [#table-twin]\n\nEvery chart must ship a table twin, which is the same data in a real table on the same screen. It is never behind a hover, in a modal or visually hidden. Put the summary first, the chart second and the table last.\n\n* **Summary.** One sentence generated from the data: metric, window, direction, magnitude, coverage and caveat. For example, \"Systolic blood pressure, last 14 days: 11 readings, ranging from 118 to 134, with no clear direction. Three days have no reading.\"\n* **Chart.** One labelled image named by the summary, or hidden when the table sits beside it.\n* **Table.** Units in the header, a caption naming metric and window, and each missing reading as an empty cell with a reason.\n\n<NotBuiltYet what=\"A chart with a table twin\">\n  No chart in the registry provides a table twin yet.\n</NotBuiltYet>\n\nBuild one with [Table](../components/table.mdx).\n\n```tsx\n<Table\n  caption=\"Example series by period, the readable twin of the chart above, showing an example count for each period\"\n  columns={[\n    { key: \"period\", header: \"Period\" },\n    { key: \"count\", header: \"Count\", numeric: true },\n  ]}\n  rows={[\n    { period: \"Period one\", count: \"12\" },\n    { period: \"Period two\", count: \"1,000\" },\n  ]}\n/>\n```\n\n## Accessibility [#accessibility]\n\n* WCAG 2.2 SC 1.1.1 is met by the table twin, not by alt text.\n* SC 1.4.11 applies to every mark, gridline and tick.\n* Whatever hover reveals, keyboard focus reveals.\n* The plot shrinks as axis labels grow with text size.\n* Test with the screen off: what does the chart show, and what was day three?"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/foundations/iconography",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/foundations/iconography.md",
      "slug": [
        "foundations",
        "iconography"
      ],
      "section": "Foundations",
      "title": "Iconography",
      "description": "One icon library, glyphs that never carry status alone, and the medical symbols opsinjs will not use.",
      "kind": "foundation",
      "aliases": [
        "icons",
        "lucide",
        "medical icons"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "opsinjs draws every glyph from lucide, and the registry components import theirs from `lucide-react`. The [icon browser](/icons) lists the curated set and each glyph's job.\n\n## Rules [#rules]\n\n1. **An icon never carries status alone.** Status is a colour, a glyph and a word together. There are no exceptions.\n2. **An icon is decorative unless it is the only content.**\n3. **Primary navigation and primary actions carry words.**\n4. **An icon never stands for a value.** A tick or a smiley beside a reading is a verdict, and verdicts are [clinical status](../health/two-colour-axes.mdx) in words.\n5. **No value, unit or status word is ever an icon or an icon font.**\n6. **Propose a missing glyph rather than drawing one.** A one-off SVG escapes the inventory and the colour-vision audit.\n\n## Status glyphs [#status-glyphs]\n\n`CLINICAL_STATUS_META[level].icon` in `lib/status.ts` names one glyph per level: `Circle` for Steady, `CircleDot` for Watch, `Diamond` for Needs attention, `Octagon` for Urgent and `Minus` for Not known. Take glyph names from the map, as [StatusPill](../components/status-pill.mdx) does, rather than choosing your own.\n\nEach silhouette is heavier than the last, so the order survives greyscale. `Minus` is the absence of a verdict, never a fifth level. Do not use a warning triangle as a status glyph by default.\n\n## Health glyphs [#health-glyphs]\n\nopsinjs does not practise medicine, so no glyph may claim a clinician is speaking. Never use:\n\n* **A red cross on white.** It is protected under the Geneva Conventions and national law.\n* **Any cross meaning \"medical\", a caduceus or a rod of Asclepius.** They signal authority.\n* **A stethoscope, white coat or clinician figure.** It implies a doctor is involved, and usually none is.\n* **A syringe, needle or blood drop.** It distresses many readers, including many the product serves.\n* **A pill meaning \"health\".** Use a pill only for a dose.\n* **A decorative ECG trace.** It is fabricated data.\n* **A health service's marks.** They imply a false endorsement.\n\nDraw the object measured or the activity recorded, or use words. Emergency is a screen with words, a phone number and a stated source ([High-stakes moments](../health/high-stakes-moments.mdx)), never a glyph.\n\n<SafetyCallout severity=\"watch\" evidence=\"opinion\">\n  This list is a design position, not a measured finding. The red cross emblem is a legal matter, and implying clinical status you do not hold is a regulatory question in most jurisdictions. Check both with your own counsel.\n</SafetyCallout>\n\n## Icons in code [#icons-in-code]\n\n[Button](../components/button.mdx), [IconButton](../components/icon-button.mdx), [MetricTile](../components/metric-tile.mdx) and [TabBar](../components/tab-bar.mdx) take a glyph as a node and wrap it `aria-hidden`. Button and IconButton size any child `svg` at `1em`.\n\n```tsx\nimport { Search } from \"lucide-react\"\n\n<IconButton\n  icon={<Search />}\n  label=\"Search readings\"\n  onClick={openSearch}\n/>\n```\n\nThe required `label` is the accessible name. Name the action (\"Dismiss alert\"), never the picture (\"cross\").\n\n* Import icons by name, never the whole library.\n* Never hardcode a fill or a stroke colour. Glyphs take `currentColor`.\n* Never put `aria-hidden` on a focusable element.\n* Never animate an icon to attract attention.\n\n## Sizing and alignment [#sizing-and-alignment]\n\n* Beside text, size in `em` so the glyph grows with the reader's text size.\n* Glyph size is not target size. A small glyph sits inside the 44px `--opsin-target-minimum` floor ([Space and layout](./space.mdx)).\n* Leave `--opsin-space-1` (4px) between a glyph and its label.\n* Align to the optical centre of the text, not its baseline.\n* Keep one size per row, and keep the icon column when a row has none.\n* Meaningful glyphs meet WCAG 2.2 SC 1.4.11 at their rendered size and stroke.\n\n## Inventory [#inventory]\n\nOnly status is mapped. Components import other glyphs directly, so keep each concept's glyph in one place until a map exists.\n\n<NoDataYet what=\"The generated role-to-glyph table\" script=\"scripts/build-registry.mts\">\n  No generator emits icon data yet, because `scripts/build-registry.mts` has no icon step.\n</NoDataYet>"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/foundations/imagery",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/foundations/imagery.md",
      "slug": [
        "foundations",
        "imagery"
      ],
      "section": "Foundations",
      "title": "Imagery",
      "description": "When a health screen earns an image, and rules for illustration, photography, skin tone, avatars and body diagrams.",
      "kind": "foundation",
      "aliases": [
        "images",
        "illustration",
        "skin tone"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "Most health screens are better with no image. Keep one only if it changes what the reader does.\n\n<NotBuiltYet />\n\nopsinjs ships no image assets, illustration set or photography.\n\n## Rules [#rules]\n\n1. **An image does a job a sentence cannot.**\n2. **Nothing lives only in the image**, and no text sits inside one.\n3. **Never illustrate a result** or soften bad news with an image ([Result disclosure](../patterns/result-disclosure.mdx)).\n4. **Drawn images use the neutral colour roles**, never `--opsin-status-*` or `--opsin-category-*`.\n5. **Nothing flashes, loops or autoplays** ([Motion](./motion.mdx)).\n6. **Never let an image delay the reading.**\n\n## Illustration [#illustration]\n\nDraw to show how something is done or where it is, never to make a screen feel friendly.\n\n* Brief the reader's question, such as where a cuff goes on the upper arm, seen from their own point of view.\n* Draw specific people across a genuine range. Faceless uniform figures depict nobody.\n* A drawn device display is blank or obviously non-numeric, never a plausible reading.\n\n## Photography [#photography]\n\nUse a photograph only for an object the reader must recognise, a real person or place the product is about, or the reader's own picture.\n\n* Never put a value over a photograph. Other text over one needs a scrim that meets the contrast floor at the image's worst region ([Materials](./materials.mdx)).\n* Never crop a symptom photograph, and show a warning with an explicit control before any clinical image.\n* Clinical photography needs clinical review, and releases, licensing and informed consent are the product's to settle.\n* A reader's own photographs are personal data ([Consent and privacy](../health/consent-and-privacy.mdx)).\n\n## Skin-tone representation [#skin-tone-representation]\n\nSkin-tone representation is an equity requirement, not a style preference. For clinical signs it is a correctness requirement too. Signs that present as red on pale skin frequently do not on brown and black skin, where they may show as purple, grey or darker brown, or as a change in texture or warmth.\n\n1. A set showing people covers a genuine range of skin tones, not two extremes.\n2. A set showing a clinical sign covers the range for that sign, or it does not ship.\n3. Tone does not correlate with role or outcome anywhere in the set.\n4. Interface colour is never derived from skin tone.\n\nAudit the set, not the image, against a published dermatological scale. Describe each sign in words that work across tones. Ask for a reader's skin tone only where a clinical comparison genuinely needs it, once, explained, optional and revocable.\n\n<SafetyCallout severity=\"watch\" evidence=\"opinion\">\n  This section cites no study. Clinical imagery needs review by somebody clinically qualified across the skin tones you serve, which a design system cannot do.\n</SafetyCallout>\n\n## Avatars [#avatars]\n\nPrefer no avatar. Where one is needed, default to initials on a neutral surface, then an abstract mark. Never use a silhouette, which depicts a body. The reader may always choose a picture. [Avatar](../components/avatar.mdx) falls back to lucide's `User` glyph when `name` is empty, so always pass a name.\n\n* Never derive an avatar from health data or inferred demographics.\n* Show the person's name in text. Initials alone cannot tell two profiles apart.\n\n## Body diagrams [#body-diagrams]\n\nA body diagram is the image most likely to be read as a diagnosis. [BodyMap](../components/body-map.mdx) is an abstract schematic that records marked regions and nothing else.\n\n* Always pair the diagram with a list of the same regions.\n* Name regions in plain English, with any clinical term secondary as a [Term](../components/term.mdx).\n* Say whose left is meant, and confirm each selection in words: \"You selected: your left knee.\"\n* Never colour a region by status or label one with a condition.\n* Regions below the 44px target floor zoom to a sub-view or live only in the list."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/foundations/materials",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/foundations/materials.md",
      "slug": [
        "foundations",
        "materials"
      ],
      "section": "Foundations",
      "title": "Materials",
      "description": "The six named rungs that say what a surface is made of, and the contrast floor every translucent rung must clear.",
      "kind": "foundation",
      "aliases": [
        "surfaces",
        "backdrop-filter",
        "frosted",
        "scrim",
        "z-index",
        "prefers-reduced-transparency",
        "material rungs"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "A material says what a surface is made of and what shows through it. The six rungs form an ordered ladder, not a palette, and translucency starts at `sheet`.\n\n<MaterialLadder />\n\n## The ladder [#the-ladder]\n\n| Rung      | Opaque | Its job                                                                                                       |\n| --------- | ------ | ------------------------------------------------------------------------------------------------------------- |\n| `canvas`  | Yes    | The page itself                                                                                               |\n| `card`    | Yes    | A bounded piece of content, lifted by a soft drop over a decorative edge. The default home for a health value |\n| `raised`  | Yes    | Above the page without covering it: a menu, popover, tooltip or toast                                         |\n| `sheet`   | No     | Covers the page and leaves it recognisable: a bottom sheet, side panel or modal                               |\n| `overlay` | No     | Chrome that content scrolls beneath, such as a tab bar                                                        |\n| `scrim`   | No     | The dimming behind a `sheet`                                                                                  |\n\nRung names are token names, so a sheet's blur is `--opsin-material-sheet-blur`, never a number. Each rung resolves eight properties: `-tint`, `-tint-alpha`, `-blur`, `-saturation`, `-border`, `-shadow`, `-scrim` and `-opaque`. People swap `overlay` and `sheet`, so translate by job, never by position. The token-only `inset` rung is the recessed well that [Callout](../components/callout.mdx) and [RangeBar](../components/range-bar.mdx) draw inside a card.\n\n[Surface](../components/surface.mdx) applies all eight together. In your own CSS, that is your job.\n\n```tsx\n<Surface rung=\"sheet\">Everything the surface holds</Surface>\n```\n\n## Choosing a rung [#choosing-a-rung]\n\n1. Does content scroll under it? It is `overlay`.\n2. Does it cover the page, so what is behind is unusable? It is `sheet`, over a `scrim`.\n3. Otherwise it is `raised` if it appears and is dismissed, `card` if it is a bounded part of the page, or else `canvas`.\n\n* Pick the lowest rung that works. A rung shows depth, never importance or [two colour axes](../health/two-colour-axes.mdx).\n* Never nest translucent rungs. A card inside a sheet is `card` or `raised`.\n* Show one `sheet` at a time. Its `scrim` is a sibling, never a child, and `overlay` chrome dims under it.\n* Never add a shadow of your own. A rung brings its drop, a line of light along its top edge and its edge together, so a card and a menu are lifted by the system rather than by a component.\n* A health value sits on an opaque rung, unless a sticky `overlay` summary repeats a value shown opaquely on the same screen.\n\n## The contrast floor [#the-contrast-floor]\n\nEvery translucent rung has a minimum backing tint, chosen so that text on it clears the contrast floor against the worst possible backdrop. The composite is `α × tint + (1 − α) × backdrop`, so the tint over black and over white bound every case, and `scripts/check-contrast.mts` measures text against both in both themes. [Contrast](../reference/generated/contrast.mdx) records each result, and today's one shortfall is `overlay` over a light backdrop in the dark theme.\n\n* Never author alpha inline. That includes `bg-white/70 backdrop-blur-xl` and `opacity` on a container, which makes the text translucent too.\n* Blur removes texture, not brightness, so it is never traded against tint.\n* Text never sits directly on an image. Put it on a translucent rung or a scrim, and ramp a gradient scrim to full opacity before the first baseline.\n\n<Todo>\n  Not yet measured: borders on translucent rungs as non-text pairs, the saturation boost on `sheet` and `overlay`, and anything in Display-P3. `contrast:verify` fails a below-floor result nightly, not on the pull request.\n</Todo>\n\n## Reduced transparency [#reduced-transparency]\n\nUnder `prefers-reduced-transparency: reduce`, `sheet` and `overlay` become the opaque card colour with no blur, and `scrim` grows more opaque. Borders, shadows and layout stay put, and a browser without `backdrop-filter` gets the same fallback. Not every browser forwards the preference, so a product may offer its own setting. `Surface` alone answers `prefers-contrast: more` and `forced-colors: active`, in part, and forced colours still loses the scrim's dimming.\n\n## Performance budget [#performance-budget]\n\nAt most three translucent surfaces may show at once, and `overlay`, `scrim` and `sheet` together is the designed worst case. Never give a repeating element a translucent rung, never set `will-change: backdrop-filter`, and never animate the blur radius. Over budget, shrink or drop the surface, never the alpha.\n\n<Todo>\n  The budget of three is an engineering judgement. No device-lab frame-time measurement backs it yet.\n</Todo>\n\n## Layering [#layering]\n\nLayer decides which surface is in front, so a modal sits above a card because of its layer, not its blur. Each layer renders into a portal at the document root, in the order `base`, `sticky`, `raised`, `overlay`, `scrim`, `modal`, `notify` and `critical`. Layer names are not rung names.\n\n* Never cover the value a surface is about. A sheet opened from a result keeps the result visible above its edge, or restates it.\n* A modal traps focus, makes the page inert and returns focus to its trigger, which choosing `sheet` does not do for you. Never stack modals, and never let a toast take focus.\n* `critical` is reserved for an escalation the product's clinical governance says must never be covered. See [High-stakes moments](../health/high-stakes-moments.mdx).\n\nThe proposed `--opsin-layer-<name>` tokens are not generated yet.\n\n<NoDataYet script=\"scripts/build-tokens.mts\" />\n\n## Tokens [#tokens]\n\n<TokenTable scope=\"material\" />"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/foundations/motion",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/foundations/motion.md",
      "slug": [
        "foundations",
        "motion"
      ],
      "section": "Foundations",
      "title": "Motion",
      "description": "Springs as CSS tokens, motion chosen by the job it does, and a reduced-motion fallback declared token by token.",
      "kind": "foundation",
      "aliases": [
        "easing",
        "spring",
        "linear()",
        "transition",
        "stagger",
        "count-up",
        "prefers-reduced-motion",
        "haptics"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "Motion shows where things went, such as a sheet arriving from the row you tapped. It never celebrates, never carries urgency and never delays an answer. A new surface starts with none and gains it only when you can name what it explains.\n\n## Springs as tokens [#springs-as-tokens]\n\nA spring is authored in `tokens/motion.json` as stiffness, damping and mass, sampled into a CSS `linear()` easing, and emitted by `scripts/build-tokens.mts` as two custom properties, `--opsin-ease-<name>` and `--opsin-duration-<name>`. The duration is the computed settling time, so always use the pair together. A damping ratio below 1 overshoots.\n\n| Spring          | Overshoots | Use it for                                       |\n| --------------- | ---------- | ------------------------------------------------ |\n| `spring-snap`   | Yes        | Direct manipulation, such as a switch flipped    |\n| `spring-settle` | Yes        | Popovers, tooltips and menus                     |\n| `spring-calm`   | No         | A health value on screen moving to a new reading |\n| `spring-sheet`  | No         | Sheets, dialogs and full-screen pushes           |\n\nNever hand-write a `linear()` value or tune a spring inside a component. Change `tokens/motion.json` and regenerate.\n\n## Choosing by job [#choosing-by-job]\n\nA transition that does none of these five jobs probably should not exist.\n\n| Job        | Behaviour                                                   | Tokens                                                                                        |\n| ---------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------- |\n| Enter      | Decelerates into place                                      | `ease-enter` with `duration-base`, or `duration-slow` for a full-width or full-height surface |\n| Exit       | Accelerates, about two thirds as long as its enter          | `ease-exit` with `duration-fast`                                                              |\n| Feedback   | Acknowledges a touch on pointer-down and settles on release | `duration-instant` down, `spring-snap` back                                                   |\n| Navigation | The surface beneath recedes and dims                        | `spring-sheet`                                                                                |\n| Loading    | Loops, so it alone uses keyframes                           | `duration-shimmer`                                                                            |\n\nDuration follows distance, not importance, and `duration-deliberate` is the ceiling for anything a reader waits on. Use transitions wherever a reader can interrupt, because a transition reverses from wherever it is. Controls accept input while they animate.\n\n## Five interaction motions [#five-interaction-motions]\n\nEach is one job above, on the token kept for it, and built into the components listed. Try them, then again with reduced motion on.\n\n<ComponentPreview name=\"motion-the-five-interactions\" kind=\"example\" align=\"start\" minHeight=\"600\" />\n\n| Motion             | What moves                                                                      | Components                                                                  | Timing                                      | Under reduced motion                      |\n| ------------------ | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------- | ----------------------------------------- |\n| Press              | A capsule sinks to 0.97 and settles back                                        | Button, a button-shaped Link, the close controls on Dialog, Sheet and Toast | `duration-instant` down, `spring-snap` up   | One frame, no travel                      |\n| Press on a surface | A linked tile sinks to 0.98, with no overshoot                                  | Card, MetricTile                                                            | `duration-instant` down, `duration-fast` up | One frame, no travel                      |\n| Toggle             | The thumb squashes while held and travels, the tick draws itself, the dot grows | Switch, Checkbox, RadioGroup                                                | `spring-snap`                               | No squash, one frame                      |\n| Glide              | One puck or bar moves to the new choice                                         | SegmentedControl, Tabs                                                      | `spring-snap`                               | One frame                                 |\n| Unfold             | A popup grows from its anchor and comes into focus from a slight blur           | Popover, Menu, Select, Combobox, Tooltip                                    | `spring-settle` in, `ease-exit` out         | A short crossfade                         |\n| Arrive             | A toast rises from its edge, follows a swipe and leaves the way it was thrown   | Toast                                                                       | `spring-settle` in, `ease-exit` out         | A short fade, and the swipe still follows |\n\n* None of the five moves a value. A tile holding a reading never springs, and Value, RangeBar and ScoreDial stay still.\n* A link inside a sentence keeps its one-pixel press, because a word in running text should not change size.\n* Escape closes a popup at once, and a tooltip reached with Tab appears at once.\n\n## Health values [#health-values]\n\n* Motion never signals urgency, so nothing pulses, flashes or shakes. [Alerts](../health/alerts.mdx) owns that rule.\n* A health value appears at its final figure, with no count-up and no dial sweep.\n* No overshooting spring touches a measurement, range position, status or count, because for one frame it would show a number nobody measured. A value already on screen moves on `spring-calm`, and its digits are replaced in place rather than rolled.\n\n## Choreography [#choreography]\n\n* **Morph, do not swap.** A tile that opens into a detail view becomes that view, and its value never leaves the screen.\n* **Depth, not translation.** An arriving surface comes forward while the one beneath recedes and dims. Nothing slides sideways or pans the screen.\n* **One thing moves at a time.** Stagger only a list arriving, most important first and capped, and never re-stagger what is already on screen.\n* **Exits leave together.** Focus moves once, when the sequence ends.\n\n## Reduced motion [#reduced-motion]\n\nSix of the thirteen motion tokens declare a fallback, which `scripts/build-tokens.mts` emits inside `@media (prefers-reduced-motion: reduce)`. A fallback removes travel and keeps the cue that something changed.\n\n| Token                           | Under reduced motion                                   |\n| ------------------------------- | ------------------------------------------------------ |\n| `spring-snap`, `spring-calm`    | `linear` over `0ms`, so the end state arrives at once  |\n| `spring-settle`, `spring-sheet` | `linear`, as a cross-fade of about a tenth of a second |\n| `ease-standard`                 | `linear`                                               |\n| `duration-shimmer`              | Zero, so a skeleton stops sweeping                     |\n\n`ease-enter`, `ease-exit` and the five plain durations declare nothing, so a component built on them reduces itself inside the media query. A component that travels far also swaps the travel for opacity, as [Sheet](../components/sheet.mdx) does.\n\n<MotionDemo easing=\"--opsin-ease-spring-sheet\" duration=\"--opsin-duration-spring-sheet\" property=\"translate\" label=\"A sheet arriving, with and without the preference\" />\n\n<Todo>\n  Declare a fallback on the seven motion tokens that have none, then make `scripts/build-tokens.mts --check` fail when one is missing. What each becomes is a design decision nobody has taken.\n</Todo>\n\n## In practice [#in-practice]\n\nBase UI keeps a leaving element mounted and marks it with `data-starting-style` and `data-ending-style`, so one transition covers both directions.\n\n```css\n.sheet {\n  transition:\n    opacity var(--opsin-duration-spring-sheet) var(--opsin-ease-spring-sheet),\n    translate var(--opsin-duration-spring-sheet) var(--opsin-ease-spring-sheet);\n  opacity: 1;\n  translate: 0 0;\n}\n.sheet[data-starting-style],\n.sheet[data-ending-style] {\n  opacity: 0;\n  translate: 0 1rem;\n}\n```\n\nTransition `opacity`, `translate`, `scale` or `filter`, never `width`, `height`, `top` or `margin`. The exception is an absolutely positioned selection indicator, such as the SegmentedControl puck or the Tabs bar, which may transition its width and height because it reflows nothing. An exit does not run if you unmount the element yourself.\n\n## Sound and haptics [#sound-and-haptics]\n\n<NotBuiltYet />\n\nSound and haptics may reinforce a message already on screen in words, and never carry one alone. opsinjs ships neither. Safari on iOS does not implement the Web Vibration API, so opsinjs specifies three haptic patterns for a native shell to implement: `acknowledge` when a user-initiated action commits, `warn` when the product has decided its result needs attention, and `reject` when it is refused. Fire one per action, make no sound by default, let people turn haptics off in the product, and share the escalation budget of visual alerts.\n\n## Tokens [#tokens]\n\n<TokenTable scope=\"motion\" />"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/foundations/shape",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/foundations/shape.md",
      "slug": [
        "foundations",
        "shape"
      ],
      "section": "Foundations",
      "title": "Shape",
      "description": "A radius ladder derived from one value, concentric nesting, and squircle corners where the browser supports them.",
      "kind": "foundation",
      "aliases": [
        "corners",
        "border radius",
        "radius ladder",
        "concentric corners",
        "squircle",
        "corner-shape",
        "superellipse",
        "radius tokens"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "Shape decides how big a corner is and which curve draws it. It never carries meaning, so a rounder card is not a friendlier result.\n\n## Radius scale [#radius-scale]\n\nEvery rung is a fixed multiple of one root, `--opsin-radius-base`. Rungs are named for the object, not the size, and `rounded-opsin-<rung>` applies them.\n\n| Rung   | Use it for                                                                                                                                                                             |\n| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `none` | Full-bleed media and anything that meets a screen edge                                                                                                                                 |\n| `xs`   | Inline marks and small indicators, and the floor for a nested corner                                                                                                                   |\n| `sm`   | Small controls and a well inside a card                                                                                                                                                |\n| `md`   | The default for a bounded surface: [Card](../components/card.mdx), a tile, a callout, a field, a list row                                                                              |\n| `lg`   | A card nearly the width of a phone screen, and a banner                                                                                                                                |\n| `xl`   | Sheets and dialogs                                                                                                                                                                     |\n| `full` | Capsules and circles: a [Button](../components/button.mdx), a chip, a segmented control, a status pill. Use `rounded-full`, because a capsule is a different object, not a bigger rung |\n\n* Things a reader presses are capsules, and things a reader reads are squircles.\n* Match the rung to the object. When two adjacent rungs both seem right, take the smaller.\n* A different character is a change to the root in your theme, never to one component's radius.\n* Never square a corner for emphasis, and never animate a radius.\n\n## Nesting [#nesting]\n\nWhen one rounded box sits inside another, the inner radius is the outer radius minus the padding between them, and never less than `xs`.\n\n```text\ninner = max(outer - gap, radius-xs)\n```\n\nOnly this keeps the two curves parallel. An equal inner radius pinches the gap on the diagonal, and a larger one bulges. Compute it from tokens, since a hard-coded `8px` fits exactly one padding.\n\n## Squircle [#squircle]\n\nCard, [Dialog](../components/dialog.mdx), [Sheet](../components/sheet.mdx), [Callout](../components/callout.mdx), [Field](../components/field.mdx), [Accordion](../components/accordion.mdx), [MetricTile](../components/metric-tile.mdx), [ResultCard](../components/result-card.mdx) and [AlertBanner](../components/alert-banner.mdx) carry `[corner-shape:var(--opsin-corner-shape)]` beside their radius. The token holds `superellipse(2)`, the same curve as the CSS keyword `squircle`, which eases curvature into the straight edge instead of pinching where an arc meets it. The argument is a power of two, so `superellipse(4)`, which the token held until 2026-11, drew a nearly square corner. A browser without `corner-shape` drops the declaration and draws an ordinary rounded corner at the same radius, so no `@supports` guard is needed and nothing depends on it.\n\n* Opt in on surfaces the system draws, never on images, embeds or video.\n* Do not shrink the radius to compensate, or the nesting arithmetic differs between browsers.\n* Do not fake it with a clip path or an SVG mask, which clip focus rings and shadows.\n\n## Accessibility [#accessibility]\n\n* Small controls do not take large rungs, because a radius takes tappable area from the 44pt floor in [Space and layout](./space.mdx).\n* A parent with a smaller radius can clip a child's focus ring, so the ring is drawn outside the box with an offset.\n* Assistive technology announces no corner, which is why shape may not carry information.\n\nThis site's chrome takes the same shapes at desk density, so its sheets, capsules and focus rings follow the rules on this page.\n\n## Tokens [#tokens]\n\n<TokenTable scope=\"shape\" />"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/foundations/space",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/foundations/space.md",
      "slug": [
        "foundations",
        "space"
      ],
      "section": "Foundations",
      "title": "Space and layout",
      "description": "A 4px spacing scale, the 44pt touch floor, responsive modes, and the shell every screen sits in.",
      "kind": "foundation",
      "aliases": [
        "spacing",
        "4pt grid",
        "density",
        "touch target",
        "hit area",
        "breakpoints",
        "page shell",
        "safe area"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "opsinjs is roomy on purpose. Scrolling costs a reader a second, but a mis-tap logs a reading they did not take or dismisses an alert they did not read.\n\n## Spacing scale [#spacing-scale]\n\nThe scale is a 4px grid. Tailwind derives every spacing utility from `--spacing`, which the product theme sets to 0.25rem, so `p-4` is 16px. The fixed steps are `--opsin-space-*`, written `p-opsin-4`, and at the default density both spellings land on the same pixel.\n\n`[data-density=\"compact\"]` multiplies `--spacing` by 0.875, so `p-4` renders 14px and leaves the grid on purpose. Type size, the touch floor and the fixed steps do not move. [Card](../components/card.mdx) pads with the scaled `p-5`, and [Dialog](../components/dialog.mdx) with a fixed step that holds its inset. Use compact for dense lists, never for a screen's primary value.\n\n* Use a step, never a one-off value. A `13px` gap ignores density and breaks the nesting arithmetic in [Shape](./shape.mdx).\n* Group by proximity before reaching for a border. Gaps inside and between groups need two steps of difference to read as groups.\n* Never remove padding to make something fit. Cut the content or change the layout.\n* Steps are in rem, so space grows with the reader's text size.\n\n## Touch targets [#touch-targets]\n\nAnything a person taps is at least 44pt on both axes, measured on the interactive area rather than the visible box. The floor is `--opsin-target-minimum`, in rem so it grows with text. It sits above the 24 by 24 CSS pixels of WCAG 2.2 SC 2.5.8, and opsinjs does not use that criterion's spacing exception. The product theme backstops buttons and form controls with a minimum size, which is a safety net rather than a sizing method.\n\n* `--opsin-target-separation` is the minimum gap between targets whose visible boxes are smaller than the floor.\n* Controls with unequal consequences, such as save beside delete, sit further apart or not side by side.\n* Never stretch a hit area invisibly into a neighbour's space.\n* Anything behind a hover is also reachable on tap and on focus.\n* Primary actions sit low, where a thumb rests, and destructive ones do not. This is opinion informed by platform guidance.\n\n## Responsive modes [#responsive-modes]\n\nOn a wider screen nothing gets bigger. The reader sees more of the story at once: a reading beside its history, a list beside its detail, a sheet that becomes a pane.\n\n| May change with mode                   | Never changes                             |\n| -------------------------------------- | ----------------------------------------- |\n| Columns and regions                    | Body text size                            |\n| Whether a surface is a sheet or a pane | The touch floor and radius rungs          |\n| How much history and provenance shows  | The line-length cap                       |\n| The outer gutter                       | The meaning, order and wording of content |\n\nThe space tokens define `phone`, `tablet` and `wide` modes, each with its own `--opsin-gutter-*`. Prose stops at `--opsin-measure-comfortable` however wide the screen. Components query their container, never the viewport, so a tile in a narrow pane lays out as it would on a phone. Only the shell reads the viewport, because nothing sits above it.\n\nNothing may be reachable in only one mode, and DOM order never changes with mode. Design the narrowest mode first, then ask what did not fit.\n\n## Layout [#layout]\n\nThe shell has four regions, in DOM order:\n\n1. Header, with the screen's H1 and at most one secondary action.\n2. Content, one scrolling column.\n3. Action, the persistent primary action, pinned low but last in the DOM so focus reaches it after the content.\n4. Chrome, the tab bar, outside the screen's landmark.\n\nAdd the `--opsin-safe-*` insets to the gutter at screen edges, and to a fixed action bar's padding rather than its height. Keep the action region and a focused field above the on-screen keyboard.\n\nAn overview screen is a heading, a run of tiles that each carry their own status and freshness, and a persistent action, with a ceiling on urgent surfaces set by [Alerts](../health/alerts.mdx). A reading screen puts the value with its unit, status and range first, then what it means, what to do, when it was taken and its history. Nothing covers the value, and it sits above the fold on the smallest supported screen.\n\n## Tokens [#tokens]\n\n<TokenTable scope=\"space\" />"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/foundations/states",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/foundations/states.md",
      "slug": [
        "foundations",
        "states"
      ],
      "section": "Foundations",
      "title": "States",
      "description": "The six interaction states every control shows, and the five data states every surface that displays a value must render.",
      "kind": "foundation",
      "aliases": [
        "hover",
        "pressed",
        "focus-visible",
        "disabled",
        "busy",
        "stale data"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "Interaction states say what you are doing to a control. Data states say what the system knows about the value inside it. A button can be hovered but never stale, and a reading can be stale but never hovered.\n\n## Interaction states [#interaction-states]\n\nEvery interactive component must implement all six, or its page must say why not.\n\n| State    | Rule                                                                                                                                                                    |\n| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Hover    | Pointer only, so never the only signal. A small lightness step, darker in the light theme and lighter in the dark                                                       |\n| Press    | Applied on pointer-down, not on click, on `duration-instant`, and released on `spring-snap`, or on `duration-fast` where the control holds a reading                    |\n| Focus    | `:focus-visible` only. An offset outline outside the box, in one system-wide colour, so it never moves layout or gets clipped                                           |\n| Selected | Persistent and distinct from focus. A fill and a mark, never a fill alone                                                                                               |\n| Disabled | Dimmed, with no pointer affordance, but readable. It leaves the tab order, so state the reason where a keyboard user will find it                                       |\n| Busy     | Keeps its label and tab stop and refuses activation, without becoming `disabled`. [Button](../components/button.mdx)'s `busy` prop sets `aria-busy` and `aria-disabled` |\n\nStates resolve in a fixed order: disabled, busy, pressed, selected, focus, hover. A pressed control keeps its focus ring, and a disabled control never looks hoverable.\n\n* Never author a state colour. Hover and press come from shared fills.\n* A state is never a verdict. A tapped result card may darken, but it never takes a [status colour](../health/two-colour-axes.mdx).\n* When a control becomes disabled or disappears, focus moves somewhere documented, never to the document body.\n\nPress is implemented on Button and [Link](../components/link.mdx), and every component built from them inherits it. It is also on a linked Card and MetricTile, and on the close controls of [Dialog](../components/dialog.mdx), [Sheet](../components/sheet.mdx) and [Toast](../components/toast.mdx). [Motion](./motion.mdx) sets out how it moves.\n\nDerived state values and their measured contrast are not generated yet.\n\n<NoDataYet script=\"scripts/build-tokens.mts\" />\n\n## Data states [#data-states]\n\nEvery surface that shows a value must render five data states, so that a blank, a `--` or a zero never stands in for a value nobody knows. A surface shows the first state below that applies.\n\n| State   | Means                           | Render                                                                                                                                     |\n| ------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |\n| Error   | The system tried and failed     | [EmptyState](../components/empty-state.mdx) with `reason=\"could-not-load\"`, a neutral word and icon with a retry or a route onwards        |\n| Loading | The system is trying            | A [Skeleton](../components/skeleton.mdx) in the final layout, with no placeholder digits or plausible chart                                |\n| Empty   | There is genuinely nothing      | EmptyState naming what would appear here, with one next action                                                                             |\n| Partial | Only some of the window arrived | The value with its coverage, such as four of seven days, or EmptyState with `reason=\"not-enough\"`                                          |\n| Stale   | Real but old                    | The value with its age and a refresh route, keeping its status colour. [MetricTile](../components/metric-tile.mdx) takes `staleAfterHours` |\n\n* Every state carries a word, and the state itself never takes a status colour.\n* Never average across a gap without saying so.\n* The product's clinical governance sets when a value turns stale ([Trends and uncertainty](../health/trends.mdx)), and the product sets how long loading runs before saying what it waits for. opsinjs renders the state, never the number.\n* Announce each change once. Skeletons are hidden from assistive technology, and stale and partial belong in the accessible name.\n\n<Todo>\n  No surface takes a state input or emits `data-state`, and nothing accepts the `DataState` type in `lib/opsinjs.ts` yet. Wire the five states from separate parts, and select on the words a surface renders.\n</Todo>"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/foundations/typography",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/foundations/typography.md",
      "slug": [
        "foundations",
        "typography"
      ],
      "section": "Foundations",
      "title": "Typography",
      "description": "The platform UI font, a type scale named for jobs rather than sizes, and the reader's own text size.",
      "kind": "foundation",
      "aliases": [
        "font",
        "system-ui",
        "typeface",
        "text styles",
        "type ramp",
        "tabular numerals",
        "dynamic type",
        "font scaling"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "opsinjs ships no typeface. The product theme's `--font-sans` starts with `ui-sans-serif, system-ui`, so the device answers: SF Pro on an iPhone, Roboto on Android, Segoe UI Variable on Windows.\n\n## Why the system font [#why-the-system-font]\n\n* It is the font the reader already reads, tuned for the screen in their hand.\n* Bold text, larger accessibility sizes and the platform's text-size controls apply to the system font.\n* It never loads, so text never flashes or waits.\n* SF Pro cannot be served as a webfont, because Apple licenses it for Apple platforms and not for redistribution. Read Apple's licence yourself. `system-ui` reaches the copy already installed.\n\nA brand face is an opt-in through `--font-sans`.\n\n## Type scale [#type-scale]\n\nRoles are named for their job, not their size. Each sets size, line height, tracking and weight, and `text-opsin-<role>` applies it.\n\n| Role          | Use it for                                                                                                          |\n| ------------- | ------------------------------------------------------------------------------------------------------------------- |\n| `large-title` | One number or word that is a surface's whole subject. No component uses it yet                                      |\n| `title1`      | A screen title, and the display number in [Value](../components/value.mdx)                                          |\n| `title2`      | A section title, and the floor for a primary health value in a card                                                 |\n| `title3`      | A [Dialog](../components/dialog.mdx) or [Sheet](../components/sheet.mdx) title, and the unit beside a display value |\n| `headline`    | A card title or an emphasised lead line, at body size and heavier                                                   |\n| `body`        | Default reading text, at 17px                                                                                       |\n| `callout`     | Secondary prose in a dense container                                                                                |\n| `subheadline` | The label beside a value. `subheadline-emphasis` is its heavier twin for a compact control                          |\n| `footnote`    | Provenance: who measured this, when, with what                                                                      |\n| `caption1`    | Axis labels, legends and legal text                                                                                 |\n| `caption2`    | The floor, only for text that repeats a label shown elsewhere                                                       |\n\n* Pick the role, never the size, and default to `body`.\n* Set a health value at `title2` or larger, and never below `body`.\n* A role is not a heading level. Choose `h2` from the page outline and the role from how it should look.\n* Use two weights, three at most. Size and weight show hierarchy, never status.\n* Nothing is smaller than `caption2`. If text does not fit, change the layout.\n\n## Tabular figures [#tabular-figures]\n\nThe product theme sets `font-variant-numeric: tabular-nums` on anything carrying `data-opsinjs-value`, so a changing reading does not shift the layout. The role does not set tabular figures, and `font-opsin-numeric` sets only the family. A resting heart rate is `62` in `title1` with the attribute, `bpm` in `title3`, the label in `subheadline` and \"Measured 3 hours ago\" in `footnote`.\n\n## Text size [#text-size]\n\nEvery component must survive a 1.3× text multiplier with no clipping, truncation, overlap or horizontal scroll, and the system must stay usable at 200%. Every role is in `rem` and the multiplier is applied once at the root, so the reader's setting reaches every step. A single `px` font size opts that element out. Check with the text-size switch on any component preview.\n\nFive layout habits break first:\n\n* Fixed heights. Use a minimum height and let content decide.\n* `white-space: nowrap` and ellipses. Never truncate a value, a unit or a status word.\n* Label and value pairs forced side by side. Stack them with a container query.\n* Icons sized in px beside text. Size them in `em`.\n* Sticky headers and action bars. Let them collapse.\n\nNever disable text scaling with a viewport meta tag, a fixed px size on the root or `text-size-adjust: none`. Set `lang` on the document, because hyphenation and screen-reader pronunciation depend on it.\n\n## Tokens [#tokens]\n\n<TokenTable scope=\"type\" />"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/foundations/writing",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/foundations/writing.md",
      "slug": [
        "foundations",
        "writing"
      ],
      "section": "Foundations",
      "title": "Writing",
      "description": "How a product built on opsinjs sounds, and the rules every string follows.",
      "kind": "foundation",
      "aliases": [],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "Copy is part of the component. A [StatusPill](../components/status-pill.mdx) with the wrong word is as broken as one with the wrong colour. Five rules cover every string:\n\n1. **Answer first.**\n2. **Use the reader's words**, from [Plain English A to Z](../reference/plain-english.mdx).\n3. **Claim no more certainty than the data has.**\n4. **Match the tone to the status level, not the brand.**\n5. **Never say what a result means clinically.** Describe it and say who can interpret it.\n\nThe writing rules here are our judgement, not findings from a study.\n\n## Voice and tone [#voice-and-tone]\n\nThe voice is calm, plain and in the second person. The tone follows the [status level](../health/two-colour-axes.mdx).\n\n* `steady` states the fact and stops.\n* `watch` gives the comparison and what would make it matter, with no imperative.\n* `attention` gives the fact, one action, then a true reassurance if there is one.\n* `urgent` puts the action first, with no brand voice and no hedging.\n\nNever celebrate a health number.\n\n## Health literacy [#health-literacy]\n\n* Give the comparison with the figure: \"72 bpm, within your usual range of 58 to 76\".\n* Never make the reader do arithmetic.\n* Assume interruption. Each paragraph must stand alone.\n* Give risk as natural frequencies, such as \"about 3 in every 100 people\", never as a bare percentage the reader must act on.\n\nAim no higher than a reading age of about 9 to 11, except in `urgent` copy. Treat a readability score as a smoke alarm. Fix the sentence, not the score.\n\n<Todo>\n  Add a readability pass to `pnpm run check` that reports each page's longest sentence. Publish no reading-level score until it has run.\n</Todo>\n\n## Grammar and mechanics [#grammar-and-mechanics]\n\n* Sentence case everywhere. No full stop on a label or heading. No exclamation marks, em dashes, en dashes or Latin abbreviations.\n* Expand an abbreviation on first use on each screen, and never abbreviate in a notification or alert.\n* Status words come verbatim from `CLINICAL_STATUS_META` in `lib/status.ts`: Steady, Watch, Needs attention, Urgent and Not known.\n\n## Numbers, dates and time [#numbers-dates-and-time]\n\n[Numbers and units](../health/numbers.mdx) owns precision, rounding and units. Use relative time only within a day, and never alone in an export, a printout or a notification.\n\n| Write                               | Not                   |\n| ----------------------------------- | --------------------- |\n| Your usual range is 90 to 120 mmHg. | Normal range: 90-120. |\n| 14 March 2026 at 08:12              | 14/03/2026            |\n| Taken 2 hours ago (today at 08:12)  | Taken 2 hours ago     |\n\n## Alt text [#alt-text]\n\nDescribe the answer, not the picture. Describe a [ScoreDial](../components/score-dial.mdx) by its number and comparison, never as \"a needle in the amber zone\". Give an accessible name, a caption with the window and source, and a table twin for a chart. [Data visualisation](./data-visualisation.mdx) requires the twin, and no chart in the registry ships one yet. Never interpret. A decorative image takes `alt=\"\"`.\n\n## Status and alerts [#status-and-alerts]\n\nThe level and the wording never disagree. If the sentence needs to be stronger, the level is wrong. [Alerts](../health/alerts.mdx) caps a screen at one `urgent` surface.\n\nBad news goes first, says what it is rather than what it might be, and gives one next step. Never wrap it in praise or call a result nothing to worry about. A push notification never shows the value. Emergency wording is on [High-stakes moments](../health/high-stakes-moments.mdx).\n\n| Write                                                                                                                   | Not                                                                          |\n| ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |\n| Your reading was 152 over 96. That is higher than the range your GP set for you. Take another reading tomorrow morning. | Warning! Elevated blood pressure detected. This could indicate hypertension. |\n| Call 999 now. Tell them you have chest pain.                                                                            | We'd recommend seeking urgent medical attention as soon as possible.         |\n\n## Sensitive questions [#sensitive-questions]\n\n* Say why you are asking, in one clause beside the question.\n* Write \"optional\" or \"required\" on the label, never an asterisk.\n* Offer \"Prefer not to say\" and store it apart from \"Not answered\".\n* Never challenge a refusal with \"Are you sure?\".\n\nRead [High-stakes moments](../health/high-stakes-moments.mdx) before asking about mood, self-harm or safety at home. [Ask users for…](../patterns/ask-users-for.mdx) covers each kind of detail.\n\n## Errors and empty states [#errors-and-empty-states]\n\nSay what happened, whether the reader's data is safe, and what to do next. A stale value says so beside the value, never only in a toast. Name each [data state](./states.mdx) in words.\n\n| Write                                                                                   | Not                                           |\n| --------------------------------------------------------------------------------------- | --------------------------------------------- |\n| We could not save your reading. Your numbers are still here. Try again.                 | Something went wrong. Please try again later. |\n| These readings were last updated on 12 March at 07:40. We could not get anything newer. | Offline                                       |\n\n## Inclusive language [#inclusive-language]\n\n* Write \"people with diabetes\" and \"lives with\", not \"diabetics\" and \"suffers from\". Follow a community's preference for identity-first language.\n* Assume no default household: \"a partner or someone who helps you\".\n* Ask for sex assigned at birth only where a measurement uses it, and about gender separately.\n* State the measurement, never a verdict on a body.\n\n## Localisation [#localisation]\n\n* Pass `locale` to [Value](../components/value.mdx), [RelativeTime](../components/relative-time.mdx) and [RangeBar](../components/range-bar.mdx). Without it, the server's locale formats the first paint.\n* Use CSS logical properties. Never join translated fragments into a sentence.\n* Never translate a unit symbol or a medicine name.\n* Status words ship in English. A translation passed to StatusPill's `label` keeps the levels' order, carries no verdict, and is reviewed by someone who understands the clinical intent.\n\n## Words to avoid [#words-to-avoid]\n\n| Avoid                       | Use instead                                   |\n| --------------------------- | --------------------------------------------- |\n| normal, abnormal            | in your usual range, outside your usual range |\n| elevated, reduced           | higher than, lower than                       |\n| could indicate, may suggest | the reading, and who can interpret it         |\n| critical, emergency         | only at `urgent`                              |"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components.md",
      "slug": [
        "components"
      ],
      "section": "Components",
      "title": "Components",
      "description": "Sixty components in twelve categories, each installed as source you own.",
      "kind": "guide",
      "aliases": [],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "Every component is `shipped`, which means its source installs and renders and its API may change in any release. Each was audited against WCAG 2.2 AA by its own authors. None has had an independent accessibility review or a clinical review, so none is ready for a production health surface.\n\n## Install [#install]\n\n```bash\nnpx shadcn@latest add @opsinjs/<name>\n```\n\nThe CLI copies the component's source and the opsinjs `lib/` files it reads into your project, and adds its npm dependencies. `<name>` is the id in each link below. Add the `@opsinjs` entry to `components.json` first, as [Getting started](../getting-started.mdx) shows.\n\n## Usage [#usage]\n\n```tsx\nimport { Button } from \"@/components/ui/button\"\n```\n\n```tsx\n<Button variant=\"primary\" onClick={save}>\n  Save reading\n</Button>\n```\n\nThe import path follows the `ui` alias in `components.json`.\n\n## Health data display [#health-data-display]\n\n| Component                               | Use it for                              |\n| --------------------------------------- | --------------------------------------- |\n| [ResultCard](./result-card.mdx)         | One test result in full                 |\n| [RangeBar](./range-bar.mdx)             | One reading against its range           |\n| [ScoreDial](./score-dial.mdx)           | A composite score and its band          |\n| [TrendSparkline](./trend-sparkline.mdx) | One measurement over time               |\n| [MetricTile](./metric-tile.mdx)         | One reading at a glance                 |\n| [StatusPill](./status-pill.mdx)         | A status your product assigned          |\n| [RangeLegend](./range-legend.mdx)       | The key to a RangeBar's tones           |\n| [TimelineEntry](./timeline-entry.mdx)   | One dated event in a history            |\n| [GoalRing](./goal-ring.mdx)             | Progress towards a goal the product set |\n\n## Health communication [#health-communication]\n\n| Component                               | Use it for                          |\n| --------------------------------------- | ----------------------------------- |\n| [AlertBanner](./alert-banner.mdx)       | Something the reader must know now  |\n| [CareCard](./care-card.mdx)             | One instruction at a stated urgency |\n| [Term](./term.mdx)                      | A clinical word, explained          |\n| [ConsentSheet](./consent-sheet.mdx)     | Asking permission for one thing     |\n| [DisclaimerNote](./disclaimer-note.mdx) | The not-medical-advice note         |\n| [SourceCitation](./source-citation.mdx) | Where health information came from  |\n\n## Health input [#health-input]\n\n| Component                             | Use it for                             |\n| ------------------------------------- | -------------------------------------- |\n| [LogSheet](./log-sheet.mdx)           | Recording one reading, dose or note    |\n| [ReadingInput](./reading-input.mdx)   | Typing a measurement with its unit     |\n| [BodyMap](./body-map.mdx)             | Pointing at a body region              |\n| [ScaleInput](./scale-input.mdx)       | A self-report on the product's scale   |\n| [DoseTracker](./dose-tracker.mdx)     | Doses already logged, shown as facts   |\n| [Questionnaire](./questionnaire.mdx)  | The product's questions, with progress |\n| [SymptomPicker](./symptom-picker.mdx) | Symptoms from the product's list       |\n\n## Health formatting [#health-formatting]\n\n| Component                           | Use it for               |\n| ----------------------------------- | ------------------------ |\n| [Value](./value.mdx)                | Any number with its unit |\n| [RelativeTime](./relative-time.mdx) | When something happened  |\n\n## Actions and forms [#actions-and-forms]\n\n| Component                         | Use it for                          |\n| --------------------------------- | ----------------------------------- |\n| [Button](./button.mdx)            | An action the reader presses        |\n| [Link](./link.mdx)                | Going somewhere else                |\n| [Field](./field.mdx)              | Label, hint and error for any input |\n| [IconButton](./icon-button.mdx)   | An icon-only action                 |\n| [Switch](./switch.mdx)            | A setting that applies at once      |\n| [Checkbox](./checkbox.mdx)        | One option ticked on or off         |\n| [RadioGroup](./radio-group.mdx)   | One choice from a short list        |\n| [Select](./select.mdx)            | One choice from a long list         |\n| [NumberField](./number-field.mdx) | A non-clinical count with steppers  |\n| [Textarea](./textarea.mdx)        | A free-text note                    |\n| [Slider](./slider.mdx)            | A coarse, non-clinical preference   |\n| [Combobox](./combobox.mdx)        | Typing to narrow a long list        |\n\n## Navigation [#navigation]\n\n| Component                                   | Use it for                        |\n| ------------------------------------------- | --------------------------------- |\n| [SegmentedControl](./segmented-control.mdx) | Switching between a few views     |\n| [TabBar](./tab-bar.mdx)                     | Top-level destinations on a phone |\n| [Stepper](./stepper.mdx)                    | Where the reader is in a sequence |\n| [Tabs](./tabs.mdx)                          | Panels that share one region      |\n| [Accordion](./accordion.mdx)                | Sections that expand and collapse |\n\n## Surfaces [#surfaces]\n\n| Component                | Use it for                             |\n| ------------------------ | -------------------------------------- |\n| [Surface](./surface.mdx) | The layer under every panel and card   |\n| [Card](./card.mdx)       | A bordered group of related content    |\n| [Sheet](./sheet.mdx)     | A panel that slides up                 |\n| [Dialog](./dialog.mdx)   | A question that must be answered first |\n\n## Feedback [#feedback]\n\n| Component                       | Use it for                         |\n| ------------------------------- | ---------------------------------- |\n| [Callout](./callout.mdx)        | A note, tip or caveat              |\n| [EmptyState](./empty-state.mdx) | A screen with nothing on it yet    |\n| [Skeleton](./skeleton.mdx)      | The shape of content still loading |\n| [Toast](./toast.mdx)            | Confirming the reader's own action |\n| [Progress](./progress.mdx)      | How far through a task             |\n| [Spinner](./spinner.mdx)        | A brief wait of unknown shape      |\n\n## Overlay [#overlay]\n\n| Component                | Use it for                            |\n| ------------------------ | ------------------------------------- |\n| [Tooltip](./tooltip.mdx) | A label the reader can do without     |\n| [Popover](./popover.mdx) | A small panel anchored to its control |\n| [Menu](./menu.mdx)       | Actions opened from a button          |\n\n## Data display [#data-display]\n\n| Component            | Use it for                            |\n| -------------------- | ------------------------------------- |\n| [Table](./table.mdx) | Rows and columns, and a chart's twin  |\n| [Badge](./badge.mdx) | A neutral count or word, never status |\n\n## Layout [#layout]\n\n| Component                       | Use it for                       |\n| ------------------------------- | -------------------------------- |\n| [Divider](./divider.mdx)        | A hairline between two groups    |\n| [ScrollArea](./scroll-area.mdx) | Scrolling inside a card or panel |\n\n## Utility [#utility]\n\n| Component                               | Use it for                        |\n| --------------------------------------- | --------------------------------- |\n| [Avatar](./avatar.mdx)                  | A person's picture or initials    |\n| [VisuallyHidden](./visually-hidden.mdx) | Text only screen readers announce |\n\n## Choosing a component [#choosing-a-component]\n\nStart from your data, and from who assigned any status it carries.\n\n* A measurement the reader interprets is a ResultCard, or a RangeBar when its place in the range is the point. A MetricTile that needs interpreting is a ResultCard at the wrong size.\n* A ScoreDial implies a composite index, so it never shows a single measurement.\n* Status appears only where a rule your product owns assigned it, and no component computes one. A category, a trend or a position against a range is not a status. See [Two colour axes](../health/two-colour-axes.mdx).\n* Allow at most one urgent surface per screen. See [Alerts](../health/alerts.mdx).\n* Decide what each component renders in all five data states: empty, loading, error, stale and partial. See [States](../foundations/states.mdx).\n\n<Todo>\n  A rule for choosing between input components. Until then, read each component's page.\n</Todo>\n\n## Bundle size [#bundle-size]\n\nYou copy source, so you ship only what you import. Per-component sizes are not measured yet. The limit more likely to bite is the budget of three overlapping composited surfaces in [Materials](../foundations/materials.mdx).\n\n<NoDataYet script=\"scripts/build-registry.mts\" />"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/accordion",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/accordion.md",
      "slug": [
        "components",
        "accordion"
      ],
      "section": "Components",
      "title": "Accordion",
      "description": "Sections that expand and collapse, one or several at a time, built on Base UI Accordion.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "disclosure",
        "expander",
        "collapsible"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"accordion\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;Nothing a reader must not miss may live in a collapsed panel, but the wrapper cannot read its content, so a folded safety message passes every automated gate.&#x22;,\n  &#x22;Nobody has listened to it in a screen reader, so whether a section opens cleanly and the h3 level suits the host page is unheard.&#x22;,\n  &#x22;No contrast pair has been measured, and forced-colors, prefers-contrast: more and the panel's reduced-motion mount are untested beyond the product stylesheet.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"accordion\" unbuilt=\"false\" importPath=\"@/components/ui/accordion\" dependencies=\"[&#x22;@base-ui/react&#x22;, &#x22;lucide-react&#x22;]\" />\n\n```tsx\nimport { Accordion } from \"@/components/ui/accordion\"\n```\n\n```tsx\n<Accordion\n  items={[\n    { value: \"hours\", title: \"When can I reach the team?\", content: \"Weekday mornings.\" },\n    { value: \"records\", title: \"Where are my notes kept?\", content: \"On your device.\" },\n  ]}\n/>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"accordion\" />\n\n### A frequently asked list [#a-frequently-asked-list]\n\nThree headers form an index; the reader opens one. Fictional copy.\n\n<ComponentPreview name=\"accordion-frequently-asked\" kind=\"example\" align=\"start\" />\n\n### One section open at a time [#one-section-open-at-a-time]\n\nWith `multiple` off (the default), opening one section closes the last.\n\n<ComponentPreview name=\"accordion-one-open-at-a-time\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;An index of related sections a reader scans first and opens one at a time, such as questions and answers.&#x22;,\n  &#x22;Detail a reader wants on demand but not on arrival, such as small print under a summary.&#x22;,\n  &#x22;Several independent groups of settings on one small screen, opened together with multiple.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;A safety message, an urgent instruction or anything a reader must not miss. A collapsed panel may never be opened.&#x22;, instead: &#x22;callout&#x22; },\n  { case: &#x22;Content that must always be visible, not behind a header a reader has to press.&#x22;, instead: &#x22;card&#x22; },\n  { case: &#x22;Choosing a header should swap the whole view for another in the same space, not reveal detail in place.&#x22;, instead: &#x22;tabs&#x22; },\n]\"\n/>\n\n## Accessibility [#accessibility]\n\nAxe, target-size, focus-visible and 320px reflow checks were clean. Base UI\nrenders each header as an `h3` with a `button`, wires `aria-expanded` and\n`aria-controls` between trigger and panel, and hides the chevron with\n`aria-hidden`, so a reader relies on `aria-expanded`, not the glyph. The\nchevron's turn uses `--opsin-duration-fast`, collapsed under\n`prefers-reduced-motion`, and a closed panel is unmounted, leaving the tab order.\nThe audit fixed one SC 2.4.7 defect: the trigger's focus ring was drawn outside\nthe trigger, where the root's `overflow-hidden` clipped it, and it now renders\ninside, whole on every straight edge.\n\n**Residual items.**\n\n* A small notch of the focus ring is still clipped at the first and last sections' outer corners.\n* Every contrast pair against the card surface is unmeasured, not known-failing.\n* That no must-see content may sit in a closed panel stays a docs contract the wrapper cannot enforce.\n\n<KeyboardTable\n  name=\"accordion\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves focus to the next header&#x22;,\n    notes: &#x22;An ordinary tab stop. A disabled header keeps its stop.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Moves focus to the previous header&#x22;,\n    notes: &#x22;The same in reverse.&#x22;,\n  },\n  {\n    keys: &#x22;Enter, Space&#x22;,\n    action: &#x22;Opens or closes the focused section&#x22;,\n    notes: &#x22;A native button. With multiple off, the open section closes.&#x22;,\n  },\n  {\n    keys: &#x22;Arrow keys&#x22;,\n    action: &#x22;Not bound&#x22;,\n    notes: &#x22;Base UI follows the updated APG guidance, which dropped roving focus.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"accordion\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"AccordionProps\" />\n\n`multiple` defaults to `false`. `value` without `onValueChange` fixes the open\nsections as given. An empty `items` array renders nothing and warns in\ndevelopment, as does a duplicated `value`.\n\n### Data attributes [#data-attributes]\n\n<DataAttributesTable\n  name=\"accordion\"\n  rows=\"[\n  {\n    attribute: &#x22;data-slot&#x22;,\n    condition: &#x22;On the root and each part&#x22;,\n    value: &#x22;accordion, accordion-item, accordion-header, accordion-trigger, accordion-title, accordion-panel&#x22;,\n  },\n  {\n    attribute: &#x22;data-open&#x22;,\n    condition: &#x22;On the item and the panel&#x22;,\n    value: &#x22;Present while expanded&#x22;,\n  },\n  {\n    attribute: &#x22;data-panel-open&#x22;,\n    condition: &#x22;On the trigger&#x22;,\n    value: &#x22;Present while its section is open&#x22;,\n  },\n  {\n    attribute: &#x22;data-disabled&#x22;,\n    condition: &#x22;On the item and its trigger&#x22;,\n    value: &#x22;Present while disabled&#x22;,\n  },\n]\"\n/>"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/alert-banner",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/alert-banner.md",
      "slug": [
        "components",
        "alert-banner"
      ],
      "section": "Components",
      "title": "AlertBanner",
      "description": "A message that appears at the top of a screen because something needs your attention now, saying what has happened and what to do about it.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "warning",
        "notification",
        "alert",
        "banner",
        "warning banner",
        "notification banner",
        "inline alert"
      ],
      "implements": [],
      "governedBy": [
        "two-colour-axes",
        "alerts",
        "high-stakes-moments",
        "safety-review"
      ],
      "usedIn": [
        "alert-escalation",
        "offline-and-stale-data"
      ],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"alert-banner\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;The budget of one urgent banner and two per screen is not enforced at runtime, because a banner only sees itself.&#x22;,\n  &#x22;Nobody has listened in a screen reader: whether a heading survives navigation inside role=\\&#x22;alert\\&#x22;, and what in-place escalation announces, are untested.&#x22;,\n  &#x22;`steady` is legal for de-escalation, yet a banner that can say nothing needs attention is one products will reach for to be noticed.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"alert-banner\" unbuilt=\"false\" importPath=\"@/components/ui/alert-banner\" registryDependencies=\"[&#x22;status-pill&#x22;, &#x22;button&#x22;, &#x22;link&#x22;]\" />\n\n```tsx\nimport { AlertBanner } from \"@/components/ui/alert-banner\"\n```\n\n```tsx\n<AlertBanner\n  status=\"attention\"\n  heading=\"Your example measurement is outside the range your clinic set\"\n  detectedAt=\"2026-03-14T09:40:00+00:00\"\n  actions={[\n    { label: \"Contact your clinic\", href: \"/clinic\" },\n    { label: \"See the reading and the range\", href: \"/results/example\" },\n  ]}\n>\n  Contact your clinic before your next appointment. This reading is outside the range they\n  asked us to tell you about.\n</AlertBanner>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"alert-banner\" />\n\nThe banner is a sheet tinted by its level. The recommended action is filled with the level's\nown ink and labelled in its surface colour, the measured ink pair turned inside out, and the\nsecond action and the dismiss control are outlined. All four levels take the same treatment.\n\n### Two is the ceiling [#two-is-the-ceiling]\n\nTwo banners, the more serious first, because a reader meets them in DOM order.\n\n<ComponentPreview name=\"alert-banner-two-is-the-ceiling\" kind=\"example\" align=\"start\" />\n\n### An urgent banner is acknowledged, not dismissed [#an-urgent-banner-is-acknowledged-not-dismissed]\n\n`dismissible` renders nothing without `onAcknowledge`, which at `urgent` is the record, and\nremoving the banner drops focus to `<body>`, which the product must recover. One action,\nbecause the route is same-day.\n\n<ComponentPreview name=\"alert-banner-acknowledging-an-urgent-banner\" kind=\"example\" align=\"start\" />\n\n### `steady` is for de-escalation [#steady-is-for-de-escalation]\n\nThe one honest use of the quietest level: withdrawing an alert the product raised earlier.\nNo `actions`, because only `attention` and `urgent` require one.\n\n<ComponentPreview name=\"alert-banner-steady-is-for-de-escalation\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;Something has changed since the reader last looked, and they need to know before carrying on.&#x22;,\n  &#x22;A reading has crossed a threshold the product owns, with a specific action attached.&#x22;,\n  &#x22;A condition affects the whole screen: stale data, a disconnected device, an unfinished sync.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;Information the reader can take or leave, where nothing changes if they do not read it.&#x22;, instead: &#x22;callout&#x22; },\n  { case: &#x22;The status belongs to one result, not the screen.&#x22;, instead: &#x22;status-pill&#x22; },\n  { case: &#x22;The content is an instruction with steps and timing, not an announcement.&#x22;, instead: &#x22;care-card&#x22; },\n  { case: &#x22;The reader must respond before anything else can happen.&#x22;, instead: &#x22;dialog&#x22; },\n  { case: &#x22;Someone has disclosed thoughts of self-harm or suicide, which is not the status axis. See Crisis and self-harm.&#x22;, instead: &#x22;care-card&#x22; },\n]\"\n/>\n\n## Clinical meaning [#clinical-meaning]\n\n**Asserts.** That the product has decided this screen needs the reader's attention at one\nof four levels, with something specific to do at `attention` and `urgent`. The component\ncompares nothing: `status` is assigned from a range the product owns.\n\n**Never read as.** A clinical judgement about the reader, an instruction from a person, or\na substitute for emergency services. A finding routed *stop and call for help now* leaves\nthe banner. See [High-stakes moments](../health/high-stakes-moments.mdx).\n\n**Colour axis.** Status only, with no `category` prop, so a banner never carries category\ncolour. Urgency is never carried by motion either, and no transition ships. See\n[Alerts](../health/alerts.mdx).\n\n**Thresholds.** None. No staleness default and no number in the component. The level's\nword comes from the composed [StatusPill](./status-pill.mdx), never from `heading`.\n\n**Budget.** At most one `urgent` banner and two per screen, per\n[Alerts](../health/alerts.mdx), and the component cannot count across a screen. No live\nregion mounts at `steady` or `watch`, a named departure from\n[Two colour axes](../health/two-colour-axes.mdx) rule 9.\n\n<SafetyCallout severity=\"urgent\" evidence=\"opinion\">\n  An `urgent` banner must never be the only place a serious message appears, and never\n  dismissible without an acknowledgement the product records.\n</SafetyCallout>\n\n## Accessibility [#accessibility]\n\nConfirmed: colour never carries meaning alone, because the word and glyph come from the\ncomposed [StatusPill](./status-pill.mdx) and shape and position separate the levels. The\nlive region wraps only the heading and body, `role=\"alert\"` at `urgent` and\n`aria-live=\"polite\"` with `aria-atomic` at `attention`. Focus never moves, every control\nclears the 44pt floor, axe and focus-visible checks were clean, and the audit changed\nnothing.\n\n**Residual items.**\n\n* At `steady` and `watch` no live region mounts, so a de-escalation banner inserted after\n  a condition resolves is not announced to a reader already on the page. That is a\n  deliberate departure from [Two colour axes](../health/two-colour-axes.mdx) rule 9 on\n  alarm-fatigue grounds, a doctrine call left for a human reviewer.\n* Escalating in place relies on the caller passing `key={status}` to remount, which the\n  component cannot enforce.\n* Still ungated: any real screen reader, `forced-colors`, and the root's missing\n  accessible name.\n\n<KeyboardTable\n  name=\"alert-banner\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves through the actions, then dismiss&#x22;,\n    notes: &#x22;The banner itself is not a tab stop.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;The same in reverse&#x22;,\n  },\n  {\n    keys: &#x22;Enter&#x22;,\n    action: &#x22;Follows a link action or activates a button&#x22;,\n    notes: &#x22;href renders an anchor, onSelect a real button.&#x22;,\n  },\n  {\n    keys: &#x22;Space&#x22;,\n    action: &#x22;Activates a button action or the dismiss&#x22;,\n    notes: &#x22;On a link action Space scrolls the page.&#x22;,\n  },\n  {\n    keys: &#x22;Escape&#x22;,\n    action: &#x22;Nothing&#x22;,\n    notes: &#x22;The dismiss control is the only way out.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"alert-banner\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"AlertBannerProps\" />\n\nA `status` outside the four levels renders nothing and reports OPSIN-0021 (OPSIN-0011 for\n`unknown`). `heading` names the subject, because the component renders the level's word.\n`headingLevel` outside 2 to 6 falls back to `h2`. A third action renders and is reported.\n`dismissible` needs `onAcknowledge` at every level. `now`, `locale` and `timeZone` render\nnothing. `AlertAction` is also exported:\n\n```ts\nexport interface AlertAction {\n  label: string\n  href?: string\n  onSelect?: () => void\n  recommended?: boolean\n}\n```\n\n### Data attributes [#data-attributes]\n\n<DataAttributesTable\n  name=\"alert-banner\"\n  rows=\"[\n  {\n    attribute: &#x22;data-slot&#x22;,\n    condition: &#x22;On the root, always&#x22;,\n    value: &#x22;alert-banner&#x22;,\n  },\n  {\n    attribute: &#x22;data-slot&#x22;,\n    condition: &#x22;On inner parts&#x22;,\n    value: &#x22;alert-banner-announcement, -heading, -heading-text, -body, -actions, -action, -dismiss&#x22;,\n  },\n  {\n    attribute: &#x22;data-status&#x22;,\n    condition: &#x22;On the root, always&#x22;,\n    value: &#x22;steady | watch | attention | urgent&#x22;,\n  },\n  {\n    attribute: &#x22;data-detected-at&#x22;,\n    condition: &#x22;On the root, when detectedAt is non-empty&#x22;,\n    value: &#x22;The ISO 8601 instant, verbatim. Absent otherwise.&#x22;,\n  },\n]\"\n/>"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/avatar",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/avatar.md",
      "slug": [
        "components",
        "avatar"
      ],
      "section": "Components",
      "title": "Avatar",
      "description": "A picture or initials standing for a person, with the person's name as its accessible label and a neutral fallback when there is no picture.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "profile picture",
        "initials",
        "user image"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"avatar\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;No contrast pair has been measured for the initials ink or the person glyph on the muted fill this component draws.&#x22;,\n  &#x22;Nobody has listened to it in a screen reader, so whether the name reads cleanly through role=\\&#x22;img\\&#x22; is unverified.&#x22;,\n  &#x22;Initials are taken by code point, not grapheme cluster, so a first character with a combining mark can lose the mark.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"avatar\" unbuilt=\"false\" importPath=\"@/components/ui/avatar\" dependencies=\"[&#x22;lucide-react&#x22;]\" />\n\n```tsx\nimport { Avatar } from \"@/components/ui/avatar\"\n```\n\n```tsx\n<Avatar name=\"Ada Vance\" src=\"/people/ada-vance.jpg\" size=\"md\" />\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"avatar\" />\n\n### A name becomes its initials [#a-name-becomes-its-initials]\n\n`name` drives the initials. A two-part name gives first and last, a single name\ngives one, and a non-Latin name keeps its own script rather than a transliterated guess.\n\n<ComponentPreview name=\"avatar-initials-from-a-name\" kind=\"example\" align=\"start\" />\n\n### The fallback chain, one tier at a time [#the-fallback-chain-one-tier-at-a-time]\n\n`src` and `name` decide the tier: a picture that loads, initials when there is no\npicture, and a neutral person glyph when there is neither.\n\n<ComponentPreview name=\"avatar-the-fallback-chain\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;Beside a person's name in a message, a comment or a care-team list, to tell one author from another.&#x22;,\n  &#x22;As the fallback identity for a person with no photo, where initials or a neutral glyph stand in without pretending a picture exists.&#x22;,\n  &#x22;At a small fixed size in a dense list, where a full name would not fit.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;You want the mark to open a menu or a profile when it is pressed.&#x22;, instead: &#x22;icon-button&#x22; },\n  { case: &#x22;You are showing a count or a short status word rather than a person.&#x22;, instead: &#x22;badge&#x22; },\n  { case: &#x22;You need a round placeholder to hold an avatar's space while its picture is still loading.&#x22;, instead: &#x22;skeleton&#x22; },\n  { case: &#x22;You are trying to show who wrote a piece of health guidance and on whose authority.&#x22;, instead: &#x22;source-citation&#x22; },\n]\"\n/>\n\n## Accessibility [#accessibility]\n\nThe audit fixed one defect: a picture with a missing or blank name rendered an empty\n`alt`, so a screen reader announced nothing while a sighted reader saw a face. The\npicture tier now requires a usable name too, so a nameless avatar falls through to the\nneutral person glyph. On every commit `pnpm run check:a11y` confirms every colour is a\nrole token, no type size is in `px` and no banned word appears.\n\n* The avatar takes no focus and is not a tab stop. Inside a button or a link, that\n  control owns the focus and the name.\n* With a fallback showing, the root is `role=\"img\"` with the name as `aria-label`,\n  and the initials or glyph are `aria-hidden`.\n* With a picture showing, the image's own `alt` carries the name and the root stays a\n  plain container, so the name is announced once.\n\n**Residual items.**\n\n* An empty name warns in development, draws the person glyph and leaves the circle\n  unlabelled, because the component cannot invent a label.\n* The initials and the glyph take their contrast on the muted fill from shared role\n  tokens. The rendered pass found no violation, but no ContrastReport data exists yet\n  for this pair.\n* Initials are taken by code point rather than grapheme cluster, so a combining mark\n  can be lost.\n\n<KeyboardTable\n  name=\"avatar\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Skips the avatar&#x22;,\n    notes: &#x22;Not focusable. Inside a button or link, the wrapper is the tab stop.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Skips the avatar in reverse&#x22;,\n    notes: &#x22;Absent from the tab sequence in both directions.&#x22;,\n  },\n  {\n    keys: &#x22;Enter&#x22;,\n    action: &#x22;Does nothing here&#x22;,\n    notes: &#x22;The avatar captures no key. A wrapping link or button owns Enter.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"avatar\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"AvatarProps\" />\n\n`name` is required, but an empty string still compiles. It warns in development and\nfalls back to the person glyph. A missing or broken `src` is a fallback, not an error.\n`size` defaults to `md`, and an unknown value is repaired to `md` with a warning."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/badge",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/badge.md",
      "slug": [
        "components",
        "badge"
      ],
      "section": "Components",
      "title": "Badge",
      "description": "A small neutral label attached to something else, like a count on a tab or a word on a list row. It takes no colour axis and never stands in for status.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "counter",
        "label chip"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"badge\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;Nothing stops a caller passing a status or category colour through className, which is the exact axis mixing the roster cited when it declined a generic badge.&#x22;,\n  &#x22;Nobody has heard a badge in a screen reader, so whether a labelled count reads usefully in the flow of its host is reasoned rather than listened to.&#x22;,\n  &#x22;No contrast pair has been measured, so whether the soft chip and the outline chip read at the text and non-text floors is argued from the roles alone.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"badge\" unbuilt=\"false\" importPath=\"@/components/ui/badge\" />\n\n```tsx\nimport { Badge } from \"@/components/ui/badge\"\n```\n\n```tsx\n<span className=\"inline-flex items-center gap-2\">\n  Messages\n  <Badge srLabel=\"3 unread\">3</Badge>\n</span>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"badge\" />\n\n### A count on a label [#a-count-on-a-label]\n\nEach badge attaches a fictional count to the label beside it. `srLabel` names\nthat count, so a screen reader hears \"5 waiting\" rather than a lone \"5\".\n\n<ComponentPreview name=\"badge-a-count-on-a-label\" kind=\"example\" align=\"start\" />\n\n### The two weights [#the-two-weights]\n\n`variant` chooses `soft` or `outline`, and both are neutral. Read in greyscale\nthey are two quiet chips, and a status pill beside them would still be the only\nthing carrying a level.\n\n<ComponentPreview name=\"badge-the-two-weights\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;A small neutral count attached to a label, such as an unread count on a tab, where the number carries no clinical meaning.&#x22;,\n  &#x22;A short neutral word on a list row or a heading, such as a category name the product owns, that is not a status.&#x22;,\n  &#x22;A compact chip of neutral chrome that reads more calmly than a full sentence, as long as it carries content rather than urgency.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;The label says what a reading means or how urgent it is. A badge would carry that as colour alone.&#x22;, instead: &#x22;status-pill&#x22; },\n  { case: &#x22;You are showing a measurement and its unit rather than a count or a word.&#x22;, instead: &#x22;value&#x22; },\n  { case: &#x22;The chip has to be tapped to do something. A badge is content, not a control, and takes no focus.&#x22;, instead: &#x22;button&#x22; },\n]\"\n/>\n\n## Accessibility [#accessibility]\n\n`pnpm run check:a11y` confirms on every commit that the badge draws only\nneutral chrome roles, carries no `data-status` and sets its text at the\n`caption1` step rather than a `px` size. The audit fixed one defect: `aria-label`\non a bare `span`, whose implicit role is generic, does not reliably carry an\nauthor-supplied name, so a non-empty `srLabel` now adds `role=\"img\"`, the\npairing [Avatar](./avatar.mdx) uses. Nothing else changed.\n\n**Argued from the source, not measured.** `srLabel=\"\"` sets `aria-hidden`, so a\ncount already spoken beside the badge is not read twice. Nothing takes focus,\nanswers a key or animates, so there is no keyboard contract and nothing for\n`prefers-reduced-motion` to reduce. At 200% text and under a wider text-spacing\noverride the chip grows rather than clipping, because nothing fixes its height\nor hides its overflow.\n\n**Residual items.**\n\n* No contrast pair in either weight has been measured against real token\n  values, so the figures below are whatever the generator has produced so far.\n* Nothing checks that `srLabel` textually contains the visible content, so a\n  caller can still write a disjoint label. That is a documented usage contract,\n  not enforced behaviour.\n* Nobody has listened to a labelled badge in a screen reader in the flow of its\n  host, so how it reads there is reasoned from the roles.\n\n<KeyboardTable\n  name=\"badge\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Skips the badge&#x22;,\n    notes: &#x22;A badge is content, not a control. Nothing here is focusable.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Skips the badge&#x22;,\n    notes: &#x22;Same in reverse. A badge never appears in the focus order.&#x22;,\n  },\n  {\n    keys: &#x22;Arrow keys&#x22;,\n    action: &#x22;Nothing&#x22;,\n    notes: &#x22;There is nothing to select, move or expand.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"badge\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"BadgeProps\" />\n\n`variant` defaults to `soft` and chooses a neutral weight only. There is no\ncolour prop, because a badge is on neither axis, and colour passed through\n`className` is the caller's to keep off both. `srLabel` names a bare count, and\nan empty string hides a decorative badge from the accessibility tree."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/body-map",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/body-map.md",
      "slug": [
        "components",
        "body-map"
      ],
      "section": "Components",
      "title": "BodyMap",
      "description": "A neutral, non-realistic body schematic for pointing to a location. It records region keys and interprets nothing, so the product owns every meaning.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "pain map",
        "anatomy diagram",
        "where does it hurt"
      ],
      "implements": [],
      "governedBy": [
        "two-colour-axes"
      ],
      "usedIn": [],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"body-map\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;The native toggle buttons with aria-pressed and a per-region aria-label are argued rather than verified against VoiceOver, NVDA or TalkBack.&#x22;,\n  &#x22;Whether the nine-stop schematic should become a single roving toolbar is undecided, and the checkbox list is the primary keyboard path meanwhile.&#x22;,\n  &#x22;The deliberately non-realistic silhouette has not been reviewed for whether it reads as neutral to every reader, and no user research backs the choice yet.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"body-map\" unbuilt=\"false\" importPath=\"@/components/ui/body-map\" />\n\n```tsx\nimport { BodyMap } from \"@/components/ui/body-map\"\n```\n\n```tsx\n<BodyMap\n  label=\"Where are you noticing something?\"\n  value={regions}\n  onValueChange={setRegions}\n/>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"body-map\" />\n\n### Pointing at what hurts [#pointing-at-what-hurts]\n\nA controlled multi-select over both figures, driven by `value` and `onValueChange`.\nA marked region stands out in greyscale, without colour.\n\n<ComponentPreview name=\"body-map-pointing-at-what-hurts\" kind=\"example\" align=\"start\" />\n\n### Pairing the map with a checkbox list [#pairing-the-map-with-a-checkbox-list]\n\nThe map and a native checkbox list share one `value`, so a keyboard or\nassistive-technology user has a robust path to the same answer. Ship both together.\n\n<ComponentPreview name=\"body-map-with-a-checkbox-list\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;Letting someone point at one or more general regions of the body, as structured input a product interprets on its own terms.&#x22;,\n  &#x22;Capturing a coarse location beside a free-text note or a reading, where a key like left-arm is more reliable than a sentence.&#x22;,\n  &#x22;Offering a faster alternative to a long checkbox list, while keeping that list available for keyboard and assistive-technology users.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;You are recording one specific measurement or reading rather than a location.&#x22;, instead: &#x22;reading-input&#x22; },\n  { case: &#x22;You need a realistic figure that represents a particular body, age or condition.&#x22;, instead: &#x22;field&#x22; },\n  { case: &#x22;You are asking how strong or how bad something is rather than where it is.&#x22;, instead: &#x22;scale-input&#x22; },\n  { case: &#x22;The answer is really free text and a diagram would only get in the way.&#x22;, instead: &#x22;field&#x22; },\n]\"\n/>\n\n## Clinical meaning [#clinical-meaning]\n\n**Asserts.** Only that the reader indicated these regions, not what is there, whether\nit hurts, how strongly, since when, or what it means. The shipped labels are generic\nplaceholders, and the consuming product owns the region words and any interpretation.\n\n**Never read as.** A symptom checker, a triage or a diagnosis. A product that treats\na marked region as evidence of a condition has added a judgement the component does\nnot make, and owns it.\n\n**Colour axis.** Neither. A selection is a muted fill, a hairline and a tick, never\na hue, and a marked region carries no clinical level and names no category. See\n[Two colour axes](../health/two-colour-axes.mdx).\n\n**Thresholds.** None. The component runs no rules over a selection and reaches no\nconclusion from it, and whether a selection triggers anything is the product's\ndecision.\n\n## Accessibility [#accessibility]\n\nEach region is a real `button`, named by its label, with `aria-pressed` for its state,\ninside a group named by `label`. Unselected shows a plus, the selected state survives\ngreyscale with `aria-pressed` as its carrier, and each marker meets the 44 by 44 floor\non both axes in `rem`. Every colour is a role token, no type size is in `px`, and no\nbanned word appears. Left and right are the subject's own sides, so the `left-arm`\nmarker sits on the viewer's right, matching clinical convention.\n\nThe audit fixed one defect. The `rem` markers outgrew the `px`-pinned figure box at\n200% text and collided, so they could not be tapped separately (1.4.4, 1.4.10). The\nbox now scales in `rem` in lockstep with the markers, so the spacing ratio holds at\nevery text size and the default view is unchanged.\n\n**Residual items.**\n\n* The Front and Back captions are `<p>`, not headings, by design, so the component\n  hardcodes no heading level into a host document of unknown depth. Each figure still\n  carries a named `role=\"group\"`.\n* Screen-reader output in VoiceOver, NVDA and TalkBack, the nine-stop tab sequence and\n  forced colours are not gated.\n* The paired checkbox list stays the primary path for readers who cannot point at a\n  target.\n\n<KeyboardTable\n  name=\"body-map\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves to the next region&#x22;,\n    notes: &#x22;Each region is its own stop, so the default map is nine stops.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Moves to the previous region&#x22;,\n    notes: &#x22;The same sequence in reverse.&#x22;,\n  },\n  {\n    keys: &#x22;Space or Enter&#x22;,\n    action: &#x22;Toggles the focused region&#x22;,\n    notes: &#x22;Native button activation. aria-pressed flips, and the fill and tick follow it.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"body-map\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"BodyMapProps\" />\n\n`label` is required and has no default. Name it as the question the reader is\nanswering. A region `key` with no built-in place on the figure is warned once in\ndevelopment and skipped rather than drawn. `view` defaults to `both`."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/button",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/button.md",
      "slug": [
        "components",
        "button"
      ],
      "section": "Components",
      "title": "Button",
      "description": "A control you press to make something happen. It is the least clinical component here, and its page sets the pattern every other component page follows.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "cta",
        "action",
        "submit",
        "primary button"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [
        "daily-logging",
        "forms",
        "onboarding-and-first-run"
      ],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"button\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;Whether an ink outline is warning enough for the destructive variant, or whether a destructive action belongs behind a confirmation Dialog instead.&#x22;,\n  &#x22;A busy button given no busyLabel leaves a reduced-motion reader a still glyph and no word for what is happening.&#x22;,\n  &#x22;Base UI defaults type to button, so a form's submit control has to say type=\\&#x22;submit\\&#x22;; whether to restore the platform default is open.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"button\" unbuilt=\"false\" importPath=\"@/components/ui/button\" dependencies=\"[&#x22;@base-ui/react&#x22;, &#x22;lucide-react&#x22;]\" />\n\n```tsx\nimport { Button } from \"@/components/ui/button\"\n```\n\n```tsx\n<Button variant=\"primary\" onClick={save}>\n  Save reading\n</Button>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"button\" />\n\n### One primary per surface [#one-primary-per-surface]\n\nOne filled button answers &#x2A;what should I do here?* Everything else is secondary or\nquiet.\n\n<ComponentPreview name=\"button-one-primary-per-surface\" kind=\"example\" align=\"start\" />\n\n### Busy, at the foot of a form [#busy-at-the-foot-of-a-form]\n\n`busy` keeps the label, blocks activation and shows the indicator in the icon's\nseat. `busyLabel=\"Saving\"` gives the state a word, and `fullWidth` stops the control\ngrowing when it appears.\n\n<ComponentPreview name=\"button-busy-at-the-foot-of-a-form\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;An action that changes something: saving a reading, submitting a form, confirming a decision.&#x22;,\n  &#x22;The one primary action on a surface, with everything else secondary or quiet.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;The control takes the reader somewhere. A new URL is a link, however it is styled.&#x22;, instead: &#x22;link&#x22; },\n  { case: &#x22;The control turns something on or off immediately, with no confirmation step.&#x22;, instead: &#x22;switch&#x22; },\n  { case: &#x22;The control chooses one of a few options rather than performing an action.&#x22;, instead: &#x22;segmented-control&#x22; },\n  { case: &#x22;The control is icon-only, in a toolbar or a header.&#x22;, instead: &#x22;icon-button&#x22; },\n  { case: &#x22;The action is a clinical instruction with an author and a time behind it.&#x22;, instead: &#x22;care-card&#x22; },\n]\"\n/>\n\n## Accessibility [#accessibility]\n\nIt is a real `button` with the platform role and keys, named by its visible label,\nwith the icon `aria-hidden`. `busy` works through `aria-busy` and `aria-disabled`, so\nthe control keeps its tab stop, and the outline focus ring never shifts layout. A press\nsinks it to 0.97 on pointer-down and lets it settle back on `spring-snap`, and a busy\ncontrol does not sink. Under `prefers-reduced-motion` the sink is a single frame with no\ntravel. [Motion](../foundations/motion.mdx) sets out all five interaction motions.\nRendered, it shows no axe, target-size, focus-visible or reflow failure, and the audit\nchanged nothing.\n\n**Residual items.**\n\n* No live region mounts, by design. `busy` reaches the tree on the focused control as\n  `aria-busy` plus `aria-disabled`, and `busyLabel` carries a word there, but with no\n  `busyLabel` it is not otherwise announced.\n* The ring is an outline with offset, so an ancestor set to clip can hide it.\n* `Button.Target` raises the hit area to the 44px floor under the SC 2.5.8 inline\n  exception, so a project without the product stylesheet owes\n  `--opsin-target-separation`.\n* `quiet` has no fill and no boundary, so its accent ink is the cue a reader who cannot\n  hover has that it is a control. It is never underlined; an underline marks a link\n  inside running text.\n\n<KeyboardTable\n  name=\"button\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves focus to the button&#x22;,\n    notes: &#x22;One tab stop for the whole control. A busy button keeps its stop.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Moves focus back out&#x22;,\n    notes: &#x22;Natural DOM order. A tabIndex above zero raises a development warning.&#x22;,\n  },\n  {\n    keys: &#x22;Enter&#x22;,\n    action: &#x22;Activates the button&#x22;,\n    notes: &#x22;Platform behaviour on a real button element. Blocked while busy.&#x22;,\n  },\n  {\n    keys: &#x22;Space&#x22;,\n    action: &#x22;Activates the button&#x22;,\n    notes: &#x22;Consumed by the button, so the page does not scroll. Blocked while busy.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"button\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"ButtonProps\" />\n\n`type` defaults to `button`, not `submit`, so a form's submit control has to say\n`type=\"submit\"`. There is no `disabled` convenience prop: the native attribute is\nthe whole of it, and passing `busy` and `disabled` together warns in development.\n`className` and `style` merge caller last and must never resolve a `--opsin-status-*`\nor `--opsin-category-*` role, because a Button carries no clinical axis.\n\n### Data attributes [#data-attributes]\n\n<DataAttributesTable\n  name=\"button\"\n  rows=\"[\n  {\n    attribute: &#x22;data-slot&#x22;,\n    condition: &#x22;On the root and every inner part, always&#x22;,\n    value: &#x22;button, button-target, button-icon, button-busy, button-busy-label, button-label&#x22;,\n  },\n  {\n    attribute: &#x22;data-disabled&#x22;,\n    condition: &#x22;On the root while busy or while the caller's disabled prop is true&#x22;,\n    value: &#x22;Present with no value; absent otherwise&#x22;,\n  },\n]\"\n/>"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/callout",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/callout.md",
      "slug": [
        "components",
        "callout"
      ],
      "section": "Components",
      "title": "Callout",
      "description": "A short piece of set-apart information that helps you understand what you are reading without claiming anything about your health. A note, tip or caveat.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "admonition",
        "note",
        "info box",
        "aside",
        "note box",
        "tip"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [
        "alert-escalation"
      ],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"callout\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;An axis colour passed through className is stripped in every build, but a consumer's own stylesheet or style attribute is not, and nothing checks consumer code.&#x22;,\n  &#x22;The root is a role=\\&#x22;note\\&#x22; named by its title, and nobody has listened to it in VoiceOver or TalkBack, or to a screen carrying several.&#x22;,\n  &#x22;Nothing here is dismissible, and a dismiss control would need a name, a 44pt target and a memory that outlives the render, none of them designed.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"callout\" unbuilt=\"false\" importPath=\"@/components/ui/callout\" dependencies=\"[&#x22;lucide-react&#x22;]\" />\n\n```tsx\nimport { Callout } from \"@/components/ui/callout\"\n```\n\n```tsx\n<Callout variant=\"caveat\" title=\"What this average leaves out\">\n  This average does not include days when you did not wear the device.\n</Callout>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"callout\" />\n\n### Next to what it explains [#next-to-what-it-explains]\n\nOne callout per surface, directly under the thing it annotates, saying something specific and checkable. `title` names what the reader is about to be told.\n\n<ComponentPreview name=\"callout-next-to-what-it-explains\" kind=\"example\" align=\"start\" />\n\n### On a card [#on-a-card]\n\nThe fill sets the callout apart, so `bg-card` behind it changes how much work the boundary does. The caller passes `rounded-opsin-xs` through `className` for the concentric inner radius.\n\n<ComponentPreview name=\"callout-on-a-card\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;Setting apart a note, a tip or a caveat that helps the reader understand the content around it.&#x22;,\n  &#x22;General health information that is true for everybody and is not about this reader's data.&#x22;,\n  &#x22;Explaining a limitation of what is on screen: how a figure was worked out, what it leaves out, where it came from.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;The message is about this reader's data and carries a level of attention.&#x22;, instead: &#x22;status-pill&#x22; },\n  { case: &#x22;Something has changed and the reader needs to know before carrying on.&#x22;, instead: &#x22;alert-banner&#x22; },\n  { case: &#x22;The reader is being asked to do something by a certain time.&#x22;, instead: &#x22;care-card&#x22; },\n  { case: &#x22;It is the standing statement about what this product is not.&#x22;, instead: &#x22;disclaimer-note&#x22; },\n  { case: &#x22;You are explaining a single word rather than a passage.&#x22;, instead: &#x22;term&#x22; },\n]\"\n/>\n\n## Accessibility [#accessibility]\n\nIt is a server component with no interactive elements, so the keyboard, focus and control criteria do not apply. `role=\"note\"` gives it a start and end boundary, and a title supplies the accessible name through `aria-label`. It paints no colour from either axis and carries no clinical status, so greyscale and `forced-colors` take away nothing. Type sizes and colours are role tokens, the icon is sized in em, and the body reflows at 200% through `min-w-0` and `wrap-break-word` rather than scrolling. Nothing in the source needed to change.\n\n**Residual items.**\n\n* The variant glyph is `aria-hidden`, so the note, tip and caveat distinction reaches sighted readers alone. This is deliberate. Announcing the glyph name would not convey the sense either, so the copy is required to carry it, and both examples do.\n* The title renders as styled text rather than an `h1` to `h6`, because the component cannot know its nesting level, but it stays exposed to assistive technology as the accessible name.\n* The four contrast pairs it paints are not yet measured, and the report below says so.\n\n<KeyboardTable\n  name=\"callout\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Skips the callout&#x22;,\n    notes: &#x22;No tab stop. A link inside the body is the stop, not the callout.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Skips the callout&#x22;,\n    notes: &#x22;Same in reverse. Never in the focus order.&#x22;,\n  },\n  {\n    keys: &#x22;Escape&#x22;,\n    action: &#x22;Does nothing&#x22;,\n    notes: &#x22;There is no dismiss control, so nothing closes.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"callout\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"CalloutProps\" />\n\nThere is no `status`, `severity`, `color` or `warning` variant, and no `action` or `dismissible`. The variant union is not exported, so a wrapper writes `CalloutProps[\"variant\"]`. An axis colour in `className` is stripped before it reaches the root, and development warns once per offending class list."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/card",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/card.md",
      "slug": [
        "components",
        "card"
      ],
      "section": "Components",
      "title": "Card",
      "description": "A bounded group of related content with a border and consistent padding is the ordinary box that most of a screen is made of.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "panel",
        "container",
        "box",
        "tile group",
        "content box"
      ],
      "implements": [],
      "governedBy": [
        "two-colour-axes"
      ],
      "usedIn": [
        "result-disclosure",
        "onboarding-and-first-run",
        "trend-review"
      ],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"card\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;A link card may hold no other interactive element, but the rule is stated, not enforced: TypeScript and a runtime walk both miss wrapped controls.&#x22;,\n  &#x22;Nested cards are announced no differently from unnested ones, and how deep is acceptable is unanswered.&#x22;,\n  &#x22;A link card's accessible name is its whole text content; whether Card should offer a way to name the link is open.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"card\" unbuilt=\"false\" importPath=\"@/components/ui/card\" dependencies=\"[&#x22;lucide-react&#x22;]\" registryDependencies=\"[&#x22;surface&#x22;]\" />\n\n```tsx\nimport { Card } from \"@/components/ui/card\"\n```\n\n```tsx\n<Card>\n  <Card.Header title={<h3>Recent readings</h3>} />\n  <Card.Body>Card content</Card.Body>\n</Card>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"card\" />\n\n### The whole card as one link [#the-whole-card-as-one-link]\n\n`href` makes the card one anchor and one tab stop. A chevron marks it at rest,\nthe title underlines on hover, and it holds no buttons.\n\n<ComponentPreview name=\"card-as-a-link\" kind=\"example\" align=\"start\" />\n\n### Cards on a sheet, and the rung that stays put [#cards-on-a-sheet-and-the-rung-that-stays-put]\n\nThe sheet is the layer; the cards on it stay on the `card` rung, since a\ntranslucent rung never contains one.\n\n<ComponentPreview name=\"card-on-a-sheet\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;Grouping content that belongs together and needs a visible boundary.&#x22;,\n  &#x22;Giving a block its own padding, radius and rung so it reads as one thing, not a region of the page.&#x22;,\n  &#x22;As the base for a purpose-built card with its own contract, the way ResultCard and CareCard are.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;The content is a health result with a value, range, status and meaning.&#x22;, instead: &#x22;result-card&#x22; },\n  { case: &#x22;The content is an instruction the reader must act on.&#x22;, instead: &#x22;care-card&#x22; },\n  { case: &#x22;The content is one measurement in a dashboard grid.&#x22;, instead: &#x22;metric-tile&#x22; },\n  { case: &#x22;You need a layer over scrolling content that must stay readable.&#x22;, instead: &#x22;surface&#x22; },\n  { case: &#x22;You want a border for advisory prose.&#x22;, instead: &#x22;callout&#x22; },\n]\"\n/>\n\n## Accessibility [#accessibility]\n\nA card takes no role or name unless it is a link. It carries the page's heading level\nin a title slot that resets font and margin, floors a link target at\n`--opsin-target-minimum`, and keeps its edge under greyscale, `forced-colors` and print.\nThe resting chevron is `aria-hidden`, backed by the title underline and anchor as\nredundant cues. There is no axe violation and no 320px reflow failure, and\n`pnpm run check:a11y` confirms on every commit that every colour is a role token, no\ntype size is in `px`, and no banned word appears. The audit moved the link card's\n`focus-visible` ring from a hardcoded 2px outline to `--opsin-border-focus` and\n`--opsin-border-focus-offset`, so a product raising those gets a wider ring here, and\nthe default stays 2px. A link card sinks to 0.98 when pressed and comes back on the\nstandard curve, never on a spring, because a card can hold a reading.\n\n**Residual items.** A link card is one anchor, so its accessible name is all its text\nat once. Weigh that verbosity before putting `href` on a long card.\n\n<KeyboardTable\n  name=\"card\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves to the card, when the card is a link&#x22;,\n    notes: &#x22;One stop per card. A card without href is not focusable.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Moves backwards to the card&#x22;,\n    notes: &#x22;Reverse order matches visual order.&#x22;,\n  },\n  {\n    keys: &#x22;Enter&#x22;,\n    action: &#x22;Follows the link, on a card that has an href&#x22;,\n    notes: &#x22;The root is a real anchor, so this is browser behaviour.&#x22;,\n  },\n  {\n    keys: &#x22;Space&#x22;,\n    action: &#x22;Scrolls the page&#x22;,\n    notes: &#x22;A link activates on Enter, not Space.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"card\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"CardProps\" />\n\n`rung` defaults to `card`, not `raised`, and never goes above `raised`: a\ntranslucent rung warns in development and renders. `render` takes the\nrouter's link element, not a function, and does nothing without `href`. There is\nno `status`, `variant`, `color` or `category`.\n\n<PropsTable name=\"CardHeaderProps\" />\n\n<PropsTable name=\"CardBodyProps\" />\n\n<PropsTable name=\"CardFooterProps\" />"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/care-card",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/care-card.md",
      "slug": [
        "components",
        "care-card"
      ],
      "section": "Components",
      "title": "CareCard",
      "description": "A card that tells you what to do and when. It carries one instruction at one of three urgency levels, with the urgency stated in the heading, not implied.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "next steps",
        "what to do",
        "advice",
        "action card",
        "what to do next",
        "advice card",
        "guidance card"
      ],
      "implements": [],
      "governedBy": [
        "two-colour-axes",
        "alerts",
        "health/index",
        "high-stakes-moments",
        "consent-and-privacy",
        "numbers",
        "safety-review"
      ],
      "usedIn": [
        "alert-escalation",
        "empty-and-first-use",
        "onboarding-and-first-run",
        "result-disclosure"
      ],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"care-card\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;Whether an inconsistent urgency and status pair should warn, or whether warning would assert the mapping opsinjs refused to ship.&#x22;,\n  &#x22;The card reads no clock, so one left open overnight says today about yesterday, and who re-renders it is undecided.&#x22;,\n  &#x22;An urgent card may say ring for help, yet a tel: action is a plain link with no number and no emergency mode.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"care-card\" unbuilt=\"false\" importPath=\"@/components/ui/care-card\" registryDependencies=\"[&#x22;card&#x22;, &#x22;button&#x22;, &#x22;status-pill&#x22;, &#x22;link&#x22;]\" />\n\n```tsx\nimport { CareCard } from \"@/components/ui/care-card\"\n```\n\n```tsx\n<CareCard\n  heading=\"Book a repeat blood test\"\n  urgency=\"this-week\"\n  attribution=\"Your clinic asks\"\n/>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"care-card\" />\n\n### A steady card that still asks for something [#a-steady-card-that-still-asks-for-something]\n\n`status=\"steady\"` with `urgency=\"when-convenient\"` is the routine follow-up.\n\n<ComponentPreview name=\"care-card-steady-and-still-asking\" kind=\"example\" align=\"start\" />\n\n### A deadline the reader is already behind [#a-deadline-the-reader-is-already-behind]\n\n`dueBy` renders as a written date and `overdue` is a product-supplied boolean. No\n`urgency` is set; the date is the timing.\n\n<ComponentPreview name=\"care-card-a-deadline-that-has-passed\" kind=\"example\" align=\"start\" />\n\n### The author is missing [#the-author-is-missing]\n\nThe same instruction with and without `attribution`. Without one, the card says so.\n\n<ComponentPreview name=\"care-card-no-author-supplied\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;The reader must do something, and the product can say what, by when and who asks.&#x22;,\n  &#x22;A result or a change produced a next step that would otherwise be buried in a paragraph.&#x22;,\n  &#x22;Aftercare, preparation and follow-up instructions for one person at one moment.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;Nothing needs doing, or the content is general information not addressed to this reader.&#x22;, instead: &#x22;callout&#x22; },\n  { case: &#x22;The message must interrupt because it has only just become true.&#x22;, instead: &#x22;alert-banner&#x22; },\n  { case: &#x22;You only need to label how much attention a result needs.&#x22;, instead: &#x22;status-pill&#x22; },\n  { case: &#x22;The instruction is the standing not-medical-advice note that appears on every result.&#x22;, instead: &#x22;disclaimer-note&#x22; },\n  { case: &#x22;The reader must respond before they can do anything else.&#x22;, instead: &#x22;dialog&#x22; },\n]\"\n/>\n\n## Clinical meaning [#clinical-meaning]\n\n**Asserts.** That the named author asks this reader to do this, optionally by a stated\ndate, for a stated reason.\n\n**Never read as.** Advice from a clinician who has assessed this reader, unless the card\nsays so. `attribution` is required.\n\n**Colour axis.** Status only, on the embedded [StatusPill](./status-pill.mdx). Surface,\nboundary and heading take no category colour. See\n[Two colour axes](../health/two-colour-axes.mdx).\n\n**Thresholds.** None. `urgency` says when to act, `status` says how much attention the\nreading needs, neither is derived from the other, and all fifteen pairs render. See\n[Two colour axes](../health/two-colour-axes.mdx),\n[Alerts](../health/alerts.mdx) and\n[High-stakes moments](../health/high-stakes-moments.mdx).\n\n**No clock.** *Do this today* still says so after midnight. `overdue` is a product-supplied\nboolean. See\n[Health](../health/index.mdx).\n\n<SafetyCallout severity=\"urgent\" evidence=\"opinion\">\n  At most one `urgent` surface per screen, counted on the status axis. If the step is ringing\n  for help, give the number: the component ships none.\n</SafetyCallout>\n\n## Accessibility [#accessibility]\n\nThe card is a `section` named by `aria-label` from its heading, so entering it speaks the\ninstruction, and it takes no tab stop. Urgency is text with no glyph or colour, and status\nis carried by [StatusPill](./status-pill.mdx) as word, glyph and tint, never colour alone.\nOf two actions, the recommended one is set apart by a bordered shape and a hidden\nqualifier, not by colour.\n\n**Residual items.**\n\n* The `sm` quiet button and secondary quiet link variants inherit the 44px target floor\n  but were not exercised in a browser.\n* Contrast for the action tones and the timing phrase stays unmeasured, as the report\n  below records.\n\n<KeyboardTable\n  name=\"care-card\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves to the first action, then to the second&#x22;,\n    notes: &#x22;The card is not focusable.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Moves back through the actions, then out of the card&#x22;,\n    notes: &#x22;Actions keep DOM order.&#x22;,\n  },\n  {\n    keys: &#x22;Enter&#x22;,\n    action: &#x22;Activates the focused action&#x22;,\n    notes: &#x22;No action is destructive: no dismiss, snooze or delete.&#x22;,\n  },\n  {\n    keys: &#x22;Space&#x22;,\n    action: &#x22;Activates a focused action that is a button&#x22;,\n    notes: &#x22;An href action is a link, so Space scrolls.&#x22;,\n  },\n  {\n    keys: &#x22;Arrow keys&#x22;,\n    action: &#x22;Nothing&#x22;,\n    notes: &#x22;Not a composite widget.&#x22;,\n  },\n  {\n    keys: &#x22;Escape&#x22;,\n    action: &#x22;Nothing&#x22;,\n    notes: &#x22;Not an overlay.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"care-card\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"CareCardProps\" />\n\n`CareUrgency` and `CareAction` are exported from the same file, absent from the table.\n\n```tsx\nexport type CareUrgency = \"when-convenient\" | \"this-week\" | \"today\"\n\nexport interface CareAction {\n  label: string\n  href?: string\n  onSelect?: () => void\n  recommended?: boolean\n}\n```\n\nAn `href` action renders a link and an `onSelect` action a button. Given both, the link\nwins. `headingLevel` defaults to 3. A `dueBy` without `locale` warns in development."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/checkbox",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/checkbox.md",
      "slug": [
        "components",
        "checkbox"
      ],
      "section": "Components",
      "title": "Checkbox",
      "description": "A single labelled box a reader ticks, unticks or leaves in a mixed state, built on Base UI Checkbox and carrying neither colour axis.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "tick box",
        "multi select"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"checkbox\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;No contrast pair is measured here: the unticked hairline and the description ink against the page ground are argued, not checked.&#x22;,\n  &#x22;Nobody has listened to the box in a screen reader, so whether aria-checked=\\&#x22;mixed\\&#x22; is heard as partly on is reasoned, not heard.&#x22;,\n  &#x22;Forced colours are unhandled: the fill and the hairline both become the platform pair, and whether ticked, unticked and mixed stay distinct is untested.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"checkbox\" unbuilt=\"false\" importPath=\"@/components/ui/checkbox\" dependencies=\"[&#x22;@base-ui/react&#x22;, &#x22;lucide-react&#x22;]\" />\n\n```tsx\nimport { Checkbox } from \"@/components/ui/checkbox\"\n```\n\n```tsx\n<Checkbox\n  label=\"Email me a copy\"\n  checked={agreed}\n  onCheckedChange={setAgreed}\n/>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"checkbox\" />\n\n### An optional agreement [#an-optional-agreement]\n\nA lone box with `label` and `description`. The description says what ticking does.\n\n<ComponentPreview name=\"checkbox-an-optional-agreement\" kind=\"example\" align=\"start\" />\n\n### A three-state parent [#a-three-state-parent]\n\nThe example passes `checked=\"indeterminate\"` when some but not all children are ticked, so the box draws a Minus, not a Check.\n\n<ComponentPreview name=\"checkbox-a-three-state-parent\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;A single option a reader turns on or off, such as an optional agreement.&#x22;,\n  &#x22;Any-number-including-none choices across a short list, where each row is its own box.&#x22;,\n  &#x22;The head of such a list, where a parent box uses the mixed state for the some case.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;Exactly one option must be chosen. Checkboxes let a reader pick two answers to a one-answer question.&#x22;, instead: &#x22;radio-group&#x22; },\n  { case: &#x22;The label has to say what a reading means or how urgent it is.&#x22;, instead: &#x22;status-pill&#x22; },\n  { case: &#x22;The box has to join a form's label, hint, error and validity as one unit.&#x22;, instead: &#x22;field&#x22; },\n]\"\n/>\n\n## Accessibility [#accessibility]\n\nThe description is tied with `aria-describedby`, and fill, border and the Check against\nMinus glyph move together, so colour is never the sole state carrier. Sizes are rem.\nThe tick draws itself along its stroke on `spring-snap`, which collapses to 0ms under\n`prefers-reduced-motion`, so there the tick is whole the frame after the box is ticked.\nThe audit\nfixed a missing name (WCAG 4.1.2): Base UI draws the box as a `span` with\n`role=\"checkbox\"`, and the wrapping `label` named only the hidden input. The box now\npoints `aria-labelledby` at the visible label's `id`, so its name is the visible words\nverbatim (WCAG 2.5.3), in the demo and both examples.\n\n**Residual items.**\n\n* The inner box measures 20 by 20, under SC 2.5.8, but the pointer target is the 44px\n  label row, which toggles anywhere along it and so clears the house floor.\n* Contrast pairs are not yet measured.\n\n<KeyboardTable\n  name=\"checkbox\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves focus onto the box&#x22;,\n    notes: &#x22;One tab stop. A disabled box is skipped.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Moves focus back off the box&#x22;,\n    notes: &#x22;One stop in reverse too.&#x22;,\n  },\n  {\n    keys: &#x22;Space&#x22;,\n    action: &#x22;Toggles the box&#x22;,\n    notes: &#x22;A mixed box becomes ticked and reports true.&#x22;,\n  },\n  {\n    keys: &#x22;Enter&#x22;,\n    action: &#x22;Does nothing&#x22;,\n    notes: &#x22;A box at the foot of a form does not toggle on submit.&#x22;,\n  },\n  {\n    keys: &#x22;Pointer on the label&#x22;,\n    action: &#x22;Toggles the box&#x22;,\n    notes: &#x22;Anywhere along the row, not only the box.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"checkbox\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"CheckboxProps\" />\n\n`label` is required. `checked`\naccepts `true`, `false` or `\"indeterminate\"`; omitted, the box is uncontrolled\nfrom an unticked start. `indeterminate` is the other route to the mixed state\nand wins when both are given. `onCheckedChange` reports a boolean, so a mixed\nbox reports `true` when ticked.\n\n### Data attributes [#data-attributes]\n\n<DataAttributesTable\n  name=\"checkbox\"\n  rows=\"[\n  {\n    attribute: &#x22;data-slot&#x22;,\n    condition: &#x22;On the root and every inner part&#x22;,\n    value: &#x22;checkbox, checkbox-control, checkbox-indicator, checkbox-label, checkbox-description&#x22;,\n  },\n  {\n    attribute: &#x22;data-checked&#x22;,\n    condition: &#x22;On Checkbox.Control while ticked&#x22;,\n    value: &#x22;Set by Base UI&#x22;,\n  },\n  {\n    attribute: &#x22;data-unchecked&#x22;,\n    condition: &#x22;On Checkbox.Control while neither ticked nor mixed&#x22;,\n    value: &#x22;Set by Base UI&#x22;,\n  },\n  {\n    attribute: &#x22;data-indeterminate&#x22;,\n    condition: &#x22;On Checkbox.Control while mixed&#x22;,\n    value: &#x22;Set by Base UI&#x22;,\n  },\n  {\n    attribute: &#x22;data-disabled&#x22;,\n    condition: &#x22;On Checkbox.Control while disabled&#x22;,\n    value: &#x22;Set by Base UI&#x22;,\n  },\n]\"\n/>"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/combobox",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/combobox.md",
      "slug": [
        "components",
        "combobox"
      ],
      "section": "Components",
      "title": "Combobox",
      "description": "A text input that narrows a list the product supplies as the reader types, then lets them choose one match.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "autocomplete",
        "typeahead",
        "search select"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"combobox\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;The filter is Base UI's default contains match, so an accented character, an abbreviation or a near-miss spelling may filter a real item away.&#x22;,\n  &#x22;Nobody has listened to this in a screen reader, so whether the list narrowing and the empty line are announced is argued, not heard.&#x22;,\n  &#x22;No contrast pair is measured and forced colours are unhandled, so the hairline, popup, highlight and tick are argued to survive rather than checked.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"combobox\" unbuilt=\"false\" importPath=\"@/components/ui/combobox\" dependencies=\"[&#x22;@base-ui/react&#x22;, &#x22;lucide-react&#x22;]\" />\n\n```tsx\nimport { Combobox } from \"@/components/ui/combobox\"\n```\n\n```tsx\n<Combobox\n  label=\"Medication\"\n  placeholder=\"Search medications\"\n  value={medication}\n  onValueChange={setMedication}\n  items={[\n    { value: \"amoxicillin\", label: \"Amoxicillin\" },\n    { value: \"ibuprofen\", label: \"Ibuprofen\" },\n    { value: \"paracetamol\", label: \"Paracetamol\" },\n  ]}\n/>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"combobox\" />\n\n### Filtering a list [#filtering-a-list]\n\n`items` supplies a fictional set of cities and typing narrows it. `value` starts\non one city, so the input is filled and the tick is shown.\n\n<ComponentPreview name=\"combobox-filtering-a-list\" kind=\"example\" align=\"start\" />\n\n### No match [#no-match]\n\nType something the list does not contain, such as \"xyz\". `emptyMessage` fills the\npopup, announced politely.\n\n<ComponentPreview name=\"combobox-no-match\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;One item from a list long enough that typing a few letters beats scrolling it: a city, a country, a product-owned medication name.&#x22;,\n  &#x22;A single choice where the reader knows roughly what they want and would rather type than hunt.&#x22;,\n  &#x22;A field that must stay compact, filtering a long list in place rather than pushing the form down.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;A short fixed set that fits in a closed menu, so typing to filter buys nothing.&#x22;, instead: &#x22;select&#x22; },\n  { case: &#x22;Two to about five short options worth comparing at a glance.&#x22;, instead: &#x22;radio-group&#x22; },\n]\"\n/>\n\n## Accessibility [#accessibility]\n\nBase UI renders `role=\"combobox\"` on the input, which is the single tab stop,\n`role=\"listbox\"` on the popup and `role=\"option\"` with `aria-selected` on each match.\nThe selection is a lucide Check and the highlight a neutral surface under\n`data-highlighted`, so both survive greyscale. The input and the trigger floor a 44pt\ntarget in rem and carry their own focus ring. The audit fixed two defects: the trigger\nbutton now takes an `aria-label` built from the field's label, and the input's stray\n`outline-none` no longer hides the keyboard focus ring. The list unfolds from the\ninput, and under `prefers-reduced-motion` only a short opacity crossfade remains.\n\n**Residual items.**\n\n* The label reaches a screen reader as `aria-label`, not a visible label element; a\n  shared repair across the other input wrappers is still open.\n* The live match count is not announced as the reader filters.\n* No contrast pair is measured.\n\n<KeyboardTable\n  name=\"combobox\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves focus into the control, onto the input&#x22;,\n    notes: &#x22;The one tab stop. A second Tab reaches the trigger.&#x22;,\n  },\n  {\n    keys: &#x22;Typing&#x22;,\n    action: &#x22;Filters the list to the matches&#x22;,\n    notes: &#x22;Contains match on the label. The popup opens as you type.&#x22;,\n  },\n  {\n    keys: &#x22;Arrow Down&#x22;,\n    action: &#x22;Opens the popup and moves the highlight into the list&#x22;,\n    notes: &#x22;Opens a closed popup and highlights the first match.&#x22;,\n  },\n  {\n    keys: &#x22;Arrow Up, Arrow Down&#x22;,\n    action: &#x22;Moves the highlight between matches&#x22;,\n    notes: &#x22;The popup holds the highlight while the input keeps the caret.&#x22;,\n  },\n  {\n    keys: &#x22;Enter&#x22;,\n    action: &#x22;Chooses the highlighted match and closes the popup&#x22;,\n    notes: &#x22;The label fills the input and onValueChange reports the value.&#x22;,\n  },\n  {\n    keys: &#x22;Escape&#x22;,\n    action: &#x22;Closes the popup without choosing&#x22;,\n    notes: &#x22;The input keeps its text.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"combobox\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"ComboboxProps\" />\n\n`value` and `onValueChange` make this controlled, with no selection state of its\nown. A `value` matching no item renders nothing chosen and raises a development\nwarning. `label` is required, and `items` comes from the product. Omitted,\n`emptyMessage` falls back to a plain line."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/consent-sheet",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/consent-sheet.md",
      "slug": [
        "components",
        "consent-sheet"
      ],
      "section": "Components",
      "title": "ConsentSheet",
      "description": "A sheet that asks permission for one specific thing at a time, explains what it is for, and makes saying no or changing your mind as easy as saying yes.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "consent",
        "permission",
        "opt in",
        "data sharing",
        "agree"
      ],
      "implements": [],
      "governedBy": [
        "consent-and-privacy",
        "health/index",
        "high-stakes-moments",
        "safety-review"
      ],
      "usedIn": [
        "consent-and-permissions",
        "onboarding-and-first-run",
        "sharing-with-a-clinician"
      ],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"consent-sheet\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;Whether refusing to ask when any required wording is missing is right in every product, or whether a partial content service needs a way to ask anyway.&#x22;,\n  &#x22;Withdrawal is a sentence, not a control, and nothing in opsinjs is yet the screen where the data lives, so no component keeps the sheet's promise.&#x22;,\n  &#x22;No previousDecision prop exists, so a reader who refused once sees the same sheet again, and re-asking on a timer is a dark pattern the component cannot refuse.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"consent-sheet\" unbuilt=\"false\" importPath=\"@/components/ui/consent-sheet\" dependencies=\"[&#x22;lucide-react&#x22;]\" registryDependencies=\"[&#x22;sheet&#x22;, &#x22;button&#x22;]\" />\n\n```tsx\nimport { ConsentSheet } from \"@/components/ui/consent-sheet\"\n```\n\n```tsx\n<ConsentSheet\n  open={open}\n  onOpenChange={setOpen}\n  consentId=\"example-consent\"\n  textVersion={copy.version}\n  heading={copy.question}\n  purpose={copy.purpose}\n  scope={copy.scope}\n  withdrawalPath={copy.withdrawal}\n  acceptLabel={copy.accept}\n  declineLabel={copy.decline}\n  onDecision={store}\n/>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"consent-sheet\" />\n\n### Closing is not consent [#closing-is-not-consent]\n\nPress a control and `onDecision` receives a record. Leave by any other exit and nothing\narrives: no record, no `false`.\n\n<ComponentPreview name=\"consent-sheet-closing-is-not-consent\" kind=\"example\" align=\"start\" />\n\n### Two questions, two sheets [#two-questions-two-sheets]\n\nNo `purposes` array exists, so two permissions are two sheets and two records. The second\nfollows an answer, never a dismissal, and shows `consequenceOfDeclining`.\n\n<ComponentPreview name=\"consent-sheet-two-questions-two-sheets\" kind=\"example\" align=\"start\" />\n\n### When the wording is missing [#when-the-wording-is-missing]\n\nAny required string blank or absent means the sheet refuses to ask, showing the not-asked\nline and naming the missing fields in the console.\n\n<ComponentPreview name=\"consent-sheet-no-wording-supplied\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;Asking permission to collect, use or share a specific kind of health data.&#x22;,\n  &#x22;Re-asking for a permission whose scope has changed, so the earlier decision no longer covers it.&#x22;,\n  &#x22;Confirming a decision with consequences the reader should see first, such as sharing a record.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;Showing permissions already given, to review or withdraw them.&#x22;, instead: &#x22;card&#x22; },\n  { case: &#x22;The reader must simply acknowledge something before continuing, with no meaningful choice.&#x22;, instead: &#x22;dialog&#x22; },\n  { case: &#x22;You need an operating-system permission, such as notifications; the platform owns that.&#x22;, instead: &#x22;sheet&#x22; },\n  { case: &#x22;The message is the standing not-medical-advice note, not a request.&#x22;, instead: &#x22;disclaimer-note&#x22; },\n  { case: &#x22;You are collecting the data itself rather than the permission to collect it.&#x22;, instead: &#x22;field&#x22; },\n]\"\n/>\n\n## Clinical meaning [#clinical-meaning]\n\n**Asserts.** One specific permission is being asked for, and the reader has been told\nwhat is collected, what it is for, who sees it and how long it is kept.\n\n**Never read as.** A condition of using the product, unless it genuinely is one and the\nsheet says so, and never as permanent, because the sheet says where to withdraw. See\n[Consent and privacy](../health/consent-and-privacy.mdx).\n\n**Colour axis.** Neither. No element carries `data-status` or `data-category`.\nSee [Health](../health/index.mdx).\n\n**Thresholds.** None. The sheet displays no reading. Every consent string\narrives as a prop, because the wording is the product's legal statement\n([Safety review](../health/safety-review.mdx)).\n\n**Closing is not deciding.** Only the two controls call `onDecision`. Escape, scrim,\ndrag and header Close call nothing, so *did not answer* is the absence of a call, never\na stored `false`.\n\n<SafetyCallout severity=\"urgent\" evidence=\"opinion\">\n  No pre-ticked boxes, no default-on switches, no *agree* that is also *continue*, and no\n  sheet that cannot be closed without deciding.\n</SafetyCallout>\n\n## Accessibility [#accessibility]\n\n`heading` is the dialog's accessible name and `purpose` its description, and focus lands\non the sheet. The two decisions are one grid, one `Button` variant at one size, decline\nfirst and never stacked, and the copy carries every meaning so nothing rides on colour.\nThe details trigger is a real button with `aria-expanded` and `aria-controls`. The\naudit's one fix put its focus ring on the decision buttons' `--opsin-border-focus`\ntoken, so a theme that thickens the ring reaches it too. A ring was already visible, so\nno gap closed. `pnpm run check:a11y` holds every commit to no `px` size, raw colour,\nbanned word or element resolving a category or status property.\n\n**Residual items.**\n\n* With `heading` omitted the sheet refuses to ask and the dialog has no accessible name.\n  The component warns in development, so this is invalid usage, not a supported state.\n* The open sheet could not be exercised rendered, so its verdicts rest on source.\n* Focus trap, focus return, dismissal and the swipe close alternative belong to\n  [Sheet](./sheet.mdx) and are verified there.\n\n<KeyboardTable\n  name=\"consent-sheet\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves through the sheet in DOM order: close, scrolling region, disclosure if present, decline, accept&#x22;,\n    notes: &#x22;Focus starts on the sheet.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;The same order in reverse&#x22;,\n    notes: &#x22;Focus is trapped while modal, so the order wraps.&#x22;,\n  },\n  {\n    keys: &#x22;Enter&#x22;,\n    action: &#x22;Activates the control that has focus&#x22;,\n    notes: &#x22;&#x22;,\n  },\n  {\n    keys: &#x22;Space&#x22;,\n    action: &#x22;Activates the control that has focus&#x22;,\n    notes: &#x22;Identical to Enter.&#x22;,\n  },\n  {\n    keys: &#x22;Escape&#x22;,\n    action: &#x22;Closes the sheet without deciding, returning focus to the opener&#x22;,\n    notes: &#x22;onDecision is not called. onOpenChange reports route \\&#x22;escape\\&#x22;.&#x22;,\n  },\n  {\n    keys: &#x22;Arrow keys&#x22;,\n    action: &#x22;Nothing&#x22;,\n    notes: &#x22;Two tab stops, not a radio group.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"consent-sheet\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"ConsentSheetProps\" />\n\n```ts\ninterface ConsentScope { collected: string; sharedWith: string; retention: string }\ninterface ConsentDetails { label: string; content: ReactNode }\ninterface ConsentDecision {\n  granted: boolean; at: string; consentId: string; textVersion: string; scope: ConsentScope\n}\n```\n\n`ConsentSheetProps` extends [SheetProps](./sheet.mdx#props-interface) with `title`,\n`children` and `footer` removed, because `heading` is the title. A whitespace-only string\ncounts as missing. There is no `purposes`, `defaultGranted`, `required`, `hideDecline`,\n`acceptVariant` or `declineVariant`."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/dialog",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/dialog.md",
      "slug": [
        "components",
        "dialog"
      ],
      "section": "Components",
      "title": "Dialog",
      "description": "A window over the page that waits for an answer. It takes your keyboard and attention until you deal with it, and gives them back where it found them.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "modal",
        "alert dialog",
        "popup",
        "confirm"
      ],
      "implements": [],
      "governedBy": [
        "alerts",
        "consent-and-privacy",
        "high-stakes-moments"
      ],
      "usedIn": [
        "alert-escalation",
        "consent-and-permissions"
      ],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"dialog\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;`sheetBelow` is gone because a Sheet is dismissible, and whether an inset panel is the right phone answer stays open.&#x22;,\n  &#x22;A refused Escape re-announces the question, never the reason, and nobody has put a screen reader on that announcement.&#x22;,\n  &#x22;`actions` states a cap of two and cannot enforce it, because `ReactNode` does not say how many controls are inside.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"dialog\" unbuilt=\"false\" importPath=\"@/components/ui/dialog\" dependencies=\"[&#x22;@base-ui/react&#x22;, &#x22;lucide-react&#x22;]\" registryDependencies=\"[&#x22;surface&#x22;, &#x22;button&#x22;]\" />\n\n```tsx\nimport { Dialog } from \"@/components/ui/dialog\"\n```\n\n```tsx\n<Dialog\n  open={open}\n  onOpenChange={setOpen}\n  title=\"Delete this reading?\"\n  description=\"It will be removed from your history and from any trends it appears in.\"\n  actions={\n    <>\n      <Button variant=\"destructive\" onClick={remove}>Delete reading</Button>\n      <Button variant=\"primary\" onClick={() => setOpen(false)}>Keep it</Button>\n    </>\n  }\n/>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"dialog\" />\n\n### Confirming something that cannot be undone [#confirming-something-that-cannot-be-undone]\n\nDestructive first, safest last, where `initialFocus=\"safest\"` lands, so a stray\nReturn keeps the reading.\n\n<ComponentPreview name=\"dialog-confirming-a-deletion\" kind=\"example\" align=\"start\" />\n\n### An answer is needed [#an-answer-is-needed]\n\n`severity=\"alert\"` sets `role=\"alertdialog\"`, removes the close control, and\nrefuses both the scrim and Escape.\n\n<ComponentPreview name=\"dialog-an-answer-is-needed\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;A decision the reader must make before anything else can proceed.&#x22;,\n  &#x22;Confirming an action that cannot be undone or that the reader may not have anticipated.&#x22;,\n  &#x22;A short blocking task, such as re-authenticating before revealing sensitive values.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;The reader could carry on without answering, or you are announcing, not asking.&#x22;, instead: &#x22;alert-banner&#x22; },\n  { case: &#x22;A task the reader chose to start and can abandon.&#x22;, instead: &#x22;sheet&#x22; },\n  { case: &#x22;Asking permission to collect or share health data.&#x22;, instead: &#x22;consent-sheet&#x22; },\n  { case: &#x22;Confirming something that has already happened.&#x22;, instead: &#x22;toast&#x22; },\n  { case: &#x22;Supporting detail attached to a control.&#x22;, instead: &#x22;popover&#x22; },\n]\"\n/>\n\n## Accessibility [#accessibility]\n\nThe rendered pass found no axe violation, undersized target or focus-visible miss, and\nheld at 320px, and the source had no critical, serious or moderate defect.\n\n* `severity=\"alert\"` swaps in Base UI's alert-dialog root, tying the role to the\n  refusal to dismiss.\n* It is named by its title and described by its description. A blank description\n  renders nothing.\n* Focus moves in on open, is trapped, and returns on close to whatever had it.\n* The Close control sinks when pressed, so a tap on the way out shows it landed.\n* The page behind is `aria-hidden`, not `inert`, so focus from behind can still\n  reach it.\n\n**Residual items.** `Dialog.Close` uses a raw `focus-visible` utility, not the\nborder-focus token, but renders a valid 2px offset ring, so 2.4.7 and 1.4.11 pass. It\nmatches the `sheet` close control by design.\n\n<KeyboardTable\n  name=\"dialog\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves focus to the next control inside the dialog&#x22;,\n    notes: &#x22;Trapped; initialFocus=\\&#x22;safest\\&#x22; wraps the first Tab to the top.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Moves focus back to the previous control&#x22;,\n    notes: &#x22;Reverse order matches visual order.&#x22;,\n  },\n  {\n    keys: &#x22;Enter&#x22;,\n    action: &#x22;Activates the focused action&#x22;,\n    notes: &#x22;With initialFocus=\\&#x22;safest\\&#x22;, the answer that changes nothing.&#x22;,\n  },\n  {\n    keys: &#x22;Space&#x22;,\n    action: &#x22;Activates the focused action&#x22;,\n    notes: &#x22;Consumed by the button. The page behind is scroll-locked.&#x22;,\n  },\n  {\n    keys: &#x22;Escape&#x22;,\n    action: &#x22;Closes an ordinary dialog and returns focus to whatever opened it&#x22;,\n    notes: &#x22;The scrim dismisses the same way; both refuse when severity is alert.&#x22;,\n  },\n  {\n    keys: &#x22;Escape&#x22;,\n    action: &#x22;Does not close an alert dialog; moves focus to the dialog itself&#x22;,\n    notes: &#x22;Re-reads the named, described container. The reason is not spoken.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"dialog\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"DialogProps\" />\n\n`actions` and `closeLabel` are not in the specification; `closeLabel` defaults to\n*Close*, ignored on an alert dialog. `onOpenChange` does not fire when Escape is\nrefused. `sheetBelow` is not a prop: the dialog never becomes a Sheet."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/disclaimer-note",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/disclaimer-note.md",
      "slug": [
        "components",
        "disclaimer-note"
      ],
      "section": "Components",
      "title": "DisclaimerNote",
      "description": "The short standing note saying this is information, not medical advice. It is placed by rule, so it is always in the same place and never in the way.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "not medical advice",
        "disclaimer",
        "legal note",
        "safety note",
        "small print"
      ],
      "implements": [],
      "governedBy": [
        "safety-review",
        "health/index",
        "consent-and-privacy",
        "high-stakes-moments",
        "numbers",
        "reference-ranges",
        "trends"
      ],
      "usedIn": [
        "consent-and-permissions",
        "onboarding-and-first-run",
        "result-disclosure",
        "sharing-with-a-clinician"
      ],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"disclaimer-note\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;Whether the rule is one note per screen, per session or per health surface, since the code enforces none of these.&#x22;,\n  &#x22;Whether the note needs a dismiss control, whether a dismissed note returns, and whether the product must record that a reader saw it.&#x22;,\n  &#x22;Whether visible text is the right home for textVersion, or whether the closed data-attribute vocabulary needs a fifth member.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"disclaimer-note\" unbuilt=\"false\" importPath=\"@/components/ui/disclaimer-note\" dependencies=\"[&#x22;lucide-react&#x22;]\" registryDependencies=\"[&#x22;link&#x22;]\" />\n\n```tsx\nimport { DisclaimerNote } from \"@/components/ui/disclaimer-note\"\n```\n\n```tsx\n<DisclaimerNote placement=\"footer\">\n  The product's own two sentences go here. opsinjs ships none of them.\n</DisclaimerNote>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"disclaimer-note\" />\n\n### One note, at the foot of the surface [#one-note-at-the-foot-of-the-surface]\n\nThree rows and one `placement=\"footer\"` note under all of them: not one per row, and\nnever above them.\n\n<ComponentPreview name=\"disclaimer-note-once-at-the-foot-of-a-surface\" kind=\"example\" align=\"start\" />\n\n### When nobody wrote the words [#when-nobody-wrote-the-words]\n\n`children` of `undefined`, `false`, `0`, an empty array or whitespace prints an admission\nand warns in development. Copy in an element is taken at its word.\n\n<ComponentPreview name=\"disclaimer-note-no-text-supplied\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;Any surface that shows a health value, range, status or derived score to the person it belongs to.&#x22;,\n  &#x22;The end of a flow that gathered health information, where the reader may expect an assessment they will not get.&#x22;,\n  &#x22;Wherever a product could be mistaken for a clinical service, such as a symptom questionnaire or a result summary.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;The reader needs to do something now, and the note would sit above the instruction.&#x22;, instead: &#x22;care-card&#x22; },\n  { case: &#x22;The message is specific to one result rather than a standing statement about the product.&#x22;, instead: &#x22;callout&#x22; },\n  { case: &#x22;Something has changed and needs the reader's attention.&#x22;, instead: &#x22;alert-banner&#x22; },\n  { case: &#x22;You are explaining a word rather than the product's limits.&#x22;, instead: &#x22;term&#x22; },\n  { case: &#x22;The reader must acknowledge the statement before continuing, and the product needs a record of it.&#x22;, instead: &#x22;consent-sheet&#x22; },\n]\"\n/>\n\n## Clinical meaning [#clinical-meaning]\n\n**Asserts.** That the product provides information rather than clinical assessment,\ndoes not replace a clinician's advice and, where relevant, is not a medical device.\nThe component supplies position, type size, ink and boundary, and none of the content.\n\n**Never read as.** A waiver or a substitute for designing safely, because a disclaimer\ndoes not make an unsafe screen safe and the\n[safety review](../health/safety-review.mdx) judges the screen. It is never *this number\nis unreliable*, since the note is about the product's role, not the measurement.\n\n**Colour axis.** Neither. There is no `status` or `category` prop, no `data-status` or\n`data-category`, and no fill ([Two colour axes](../health/two-colour-axes.mdx)).\n\n**Thresholds.** None. No clinical number is written into the component and none passes\nthrough it: no threshold, reference range, score band or staleness boundary.\n\n**Words.** The consuming product's, under the rules in [Health](../health/index.mdx).\nopsinjs ships no legal text: no default string, no placeholder, no vetted variant and\nno translation fallback. [Safety review](../health/safety-review.mdx) sets\nout what DCB0129, DCB0160, the EU MDR and FDA SaMD ask of the product.\n\n<SafetyCallout severity=\"attention\" evidence=\"opinion\">\n  This note sets expectations. It never transfers risk onto the reader.\n</SafetyCallout>\n\n## Accessibility [#accessibility]\n\nThe rendered pass was clean, with zero axe violations, the link at its target floor,\nfocus-visible holding and nothing scrolling sideways at 320px or 200% text, and nothing in\nthe source needed changing. Type sizes and colours are role tokens, the decorative glyph\nis `aria-hidden`, the statement is a real paragraph, and the only interactive element is\na real anchor that warns on unhelpful labels. Standing gates cover its one string on\nevery commit: no `px` type size, no raw colour literal, no banned word.\n\n**Residual items.** The root is a plain `<div>` with no `role` and no accessible name, so\na screen reader meets the note as ordinary sentences rather than a bounded \"note\".\nReading order and content are fully conveyed, so this is not an AA failure. The boundary\nis an enhancement left out on purpose, because a `role` is a spec decision reserved to\nreview and an `aria-label` would inject an English string into a translation-neutral\ncomponent.\n\n<KeyboardTable\n  name=\"disclaimer-note\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves to the link, when there is one&#x22;,\n    notes: &#x22;The note is text, not a tab stop. The link is the only focusable part.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Moves back out of the link&#x22;,\n    notes: &#x22;One stop, so reverse order matches visual order.&#x22;,\n  },\n  {\n    keys: &#x22;Enter&#x22;,\n    action: &#x22;Follows the link&#x22;,\n    notes: &#x22;An ordinary anchor, so modifier-clicks keep the browser's behaviour.&#x22;,\n  },\n  {\n    keys: &#x22;Space&#x22;,\n    action: &#x22;Scrolls the page, as it does anywhere else&#x22;,\n    notes: &#x22;Nothing here captures Space.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"disclaimer-note\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"DisclaimerNoteProps\" />\n\n`children` is typed optional and required by the contract, so the missing state can\nrender and print its admission. `placement` changes only the space above the note, and\nthere is no `top` value: never above the result. There is no default text and no\ncolour prop, and an axis class through `className` raises a development warning."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/divider",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/divider.md",
      "slug": [
        "components",
        "divider"
      ],
      "section": "Components",
      "title": "Divider",
      "description": "A thin line that separates two groups of content, with an optional centred label, drawn as a neutral hairline and carrying no status or category colour.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "separator",
        "rule"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"divider\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;The neutral hairline's rendered pixels have not been measured against a card, a sheet or the page, only its token pair is published.&#x22;,\n  &#x22;Nobody has listened to a divider in a screen reader, so neither the separator role nor the labelled form's plain-text label is verified.&#x22;,\n  &#x22;Whether an unlabelled separator should be announced at all, or hidden with every boundary carried by structure, is unresolved.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"divider\" unbuilt=\"false\" importPath=\"@/components/ui/divider\" />\n\n```tsx\nimport { Divider } from \"@/components/ui/divider\"\n```\n\n```tsx\n<Divider />\n<Divider label=\"Earlier\" />\n<Divider orientation=\"vertical\" />\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"divider\" />\n\n### A labelled boundary in a list [#a-labelled-boundary-in-a-list]\n\n`label` marks the seam between today's items and the earlier ones. The two lists\ncarry the grouping on their own; the divider is the visible echo, not the only signal.\n\n<ComponentPreview name=\"divider-a-labelled-group-boundary\" kind=\"example\" align=\"start\" />\n\n### A vertical rule between inline facts [#a-vertical-rule-between-inline-facts]\n\n`orientation=\"vertical\"` draws a hairline that takes its height from the flex row\naround it. In a block that gives it no height it collapses to nothing.\n\n<ComponentPreview name=\"divider-vertical-between-inline-facts\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;Between two stacked groups that are already distinct, to make the seam visible without giving either group a surface of its own.&#x22;,\n  &#x22;As a named boundary in a list, with a short label such as \\&#x22;Earlier\\&#x22; or \\&#x22;Today\\&#x22;, echoing a grouping the list structure already carries.&#x22;,\n  &#x22;As a thin vertical rule between a few inline facts, inside a flex row that gives the rule its height.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;You are grouping content that needs its own background, edge or padding, rather than a line between peers.&#x22;, instead: &#x22;card&#x22; },\n  { case: &#x22;You are separating layers of the interface by depth, such as a panel above the page.&#x22;, instead: &#x22;surface&#x22; },\n  { case: &#x22;You are offering a choice between mutually exclusive views and the lines are really the seams between options.&#x22;, instead: &#x22;segmented-control&#x22; },\n]\"\n/>\n\n## Accessibility [#accessibility]\n\nThe audit changed nothing. The divider is not focusable and captures no key, in either\norientation, labelled or not. Unlabelled, the root exposes `role=\"separator\"` with\n`aria-orientation`, so a reader navigating by region can skip it. Labelled, the root\nhas no role, because a separator cannot carry an accessible name, and the label is\nplain text between two `aria-hidden` hairlines. Every colour is a role token, no type\nsize is in `px`, and no banned word appears.\n\n**Residual items.**\n\n* A divider is never the only carrier of grouping for a screen reader, so the groups\n  either side must be separated by structure too.\n* The hairline's contrast against a card, a sheet and the page, and the labelled\n  form's footnote text against `--muted-foreground`, are not yet measured. Both are\n  shared role token pairs missing from the generated contrast table, so fixing either\n  means editing the token set, outside this component's own file.\n\n<KeyboardTable\n  name=\"divider\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Skips the divider&#x22;,\n    notes: &#x22;Not focusable and not a tab stop, in either orientation, labelled or not.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Skips the divider in reverse&#x22;,\n    notes: &#x22;Focus moves straight to the interactive element before it, in visual order.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"divider\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"DividerProps\" />\n\n`orientation` defaults to `horizontal`; an unknown value is drawn horizontal with\na development warning. `label` applies to the horizontal form only and is dropped\nwith a warning on a vertical rule. A whitespace-only label counts as none.\n`className` is the only route by which colour can reach the component, and both\ncolour axes stay off it."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/dose-tracker",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/dose-tracker.md",
      "slug": [
        "components",
        "dose-tracker"
      ],
      "section": "Components",
      "title": "DoseTracker",
      "description": "A record of medicine doses a product has logged, drawing each as a fact with a word and a shape, never computing adherence or judging a missed dose.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "medication",
        "pill tracker",
        "dose",
        "adherence tracker"
      ],
      "implements": [],
      "governedBy": [
        "health/index",
        "trends",
        "safety-review"
      ],
      "usedIn": [],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"dose-tracker\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;Nothing in the code stops a product summing the taken rows into an adherence figure, or tinting a missed row through className. No lint on a consumer's screen catches it.&#x22;,\n  &#x22;Nobody has listened to this list in a screen reader. Whether the note is heard as part of its entry, and whether the list needs its own name, is untested.&#x22;,\n  &#x22;No contrast pair has been measured. Each marker is a neutral hairline chip on whatever ground the host provides, so the floors are argued rather than checked.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"dose-tracker\" unbuilt=\"false\" importPath=\"@/components/ui/dose-tracker\" dependencies=\"[&#x22;lucide-react&#x22;]\" registryDependencies=\"[&#x22;relative-time&#x22;]\" />\n\n```tsx\nimport { DoseTracker } from \"@/components/ui/dose-tracker\"\n```\n\n```tsx\n<DoseTracker\n  label=\"Today's doses\"\n  now={new Date().toISOString()}\n  entries={[\n    { name: \"Morning tablet\", time: \"2026-03-14T08:00:00+00:00\", state: \"taken\" },\n    { name: \"Afternoon tablet\", time: \"2026-03-14T15:00:00+00:00\", state: \"missed\" },\n  ]}\n/>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"dose-tracker\" />\n\n### A day's doses [#a-days-doses]\n\nA day's medicines as the product logged them, some taken, one missed, one skipped, driven by each entry's `state`. In greyscale the states are still told apart by their words and shapes.\n\n<ComponentPreview name=\"dose-tracker-a-days-doses\" kind=\"example\" align=\"start\" />\n\n### A missed dose [#a-missed-dose]\n\nOne `state=\"missed\"` entry, shown as a fact and left there: a word, a shape, a time, no red, no next step and no adherence figure.\n\n<ComponentPreview name=\"dose-tracker-a-missed-dose\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;A record of medicine doses the product has already logged, taken and missed together, read as history.&#x22;,\n  &#x22;A day's doses as plain facts, each state a word and a shape beside its time, nothing computed across rows.&#x22;,\n  &#x22;Anywhere the product owns the schedule and the drug data and needs only the log drawn.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;You are logging a general daily entry, such as a symptom or a note, not a dose with a state.&#x22;, instead: &#x22;log-sheet&#x22; },\n  { case: &#x22;You need to tell the reader what to do next. That is advice, and this component asserts only facts.&#x22;, instead: &#x22;care-card&#x22; },\n  { case: &#x22;You are showing a single reading or figure rather than a list of dose events.&#x22;, instead: &#x22;metric-tile&#x22; },\n]\"\n/>\n\n## Clinical meaning [#clinical-meaning]\n\n**Asserts.** Exactly the log the product handed it: these medicines, at these times, in these states. A \"Missed\" marker says the product recorded that dose as missed, and nothing further.\n\n**Never read as.** Advice, a diagnosis, an adherence score or an instruction. A \"Missed\" row names a fact, never a fault or a next step, and no percentage is computed, because that would be a clinical figure nobody authored. [Health](../health/index.mdx) draws the line between recording a fact and prescribing a response.\n\n**Colour axis.** Neither. A dose state is a fact, not a level of urgency, so no marker carries `data-status` or `data-category`. Each marker is neutral chrome with a word and a distinct shape, so the four states survive greyscale. Painting a missed dose the red that means \"act now\" is the axis mixing [Two colour axes](../health/two-colour-axes.mdx) forbids.\n\n**Thresholds.** The consuming product, always. DoseTracker ships no schedule, no drug data, no dose, no threshold and no default text, because each would be a clinical claim [Safety review](../health/safety-review.mdx) says a presentation layer cannot make.\n\n**Time.** Each entry's `time` and `now` go to [RelativeTime](./relative-time.mdx) unmodified, so it owns what a stale or future instant renders as. [Trends and uncertainty](../health/trends.mdx) is the rule it keeps.\n\n## Accessibility [#accessibility]\n\nThe rendered pass was clean and the source needed no change. Each marker shape is `aria-hidden` beside a visible word (1.1.1), a real `ul`/`li` carries the list semantics (1.3.1), and each state is told by a word and a distinct lucide shape, with no status colour, category colour or colour literal. Icons are em-sized, so at 200% text they grow with the step and the times wrap rather than clip, and no type size is in `px`.\n\n**Residual items.**\n\n* The list's accessible name comes only from `label`, as an `aria-label`. Every example supplies one, but a persistent visible label is a recommended enhancement.\n* No `aria-live` region is announced: this static read-only log renders once and never updates in place, so 4.1.3 owes no status message.\n* With no interactive element, target size (2.5.8), focus visibility and keyboard operation do not apply.\n* Every contrast pair of hairline and muted ink against the host ground is unmeasured, and so are the markers under `forced-colors: active`.\n\n<KeyboardTable\n  name=\"dose-tracker\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Skips the whole component&#x22;,\n    notes: &#x22;Nothing is focusable. The tracker is a record to read, not a control.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Skips the whole component&#x22;,\n    notes: &#x22;Same in reverse. Never in the focus order.&#x22;,\n  },\n  {\n    keys: &#x22;Arrow keys&#x22;,\n    action: &#x22;Nothing&#x22;,\n    notes: &#x22;Nothing to select, move or expand. The entries are static content.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"dose-tracker\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"DoseTrackerProps\" />\n\nAn empty `entries` array renders nothing and warns in development. A `state` outside the four renders its row with no marker and warns, never approximated into a shape. `now` is required: read the clock once per screen and pass the same instant to every timestamp. `label` is the list's `aria-label`."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/empty-state",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/empty-state.md",
      "slug": [
        "components",
        "empty-state"
      ],
      "section": "Components",
      "title": "EmptyState",
      "description": "What a screen shows before there is anything on it. It says plainly why it is empty and gives you one clear thing to do about it.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "blank slate",
        "no data",
        "nothing here",
        "zero state"
      ],
      "implements": [],
      "governedBy": [
        "consent-and-privacy",
        "trends"
      ],
      "usedIn": [
        "consent-and-permissions",
        "daily-logging",
        "empty-and-first-use",
        "onboarding-and-first-run",
        "trend-review"
      ],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"empty-state\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;Whether an empty state may carry a primary action the reader cannot yet take, such as during a device sync.&#x22;,\n  &#x22;Whether an illustration ever helps beside an absence of somebody's own health data has not been researched here.&#x22;,\n  &#x22;A view that becomes empty should be announced once, but this component mounts no live region and nothing says what the region does.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"empty-state\" unbuilt=\"false\" importPath=\"@/components/ui/empty-state\" registryDependencies=\"[&#x22;button&#x22;, &#x22;link&#x22;]\" />\n\n```tsx\nimport { EmptyState } from \"@/components/ui/empty-state\"\n```\n\n```tsx\n<EmptyState\n  reason=\"nothing-yet\"\n  title=\"No readings yet\"\n  action={{ label: \"Add a reading\", href: \"/readings/new\" }}\n>\n  Once you add your first reading it will be here, with the range your product\n  compares it against.\n</EmptyState>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"empty-state\" />\n\n### A filter matched nothing [#a-filter-matched-nothing]\n\n`reason=\"no-matches\"` with an `onSelect` that clears the filter. The list owns the\nlive region and moves focus when the control unmounts.\n\n<ComponentPreview name=\"empty-state-a-filter-matched-nothing\" kind=\"example\" align=\"start\" />\n\n### What happens when nobody wrote the body [#what-happens-when-nobody-wrote-the-body]\n\nThe first card has no `children`, so it admits the app does not say why and\nwarns. The second has two sentences.\n\n<ComponentPreview name=\"empty-state-no-copy-supplied\" kind=\"example\" align=\"start\" />\n\n### An illustration, and what it is not allowed to do [#an-illustration-and-what-it-is-not-allowed-to-do]\n\n`illustration` is `aria-hidden` and `inert`, hidden in print and below 17rem.\nCover it and the state still reads whole.\n\n<ComponentPreview name=\"empty-state-with-an-illustration\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;Nothing added yet, where the fastest help is the first step.&#x22;,\n  &#x22;A filter or search that matched nothing, where the reader must know it was the filter, not the data.&#x22;,\n  &#x22;A view that cannot yet draw honestly, such as a trend with too few readings.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;The content is loading and will arrive shortly.&#x22;, instead: &#x22;skeleton&#x22; },\n  { case: &#x22;The whole view failed, rather than one surface that could not load.&#x22;, instead: &#x22;alert-banner&#x22; },\n  { case: &#x22;There is content, but it needs a caveat.&#x22;, instead: &#x22;callout&#x22; },\n  { case: &#x22;Permission is needed before anything can be shown.&#x22;, instead: &#x22;consent-sheet&#x22; },\n  { case: &#x22;One value is missing inside a full surface.&#x22;, instead: &#x22;value&#x22; },\n]\"\n/>\n\n## Accessibility [#accessibility]\n\nNeither colour axis is used, so nothing can mix. `titleLevel` renders a real `h2` to\n`h6`, default `2`, so check it against the outline. The `could-not-load` flag carries\nits meaning in a word beside an `aria-hidden` icon, not colour, and the `href` action is\nan anchor floored at `var(--opsin-target-minimum, 2.75rem)` on both axes. The default\npreview renders clean on `/view`, and the audit changed nothing.\n\n**Residual items.**\n\n* No live region mounts, by design. On a stateless, read-only render one could only\n  mis-fire, since it announces only changes made after first paint. The announcement\n  belongs to whatever region changed, which the caller owns, as the filter example shows.\n* The three example files were audited from source alone.\n* Contrast against the card surface is unmeasured, and the report below carries it.\n\n<KeyboardTable\n  name=\"empty-state\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves focus to the action, then to the quieter alternative&#x22;,\n    notes: &#x22;Nothing else is focusable. No action means no tab stop.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Moves focus back through the same controls&#x22;,\n    notes: &#x22;Reverse order matches visual order.&#x22;,\n  },\n  {\n    keys: &#x22;Enter&#x22;,\n    action: &#x22;Activates whichever control has focus&#x22;,\n    notes: &#x22;href follows the destination, onSelect calls the handler.&#x22;,\n  },\n  {\n    keys: &#x22;Space&#x22;,\n    action: &#x22;Activates the onSelect form only&#x22;,\n    notes: &#x22;The platform's button and link distinction. No page scroll.&#x22;,\n  },\n  {\n    keys: &#x22;After activation&#x22;,\n    action: &#x22;The caller's, not this component's&#x22;,\n    notes: &#x22;An onSelect that unmounts the state drops focus to body. Move it.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"empty-state\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"EmptyStateProps\" />\n\n`reason` and `title` are required. There is no exported `EmptyReason` type, so\nname the union `EmptyStateProps[\"reason\"]`. A blank `title`, a body with no\ntext or only a number, and an action with nothing to do each render a fallback and\nwarn once. A `secondary` with no `action` also warns."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/field",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/field.md",
      "slug": [
        "components",
        "field"
      ],
      "section": "Components",
      "title": "Field",
      "description": "The wrapper that gives every input a visible label, hint, error message and the wiring between them. It is why no control here can ship without a name.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "form field",
        "label",
        "input wrapper",
        "error message",
        "hint",
        "form control",
        "validation message"
      ],
      "implements": [],
      "governedBy": [
        "consent-and-privacy"
      ],
      "usedIn": [
        "ask-users-for",
        "daily-logging",
        "forms",
        "onboarding-and-first-run"
      ],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"field\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;Field ships required and optional with no prop to translate them, and whether a prop or a locale object fixes that is open.&#x22;,\n  &#x22;Whether Field exposes its generated ids to an error summary is open.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"field\" unbuilt=\"false\" importPath=\"@/components/ui/field\" dependencies=\"[&#x22;@base-ui/react&#x22;, &#x22;lucide-react&#x22;]\" />\n\n```tsx\nimport { Field } from \"@/components/ui/field\"\n```\n\n```tsx\n<Field label=\"Example measurement\" hint=\"For example, 14\">\n  <Field.Control name=\"example-measurement\" inputMode=\"decimal\" autoComplete=\"off\" />\n</Field>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"field\" />\n\n### The error keeps the hint [#the-error-keeps-the-hint]\n\n`error` adds a sentence beside the hint rather than replacing it.\n\n<ComponentPreview name=\"field-error-keeps-the-hint\" kind=\"example\" align=\"start\" />\n\n### Marking the exception [#marking-the-exception]\n\nOne optional field among three needed ones, marked by `optionality=\"optional\"`.\nSee [Forms](../patterns/forms.mdx).\n\n<ComponentPreview name=\"field-marking-the-exception\" kind=\"example\" align=\"start\" />\n\n### A control opsinjs does not ship [#a-control-opsinjs-does-not-ship]\n\n`render` on `Field.Control` puts the whole wiring onto a `textarea` and a\n`select`.\n\n<ComponentPreview name=\"field-with-another-control\" kind=\"example\" align=\"start\" />\n\n### Validating on submit [#validating-on-submit]\n\nThe default `validateOn` fires on submit only inside `Field.Form`, where an\nempty field on Save shows the browser's own message. Pass `error` instead.\n\n<ComponentPreview name=\"field-validating-on-submit\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;Every input in the system, where a Field is the label guarantee.&#x22;,\n  &#x22;Any control needing a hint or error wired to it, not merely placed nearby.&#x22;,\n  &#x22;As the base for purpose-built inputs, the way ReadingInput is built.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;A measurement with a unit and a plausible range.&#x22;, instead: &#x22;reading-input&#x22; },\n  { case: &#x22;The control is an action, not an input.&#x22;, instead: &#x22;button&#x22; },\n  { case: &#x22;Several related inputs are captured in one interaction.&#x22;, instead: &#x22;log-sheet&#x22; },\n  { case: &#x22;You are showing a value, not collecting one.&#x22;, instead: &#x22;value&#x22; },\n  { case: &#x22;A failed form's errors need summarising at the top.&#x22;, instead: &#x22;alert-banner&#x22; },\n]\"\n/>\n\n## Accessibility [#accessibility]\n\nA native `label` points at a generated id, `aria-describedby` survives unmount,\n`aria-invalid` sits on the control, and the invalid state is a glyph and a left rule,\nnever colour. The audit gave the error a live region, so it is announced on submit\nwhile focus is on Save, where it was silent before. Rendered, it shows no axe\nviolation and no reflow at 320px, targets meet `--opsin-target-minimum`, and focus is\nvisible. `pnpm run check:a11y` guards role tokens and non-`px` sizes.\n\n**Residual items.**\n\n* The required and optional word is English only and untranslatable by prop.\n* The focus ring lives in `product.css`, so a `shadcn add` copy without it shows no\n  ring until you add one.\n* The invalid shadow drops under forced colours and print, where the glyph, words and\n  rule still carry the state.\n\n<KeyboardTable\n  name=\"field\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves focus to the control&#x22;,\n    notes: &#x22;Only the control is focusable.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Moves focus back out of the control&#x22;,\n    notes: &#x22;Reverse order matches visual order.&#x22;,\n  },\n  {\n    keys: &#x22;Enter&#x22;,\n    action: &#x22;Asks the control to check itself, and submits an enclosing form&#x22;,\n    notes: &#x22;Focus does not move and nothing is announced.&#x22;,\n  },\n  {\n    keys: &#x22;Escape&#x22;,\n    action: &#x22;Nothing&#x22;,\n    notes: &#x22;Not a popup. The key reaches a dialog.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"field\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"FieldProps\" />\n\n`label` is required and there is no `hideLabel`. An empty `label` or `error` is\nrefused with a development warning. Without a `Field.Form` ancestor the default\n`validateOn` checks on Enter alone.\n\n<PropsTable name=\"FieldControlProps\" />\n\n### Data attributes [#data-attributes]\n\n<DataAttributesTable\n  name=\"field\"\n  rows=\"[\n  {\n    attribute: &#x22;data-slot&#x22;,\n    condition: &#x22;Root, label and control always; optionality, hint and error only when that part renders; Field.Form where mounted.&#x22;,\n    value: &#x22;field, field-label, field-optionality, field-hint, field-error, field-control, field-form&#x22;,\n  },\n  {\n    attribute: &#x22;data-invalid&#x22;,\n    condition: &#x22;On the root and control, when error is non-empty or a constraint fails.&#x22;,\n    value: &#x22;Present with no value when invalid; absent otherwise&#x22;,\n  },\n]\"\n/>"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/goal-ring",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/goal-ring.md",
      "slug": [
        "components",
        "goal-ring"
      ],
      "section": "Components",
      "title": "GoalRing",
      "description": "A ring that shows how far a reading has come towards a goal the product set, paired with a text twin that states every figure, and rewarding no streak.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "activity ring",
        "close your rings",
        "daily goal"
      ],
      "implements": [],
      "governedBy": [
        "two-colour-axes",
        "numbers",
        "alerts"
      ],
      "usedIn": [],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"goal-ring\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;No contrast pair has been measured: the fill and the track sit on whatever ground the host paints, not a matching surface the token contract tunes against.&#x22;,\n  &#x22;Nobody has listened to the ring in a screen reader, so whether the accessible name and the same three visible lines read as thorough or as a stammer is unheard.&#x22;,\n  &#x22;No gate stops a product composing a streak counter beside the ring, which undoes the refusal to reward a streak that the code keeps.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"goal-ring\" unbuilt=\"false\" importPath=\"@/components/ui/goal-ring\" />\n\n```tsx\nimport { GoalRing } from \"@/components/ui/goal-ring\"\n```\n\n```tsx\n<GoalRing\n  label=\"Steps today\"\n  value={6200}\n  goal={8000}\n  unit=\"steps\"\n  category=\"activity\"\n/>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"goal-ring\" />\n\n### Progress towards a goal [#progress-towards-a-goal]\n\nA synthetic step count part-way towards a goal the product set.\n`category=\"activity\"` tints the fill and the sentence beneath names the progress\nwithout praise.\n\n<ComponentPreview name=\"goal-ring-progress-to-a-goal\" kind=\"example\" align=\"start\" />\n\n### No reading yet [#no-reading-yet]\n\n`value={null}` draws an empty ring and words that say nothing has been measured,\nnever a zero.\n\n<ComponentPreview name=\"goal-ring-no-reading-yet\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;A single reading against a goal the product set, where the goal is the product's own rather than a clinical target.&#x22;,\n  &#x22;A daily count that resets, such as steps, active minutes or water, where the words carry the exact figures.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;A composite number the product calculated, with named bands. That is a score against a scale, not progress towards a goal.&#x22;, instead: &#x22;score-dial&#x22; },\n  { case: &#x22;One reading on its own, with its unit and when it was taken, and no goal to measure it against.&#x22;, instead: &#x22;metric-tile&#x22; },\n  { case: &#x22;A reading against a reference range, where the meaning is which band it falls in rather than how far along a target it is.&#x22;, instead: &#x22;range-bar&#x22; },\n]\"\n/>\n\n## Clinical meaning [#clinical-meaning]\n\n**Asserts.** One thing: this value is this far towards a goal the product set,\nand the fraction is arithmetic over the two values. The readout prints both in\nthe [reader's locale](../health/numbers.mdx), unit after, and the fill is drawn\nwhere the reading sits, with [nothing sweeping](../health/alerts.mdx) on first\npaint.\n\n**Never read as.** A diagnosis, a verdict on the reader, or a target opsinjs\nchose. A full ring means the product's goal was met, never that the reader is\nwell, and an open ring never means something is wrong. It rewards no streak, and\n\"normal\" and \"abnormal\" appear in\n[no state it draws](../health/reference-ranges.mdx).\n\n**Colour axis.** Category only. The fill takes the identity tint of what the\nring counts, the track stays neutral, and no element carries `data-status`. See\n[Two colour axes](../health/two-colour-axes.mdx).\n\n**Thresholds.** None. The product owns the goal, the label and the unit;\nGoalRing ships no default goal and no clinical vocabulary.\n\n## Accessibility [#accessibility]\n\n**Checked by `pnpm run check:a11y` on every commit.**\n\n* No element carries both axes: the fill carries `data-category` alone and nothing stamps `data-status`.\n* No raw colour literal and no ramp step. The plate, the face and the groove are mixed from the card and foreground roles, and the fill is the category accent role.\n* No type size in pixels: the label, the figure, the goal beside it and the sentence are the `subheadline`, `title1`, `body` and `footnote` steps.\n\nThe fill had drawn in the inherited ink rather than its category, because its class named a utility the theme does not declare; it is fixed. The graphic is `role=\"img\"`\nwith an accessible name that speaks the label, the value against the goal and the\nprogress sentence, all repeated in the visible words beside it. Nothing takes\nfocus or animates on first paint, so there is no keyboard contract. Three states\nstay three: a finite value draws a fill, null says \"no reading yet\", and a broken\nvalue says \"not available\". Under forced colours the plate maps to Canvas, the track\nto CanvasText and the fill to Highlight.\n\n**Residual items.**\n\n* No contrast pair is measured, so the page prints the contrast pairs as unmeasured rather than as a pass.\n* The arc and track repeat every fact in the visible text and the accessible name, so under SC 1.4.11 they are not graphical objects required to understand the content.\n* A read-only display carries no live region, so a screen reader is not told when the value changes over time. The product owns whether to wrap the ring in one.\n\n<KeyboardTable\n  name=\"goal-ring\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Skips the whole component&#x22;,\n    notes: &#x22;A labelled image, not a control.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Skips the whole component&#x22;,\n    notes: &#x22;Never in the focus order.&#x22;,\n  },\n  {\n    keys: &#x22;Arrow keys&#x22;,\n    action: &#x22;Nothing&#x22;,\n    notes: &#x22;Nothing to select or change.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"goal-ring\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"GoalRingProps\" />\n\n`value` is `number | null`: null is no reading and is never drawn as zero, and a\nnon-finite value is announced as \"not available\". A goal of zero or less draws\nan empty ring and raises a development warning. `category` outside the six\nknown names is refused with a development warning and the fill falls back to\nneutral.\n\n### Data attributes [#data-attributes]\n\n<DataAttributesTable\n  name=\"goal-ring\"\n  rows=\"[\n  {\n    attribute: &#x22;data-slot&#x22;,\n    condition: &#x22;On the root and every part but the svg, always&#x22;,\n    value: &#x22;goal-ring, goal-ring-track, goal-ring-fill, goal-ring-words, goal-ring-label, goal-ring-value, goal-ring-derivation&#x22;,\n  },\n  {\n    attribute: &#x22;data-category&#x22;,\n    condition: &#x22;On the fill, while it is drawn with a known category&#x22;,\n    value: &#x22;The category name, such as activity. Absent when no category is given.&#x22;,\n  },\n]\"\n/>"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/icon-button",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/icon-button.md",
      "slug": [
        "components",
        "icon-button"
      ],
      "section": "Components",
      "title": "IconButton",
      "description": "A button whose only visible content is an icon, so it always needs an accessible name you supply. Prefer a labelled button where there is room for a word.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "glyph button",
        "round button"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"icon-button\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;No contrast pair has been measured for the glyph against any variant's fill or for the focus ring, and Button's own unmeasured pairs are inherited.&#x22;,\n  &#x22;Nobody has listened to this control in a screen reader, so whether the name set twice reads as one name or two is unheard.&#x22;,\n  &#x22;Forced colours and prefers-contrast are unhandled, inherited from Button, and a quiet icon button carrying only ink may not survive a palette that replaces author ink.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"icon-button\" unbuilt=\"false\" importPath=\"@/components/ui/icon-button\" dependencies=\"[&#x22;lucide-react&#x22;]\" registryDependencies=\"[&#x22;button&#x22;]\" />\n\n```tsx\nimport { IconButton } from \"@/components/ui/icon-button\"\n```\n\n```tsx\nimport { Search } from \"lucide-react\"\n\n<IconButton\n  icon={<Search />}\n  label=\"Search readings\"\n  onClick={openSearch}\n/>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"icon-button\" />\n\n### A toolbar of icon buttons [#a-toolbar-of-icon-buttons]\n\nA header row where each glyph is one the reader already knows, and each control still\ncarries a distinct `label`.\n\n<ComponentPreview name=\"icon-button-toolbar\" kind=\"example\" align=\"start\" />\n\n### Icon buttons in a list row [#icon-buttons-in-a-list-row]\n\nEdit and Remove repeat on every row as icon buttons. Each `label` carries its row's\ncontext, so a voice-control user reaches one control.\n\n<ComponentPreview name=\"icon-button-list-row\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;A dense toolbar or card header where a universally understood glyph, such as a close cross, stands in for a word that would not fit.&#x22;,\n  &#x22;A repeated action in a list or table row, where a labelled button on every row would crowd the content out.&#x22;,\n  &#x22;A secondary control beside a labelled primary, where the reader has already taken in the row's context.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;There is room for a word. A short verb beats a glyph almost everywhere.&#x22;, instead: &#x22;button&#x22; },\n  { case: &#x22;The control turns something on or off, where a glyph reads as a state rather than an action.&#x22;, instead: &#x22;switch&#x22; },\n  { case: &#x22;You were about to explain the icon through a hover tooltip. There is no hover on a phone.&#x22;, instead: &#x22;tooltip&#x22; },\n]\"\n/>\n\n## Accessibility [#accessibility]\n\nA real `button` element through [Button](./button.mdx) supplies Return, Space, the role\nand the tab stop. The control is icon-only by design, so `aria-label` plus a visually\nhidden text node is its correct and complete name route rather than a persistent visible\nlabel, and the glyph is `aria-hidden`, never announced as a second, pictorial name. The\naudit found no critical, serious or moderate defect in the source, and\n`pnpm run check:a11y` confirms on every commit that every colour is a role token, no\ntype size is in `px`, and no banned word appears anywhere.\n\n**Residual items.**\n\n* A missing or whitespace-only `label` raises a development warning.\n* The target is a 44pt square in rem with horizontal padding removed, and separation is\n  left to the caller's `--opsin-target-separation`.\n* Contrast on every variant, the focus ring, and forced colours are not measured, and\n  all are inherited from Button.\n\n<KeyboardTable\n  name=\"icon-button\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves focus to the icon button&#x22;,\n    notes: &#x22;One tab stop for the whole control. The glyph and name are parts, not stops.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Moves focus back out, to whatever precedes it&#x22;,\n    notes: &#x22;Reverse order matches the visual order. The component never moves focus of its own accord.&#x22;,\n  },\n  {\n    keys: &#x22;Enter&#x22;,\n    action: &#x22;Activates the button&#x22;,\n    notes: &#x22;Platform behaviour on a real button element, inherited from Button. Nothing here intercepts it.&#x22;,\n  },\n  {\n    keys: &#x22;Space&#x22;,\n    action: &#x22;Activates the button&#x22;,\n    notes: &#x22;Consumed by the focused button, so the page does not scroll.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"icon-button\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"IconButtonProps\" />\n\n`icon` and `label` are both required. `variant` defaults to `secondary` over\n`quiet`, since a bordered control is easier to recognise without a word inside\nit. There is no `busy`, `busyLabel`, `fullWidth`, `iconPosition` or `type`.\n`className` must never resolve a `--opsin-status-*` or `--opsin-category-*`\nrole; an IconButton carries no clinical axis."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/link",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/link.md",
      "slug": [
        "components",
        "link"
      ],
      "section": "Components",
      "title": "Link",
      "description": "The control that takes the reader elsewhere, and the one place the system decides how a navigation link looks, so a banner's action and a card's match.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "anchor",
        "hyperlink"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"link\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;The render slot is untested against Next or React Router, so a router element that draws its own focus ring, or strips className, could leave two rings or none.&#x22;,\n  &#x22;No contrast pair for the three emphases has been measured, and whether the ladder holds in greyscale without hue is argued, not tested.&#x22;,\n  &#x22;On a status tint an action link takes a per-level boundary colour the caller supplies, and that colour has not been measured against the four tints in either theme.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"link\" unbuilt=\"false\" importPath=\"@/components/ui/link\" registryDependencies=\"[&#x22;button&#x22;]\" />\n\n```tsx\nimport { Link } from \"@/components/ui/link\"\n```\n\n```tsx\n<Link href=\"/results\" emphasis=\"action\">\n  See your results\n</Link>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"link\" />\n\n### Each emphasis [#each-emphasis]\n\n`emphasis` is required and has no default. `inline` sits inside a sentence,\n`action` is a card's primary action and `secondary` is the quiet one beside it.\n\n```tsx\n<p>\n  Your readings are yours to keep, and you can{\" \"}\n  <Link href=\"/how-it-works\" emphasis=\"inline\">\n    read how this measurement is worked out\n  </Link>{\" \"}\n  before you share them.\n</p>\n\n<Link href=\"/appointments/new\" emphasis=\"action\">\n  Book a repeat appointment\n</Link>\n\n<Link href=\"/about/this-measurement\" emphasis=\"secondary\">\n  Read about this measurement\n</Link>\n```\n\n### Routing through the product's own link [#routing-through-the-products-own-link]\n\nPass the router link as `render` so navigation stays client-side. Link merges\nits classes, its `data-slot` and its target floor onto that element and replaces\nits children with the label.\n\n```tsx\nimport NextLink from \"next/link\"\nimport { Link } from \"@/components/ui/link\"\n\n<Link href=\"/results\" emphasis=\"action\" render={<NextLink href=\"/results\" />}>\n  See your results\n</Link>\n```\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;Navigation to another page or view, written in the reader's own words for the destination.&#x22;,\n  &#x22;A card's or a banner's primary action when it produces a new URL, as the action emphasis.&#x22;,\n  &#x22;A quieter secondary action beside that primary one, as the secondary emphasis, which differs by a smaller box and no boundary.&#x22;,\n  &#x22;A reference inside a sentence that opens a source or a related page, as the inline emphasis, underlined and reflowing with the paragraph.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;The control does something rather than going somewhere: saving a reading, submitting a form, confirming a decision. Button refuses href.&#x22;, instead: &#x22;button&#x22; },\n  { case: &#x22;The whole card is the destination and the entire surface should be one target. Card carries its own wrapper anchor.&#x22;, instead: &#x22;card&#x22; },\n]\"\n/>\n\n## Accessibility [#accessibility]\n\nOn every commit `pnpm run check:a11y` confirms every colour is a role token, no type\nsize is in `px` and no banned word appears. The audit fixed two moderate gaps.\n\n* A `target=\"_blank\"` link now defaults `rel` to `noopener noreferrer`, keeping any `rel`\n  the caller supplied, and appends an `sr-only` \"(opens in a new tab)\" tail so the change\n  of destination is spoken (2.4.4).\n* The `inline` focus ring now reads `--opsin-border-focus`, so it grows when a low-vision\n  consumer raises that token. It still defaults to 2px, so nothing changes visually\n  (2.4.7, 1.4.11).\n\n**Residual items.**\n\n* The new-tab cue is spoken only through `sr-only` text, not a visible marker, to\n  preserve the visual design. A caller who wants a visible external cue adds their own.\n* `inline` sits below the 24px target floor by design, because SC 2.5.8 exempts an inline\n  target inside a sentence and a full floor would inflate the line box. `action` and\n  `secondary` keep the `--opsin-target-minimum` floor in both axes.\n* Contrast for the three emphases and for the per-level boundary on a status tint is not\n  yet measured, and whether the ladder holds in greyscale is argued rather than tested.\n\n<ContrastReport component=\"link\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"LinkProps\" />\n\n`href` and `emphasis` are both required, with no default for either. `ground`\ndefaults to `neutral` and is inert for `inline`. When `render` is passed, Link's\nown `href`, `data-slot` and attributes win over the router element's, and the\ntwo class lists are joined."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/log-sheet",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/log-sheet.md",
      "slug": [
        "components",
        "log-sheet"
      ],
      "section": "Components",
      "title": "LogSheet",
      "description": "A small sheet that slides up so you can record something in a few seconds without leaving the screen you were on. One reading, one dose, one note.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "log",
        "capture",
        "quick entry",
        "bottom sheet entry",
        "diary",
        "journal",
        "daily entry"
      ],
      "implements": [],
      "governedBy": [
        "numbers",
        "consent-and-privacy"
      ],
      "usedIn": [
        "daily-logging"
      ],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"log-sheet\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;The field ceiling is unenforced because React.Children sees direct children only, so is the answer a lint rule, a fields prop, or a rule people follow?&#x22;,\n  &#x22;The sheet cannot tell a duplicate reading from a real second measurement minutes later, so should the entry carry something that lets the product decide?&#x22;,\n  &#x22;Daily logging names six entry states, LogSheet expresses only draft through onDiscard, and where saving, queued, conflict, failed and first use belong is open.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"log-sheet\" unbuilt=\"false\" importPath=\"@/components/ui/log-sheet\" registryDependencies=\"[&#x22;sheet&#x22;, &#x22;field&#x22;, &#x22;button&#x22;]\" />\n\n```tsx\nimport { LogSheet } from \"@/components/ui/log-sheet\"\n```\n\n```tsx\n<LogSheet\n  open={open}\n  onOpenChange={setOpen}\n  title=\"An example entry\"\n  values={values}\n  saveLabel=\"Save the example entry\"\n  onSave={(entry) => store(entry)}\n>\n  <Field label=\"Example measurement\">\n    <Field.Control value={held ?? \"\"} onChange={write} />\n  </Field>\n</LogSheet>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"log-sheet\" />\n\n### Leaving with unsaved input [#leaving-with-unsaved-input]\n\nEscape, the background, a drag and the close control all ask the same question in the\nfooter. `onDiscard` receives the entry about to be lost.\n\n<ComponentPreview name=\"log-sheet-leaving-with-unsaved-input\" kind=\"example\" align=\"start\" />\n\n### Two fields, and the window the product owns [#two-fields-and-the-window-the-product-owns]\n\nTwo controls write two keys into one entry through `values`. `maxBackdateDays` sets the\npicker's earliest day, and the sheet still refuses no save.\n\n<ComponentPreview name=\"log-sheet-two-fields-and-a-backdate-window\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;Recording one thing the reader does repeatedly: a reading, a dose, a symptom or a note.&#x22;,\n  &#x22;Capture that must not lose the reader's place, from a dashboard or a notification.&#x22;,\n  &#x22;An entry that should take under fifteen seconds one-handed.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;The entry needs more than about five fields, or branching questions.&#x22;, instead: &#x22;field&#x22; },\n  { case: &#x22;The questions form an assessment rather than a record.&#x22;, instead: &#x22;questionnaire&#x22; },\n  { case: &#x22;You need permission before you can store what is being logged.&#x22;, instead: &#x22;consent-sheet&#x22; },\n  { case: &#x22;There is exactly one numeric value with a unit and nothing else.&#x22;, instead: &#x22;reading-input&#x22; },\n  { case: &#x22;You are showing what was logged rather than capturing it.&#x22;, instead: &#x22;result-card&#x22; },\n]\"\n/>\n\n## Clinical meaning [#clinical-meaning]\n\n**Asserts.** That the reader recorded this value, at this time, themselves.\n`LogEntry.provenance` is the literal `\"self-reported\"` and no prop changes it. See\n[Trends and uncertainty](../health/trends.mdx).\n\n**Never read as.** A clinical observation or an assessment. The sheet never evaluates\nwhat is entered or says whether it is worth acting on.\n\n**Colour axis.** Category only, on one band beneath the heading carrying `data-category`\nwith no word and no glyph. The status axis never appears here.\n\n**Thresholds.** None. LogSheet holds no ranges and never blocks a save, so an unlikely\nvalue still saves, and a plausibility warning belongs on [ReadingInput](./reading-input.mdx).\n`maxBackdateDays` has no default and constrains the platform picker, not the save.\n\n**Timing.** `occurredAt` is the time the entry is about and `recordedAt` the save time.\n`backdated` is true only when the reader moved the time control.\n\n## Accessibility [#accessibility]\n\nBoth inputs take their name and description from [Field](./field.mdx), so name, role\nand value hold. The only coloured element is the `aria-hidden` category band, and the\nsingle tokenised column reflows and scales. `axe` on the static rendered page is clean,\nbut the open sheet was not re-measured in a browser.\n\n**Residual items.** All three are argued, not measured.\n\n* The discard question is announced by a focus move and `aria-describedby`, not a live\n  region. A second modal was declined on purpose.\n* No *Saved* status is announced. `onSave` never closes the sheet, so the component\n  cannot know the save landed, and that feedback belongs to the product.\n* Save is one explicit tap with no confirm step and no autosave. Every field stays\n  visible, and the sheet stays open for undo.\n\n<KeyboardTable\n  name=\"log-sheet\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves through the sheet's parts in visual order&#x22;,\n    notes: &#x22;Close control, fields, time, note, action. A datetime-local can cost several presses.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;The same sequence, backwards&#x22;,\n    notes: &#x22;Sheet's close control is first forwards, last backwards.&#x22;,\n  },\n  {\n    keys: &#x22;Escape&#x22;,\n    action: &#x22;Asks before discarding when there is unsaved input; closes when there is not&#x22;,\n    notes: &#x22;Same as a background tap. With the question up, it answers Keep editing.&#x22;,\n  },\n  {\n    keys: &#x22;Enter&#x22;,\n    action: &#x22;Activates the focused control&#x22;,\n    notes: &#x22;Never saves from a field. No form element, no implicit submit.&#x22;,\n  },\n  {\n    keys: &#x22;Space&#x22;,\n    action: &#x22;Activates the focused button&#x22;,\n    notes: &#x22;Real buttons, so the sheet does not scroll.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"log-sheet\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"LogSheetProps\" />\n\n`open`, `onOpenChange`, `title`, `detents` and `className` come from\n[Sheet](./sheet.mdx). `footer`, `modal` and `dismissible` are omitted on purpose.\n`onSave` never closes the sheet; only the product knows whether the save landed. Both\nhandlers receive a `LogEntry`:\n\n```tsx\nexport interface LogEntry {\n  values: Record<string, number | string | null>\n  occurredAt: string\n  recordedAt: string\n  backdated: boolean\n  provenance: \"self-reported\"\n  note?: string\n}\n```\n\n### Data attributes [#data-attributes]\n\n<DataAttributesTable\n  name=\"log-sheet\"\n  rows=\"[\n  {\n    attribute: &#x22;data-slot&#x22;,\n    condition: &#x22;On the capture region, fields wrapper and time field, always&#x22;,\n    value: &#x22;log-sheet, log-sheet-fields, log-sheet-time&#x22;,\n  },\n  {\n    attribute: &#x22;data-slot&#x22;,\n    condition: &#x22;On the note, category band and footer parts, only while rendered&#x22;,\n    value: &#x22;log-sheet-note, log-sheet-category, log-sheet-save, log-sheet-confirm, log-sheet-answers, log-sheet-discard, log-sheet-keep&#x22;,\n  },\n  {\n    attribute: &#x22;data-category&#x22;,\n    condition: &#x22;On log-sheet-category, when a recognised category is supplied&#x22;,\n    value: &#x22;sleep | heart | activity | nutrition | mind | labs&#x22;,\n  },\n]\"\n/>"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/menu",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/menu.md",
      "slug": [
        "components",
        "menu"
      ],
      "section": "Components",
      "title": "Menu",
      "description": "A list of actions opened from a button, built on Base UI Menu, that draws neutral chrome and keeps every safety-relevant action out on the screen.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "dropdown menu",
        "context menu",
        "overflow menu"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"menu\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;The refusal to hide a safety-relevant action is a convention the type system cannot enforce, so a caller can still pass a destructive command.&#x22;,\n  &#x22;Nobody has listened to this menu in a screen reader, so whether a run set apart by a separator reads as a group has only been reasoned about.&#x22;,\n  &#x22;No contrast pair has been measured for the popup against the surfaces it floats over, the highlighted row or the separator hairline.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"menu\" unbuilt=\"false\" importPath=\"@/components/ui/menu\" dependencies=\"[&#x22;@base-ui/react&#x22;]\" />\n\n```tsx\nimport { Menu } from \"@/components/ui/menu\"\n```\n\n```tsx\n<Menu\n  trigger={<button type=\"button\">Actions</button>}\n  items={[\n    { label: \"Share\", onClick: onShare },\n    { label: \"Rename\", onClick: onRename },\n    { label: \"Remove from list\", separatorBefore: true, onClick: onRemove },\n  ]}\n/>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"menu\" />\n\n### Actions from a button [#actions-from-a-button]\n\nNeutral commands fold behind an ordinary button passed as `trigger`; each\n`onClick` runs straight from the list.\n\n<ComponentPreview name=\"menu-actions-from-a-button\" kind=\"example\" align=\"start\" />\n\n### A grouped list with a separator [#a-grouped-list-with-a-separator]\n\n`separatorBefore` draws a hairline above an item, grouping by structure rather\nthan colour. A `disabled` item shows muted rather than removed.\n\n<ComponentPreview name=\"menu-with-a-separator\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;A small set of commands on one thing, such as Share, Rename and Duplicate.&#x22;,\n  &#x22;An overflow trigger on a dense list or toolbar, common actions left on screen.&#x22;,\n  &#x22;A grouped set of neutral actions, with a separator marking a related run.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;The action is safety-relevant or destructive, and a reader cannot weigh a command they cannot see.&#x22;, instead: &#x22;dialog&#x22; },\n  { case: &#x22;There is a single primary action, so a menu is a button in hiding.&#x22;, instead: &#x22;button&#x22; },\n  { case: &#x22;You want a docked sheet of actions on a phone.&#x22;, instead: &#x22;sheet&#x22; },\n]\"\n/>\n\n## Accessibility [#accessibility]\n\nBase UI renders `aria-haspopup`, `role=\"menu\"` and `role=\"menuitem\"`, and wires the\npopup's accessible name to the trigger. The highlighted item takes real keyboard focus,\nso a house focus ring on `focus-visible` marks it, drawn inward so the scroll clip never\ncuts it. A disabled row drops to the muted ink, and Escape and a choice both return focus\nto the trigger. The popup unfolds from its trigger, opened by pointer or by keyboard\nalike, and Escape closes it at once. Under `prefers-reduced-motion` only a short opacity\ncrossfade remains. Axe, target size, focus and reflow came back clean, and\n`pnpm run check:a11y` confirms on every commit that there is no colour literal and no\n`px` type size, and that every item floors at `--opsin-target-minimum`.\n\n**Residual items.**\n\n* The roving highlight fill sits near 1.13:1 against the card, short of the 3:1 a state\n  cue needs, and for now the focus ring covers that case.\n* An icon-only trigger ships an unnamed menu, so give it a label.\n* Every contrast pair remains unmeasured.\n\n<KeyboardTable\n  name=\"menu\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves focus onto the trigger&#x22;,\n    notes: &#x22;A single tab stop.&#x22;,\n  },\n  {\n    keys: &#x22;Enter, Space, Arrow Down&#x22;,\n    action: &#x22;Opens the menu, highlights the first item&#x22;,\n    notes: &#x22;Arrow Up opens on the last item.&#x22;,\n  },\n  {\n    keys: &#x22;Arrow Down, Arrow Up&#x22;,\n    action: &#x22;Moves the highlight between items&#x22;,\n    notes: &#x22;Wraps and skips disabled items.&#x22;,\n  },\n  {\n    keys: &#x22;Enter, Space&#x22;,\n    action: &#x22;Runs the highlighted item and closes the menu&#x22;,\n    notes: &#x22;Focus returns to the trigger.&#x22;,\n  },\n  {\n    keys: &#x22;Escape&#x22;,\n    action: &#x22;Closes the menu without running anything&#x22;,\n    notes: &#x22;Focus returns to the trigger.&#x22;,\n  },\n  {\n    keys: &#x22;A to Z&#x22;,\n    action: &#x22;Highlights the next item starting with that letter&#x22;,\n    notes: &#x22;Typeahead only.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"menu\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"MenuProps\" />\n\n`trigger` must be a single focusable element. No items, one item, or an\nenabled item with no `onClick` raises a development warning. `className`\nmerges last and carries no status or category tint.\n\n### Data attributes [#data-attributes]\n\n<DataAttributesTable\n  name=\"menu\"\n  rows=\"[\n  {\n    attribute: &#x22;data-slot&#x22;,\n    condition: &#x22;Always&#x22;,\n    value: &#x22;menu-trigger, menu-popup, menu-item, menu-separator&#x22;,\n  },\n  {\n    attribute: &#x22;data-highlighted&#x22;,\n    condition: &#x22;Item under the keys or pointer&#x22;,\n    value: &#x22;Drives the highlight&#x22;,\n  },\n  {\n    attribute: &#x22;data-disabled&#x22;,\n    condition: &#x22;Item with disabled set&#x22;,\n    value: &#x22;Drives the muted ink&#x22;,\n  },\n]\"\n/>"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/metric-tile",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/metric-tile.md",
      "slug": [
        "components",
        "metric-tile"
      ],
      "section": "Components",
      "title": "MetricTile",
      "description": "A compact readout of one measurement. It carries the number, its unit and how recent it is, and it is sized to sit in a grid with several others.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "stat",
        "kpi",
        "tile",
        "vitals",
        "resting heart rate",
        "spo2",
        "summary tile",
        "steps"
      ],
      "implements": [],
      "governedBy": [
        "two-colour-axes",
        "health/index",
        "trends",
        "numbers",
        "consent-and-privacy",
        "reference-ranges"
      ],
      "usedIn": [
        "alert-escalation",
        "empty-and-first-use",
        "result-disclosure",
        "offline-and-stale-data",
        "trend-review"
      ],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"metric-tile\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;There is no mask, no reveal and no sensitivity prop, and Value owns the digits and has none either.&#x22;,\n  &#x22;event names when a reading happened, never where it came from, so a device estimate and a laboratory result sound alike, with no provenance prop.&#x22;,\n  &#x22;The instant rule and the staleness verdict are computed here and again inside RelativeTime, and only a reader keeps the two in step.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"metric-tile\" unbuilt=\"false\" importPath=\"@/components/ui/metric-tile\" registryDependencies=\"[&#x22;surface&#x22;, &#x22;value&#x22;, &#x22;status-pill&#x22;, &#x22;relative-time&#x22;]\" />\n\n```tsx\nimport { MetricTile } from \"@/components/ui/metric-tile\"\n```\n\n```tsx\n<MetricTile\n  label=\"Example measurement\"\n  value={14}\n  unit=\"steps\"\n  precision={0}\n  measuredAt=\"2026-04-06T07:15:00+00:00\"\n  now={now}\n  href=\"/results/example\"\n/>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"metric-tile\" />\n\n### A summary grid [#a-summary-grid]\n\nEvery tint is category. Exactly one tile carries a `status`, as a pill with the word in\nit, and the others say nothing about urgency.\n\n<ComponentPreview name=\"metric-tile-a-summary-grid\" kind=\"example\" align=\"start\" />\n\n### No boundary was supplied [#no-boundary-was-supplied]\n\nTwo readings, three hours and five weeks old, with no `staleAfterHours`. Only the printed\ndate marks the older one.\n\n<ComponentPreview name=\"metric-tile-no-boundary-supplied\" kind=\"example\" align=\"start\" />\n\n### States [#states]\n\n| Data state | What MetricTile renders                                                                 |\n| ---------- | --------------------------------------------------------------------------------------- |\n| Error      | A `measuredAt` the tile cannot locate beside a reading is refused, and nothing renders. |\n| Empty      | `value={null}` keeps the label, drops the time line, and is not zero.                   |\n| Stale      | Past `staleAfterHours` the parts mute and the time line adds *may be out of date*.      |\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;A summary grid where several measurements are visible at once and the reader scans.&#x22;,\n  &#x22;A measurement the reader already understands, such as their resting heart rate.&#x22;,\n  &#x22;An entry point: a tile that opens the full result via href.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;The reader is seeing this measurement for the first time and needs it explained.&#x22;, instead: &#x22;result-card&#x22; },\n  { case: &#x22;The value only makes sense against a reference range that will not fit.&#x22;, instead: &#x22;range-bar&#x22; },\n  { case: &#x22;A whole surface has no reading yet. One empty cell in a grid is still a tile.&#x22;, instead: &#x22;empty-state&#x22; },\n  { case: &#x22;You need to show how the value has moved. This draws no line.&#x22;, instead: &#x22;trend-sparkline&#x22; },\n  { case: &#x22;The value is still loading and the grid would otherwise reflow.&#x22;, instead: &#x22;skeleton&#x22; },\n]\"\n/>\n\n## Clinical meaning [#clinical-meaning]\n\n**Asserts.** With a reading, that this measurement had this value, in this unit, at\nthis time, so `measuredAt` is required beside one. An absence is not a reading of zero.\n\n**Never read as.** A current reading, unless it is one. Past the product's boundary the\ntile mutes and says so in words, as\n[Trends and uncertainty](../health/trends.mdx) requires.\n\n**Colour axis.** Category, on the icon and the label only. Status appears as an embedded\n[StatusPill](./status-pill.mdx), never the tile's background, so no element carries\nboth ([Two colour axes](../health/two-colour-axes.mdx)).\n\n**Thresholds.** None. `staleAfterHours` has no default, because opsinjs holds no boundary\nfor any measurement, and omitting it means no stale treatment. The tile derives no level,\nbecause `status` is the product's under [Two colour axes](../health/two-colour-axes.mdx).\nPair `attention` or `urgent` with an `href`, because nothing here enforces it.\n\n**Provenance and masking.** There is no provenance prop and no mask, so do not route a\nfigure nobody measured through `measuredAt`.\n[Trends and uncertainty](../health/trends.mdx) and\n[Consent and privacy](../health/consent-and-privacy.mdx) name this component, and neither is met.\n\n## Accessibility [#accessibility]\n\nThe rendered pass found no axe violation, target-size hit, `focus-visible` failure or\nreflow at 320px, and the source needed no fix. A linked tile sinks to 0.98 when pressed\nand comes back with no spring, so its reading is never drawn past its true size.\n\n**Residual items.**\n\n* `Value` speaks *kilograms* for a visible *kg*, so a linked tile can trip WCAG 2.5.3\n  Label in Name. The repair belongs in `Value` and is deferred, and the *steps* demo does\n  not trip.\n* Nothing enforces the JSDoc rule that `attention` and `urgent` pair with an `href`.\n* Contrast as the tile composes it, `prefers-contrast: more`, `forced-colors`, 200% text,\n  print and masking are unverified.\n\n<KeyboardTable\n  name=\"metric-tile\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves to the tile, when it has an href&#x22;,\n    notes: &#x22;One stop for the whole tile, none without an href.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Moves backwards to the tile&#x22;,\n    notes: &#x22;DOM order is visual order.&#x22;,\n  },\n  {\n    keys: &#x22;Enter&#x22;,\n    action: &#x22;Follows the link&#x22;,\n    notes: &#x22;Only when href is set.&#x22;,\n  },\n  {\n    keys: &#x22;Space&#x22;,\n    action: &#x22;Scrolls the page&#x22;,\n    notes: &#x22;A link does not activate on Space.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"metric-tile\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"MetricTileProps\" />\n\nA `measuredAt` the tile cannot locate beside a reading renders nothing, and development\nreports it once. `label`, `value`, `measuredAt`, `now` and `precision` are required with\nno default. `value` is `number | null`, so a compound reading takes two\ntiles. Read `now` once per screen and pass it to every tile.\n\n### Data attributes [#data-attributes]\n\n<DataAttributesTable\n  name=\"metric-tile\"\n  rows=\"[\n  {\n    attribute: &#x22;data-slot&#x22;,\n    condition: &#x22;On the root and every part; icon, affordance and time only when rendered&#x22;,\n    value: &#x22;metric-tile, metric-tile-header, metric-tile-icon, metric-tile-label, metric-tile-affordance, metric-tile-reading, metric-tile-time&#x22;,\n  },\n  {\n    attribute: &#x22;data-category&#x22;,\n    condition: &#x22;On the icon and the label only, when a known category is passed&#x22;,\n    value: &#x22;sleep | heart | activity | nutrition | mind | labs&#x22;,\n  },\n  {\n    attribute: &#x22;data-status&#x22;,\n    condition: &#x22;On the embedded StatusPill only, when a status is set. The tile stamps none&#x22;,\n    value: &#x22;steady | watch | attention | urgent&#x22;,\n  },\n  {\n    attribute: &#x22;data-opsinjs-value&#x22;,\n    condition: &#x22;On the embedded Value, always&#x22;,\n    value: &#x22;The unrounded number, or an empty string with no reading&#x22;,\n  },\n]\"\n/>"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/number-field",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/number-field.md",
      "slug": [
        "components",
        "number-field"
      ],
      "section": "Components",
      "title": "NumberField",
      "description": "An input for a non-clinical number with increment and decrement steppers, built on Base UI NumberField.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "stepper input",
        "quantity input"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"number-field\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;No contrast pair has been measured: the hairline, the stepper glyphs, the input ink and the muted disabled ink are argued from their roles, not checked.&#x22;,\n  &#x22;Nobody has heard the field in a screen reader, so whether a named spinbutton with two named steppers arrives in the expected order is reasoned, not tested.&#x22;,\n  &#x22;A stepper disabled at a bound is drawn in muted ink alone, and whether reaching a bound is announced to assistive technology has not been tested.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"number-field\" unbuilt=\"false\" importPath=\"@/components/ui/number-field\" dependencies=\"[&#x22;@base-ui/react&#x22;, &#x22;lucide-react&#x22;]\" />\n\n```tsx\nimport { NumberField } from \"@/components/ui/number-field\"\n```\n\n```tsx\n<NumberField\n  label=\"Number of copies\"\n  value={copies}\n  onValueChange={setCopies}\n  min={1}\n  max={10}\n  step={1}\n/>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"number-field\" />\n\n### A quantity [#a-quantity]\n\nA reader sets how many copies to print, stepping with the buttons or typing.\n`label` names the count, which is fictional and carries no unit.\n\n<ComponentPreview name=\"number-field-a-quantity\" kind=\"example\" align=\"start\" />\n\n### With bounds [#with-bounds]\n\n`min` and `max` fix the range and `step` sets how far one press moves. The\ndecrement button disables at the floor and the increment button at the ceiling.\n\n<ComponentPreview name=\"number-field-with-bounds\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;A plain quantity or count with no clinical meaning, such as the number of copies to print.&#x22;,\n  &#x22;A value the reader nudges one at a time as readily as types it.&#x22;,\n  &#x22;A bounded count where a floor and a ceiling the product owns keep the reader inside a range.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;It is a clinical measurement, which carries a unit, needs an out-of-range warning and is typed in whole.&#x22;, instead: &#x22;reading-input&#x22; },\n  { case: &#x22;The number is typed once and never nudged, such as a year or a reference code.&#x22;, instead: &#x22;field&#x22; },\n]\"\n/>\n\n## Accessibility [#accessibility]\n\nThe audit found no axe violation and no loss at 320px reflow, with focus visible\nand a 44px target floor. Icons are `aria-hidden`, there is neither colour axis\nnor a colour-only state, type uses role tokens with no `px` size, and Base UI\nsupplies its own keyboard and names. The input could be named only through\n`aria-label`, so the audit made the wrapper also forward `id` and `aria-labelledby`,\nsuppressing the redundant `aria-label` when a visible label is wired so it wins\nthe name and Label in Name holds. `label` stays the required default, so the\nchange is additive.\n\n**Residual items.**\n\n* The default still names the input through `aria-label`. A persistent visible label is a recommended enhancement, deferred to one central repair across the input wrappers.\n* Base UI hard-codes `autoComplete=\"off\"`, acceptable for a count with no WCAG token, and surfaces no error text, since it clamps to bounds and owns validation.\n* Every contrast pair, including the disabled ink at a bound, is unmeasured, so the report below stands in.\n\n<KeyboardTable\n  name=\"number-field\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves focus into the field, onto the input&#x22;,\n    notes: &#x22;The buttons are reachable with Tab too.&#x22;,\n  },\n  {\n    keys: &#x22;Arrow Up, Arrow Down&#x22;,\n    action: &#x22;Steps the value up or down by step&#x22;,\n    notes: &#x22;Stops at max going up, min going down.&#x22;,\n  },\n  {\n    keys: &#x22;Page Up, Page Down&#x22;,\n    action: &#x22;Steps by a larger amount&#x22;,\n    notes: &#x22;Base UI's large step, for crossing a bounded range quickly.&#x22;,\n  },\n  {\n    keys: &#x22;Home, End&#x22;,\n    action: &#x22;Jumps to min or max&#x22;,\n    notes: &#x22;Only where that bound is set.&#x22;,\n  },\n  {\n    keys: &#x22;Enter&#x22;,\n    action: &#x22;Commits the typed value&#x22;,\n    notes: &#x22;Inside a form it also submits, the same as any text input.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"number-field\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"NumberFieldProps\" />\n\n`value` and `onValueChange` make this a controlled component with no internal\nvalue state. The caller stores the number, or `null` when the field is empty.\n`label` is required, because a spinbutton needs an accessible name. A `min`\nabove `max` raises a development warning. `min`, `max` and `step` are the\ncount's own bounds, never a clinical range."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/popover",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/popover.md",
      "slug": [
        "components",
        "popover"
      ],
      "section": "Components",
      "title": "Popover",
      "description": "A small panel anchored to the control that opened it, floated in a portal and dismissed by leaving it, built as a thin themed wrapper over Base UI Popover.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "anchored panel",
        "flyout"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"popover\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;Nobody has heard a popover in a screen reader, so whether a non-modal dialog over a live page reads usefully is open.&#x22;,\n  &#x22;No contrast pair has been measured: the card panel, its hairline, the arrow and the trigger are argued from the roles rather than checked.&#x22;,\n  &#x22;Under forced-colors: active the shadow drops and the arrow takes the platform's own pair, and no high-contrast reader has seen it.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"popover\" unbuilt=\"false\" importPath=\"@/components/ui/popover\" dependencies=\"[&#x22;@base-ui/react&#x22;]\" />\n\n```tsx\nimport { Popover } from \"@/components/ui/popover\"\n```\n\n```tsx\n<Popover title=\"How readings are grouped\" trigger=\"Why two lists?\">\n  <p>\n    Entries you add yourself sit in one list, and entries from a connected\n    device sit in another, so you can always tell which is which.\n  </p>\n</Popover>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"popover\" />\n\n### Anchored to a button [#anchored-to-a-button]\n\nA short note anchored to a button, left uncontrolled. Escape or an outside press\ncloses it and returns focus.\n\n<ComponentPreview name=\"popover-anchored-to-a-button\" kind=\"example\" align=\"start\" />\n\n### With a form fragment [#with-a-form-fragment]\n\nA labelled input and a save button. `open` and `onOpenChange` take the state over,\nsince a control inside closes it.\n\n<ComponentPreview name=\"popover-with-a-form-fragment\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;A short aside anchored to a control, such as a note explaining a label.&#x22;,\n  &#x22;A couple of options or a small form fragment, such as renaming a list.&#x22;,\n  &#x22;Anywhere dismissing without acting is a valid outcome, because the page behind stays live.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;The reader must answer before they carry on, so dismissing would leave the product guessing.&#x22;, instead: &#x22;dialog&#x22; },\n  { case: &#x22;The content is a large form, or needs its own scroll and a docked layout.&#x22;, instead: &#x22;sheet&#x22; },\n  { case: &#x22;You only want a short passive label, nothing to open or dismiss.&#x22;, instead: &#x22;term&#x22; },\n]\"\n/>\n\n## Accessibility [#accessibility]\n\nThe panel is `role=\"dialog\"`, named by `aria-labelledby`, and a missing title warns.\nBase UI moves focus into the panel on open and back to the trigger on close. The arrow\nis `aria-hidden`. The panel unfolds from its trigger and comes into focus as it\nsettles, and under `prefers-reduced-motion` only a short opacity crossfade remains. The\ncomponent uses only neutral chrome, the `overlay` shadow token and the `body` and\n`headline` steps, with no status colour, literal, ramp step or `px` size. The trigger's\nhit area was floored on height alone, so an icon-only trigger could clear the AA 24px\nminimum while still missing the house width floor. The audit added a matching `min-w`\nat `--opsin-target-minimum`, following the `icon-button` pattern, so the width is\nfloored too.\n\n**Residual items.**\n\n* The wrapper takes no `aria-label` prop, so an icon-only trigger needs a name from the\n  caller's trigger node. Every shipped trigger already uses named text.\n* Contrast pairs remain unmeasured, below.\n\n<KeyboardTable\n  name=\"popover\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves focus to the trigger&#x22;,\n    notes: &#x22;One tab stop; the panel joins the tab order only when open.&#x22;,\n  },\n  {\n    keys: &#x22;Enter, Space&#x22;,\n    action: &#x22;Opens the panel from the trigger&#x22;,\n    notes: &#x22;Focus moves onto its first focusable content.&#x22;,\n  },\n  {\n    keys: &#x22;Escape&#x22;,\n    action: &#x22;Closes the panel&#x22;,\n    notes: &#x22;Focus returns to the trigger.&#x22;,\n  },\n  {\n    keys: &#x22;Tab, Shift + Tab&#x22;,\n    action: &#x22;Moves through the focusable content in the panel&#x22;,\n    notes: &#x22;Focus is not trapped; past the last control it leaves the panel.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"popover\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"PopoverProps\" />\n\n`trigger` is the button's visible content; a button here would nest inside another.\n`side` defaults to `bottom`, a preference the primitive overrides on collision.\n`className` merges onto the panel and must resolve neither colour axis."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/progress",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/progress.md",
      "slug": [
        "components",
        "progress"
      ],
      "section": "Components",
      "title": "Progress",
      "description": "A bar for how far through a task or a set of steps the reader has got, built on Base UI Progress and never used to draw a health value.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "progress bar",
        "completion"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"progress\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;Nobody has listened to the bar in a screen reader, so whether label, then value, then busy state lands as a hearing reader expects is reasoned, not heard.&#x22;,\n  &#x22;Under prefers-reduced-motion the indeterminate pulse is dropped, and whether a full static fill reads as running rather than done has not been checked with a reader who turns motion off.&#x22;,\n  &#x22;Under forced colours the muted track and the accent fill are both replaced by the platform's pair, and whether the fill stays distinct from the track is untested.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"progress\" unbuilt=\"false\" importPath=\"@/components/ui/progress\" dependencies=\"[&#x22;@base-ui/react&#x22;]\" />\n\n```tsx\nimport { Progress } from \"@/components/ui/progress\"\n```\n\n```tsx\n<Progress label=\"Uploading photos\" value={45} />\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"progress\" />\n\n### A task completing [#a-task-completing]\n\nA fictional upload part way done. `value` sets the fill, and the readout writes\nthe same figure beside it for a reader who cannot use the fill.\n\n<ComponentPreview name=\"progress-a-task-completing\" kind=\"example\" align=\"start\" />\n\n### An indeterminate task [#an-indeterminate-task]\n\n`value={null}` for a task with no known shape. The fill spans the track and\npulses, the readout says the work is in progress, and Base UI drops\n`aria-valuenow` so a screen reader announces a busy state.\n\n<ComponentPreview name=\"progress-indeterminate\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;Showing how far through an upload or a download the reader has got, where the amount done is a real fraction of a known whole.&#x22;,\n  &#x22;Tracking a multi-step flow, such as step three of five, by passing the step count as value and the total as max.&#x22;,\n  &#x22;Signalling that a task with no known shape is running, by passing value={null}, rather than inventing a percentage.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;You are drawing a health reading against a range. A bar implies a target the reading does not have and carries no reference bounds.&#x22;, instead: &#x22;range-bar&#x22; },\n  { case: &#x22;You are showing a composite score. A bar reads it as a mark out of its top, the one reading a score must not invite.&#x22;, instead: &#x22;score-dial&#x22; },\n  { case: &#x22;The wait has no bar-shaped answer, because you cannot say what is arriving as a fraction. A placeholder of the shape to come says more.&#x22;, instead: &#x22;skeleton&#x22; },\n]\"\n/>\n\n## Accessibility [#accessibility]\n\n`aria-valuenow` carries the amount done, with the label, minimum and maximum.\nNothing takes focus, so the bar costs no tab stop. The transition and pulse drop\nunder `prefers-reduced-motion`, and words carry the state. Type steps and the\n`em` track height scale together, so 200% text grows the bar rather than\nclipping it. `pnpm run check:a11y` confirms on every commit that colour is a\nrole token on neither axis and that no type size is in `px`.\n\nThe audit made three fixes: a plain `aria-label` on the root so the name\nsurvives a first paint before Base UI's own wiring runs, a sibling status region\nannouncing `\"{label} complete.\"` at max, and `aria-hidden` on the indeterminate\nbranch's text to match the determinate readout.\n\n**Residual items.**\n\n* Fill contrast against the track is not measured, and the report below carries\n  it until it is.\n* Wrap for a long label and print output were not checked.\n\n<KeyboardTable\n  name=\"progress\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Skips the bar&#x22;,\n    notes: &#x22;Not a control. Nothing is focusable, so a keyboard user pays no tab stop.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Skips the bar&#x22;,\n    notes: &#x22;Same in reverse. The bar never appears in the focus order.&#x22;,\n  },\n  {\n    keys: &#x22;Arrow keys&#x22;,\n    action: &#x22;Nothing&#x22;,\n    notes: &#x22;Nothing to select, move or change. The product sets the value.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"progress\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"ProgressProps\" />\n\n`value={null}` is a different state from `value={0}`: `null` draws the running\nstate and 0 a task not started. A value outside 0 to `max` is clamped by Base UI\nand raises a development warning. No colour prop exists, and `className` takes\nneither a status nor a category tint."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/questionnaire",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/questionnaire.md",
      "slug": [
        "components",
        "questionnaire"
      ],
      "section": "Components",
      "title": "Questionnaire",
      "description": "The styled form shell that groups a product's own questions and shows how far through them a reader is, while scoring and interpreting nothing clinical.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "survey",
        "assessment",
        "phq",
        "screening form"
      ],
      "implements": [],
      "governedBy": [
        "health/index",
        "safety-review",
        "high-stakes-moments"
      ],
      "usedIn": [],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"questionnaire\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;No contrast pair has been measured: the hairline, the title ink and the muted progress ink all sit on whatever ground the host provides.&#x22;,\n  &#x22;Nobody has listened to the aria-live progress readout, so whether 'Question 2 of 3' on every focus move helps a reader or talks over them is unheard.&#x22;,\n  &#x22;The refusal to score binds only the shell: nothing stops a product wiring a running total into its own controls, and no lint on consumer code catches it.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"questionnaire\" unbuilt=\"false\" importPath=\"@/components/ui/questionnaire\" />\n\n```tsx\nimport { Questionnaire } from \"@/components/ui/questionnaire\"\n```\n\n```tsx\n<Questionnaire\n  title=\"Weekly check-in\"\n  showProgress\n  onComplete={handleComplete}\n  questions={[\n    { id: \"rest\", prompt: \"How rested did you feel this week?\", control: <RestControl /> },\n    { id: \"plan\", prompt: \"How easy was it to keep to your plan?\", control: <PlanControl /> },\n  ]}\n/>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"questionnaire\" />\n\n### A set of questions [#a-set-of-questions]\n\nThree invented questions under one title, each with a control the product composed.\n\n<ComponentPreview name=\"questionnaire-a-set-of-questions\" kind=\"example\" align=\"start\" />\n\n### Showing progress [#showing-progress]\n\n`showProgress` turns on the readout above the list. It follows focus, so entering the second question reads \"Question 2 of 3\".\n\n<ComponentPreview name=\"questionnaire-showing-progress\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;A set of questions the product owns, read as one group and answered in order.&#x22;,\n  &#x22;A short form that needs one accessible name, a progress readout and one completion signal, with the product supplying each control.&#x22;,\n  &#x22;The questions of an instrument the product licenses and scores itself, every clinical decision kept on its side.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;One question with one answer, such as a single rating or a yes or no. A set of one needs no shell.&#x22;, instead: &#x22;field&#x22; },\n  { case: &#x22;A set of symptoms collected as a multi-select grid rather than a sequence of separate questions.&#x22;, instead: &#x22;symptom-picker&#x22; },\n]\"\n/>\n\n## Clinical meaning [#clinical-meaning]\n\n**Asserts.** Two things about the form, not the person: these questions, in this order, and how far through them you are. The progress count is an ordinal of position, drawn as plain text.\n\n**Never read as.** A score, a screening result, a diagnosis or triage, because a questionnaire on screen means the product has asked, not that it has assessed. The shell draws whatever wording it is handed, so a product that edits or misgrades a licensed instrument owns that hazard, which is the line [Safety review](../health/safety-review.mdx) draws around a presentation layer.\n\n**Colour axis.** Neither. The shell states no level and names no category, so it carries neither `data-status` nor `data-category`, and [Two colour axes](../health/two-colour-axes.mdx) forbids the mix.\n\n**Thresholds.** The product, always. opsinjs ships no instrument, default question, option, threshold or interpretation text, and [Safety review](../health/safety-review.mdx) is why an instrument's wording and scoring stay with its licensee.\n\n## Accessibility [#accessibility]\n\nThe audit gave every prompt a stable id and put each control in a `role=\"group\"` named by that prompt through `aria-labelledby`. It also gave the default demo's free-text control an `aria-label`, so it is no longer unnamed. A check on every commit keeps the chrome neutral, with no status colour, category colour, colour literal, ramp step or `px` type size. Title, prompts and readout are semantic type steps.\n\n**Residual items.**\n\n* The shell cannot name a product's own control node, so a product that passes a bare input still labels it, with the per-question group supplying context.\n* The title is the form's `aria-labelledby`, drawn as a styled div, because the shell cannot know the host page's heading level. A visible heading on the product's side is recommended.\n* The progress line is `aria-live=\"polite\"`, announced as focus moves. It may read as chatty, which is a tuning question for the product.\n* Every contrast pair against the host ground is unmeasured, and so is `forced-colors: active`.\n\n<KeyboardTable\n  name=\"questionnaire\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves to the next control in the set&#x22;,\n    notes: &#x22;No tab stop of its own. Entering a question updates the readout.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Moves to the previous control&#x22;,\n    notes: &#x22;Same in reverse. The title and the readout are not focusable.&#x22;,\n  },\n  {\n    keys: &#x22;Return&#x22;,\n    action: &#x22;Submits the set, which the shell turns into onComplete&#x22;,\n    notes: &#x22;Default navigation is cancelled, so Return never reloads the form.&#x22;,\n  },\n  {\n    keys: &#x22;Arrow keys, Space&#x22;,\n    action: &#x22;Belong to the control in focus&#x22;,\n    notes: &#x22;The shell captures neither. Each key is the product control's contract.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"questionnaire\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"QuestionnaireProps\" />\n\n`onComplete` is told that the reader finished and nothing else, because the shell reads no answer. Submit is cancelled even when it is omitted. An empty `questions` array renders nothing and warns in development, as does a duplicate `id` or a missing `title`.\n\n### Data attributes [#data-attributes]\n\n<DataAttributesTable\n  name=\"questionnaire\"\n  rows=\"[\n  {\n    attribute: &#x22;data-slot&#x22;,\n    condition: &#x22;On the root and every inner part, always&#x22;,\n    value: &#x22;questionnaire, questionnaire-title, questionnaire-progress, questionnaire-question, questionnaire-prompt, questionnaire-control&#x22;,\n  },\n  {\n    attribute: &#x22;data-question-index&#x22;,\n    condition: &#x22;On every question list item, always&#x22;,\n    value: &#x22;The question's zero-based position in the questions array&#x22;,\n  },\n]\"\n/>"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/radio-group",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/radio-group.md",
      "slug": [
        "components",
        "radio-group"
      ],
      "section": "Components",
      "title": "RadioGroup",
      "description": "A vertical list of labelled options where exactly one can be chosen, kept to a single tab stop with a roving focus.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "radio buttons",
        "single choice"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"radio-group\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;No contrast pair has been measured, so whether the dot on the accent fill and the disabled muted ink clear the floors on this control is unknown; the accent pairs themselves are measured.&#x22;,\n  &#x22;Nobody has listened to it in a screen reader, so whether a description reads usefully as part of its option is unheard.&#x22;,\n  &#x22;Forced colours and prefers-contrast: more are unhandled, so whether the selection survives when the platform replaces the neutral ring and dot has not been tested.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"radio-group\" unbuilt=\"false\" importPath=\"@/components/ui/radio-group\" dependencies=\"[&#x22;@base-ui/react&#x22;]\" />\n\n```tsx\nimport { RadioGroup } from \"@/components/ui/radio-group\"\n```\n\n```tsx\n<RadioGroup\n  label=\"Reminder style\"\n  value={style}\n  onValueChange={setStyle}\n  options={[\n    { value: \"standard\", label: \"Standard\" },\n    { value: \"quiet\", label: \"Quiet\" },\n    { value: \"off\", label: \"None\" },\n  ]}\n/>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"radio-group\" />\n\n### A single choice [#a-single-choice]\n\nThree options, one chosen. `options` carries the list, `value` marks the chosen one.\n\n<ComponentPreview name=\"radio-group-a-single-choice\" kind=\"example\" align=\"start\" />\n\n### Options with descriptions [#options-with-descriptions]\n\nThe same list with a `description` under each label.\n\n<ComponentPreview name=\"radio-group-with-descriptions\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;A settled single choice of two to about seven options, such as a reminder style.&#x22;,\n  &#x22;A choice whose options each need a line of helper text.&#x22;,\n  &#x22;A choice laid out in full, every option visible at once.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;One or two word options that switch a parameter of a view, on one line.&#x22;, instead: &#x22;segmented-control&#x22; },\n  { case: &#x22;More than about seven options, or long labels, so a select that collapses into one control reads more calmly.&#x22;, instead: &#x22;field&#x22; },\n  { case: &#x22;The choice needs a label, a hint and a validation message wired to it.&#x22;, instead: &#x22;field&#x22; },\n]\"\n/>\n\n## Accessibility [#accessibility]\n\nThe audit found nothing to change. The rendered pass was clean, with zero axe violations,\nrows floored at `--opsin-target-minimum`, focus kept visible and no sideways scroll at\n320px. The source has one roving tab stop, a visible legend wired by `aria-labelledby`\nrather than an `aria-label`, and selection carried three ways through `aria-checked`, the\nlifted ring and the filled dot, never on colour alone.\n\n**Residual items.**\n\n* An option's `description` renders inside the radio, so the accessible name folds it in\n  rather than exposing it through `aria-describedby`. It is announced and passes AA, and\n  wiring it as a distinct description restructures the name, a redesign rather than a fix.\n* The dot grows from the centre on `spring-snap` while the leaving one shrinks, and the\n  row's colour fades on `duration-fast`. Under `prefers-reduced-motion` the token sheets\n  collapse both to a single frame, which is what 2.3.3 asks of motion an interaction\n  starts.\n* Every colour is a role token, so no contrast ratio reads from the source. The measured\n  pairs are the report below.\n\n<KeyboardTable\n  name=\"radio-group\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves focus into the control, onto the selected option&#x22;,\n    notes: &#x22;With nothing selected, the first enabled option takes it.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Moves focus back out of the control&#x22;,\n    notes: &#x22;One stop in reverse too.&#x22;,\n  },\n  {\n    keys: &#x22;Arrow Down, Arrow Right&#x22;,\n    action: &#x22;Moves to the next option and selects it&#x22;,\n    notes: &#x22;Wraps, skips disabled. Left and Right swap under right-to-left.&#x22;,\n  },\n  {\n    keys: &#x22;Arrow Up, Arrow Left&#x22;,\n    action: &#x22;Moves to the previous option and selects it&#x22;,\n    notes: &#x22;Wraps, skips disabled options.&#x22;,\n  },\n  {\n    keys: &#x22;Space&#x22;,\n    action: &#x22;Selects the focused option&#x22;,\n    notes: &#x22;The activator of a role=\\&#x22;radio\\&#x22;.&#x22;,\n  },\n  {\n    keys: &#x22;Enter&#x22;,\n    action: &#x22;Does nothing&#x22;,\n    notes: &#x22;The primitive cancels Enter, so no form submits by accident.&#x22;,\n  },\n  {\n    keys: &#x22;Home, End&#x22;,\n    action: &#x22;Not bound&#x22;,\n    notes: &#x22;The primitive does not enable them. The browser default stands.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"radio-group\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"RadioGroupProps\" />\n\n`value` and `onValueChange` make this controlled, with no internal state. A `value`\nmatching no option renders nothing chosen and warns in development. A disabled\noption stays in the list, drawn in the muted ink and skipped by the Arrow keys. No\noptions renders nothing."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/range-bar",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/range-bar.md",
      "slug": [
        "components",
        "range-bar"
      ],
      "section": "Components",
      "title": "RangeBar",
      "description": "A single measurement drawn on a line, so you can see at a glance where your number sits compared with the range it is usually expected to fall in.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "reference range",
        "normal range",
        "in range",
        "range indicator",
        "gauge bar"
      ],
      "implements": [],
      "governedBy": [
        "two-colour-axes",
        "reference-ranges",
        "numbers",
        "safety-review"
      ],
      "usedIn": [
        "result-disclosure"
      ],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"range-bar\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;The track is aria-hidden, so the summary alone announces the reading, and no screen-reader user has been asked whether the picture should be named.&#x22;,\n  &#x22;Nothing is measured: the status word and category tint are ink roles on the host's ground.&#x22;,\n  &#x22;Two boundary labels can round to the same number, and the component warns in development rather than adding a decimal place nobody claimed.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"range-bar\" unbuilt=\"false\" importPath=\"@/components/ui/range-bar\" dependencies=\"[&#x22;lucide-react&#x22;]\" registryDependencies=\"[&#x22;value&#x22;, &#x22;status-pill&#x22;]\" />\n\n```tsx\nimport { RangeBar } from \"@/components/ui/range-bar\"\n```\n\n```tsx\n<RangeBar\n  label=\"Example measurement\"\n  value={14}\n  unit=\"mg/dL\"\n  precision={0}\n  locale=\"en-GB\"\n  range={{ low: 10, high: 20, source: \"Example data rather than a reference range\" }}\n/>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"range-bar\" />\n\n### Beyond the top of the range [#beyond-the-top-of-the-range]\n\nThe cursor sits outside the band, and that is not a verdict.\n\n<ComponentPreview name=\"range-bar-outside-the-range\" kind=\"example\" align=\"start\" />\n\n### One bound only [#one-bound-only]\n\nOne bound has no width, so no track is drawn. The summary names the direction.\n\n<ComponentPreview name=\"range-bar-an-open-ended-range\" kind=\"example\" align=\"start\" />\n\n### Three readings down a page [#three-readings-down-a-page]\n\n`category` on the labels, `status` on the cursors, no element taking both.\n\n<ComponentPreview name=\"range-bar-in-a-list-of-results\" kind=\"example\" align=\"start\" />\n\n### Far above the range [#far-above-the-range]\n\nThe extent stretches to contain `value`, so a far reading squeezes the band.\n\n<ComponentPreview name=\"range-bar-far-above-the-range\" kind=\"example\" align=\"start\" />\n\n### States [#states]\n\n| Data state | What RangeBar renders                                                                                    |\n| ---------- | -------------------------------------------------------------------------------------------------------- |\n| Error      | It owns no fetch. A range with no `source`, neither bound, or downward bounds is discarded and reported. |\n| Loading    | No skeleton or spinner; renders synchronously.                                                           |\n| Empty      | `value` of `null` differs from `0`: no cursor, and the summary names the range.                          |\n| Partial    | No range, or one bound, draws no track. The summary carries the comparison.                              |\n| Stale      | It states when the reading was taken, or that nobody knows. No boundary.                                 |\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;One measurement with a published reference range, shown to its owner.&#x22;,\n  &#x22;A value whose meaning is positional rather than absolute.&#x22;,\n  &#x22;A reader who would otherwise compare two numbers in their head.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;There is no range, or it turns on facts you lack: age, sex, medication, assay.&#x22;, instead: &#x22;value&#x22; },\n  { case: &#x22;You are showing change over time, not position.&#x22;, instead: &#x22;trend-sparkline&#x22; },\n  { case: &#x22;The number is a score you calculated, not a measurement.&#x22;, instead: &#x22;score-dial&#x22; },\n  { case: &#x22;Only the clinical status level matters.&#x22;, instead: &#x22;status-pill&#x22; },\n  { case: &#x22;You want to say what to do about it.&#x22;, instead: &#x22;care-card&#x22; },\n]\"\n/>\n\n## Clinical meaning [#clinical-meaning]\n\n**Asserts.** This measurement, in this unit ([Numbers and units](../health/numbers.mdx)),\nat this position against this range, from this source. Nothing about cause or trend.\n\n**Never read as.** A diagnosis or verdict. Outside the range is not \"abnormal\", inside\nis not \"normal\": [Reference ranges](../health/reference-ranges.mdx) has the banned words.\n\n**Colour axis.** Status only, when the product supplies one. `category` tints the label\nalone, and position never becomes a status. See\n[Two colour axes](../health/two-colour-axes.mdx).\n\n**Thresholds.** The product owns every range, status and precision\n([Numbers and units](../health/numbers.mdx)). No built-in table, no `staleAfterHours`.\nStaleness comes from [RelativeTime](./relative-time.mdx).\n\n<SafetyCallout severity=\"urgent\" evidence=\"opinion\">\n  Given no range, or one with neither bound or an empty `source`, RangeBar draws no band\n  and substitutes no default.\n</SafetyCallout>\n\n## Accessibility [#accessibility]\n\nIt is display-only, so nothing is focusable and the keyboard and target-size checks do\nnot apply. Rendered, it shows no axe violation, no focus-visible failure and no\nhorizontal scroll at 320px.\n\n* The summary paragraph is unconditional: reading, range with its source, and within,\n  above or below in words, so the picture is never named.\n* `RangeBar.Track` is `aria-hidden`, with no `slider`, `meter` or `progressbar` role.\n* Numbers go through [Value](./value.mdx), so the unit is spoken, not spelled.\n* Status carries a word and a glyph through StatusPill, redundant to the cursor's index line.\n* Under `forced-colors` the cursor keeps a `CanvasText` outline and its index line a\n  `Highlight` fill.\n\n**Residual items.** The band outline and the two boundary marks fall below the 3:1\nnon-text contrast floor, and stay because the graphic is `aria-hidden` and the summary\ncarries the same facts. Its own text and colour pairs are not measured yet, so the\nreport below stands in.\n\n<ContrastReport component=\"range-bar\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"RangeBarProps\" />\n\n`precision` is decimal places, not significant figures, and it is required. A `status`\noutside the four levels is dropped, never approximated. Omit `locale` and the server\nformats with its own while the browser uses the reader's, so the two disagree.\n\n### Data attributes [#data-attributes]\n\n<DataAttributesTable\n  name=\"range-bar\"\n  rows=\"[\n  { attribute: &#x22;data-slot&#x22;, condition: &#x22;On every part, always&#x22;, value: &#x22;range-bar, range-bar-label, status-pill, range-bar-track, range-bar-band, range-bar-mark, range-bar-tick, range-bar-value, range-bar-summary, range-bar-footnote&#x22; },\n  { attribute: &#x22;data-status&#x22;, condition: &#x22;On the StatusPill and the tick, when a status was supplied&#x22;, value: &#x22;steady | watch | attention | urgent&#x22; },\n  { attribute: &#x22;data-category&#x22;, condition: &#x22;On the label, when a category was supplied&#x22;, value: &#x22;sleep | heart | activity | nutrition | mind | labs&#x22; },\n  { attribute: &#x22;data-opsinjs-value&#x22;, condition: &#x22;On every Value, six per drawn bar&#x22;, value: &#x22;The unrounded number, or empty with no reading&#x22; },\n]\"\n/>\n\n### CSS variables [#css-variables]\n\n<CssVariablesTable\n  name=\"range-bar\"\n  rows=\"[\n  { selector: &#x22;div:has(> [data-slot=\\&#x22;range-bar-track\\&#x22;])&#x22;, variable: &#x22;--rb-label-half&#x22;, controls: &#x22;How far the reading label's midpoint is clamped from either track edge. Set inline at 3.5em.&#x22; },\n]\"\n/>"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/range-legend",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/range-legend.md",
      "slug": [
        "components",
        "range-legend"
      ],
      "section": "Components",
      "title": "RangeLegend",
      "description": "The key naming the tones a RangeBar draws, so a reader learns in one place what the reference band and each status colour mean. It asserts nothing itself.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "key",
        "chart legend",
        "band legend"
      ],
      "implements": [],
      "governedBy": [
        "reference-ranges",
        "two-colour-axes"
      ],
      "usedIn": [
        "trend-review"
      ],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"range-legend\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;No contrast pair has been measured, and every swatch and glyph is painted on the host's ground rather than a surface the token contract tunes against.&#x22;,\n  &#x22;The binding to a RangeBar is a convention rather than a gate, so nothing in the code stops a caller placing the legend away from its bars.&#x22;,\n  &#x22;No screen reader user has been asked whether a list of aria-hidden swatches with text labels reads usefully, or whether it needs an accessible name pointing at its bar.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"range-legend\" unbuilt=\"false\" importPath=\"@/components/ui/range-legend\" dependencies=\"[&#x22;lucide-react&#x22;]\" />\n\n```tsx\nimport { RangeLegend } from \"@/components/ui/range-legend\"\n```\n\n```tsx\n<RangeLegend\n  bands={[\n    { label: \"The usual range\", description: \"From your laboratory. Most results sit here.\" },\n    { label: \"Worth watching\", tone: \"watch\" },\n    { label: \"Needs attention\", tone: \"attention\" },\n  ]}\n/>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"range-legend\" />\n\n### The legend beside its bar [#the-legend-beside-its-bar]\n\nThe same container as the bars it names, `bands` holding the tones they draw. Each swatch is a miniature of the bar's own piece: the lit band in the tube, or the cursor with its index line.\n\n<ComponentPreview name=\"range-legend-beside-its-bar\" kind=\"example\" align=\"start\" />\n\n### The four levels, named once [#the-four-levels-named-once]\n\nThe whole vocabulary in one key: the neutral band and four status levels, each row's `tone` giving its word, glyph and colour.\n\n<ComponentPreview name=\"range-legend-the-four-levels\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;Beside RangeBars that share a status vocabulary, naming each level once instead of a pill per row.&#x22;,\n  &#x22;As the key beneath a single RangeBar whose status tones a first time reader has not met.&#x22;,\n  &#x22;Wherever a reader must learn the neutral band and the status colours before reading the numbers.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;You are showing one measurement against its range; the bar already states reading, range and position.&#x22;, instead: &#x22;range-bar&#x22; },\n  { case: &#x22;You want the level of one reading. A legend names the vocabulary, never a verdict.&#x22;, instead: &#x22;status-pill&#x22; },\n  { case: &#x22;You are explaining a single clinical term rather than a set of tones.&#x22;, instead: &#x22;term&#x22; },\n]\"\n/>\n\n## Clinical meaning [#clinical-meaning]\n\n**Asserts.** The tones the bar beside it draws, and what each one means. Nothing about any reading, cause or next step.\n\n**Never read as.** A scale, a diagnosis or a verdict on the reader. \"Needs attention\" names a tone a product may assign, not the reader's result. \"Normal\" and \"abnormal\" are banned; [Reference ranges](../health/reference-ranges.mdx) carries the list.\n\n**Colour axis.** The status axis and the neutral reference range band only. No element carries `data-category`, because [Two colour axes](../health/two-colour-axes.mdx) never mix. Every status row draws fill, glyph and word together, so the level survives greyscale.\n\n**Thresholds.** The product owns every word, range and level. RangeLegend ships no band names; words arrive as props and the swatch colours are all it supplies.\n\n## Accessibility [#accessibility]\n\nEach swatch and glyph carries `aria-hidden`, so a screen reader skips the decoration. No element carries both `data-category` and `data-status`, and this file writes no category colour. Nothing takes focus, answers a key or animates, so `prefers-reduced-motion` has no state to reduce. At 200% text the swatches grow with the words, which wrap with no ellipsis, and under `forced-colors: active` the tube keeps a `CanvasText` outline and a status swatch's index line takes `Highlight`.\n\nThe audit fixed two gaps. The legend `<ul>` had no accessible name, and optional `aria-label` and `aria-labelledby` props now forward onto the root, so a caller names the key or points it at the bar's heading. A blank status label would draw colour and glyph with no word, a colour-alone failure, and a guard now warns on it, with the empty-bands and invalid-tone guards.\n\n**Residual items.**\n\n* A status swatch's index line takes RangeBar's tick tone, the level's line role, inside a glass cursor, so its contrast against the cursor is unmeasured. Each is `aria-hidden` decoration redundant to the word and glyph, so a low-contrast swatch loses nothing, and measuring the four lines and the neutral border in light and dark is a recommended enhancement.\n* Label and description use the foreground and muted-foreground role tokens, not re-measured in this pass.\n* The legend cannot enforce in code that it sits beside its bar. `aria-labelledby` is how a caller binds it, and the audit cannot verify callers do.\n\n<KeyboardTable\n  name=\"range-legend\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Skips the whole component&#x22;,\n    notes: &#x22;Nothing here is focusable.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Skips the whole component&#x22;,\n    notes: &#x22;Never in the focus order.&#x22;,\n  },\n  {\n    keys: &#x22;Arrow keys&#x22;,\n    action: &#x22;Nothing&#x22;,\n    notes: &#x22;Swatches are decorative, words static.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"range-legend\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"RangeLegendProps\" />\n\n`tone` is typed to the four `ClinicalStatus` levels in [Two colour axes](../health/two-colour-axes.mdx). A value outside the four is refused with a development warning and falls back to the neutral band. An empty `bands` array renders nothing and warns in development.\n\n### Data attributes [#data-attributes]\n\n<DataAttributesTable\n  name=\"range-legend\"\n  rows=\"[\n  {\n    attribute: &#x22;data-slot&#x22;,\n    condition: &#x22;On the root and every named inner part, always&#x22;,\n    value: &#x22;range-legend, range-legend-item, range-legend-swatch, range-legend-label&#x22;,\n  },\n  {\n    attribute: &#x22;data-status&#x22;,\n    condition: &#x22;On a status row's item; absent on the neutral band row&#x22;,\n    value: &#x22;The row's tone: steady, watch, attention or urgent&#x22;,\n  },\n]\"\n/>"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/reading-input",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/reading-input.md",
      "slug": [
        "components",
        "reading-input"
      ],
      "section": "Components",
      "title": "ReadingInput",
      "description": "A field for typing in a measurement, with the unit shown and switchable beside the number, and room for an advisory the product wrote.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "measurement input",
        "numeric input",
        "unit switch",
        "enter a reading",
        "numeric entry",
        "manual entry"
      ],
      "implements": [],
      "governedBy": [
        "numbers",
        "trends"
      ],
      "usedIn": [
        "ask-users-for",
        "daily-logging",
        "forms",
        "onboarding-and-first-run"
      ],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"reading-input\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;Nobody has listened to a compound reading with a screen reader, and the announcement contract is unwritten.&#x22;,\n  &#x22;A compound reading is three tab stops, and one stop with arrow keys inside is untested.&#x22;,\n  &#x22;The component mounts no live region, and nobody who depends on speech has checked that effectText arrives in time.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"reading-input\" unbuilt=\"false\" importPath=\"@/components/ui/reading-input\" dependencies=\"[&#x22;lucide-react&#x22;]\" registryDependencies=\"[&#x22;field&#x22;]\" />\n\n```tsx\nimport { ReadingInput } from \"@/components/ui/reading-input\"\n```\n\n```tsx\n<ReadingInput\n  label=\"Example measurement\"\n  unit={unit}\n  units={[\"kg\", \"lb\", \"st\"]}\n  precision={1}\n  value={reading}\n  onChange={(next) => {\n    setReading(next.value)\n    setUnit(next.unit)\n  }}\n/>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"reading-input\" />\n\n### Two numbers that are one measurement [#two-numbers-that-are-one-measurement]\n\n`segments` turns the field into a `<fieldset>` with a `<legend>`, one box per part.\n\n<ComponentPreview name=\"reading-input-a-compound-reading\" kind=\"example\" align=\"start\" />\n\n### Switching the unit, and the sentence that follows it [#switching-the-unit-and-the-sentence-that-follows-it]\n\n`precision` sets the decimal places a conversion rounds to.\n\n<ComponentPreview name=\"reading-input-switching-the-unit\" kind=\"example\" align=\"start\" />\n\n### A sentence the product wrote [#a-sentence-the-product-wrote]\n\n`warning` shows the product's sentence without comparing anything.\n\n<ComponentPreview name=\"reading-input-a-warning-the-product-owns\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;Anywhere a person types a measurement of themselves: weight, blood pressure, glucose, temperature.&#x22;,\n  &#x22;Entry where the unit is part of the value.&#x22;,\n  &#x22;Entry where the product flags an unlikely number without stopping anybody.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;A quantity, a count or a code, not a measurement of a person.&#x22;, instead: &#x22;number-field&#x22; },\n  { case: &#x22;The value is best chosen from a small set rather than typed.&#x22;, instead: &#x22;segmented-control&#x22; },\n  { case: &#x22;The reader estimates the value, such as a pain score, not measures it.&#x22;, instead: &#x22;scale-input&#x22; },\n  { case: &#x22;You are displaying a reading, not collecting one.&#x22;, instead: &#x22;value&#x22; },\n  { case: &#x22;Several related measurements captured in one interaction.&#x22;, instead: &#x22;log-sheet&#x22; },\n]\"\n/>\n\n## Clinical meaning [#clinical-meaning]\n\n**Asserts.** That the reader typed this number, in this unit, as a measurement of\nthemselves. It is always self-reported.\n\n**Never read as.** A validated measurement, a device reading or an assessed value.\n\n**Colour axis.** Neither; the advisory is ordinary foreground.\n\n**Thresholds.** None. The component holds no bound. The product\nsupplies the finished `warning`, which never sets `aria-invalid`, moves focus or blocks\nsubmission. Staleness belongs to\n[Trends and uncertainty](../health/trends.mdx).\n\n**Unit switches.** Only definitional conversions from `tokens/units.json`: kg, lb, st,\n°C and °F. mmol/L to mg/dL is refused, because the factor is the substance's molar mass,\nso that switch clears the entry and says so. See\n[Numbers and units](../health/numbers.mdx).\n\n<SafetyCallout severity=\"attention\" evidence=\"opinion\">\n  Changing the unit must never silently change the stored value or keep the typed digits\n  without saying so on screen.\n</SafetyCallout>\n\n## Accessibility [#accessibility]\n\n**From the source.** `Field` renders a real `<label for>`, and a compound reading is a\n`<fieldset>` of one `Field` per part. The unit's spoken form joins the box's description,\neach option carries its plural on `aria-label`, and the box is `type=\"text\"` with\n`inputMode` defaulting to `decimal`. The advisory and the effect line are descriptions,\nwith no `aria-invalid` and no focus move. The audit made `autoComplete` a prop reaching\n`Field.Control`, defaulting to `\"off\"`, because a self-reported reading has no WCAG\nautofill token and the component invents none (1.3.5).\n\n**Residual items.**\n\n* The effect line reporting a switch sits in no live region, so a product must wire\n  `effectText` to a polite announcer. Without that, a non-sighted reader hears the new\n  unit but not that the number changed.\n* No hit area is measured.\n* The boundary inherits `--border` without a gated pair.\n\n<KeyboardTable\n  name=\"reading-input\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves to the box, then the unit switch&#x22;,\n    notes: &#x22;Three stops on a compound reading: two boxes and the switch.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Moves backwards through the same stops&#x22;,\n    notes: &#x22;Reverse order matches the visual order.&#x22;,\n  },\n  {\n    keys: &#x22;Any digit, . or ,&#x22;,\n    action: &#x22;Types into the focused box&#x22;,\n    notes: &#x22;Nothing is rejected, clamped or reformatted while typing.&#x22;,\n  },\n  {\n    keys: &#x22;Up / Down&#x22;,\n    action: &#x22;Changes the unit when the switch has focus&#x22;,\n    notes: &#x22;Native select. The entry converts or clears, and the line says which.&#x22;,\n  },\n  {\n    keys: &#x22;Enter&#x22;,\n    action: &#x22;Whatever the surrounding form does&#x22;,\n    notes: &#x22;Nothing is swallowed. Set enterKeyHint to name the return key's action.&#x22;,\n  },\n  {\n    keys: &#x22;Escape&#x22;,\n    action: &#x22;Nothing here&#x22;,\n    notes: &#x22;No overlay to dismiss, no entry to revert.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"reading-input\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"ReadingInputProps\" />\n\n`unit` is required and `value` is in it. Without `precision` a conversion is not rounded.\nThere is no `error` prop: an error belongs to `Field`.\n\n### Data attributes [#data-attributes]\n\n<DataAttributesTable\n  name=\"reading-input\"\n  rows=\"[\n  {\n    attribute: &#x22;data-slot&#x22;,\n    condition: &#x22;On the root, the control row, every segment and the unit, always.&#x22;,\n    value: &#x22;reading-input, reading-input-control, reading-input-segment, reading-input-unit&#x22;,\n  },\n  {\n    attribute: &#x22;data-slot&#x22;,\n    condition: &#x22;Legend and hint on a compound reading, warning when supplied, effect after a switch.&#x22;,\n    value: &#x22;reading-input-legend, reading-input-hint, reading-input-warning, reading-input-effect&#x22;,\n  },\n  {\n    attribute: &#x22;data-opsinjs-value&#x22;,\n    condition: &#x22;On every ReadingInput.Segment, always&#x22;,\n    value: &#x22;The number in that box, read off the box not the prop&#x22;,\n  },\n  {\n    attribute: &#x22;data-status, data-category&#x22;,\n    condition: &#x22;Never, at any value of any prop&#x22;,\n    value: &#x22;Never set&#x22;,\n  },\n]\"\n/>"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/relative-time",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/relative-time.md",
      "slug": [
        "components",
        "relative-time"
      ],
      "section": "Components",
      "title": "RelativeTime",
      "description": "When something happened, written the way people say it. The exact date and time stay in reach, and explicit words appear past the staleness boundary.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "ago",
        "timestamp",
        "last updated",
        "freshness",
        "staleness",
        "time ago",
        "date display"
      ],
      "implements": [],
      "governedBy": [
        "trends",
        "numbers",
        "alerts",
        "safety-review"
      ],
      "usedIn": [
        "daily-logging",
        "offline-and-stale-data",
        "sharing-with-a-clinician"
      ],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"relative-time\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;The component never ticks or reads the clock, so a surface left open for an hour keeps its first phrase; whether an opt-in re-rendering wrapper belongs is open.&#x22;,\n  &#x22;The five event words are English and locale does not translate them, and a prop to supply others would also let a product relabel synced as updated.&#x22;,\n  &#x22;The muted stale treatment is unmeasured against the muted fill, the tinted grounds it may share, and under increased contrast, and no preview renders it.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"relative-time\" unbuilt=\"false\" importPath=\"@/components/ui/relative-time\" />\n\n```tsx\nimport { RelativeTime } from \"@/components/ui/relative-time\"\n```\n\n```tsx\n<RelativeTime\n  at=\"2026-03-14T08:12:00+00:00\"\n  event=\"measured\"\n  now={new Date().toISOString()}\n  locale=\"en-GB\"\n/>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"relative-time\" />\n\n### A column of entries [#a-column-of-entries]\n\nEvery row names its `event`, and no row passes `staleAfterHours`.\n\n<ComponentPreview name=\"relative-time-in-a-log-list\" kind=\"example\" align=\"start\" />\n\n### Measured and synced are two different facts [#measured-and-synced-are-two-different-facts]\n\nBoth lines are true. The `event` prefix keeps a sync time from lending its reassurance\nto a reading taken eleven days earlier.\n\n<ComponentPreview name=\"relative-time-measured-and-synced\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;Saying when a reading was measured, a result was issued, a dose was taken, or data last synced.&#x22;,\n  &#x22;Any timestamp a reader will use to judge how much weight to give the thing it is attached to.&#x22;,\n  &#x22;Lists of recent entries, where an age is read far faster than two dates side by side.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;The date itself is the information. That is true of an appointment, a deadline and a date of birth.&#x22;, instead: &#x22;value&#x22; },\n  { case: &#x22;The reader must act by a certain time and needs the actual date and time.&#x22;, instead: &#x22;care-card&#x22; },\n  { case: &#x22;The event is far enough in the past that a relative phrase is less useful than the date.&#x22;, instead: &#x22;value&#x22; },\n  { case: &#x22;You are showing a duration rather than a point in time.&#x22;, instead: &#x22;value&#x22; },\n  { case: &#x22;The time is being entered rather than displayed.&#x22;, instead: &#x22;field&#x22; },\n]\"\n/>\n\n## Clinical meaning [#clinical-meaning]\n\n**Asserts.** That the named event happened at that instant and, past `staleAfterHours`,\nthat the product no longer considers the value current. It does not know what was\nmeasured. The phrase rounds down at every rung except the minute floor, but the\nstaleness verdict uses the exact elapsed time, not the phrase, as\n[Numbers and units](../health/numbers.mdx) requires.\n\n**Never read as.** Freshness of the data. *Synced 5 minutes ago* means the app spoke to\na server, not that the readings are that new, which is why `event` is required.\n\n**Colour axis.** Neither. The stale treatment is muted text carried by the words *may\nbe out of date*, never a status tint on a fact about the clock.\n\n**Thresholds.** Staleness belongs to the product: no default, no per-event default and\nnothing derived from `event`. Omit `staleAfterHours` and no stale treatment renders;\nsupply it and the words appear past the boundary, or wherever it could not be applied,\nas [Trends and uncertainty](../health/trends.mdx) asks. The muted treatment reaches\nthe `time` element only, so an embedding surface still owes the value's de-emphasis\nand a route to refresh.\n\n<SafetyCallout severity=\"attention\" evidence=\"opinion\">\n  Never put a sync time where a measurement time belongs. *Synced 2 minutes ago* above a\n  reading taken four months ago is two true statements that together mislead. Render both,\n  each with its event word.\n</SafetyCallout>\n\n## Accessibility [#accessibility]\n\nThere is no axe, target-size, focus-visible or 320px reflow issue and no critical or\nserious defect in the source. The exact date is always in the accessibility tree and\nin print, never behind hover, focus or a disclosure; `showAbsolute` moves it on screen\nonly. Staleness is stated in words, never by the muted tone alone, and the words stay\nat the surrounding foreground while the phrase recedes. The audit fixed one moderate\nitem: the log-list example's `list-none` `<ul>` lost its list semantics under Safari\nwith VoiceOver, so the rows read as generic text, and a `role=\"list\"` now restores the\nrole with no visual or API change.\n\n**Residual items.**\n\n* It mounts no live region and owns no timer, so nothing changes at runtime to\n  announce; a product re-rendering it should add no `aria-live`.\n* No `\"use client\"`, effect or clock read, so hydration is safe by determinism. Pass\n  an explicit `locale` or server and browser may differ.\n* The muted stale treatment's contrast on the muted or tinted grounds it may sit on is\n  unmeasured, and no shipped preview renders the stale state.\n* Screen readers in a language other than English are unverified.\n\n<KeyboardTable\n  name=\"relative-time\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Skips the timestamp&#x22;,\n    notes: &#x22;Not focusable and no keyboard behaviour: it holds no control.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Skips the timestamp&#x22;,\n    notes: &#x22;Same in reverse. The exact date is reached by reading, not operating.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"relative-time\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"RelativeTimeProps\" />\n\n`at`, `event` and `now` are required with no defaults. An `at` without an offset, or an\n`event` outside the five, renders nothing and warns in development. An unparseable `now`\nrenders the date alone. `absoluteAfterDays` defaults to `1`; `0` shows the\ndate at every age. `TimeEvent` is exported."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/result-card",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/result-card.md",
      "slug": [
        "components",
        "result-card"
      ],
      "section": "Components",
      "title": "ResultCard",
      "description": "One test result, shown in full. What was measured, the number, where it sits against its range, what that means in plain English, and what to do next.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "results",
        "lab result",
        "test result",
        "report card",
        "blood pressure",
        "a1c"
      ],
      "implements": [],
      "governedBy": [
        "two-colour-axes",
        "reference-ranges",
        "numbers",
        "trends",
        "high-stakes-moments",
        "consent-and-privacy",
        "safety-review"
      ],
      "usedIn": [
        "result-disclosure"
      ],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"result-card\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;The accessible name is the title alone, not title plus reading, and nobody has listened to whether that is enough.&#x22;,\n  &#x22;No contrast pair, hit area, printout or screen-reader pass has been measured on this card.&#x22;,\n  &#x22;The not-medical-advice note is not on this card, and whether products will place it is open.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"result-card\" unbuilt=\"false\" importPath=\"@/components/ui/result-card\" registryDependencies=\"[&#x22;status-pill&#x22;, &#x22;value&#x22;, &#x22;range-bar&#x22;, &#x22;relative-time&#x22;, &#x22;button&#x22;]\" />\n\n```tsx\nimport { ResultCard } from \"@/components/ui/result-card\"\nimport { EXAMPLE_SOURCE } from \"@/lib/opsinjs\"\n```\n\n```tsx\n<ResultCard\n  title=\"Example measurement\"\n  value={14}\n  unit=\"mg/dL\"\n  precision={0}\n  measuredAt=\"2026-03-14T08:12:00+00:00\"\n  now=\"2026-03-14T11:12:00+00:00\"\n  range={{ low: 10, high: 20, source: EXAMPLE_SOURCE }}\n  status=\"steady\"\n  category=\"labs\"\n  meaning=\"Two or three short sentences, in the second person, written by the product.\"\n/>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"result-card\" />\n\n### A reading made of two numbers [#a-reading-made-of-two-numbers]\n\n`segments` carries a compound reading, each part a real [Value](./value.mdx).\nThe unit prints once, is spoken after every part, and no bar is drawn.\n\n<ComponentPreview name=\"result-card-a-compound-reading\" kind=\"example\" align=\"start\" />\n\n### The smallest card, and the sentence it will not leave out [#the-smallest-card-and-the-sentence-it-will-not-leave-out]\n\nNo `range`, so no bar; no `status`, so no pill; no `provenance`, so no footnote.\nAn absent `meaning` still renders a sentence saying there is none.\n\n<ComponentPreview name=\"result-card-no-explanation-supplied\" kind=\"example\" align=\"start\" />\n\n### The same result at two ages [#the-same-result-at-two-ages]\n\nTwo cards differ only in `measuredAt` and share a level, because age lowers a\nreading's worth without raising the alarm.\n\n<ComponentPreview name=\"result-card-an-old-reading\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;A single result with room for its range, meaning and next step, behind authentication.&#x22;,\n  &#x22;A result seen for the first time, where the explanation matters as much as the number.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;Several readings side by side in a dashboard grid.&#x22;, instead: &#x22;metric-tile&#x22; },\n  { case: &#x22;The number has no range, no status and nothing to explain.&#x22;, instead: &#x22;value&#x22; },\n  { case: &#x22;You only need to show where a value sits within its range.&#x22;, instead: &#x22;range-bar&#x22; },\n  { case: &#x22;The main message is an instruction rather than a measurement.&#x22;, instead: &#x22;care-card&#x22; },\n  { case: &#x22;Something has changed and must interrupt the reader now.&#x22;, instead: &#x22;alert-banner&#x22; },\n]\"\n/>\n\n## Clinical meaning [#clinical-meaning]\n\n**Asserts.** A measurement was taken, at a time, in a unit, with any stated range and\nthe level the product assigned.\n[Every number](../health/numbers.mdx) goes through Value.\n\n**Never read as.** A diagnosis, a health summary or a clinician's advice. A next step\nis the product's, and your `meaning` and action labels say who is speaking. A result\nthat may distress needs [High-stakes moments](../health/high-stakes-moments.mdx)\naround it.\n\n**Colour axis.** Both, as [Two colour axes](../health/two-colour-axes.mdx) requires:\nstatus reaches only the [StatusPill](./status-pill.mdx), category only the title, and\nno prop tints the surface.\n\n**Thresholds.** The product's. No default [range](../health/reference-ranges.mdx),\nstatus derivation ([Two colour axes](../health/two-colour-axes.mdx)) or staleness\nboundary ([Trends and uncertainty](../health/trends.mdx)) exists here;\n`staleAfterHours` passes through to [RelativeTime](./relative-time.mdx). A reading you\ncannot vouch for must not drive `attention` or `urgent`.\n\n**Provenance and privacy.** `provenance` is free text with no\n[class](../health/trends.mdx), so keep an estimated or self-reported value free of\n`status` yourself. It has no mask; [Consent and privacy](../health/consent-and-privacy.mdx) is\nbuilt around the card.\n\n## Accessibility [#accessibility]\n\nThe audit changed nothing, finding no axe violation, target below the 44px floor or\nfocus-visible gap. The title is a real heading at the caller's level, the\n[StatusPill](./status-pill.mdx) carries a word and an icon, and the card reflows\nunclipped at 320px and 200%.\n\n**Residual items.**\n\n* By design, the root `<article>` takes `aria-label` from the title, not\n  `aria-labelledby`, matching the visible heading. A visible-heading reference is a\n  future enhancement.\n* `className` merges onto the root, so a caller's `truncate` can clip a reading. The\n  component truncates nothing; the JSDoc warns of it.\n* No gate checks print, `forced-colors` or `prefers-contrast`.\n\n<KeyboardTable\n  name=\"result-card\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves to the first action, where the card has one&#x22;,\n    notes: &#x22;The card itself is not a tab stop.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Moves backwards through the same stops&#x22;,\n    notes: &#x22;Reverse order matches visual order.&#x22;,\n  },\n  {\n    keys: &#x22;Enter&#x22;,\n    action: &#x22;Activates the focused action&#x22;,\n    notes: &#x22;Platform behaviour. Nothing is destructive.&#x22;,\n  },\n  {\n    keys: &#x22;Space&#x22;,\n    action: &#x22;Activates a focused button action&#x22;,\n    notes: &#x22;On an onSelect action only.&#x22;,\n  },\n  {\n    keys: &#x22;Escape&#x22;,\n    action: &#x22;Nothing&#x22;,\n    notes: &#x22;Not dismissible. Inside a Sheet or Dialog, Escape is theirs.&#x22;,\n  },\n  {\n    keys: &#x22;Arrow keys&#x22;,\n    action: &#x22;Nothing&#x22;,\n    notes: &#x22;The bar is role=\\&#x22;img\\&#x22;, not a slider.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"result-card\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"ResultCardProps\" />\n\n`now` and `precision` are required: the card never reads the clock, so pass one\n`now` to every card on a screen. `value` is `number | null`, never a string; a\npair is `segments`. A third action, a second `recommended` and a `titleLevel`\noutside 2 to 6 each warn once and fall back.\n\n### Data attributes [#data-attributes]\n\n<DataAttributesTable\n  name=\"result-card\"\n  rows=\"[\n  {\n    attribute: &#x22;data-slot&#x22;,\n    condition: &#x22;On every part, always&#x22;,\n    value: &#x22;result-card, result-card-header, -title, -time, -reading, -meaning, -actions, -footnote; result-card-action on a link action, button on an onSelect action&#x22;,\n  },\n  {\n    attribute: &#x22;data-status&#x22;,\n    condition: &#x22;On the embedded StatusPill only, with a status&#x22;,\n    value: &#x22;steady | watch | attention | urgent&#x22;,\n  },\n  {\n    attribute: &#x22;data-category&#x22;,\n    condition: &#x22;On ResultCard.Title, for one of the six categories&#x22;,\n    value: &#x22;sleep | heart | activity | nutrition | mind | labs&#x22;,\n  },\n  {\n    attribute: &#x22;data-opsinjs-value&#x22;,\n    condition: &#x22;On every Value, including a drawn RangeBar's. De-duplicate before scraping.&#x22;,\n    value: &#x22;The unrounded number, or an empty string with no reading&#x22;,\n  },\n]\"\n/>"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/scale-input",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/scale-input.md",
      "slug": [
        "components",
        "scale-input"
      ],
      "section": "Components",
      "title": "ScaleInput",
      "description": "A rating scale drawn from the points and end words the product supplies, for a self-report the product reads, shipping no instrument of its own.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "pain scale",
        "rating scale",
        "likert"
      ],
      "implements": [],
      "governedBy": [
        "health/index",
        "numbers"
      ],
      "usedIn": [],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"scale-input\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;No contrast pair has been measured, and the scale sets no surface of its own, so points are painted on the host's ground.&#x22;,\n  &#x22;Nobody has heard this scale in a screen reader, so whether the folded end words read as a scale is unknown.&#x22;,\n  &#x22;No named reviewer has signed this page off, so read every claim here as unattributed.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"scale-input\" unbuilt=\"false\" importPath=\"@/components/ui/scale-input\" dependencies=\"[&#x22;@base-ui/react&#x22;]\" />\n\n```tsx\nimport { ScaleInput } from \"@/components/ui/scale-input\"\n```\n\n```tsx\n<ScaleInput\n  label=\"Comfort right now\"\n  points={10}\n  value={rating}\n  onValueChange={setRating}\n  minLabel=\"Not at all\"\n  maxLabel=\"Completely\"\n/>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"scale-input\" />\n\n### A rating with end words [#a-rating-with-end-words]\n\nTen points with a word at each end, from `label`, `points`, `minLabel` and `maxLabel`.\n\n<ComponentPreview name=\"scale-input-rating-with-anchors\" kind=\"example\" align=\"start\" />\n\n### No answer yet [#no-answer-yet]\n\n`value` is `null`, so the scale draws with no point chosen rather than defaulting to\na middle the reader never picked.\n\n<ComponentPreview name=\"scale-input-no-answer-yet\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;One self-report on a scale the product's instrument defines, with the points and end words from the product.&#x22;,\n  &#x22;A single question asked repeatedly with the same points and end words, so the reader can watch their answer move.&#x22;,\n  &#x22;A rating with a low end and a high end the reader places themselves between, rather than unordered choices.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;The answer is free text in the reader's own words, not a point on a scale.&#x22;, instead: &#x22;textarea&#x22; },\n  { case: &#x22;The options are a fixed set of labelled choices with no end word and no ordering.&#x22;, instead: &#x22;radio-group&#x22; },\n  { case: &#x22;A multi-question instrument where several rated items add up under one heading.&#x22;, instead: &#x22;questionnaire&#x22; },\n]\"\n/>\n\n## Clinical meaning [#clinical-meaning]\n\n**Asserts.** The reader chose this point on a scale the product defined. The value\ngoes back through `onValueChange`, with no total, band, verdict or\ninterpretation added.\n\n**Never read as.** A score, a measurement or a result opsinjs derived. A far point is\na high self-report, and whether it matters is a clinical judgement this component does\nnot make; it never diagnoses, triages or advises. See [Health](../health/index.mdx).\n\n**Colour axis.** Neither. The scale writes neither `data-status` nor `data-category`,\nand the chosen point takes the accent fill, which is neither axis. A product that decides a rating\nmatters says so on its own status surface. See\n[Two colour axes](../health/two-colour-axes.mdx).\n\n**Thresholds.** None. The points and end words arrive through `points`, `minLabel`\nand `maxLabel`, and opsinjs ships no scale, no anchor words and no scoring. See\n[Health](../health/index.mdx) and [Numbers and units](../health/numbers.mdx).\n\n## Accessibility [#accessibility]\n\nOne tab stop with a roving focus: `role=\"radiogroup\"` on the root, `role=\"radio\"` and\n`aria-checked` on each point, and selection follows focus. Every point floors its hit\narea at `--opsin-target-minimum` in rem, and the row wraps rather than shrinking a\npoint below its target. The audit made the chosen point repaint in forced colours to\nthe system Highlight pair, with a Highlight border and `forced-color-adjust-none`, so\nselection stays distinct.\n\n**Residual items.**\n\n* The question reaches the radiogroup only as an `aria-label`, which is weaker than a\n  visible label. A visible label is the recommended enhancement, a decision shared\n  with combobox.\n* In normal mode the selection carries no glyph, so luminance inversion and the\n  border carry it without hue.\n* Every contrast pair on the host's ground is unmeasured, and the report below prints\n  only what has been measured.\n\n<KeyboardTable\n  name=\"scale-input\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves focus into the scale, onto the chosen point&#x22;,\n    notes: &#x22;One tab stop. Unanswered, the first point takes it; a disabled point never does.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Moves focus back out of the scale&#x22;,\n    notes: &#x22;A single stop in reverse too.&#x22;,\n  },\n  {\n    keys: &#x22;Arrow Right, Arrow Down&#x22;,\n    action: &#x22;Moves to the next point and selects it&#x22;,\n    notes: &#x22;Selection follows focus. Wraps last to first. Arrow Left and Right swap in right-to-left.&#x22;,\n  },\n  {\n    keys: &#x22;Arrow Left, Arrow Up&#x22;,\n    action: &#x22;Moves to the previous point and selects it&#x22;,\n    notes: &#x22;Wraps from the first to the last.&#x22;,\n  },\n  {\n    keys: &#x22;Space&#x22;,\n    action: &#x22;Selects the focused point&#x22;,\n    notes: &#x22;A point is a role=\\&#x22;radio\\&#x22;, so Space is its activator.&#x22;,\n  },\n  {\n    keys: &#x22;Enter&#x22;,\n    action: &#x22;Does nothing&#x22;,\n    notes: &#x22;The primitive cancels Enter, so the scale does not submit a form.&#x22;,\n  },\n  {\n    keys: &#x22;Home, End&#x22;,\n    action: &#x22;Not bound&#x22;,\n    notes: &#x22;The RadioGroup does not enable them, so they keep the browser default.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"scale-input\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"ScaleInputProps\" />\n\n`points` has no default, and fewer than two renders nothing with a development\nwarning. `value` is `number | null`: `null` draws nothing chosen, and a number\noutside 1 to `points` does the same and warns. `label` is required: a\nradiogroup with no accessible name is a defect the types cannot prevent.\n\n### Data attributes [#data-attributes]\n\n<DataAttributesTable\n  name=\"scale-input\"\n  rows=\"[\n  {\n    attribute: &#x22;data-checked, data-unchecked&#x22;,\n    condition: &#x22;On each point, stamped by the Base UI Radio&#x22;,\n    value: &#x22;One of the two, by whether the point is the chosen one&#x22;,\n  },\n]\"\n/>"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/score-dial",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/score-dial.md",
      "slug": [
        "components",
        "score-dial"
      ],
      "section": "Components",
      "title": "ScoreDial",
      "description": "A single composite score shown on a dial with its band named in words, alongside an honest statement of what went into the number.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "gauge",
        "dial",
        "ring",
        "score",
        "index",
        "bmi"
      ],
      "implements": [],
      "governedBy": [
        "reference-ranges",
        "numbers",
        "two-colour-axes",
        "alerts"
      ],
      "usedIn": [],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"score-dial\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;No provenance field exists, and nothing checks that the derivation names which inputs were device estimates and which the reader typed.&#x22;,\n  &#x22;The indicator against its tinted band fails the non-text contrast floor in both themes, and whether that arc may ship is open.&#x22;,\n  &#x22;The component mounts no live region, so what a screen reader hears when a score changes is unspecified.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"score-dial\" unbuilt=\"false\" importPath=\"@/components/ui/score-dial\" dependencies=\"[&#x22;lucide-react&#x22;]\" registryDependencies=\"[&#x22;value&#x22;, &#x22;status-pill&#x22;]\" />\n\n```tsx\nimport { ScoreDial } from \"@/components/ui/score-dial\"\n```\n\n```tsx\n<ScoreDial\n  label=\"Example composite score\"\n  value={14}\n  min={10}\n  max={20}\n  precision={0}\n  bands={[]}\n  derivation=\"Example data rather than a reference range. The score and the scale here are invented.\"\n  calculatedAt=\"2026-03-14T08:12:00+00:00\"\n/>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"score-dial\" />\n\n### opsinjs ships no bands [#opsinjs-ships-no-bands]\n\nThe dial is drawn as an instrument: a lit bezel, a ruled face, the scale's two ends and a needle on a hub. With an empty `bands`, it draws the scale, places the needle and names no band.\n\n<ComponentPreview name=\"score-dial-no-bands-supplied\" kind=\"example\" align=\"start\" />\n\n### A score built from less than usual [#a-score-built-from-less-than-usual]\n\n`coverage` puts the gap on the dial's face. `status=\"watch\"` is a prop on the dial, not a\nfield on a band.\n\n<ComponentPreview name=\"score-dial-partial-data\" kind=\"example\" align=\"start\" />\n\n### Zero is a score; absence is not [#zero-is-a-score-absence-is-not]\n\n`value={0}` reached the bottom of its scale. `value={null}` never ran, so nothing is placed.\n\n<ComponentPreview name=\"score-dial-zero-is-not-absence\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;A questionnaire total, a readiness index, or any score you calculated, meaningful only against its own bands.&#x22;,\n  &#x22;A bounded score whose scale the reader has no intuition for, where position carries more than digits.&#x22;,\n  &#x22;A score whose derivation you can state in one sentence, on the same screen.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;The number is a measurement rather than a calculation, with a published reference range.&#x22;, instead: &#x22;range-bar&#x22; },\n  { case: &#x22;You cannot say what went into the score, or it is a risk or probability, which a dial must never draw as an angle.&#x22;, instead: &#x22;value&#x22; },\n  { case: &#x22;The score is only meaningful as a trajectory, so one number says nothing alone.&#x22;, instead: &#x22;trend-sparkline&#x22; },\n  { case: &#x22;You are showing completion of something the person is doing, such as steps against a goal.&#x22;, instead: &#x22;progress&#x22; },\n  { case: &#x22;The score crossed a threshold that needs action now. The dial refuses attention and urgent.&#x22;, instead: &#x22;care-card&#x22; },\n]\"\n/>\n\n## Clinical meaning [#clinical-meaning]\n\n**Asserts.** The product computed a number from stated inputs, and it fell in a named\nband. It asserts a calculation, never a fact about the reader's body.\n\n**Never read as.** A measurement, a diagnosis, a percentage or a rank.\n[Numbers and units](../health/numbers.mdx) keeps probabilities off it, and the scale\nreads *on a scale of 10 to 20*, never *out of 20*.\n\n**Colour axis.** Status sits on the indicator and the band the score fell in, only when\nthe product passed `status`, and other bands stay neutral. Category tints the label\nalone, so [two colour axes](../health/two-colour-axes.mdx) never meet.\n\n**Thresholds.** The product owns every band and cut-off, and opsinjs ships none.\n`ScoreBand.source` is required, as [Reference ranges](../health/reference-ranges.mdx)\ndemands. `status` is an input, never derived, and `attention` and `urgent` are refused.\n\n**Staleness.** `calculatedAt` renders as a plain date, with no staleness treatment. Add\na RelativeTime when an old score must read as old.\n\n<SafetyCallout severity=\"attention\" evidence=\"opinion\">\n  When only part of the input data was available, `coverage` must say so. Name what was\n  counted in your derivation; it will not guess a noun.\n</SafetyCallout>\n\n## Accessibility [#accessibility]\n\nThe graphic is `role=\"img\"` with a complete `aria-label` and `focusable=\"false\"`, never\na `meter`, `progressbar` or `slider`, which would assert a within-range value it may not\nmake. Every status tint carries a word, a glyph and `data-status`, never colour alone,\nand the band name, scale, source and derivation are visible text no prop removes. One\nstacked column never truncates at 200% text, nothing animates, and nothing is\ninteractive, so keyboard and pointer criteria pass vacuously. It renders clean for axe,\ntarget size and 320px reflow, and the audit changed nothing.\n\n**Residual items.**\n\n* The static, read-only dial mounts no live region, so nothing announces a score change.\n  Adding one is a recommended enhancement, not a fix.\n* The tinted band strokes fall below the non-text floor in light, and stay because the\n  band name, the StatusPill word and glyph, the indicator and `data-status` say the same\n  thing.\n* The arc stroke against its card is not in the measured set, and the source records the\n  pair without a number.\n\n<KeyboardTable\n  name=\"score-dial\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Skips the dial&#x22;,\n    notes: &#x22;A picture of a reading, not a control.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Skips the dial&#x22;,\n    notes: &#x22;The SVG carries focusable=\\&#x22;false\\&#x22;.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"score-dial\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"ScoreDialProps\" />\n\n`bands` is required with no default, and may be an empty array. A `ScoreBand` carries\nan inclusive `from`, an exclusive `to`, a `name` in the reader's language and a required\n`source`. `status` accepts only `steady | watch`. `precision` is required, as\n[Numbers and units](../health/numbers.mdx) demands. A non-finite\n`value` prints and speaks *not available*.\n\n### Data attributes [#data-attributes]\n\n<DataAttributesTable\n  name=\"score-dial\"\n  rows=\"[\n  {\n    attribute: &#x22;data-slot&#x22;,\n    condition: &#x22;On every part that renders&#x22;,\n    value: &#x22;score-dial, score-dial-label, score-dial-track, score-dial-band, score-dial-boundary, score-dial-indicator, score-dial-reading, score-dial-score, score-dial-band-name, status-pill, score-dial-coverage, score-dial-scale, score-dial-band-source, score-dial-derivation, score-dial-calculated-line, score-dial-calculated-at&#x22;,\n  },\n  {\n    attribute: &#x22;data-status&#x22;,\n    condition: &#x22;On the band the score fell in, the indicator and the StatusPill&#x22;,\n    value: &#x22;steady | watch&#x22;,\n  },\n  {\n    attribute: &#x22;data-category&#x22;,\n    condition: &#x22;On ScoreDial.Label, with a category&#x22;,\n    value: &#x22;sleep | heart | activity | nutrition | mind | labs&#x22;,\n  },\n  {\n    attribute: &#x22;data-opsinjs-value&#x22;,\n    condition: &#x22;On the Value inside ScoreDial.Score&#x22;,\n    value: &#x22;The unrounded number, or empty with no reading&#x22;,\n  },\n]\"\n/>"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/scroll-area",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/scroll-area.md",
      "slug": [
        "components",
        "scroll-area"
      ],
      "section": "Components",
      "title": "ScrollArea",
      "description": "A bounded scrolling region with a thin neutral scrollbar that keeps a card or panel's overflow reachable without replacing the page's own native scroll.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "scroller",
        "overflow container"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"scroll-area\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;No contrast pair has been measured for the thumb against the surfaces it rides over, at the 3:1 non-text floor for a control.&#x22;,\n  &#x22;Nobody has scrolled this region with a screen reader or a switch device, so whether a reader is told they entered a scrollable region is unknown.&#x22;,\n  &#x22;Behaviour at 200% text and under browser zoom is untested, and a height ceiling that clips is the exact failure this component exists to avoid.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"scroll-area\" unbuilt=\"false\" importPath=\"@/components/ui/scroll-area\" dependencies=\"[&#x22;@base-ui/react&#x22;]\" />\n\n```tsx\nimport { ScrollArea } from \"@/components/ui/scroll-area\"\n```\n\n```tsx\n<ScrollArea maxHeight=\"16rem\" className=\"rounded-lg border\">\n  <ul>\n    {items.map((item) => (\n      <li key={item.id}>{item.label}</li>\n    ))}\n  </ul>\n</ScrollArea>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"scroll-area\" />\n\n### A long list [#a-long-list]\n\nThe list outruns its box, so `maxHeight` bounds the region and the rail appears\nwhile the page around it keeps its native scroll.\n\n<ComponentPreview name=\"scroll-area-a-long-list\" kind=\"example\" align=\"start\" />\n\n### In a card [#in-a-card]\n\nOne bounded panel with a heading fixed above the region, so `maxHeight` makes\nonly the card body overflow and scroll.\n\n<ComponentPreview name=\"scroll-area-in-a-card\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;Bounding one card, panel or list to a height where its content is longer than the box.&#x22;,\n  &#x22;A wide row of cards or a table that scrolls sideways inside its column.&#x22;,\n  &#x22;Holding one block's height steady on a surface that still scrolls natively.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;Wrapping the whole page or the reading column, where a bounded height clips content at 200% text.&#x22;, instead: &#x22;the browser's own page scroll&#x22;, href: &#x22;../foundations/accessibility.mdx&#x22; },\n  { case: &#x22;A small block that already fits, wrapped on the chance that it might grow.&#x22;, instead: &#x22;card&#x22; },\n]\"\n/>\n\n## Accessibility [#accessibility]\n\nThe viewport holds a keyboard tab stop and takes an accessible name through `label` or\n`labelledBy`. Reflow and target size pass, with no colour-axis, token, `px` or\ncolour-literal issue. The audit fixed one serious defect: the viewport was not a\nreliable tab stop and had no name, so a screen reader met an unnamed stop. The\ndefault demo and both examples now name their region, one by pointing `labelledBy`\nat its on-screen heading.\n\n**Residual items.**\n\n* In the card example the rounded corners can partly clip the focus ring at the flush\n  bottom edge, though the indicator stays perceivable.\n* The thumb's contrast and the pairs below are not measured in source.\n\n<KeyboardTable\n  name=\"scroll-area\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves focus onto the viewport when it is scrollable&#x22;,\n    notes: &#x22;One tab stop for the region. Base UI drops it when there is nothing to scroll.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Moves focus back out of the viewport&#x22;,\n    notes: &#x22;A single stop in reverse too, so focus does not step through the rails.&#x22;,\n  },\n  {\n    keys: &#x22;Arrow keys&#x22;,\n    action: &#x22;Scroll the focused viewport&#x22;,\n    notes: &#x22;The browser's own behaviour on a focused scroll container, along the allowed axes.&#x22;,\n  },\n  {\n    keys: &#x22;Page Up, Page Down&#x22;,\n    action: &#x22;Scroll the focused viewport by a page&#x22;,\n    notes: &#x22;The browser's default, not a key this component binds.&#x22;,\n  },\n  {\n    keys: &#x22;Home, End&#x22;,\n    action: &#x22;Scroll to the start or end of the focused viewport&#x22;,\n    notes: &#x22;Again the browser's default on a scroll container.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"scroll-area\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"ScrollAreaProps\" />\n\n`maxHeight` gives the region something to overflow, so set it in a rem rather\nthan a pixel count. Given neither it nor a height class, the region grows to fit\nand a development warning names the omission. `className` is the one route by\nwhich colour reaches the region, and the two-colour-axes rule applies in full.\n\n### Data attributes [#data-attributes]\n\n<DataAttributesTable\n  name=\"scroll-area\"\n  rows=\"[\n  {\n    attribute: &#x22;data-slot&#x22;,\n    condition: &#x22;On the root and every inner part, always&#x22;,\n    value: &#x22;scroll-area, scroll-area-viewport, scroll-area-scrollbar, scroll-area-thumb, scroll-area-corner&#x22;,\n  },\n  {\n    attribute: &#x22;data-orientation&#x22;,\n    condition: &#x22;On a scrollbar, set by Base UI&#x22;,\n    value: &#x22;vertical or horizontal&#x22;,\n  },\n  {\n    attribute: &#x22;data-hovering, data-scrolling&#x22;,\n    condition: &#x22;On a scrollbar while hovered or while the region scrolls&#x22;,\n    value: &#x22;What the rail's fade-in is keyed to&#x22;,\n  },\n]\"\n/>"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/segmented-control",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/segmented-control.md",
      "slug": [
        "components",
        "segmented-control"
      ],
      "section": "Components",
      "title": "SegmentedControl",
      "description": "A row of mutually exclusive options with exactly one chosen at a time, for switching a single view between a small set of windows.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "segmented buttons",
        "toggle group"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"segmented-control\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;No contrast pair has been measured for the selected segment against the track or for its hairline, so greyscale legibility is argued rather than measured.&#x22;,\n  &#x22;Nobody has listened to this control in a screen reader, so whether \\&#x22;radiogroup\\&#x22; is the register a reader expects for a button-like row is unchecked.&#x22;,\n  &#x22;Forced colours and `prefers-contrast: more` are unhandled, so whether the selected segment still reads as selected in those modes is untested.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"segmented-control\" unbuilt=\"false\" importPath=\"@/components/ui/segmented-control\" dependencies=\"[&#x22;@base-ui/react&#x22;]\" />\n\n```tsx\nimport { SegmentedControl } from \"@/components/ui/segmented-control\"\n```\n\n```tsx\n<SegmentedControl\n  label=\"Chart window\"\n  value={chartWindow}\n  onValueChange={setChartWindow}\n  options={[\n    { value: \"day\", label: \"Day\" },\n    { value: \"week\", label: \"Week\" },\n    { value: \"month\", label: \"Month\" },\n  ]}\n/>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"segmented-control\" />\n\n### Switching a chart window [#switching-a-chart-window]\n\nThe three options set the window of one chart rather than swapping between three\ncharts, which is why it is a radiogroup. The chart is a placeholder.\n\n<ComponentPreview name=\"segmented-control-switching-a-chart-window\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;Switching one view between a small set of mutually exclusive windows, such as a chart's day, week or month range.&#x22;,\n  &#x22;Choosing one setting from two to five short, comparable options that fit on one row and read as siblings.&#x22;,\n  &#x22;A choice the reader changes often and wants the whole set in front of them.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;The options open different views with their own content, so choosing one swaps what the reader is looking at.&#x22;, instead: &#x22;tabs&#x22; },\n  { case: &#x22;There are more than about five options, or the labels are long, so the row will not fit one line.&#x22;, instead: &#x22;field&#x22; },\n  { case: &#x22;The control performs an action rather than setting a value, such as saving a reading.&#x22;, instead: &#x22;button&#x22; },\n]\"\n/>\n\n## Accessibility [#accessibility]\n\nIt is a radio group, so the row is one tab stop with a roving focus, with\n`radiogroup` plus `radio` and `aria-checked` per segment for name, role and\nvalue. Selection is carried three ways and never by colour alone: `aria-checked`,\nthe card surface lifting the segment off the track, and a hairline. That lift is one\n`aria-hidden` puck which glides to the next choice on `spring-snap`, and until the\nscript has measured the row the chosen segment draws the same lift itself. Under\n`prefers-reduced-motion` the puck moves in one frame. The audit\nmoved the 44px hit-area floor from the height axis alone onto both axes, matching\n`scale-input` and `tab-bar`, because a single-character label or the `sm` size\ncould shrink a segment below the house minimum.\n\n**Residual items.**\n\n* `label` is applied only as the group's `aria-label`, so there is no persistent visible group heading. Every option carries visible text, so the choices are seen, but a visible group label is a recommended enhancement, deferred as one repair across the wrappers that share this pattern.\n* No contrast pair has been measured, so greyscale legibility of the selected segment is argued, not confirmed.\n\n<KeyboardTable\n  name=\"segmented-control\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves focus into the control, onto the selected segment&#x22;,\n    notes: &#x22;The group is one tab stop. A disabled segment never takes it.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Moves focus back out of the control&#x22;,\n    notes: &#x22;One stop in reverse too, so focus leaves the whole row.&#x22;,\n  },\n  {\n    keys: &#x22;Arrow Right, Arrow Down&#x22;,\n    action: &#x22;Moves to the next segment and selects it&#x22;,\n    notes: &#x22;Selection follows focus. It wraps, skips disabled segments and mirrors under right-to-left.&#x22;,\n  },\n  {\n    keys: &#x22;Arrow Left, Arrow Up&#x22;,\n    action: &#x22;Moves to the previous segment and selects it&#x22;,\n    notes: &#x22;Wraps from the first segment to the last and skips disabled segments.&#x22;,\n  },\n  {\n    keys: &#x22;Space&#x22;,\n    action: &#x22;Selects the focused segment&#x22;,\n    notes: &#x22;A segment is a role=\\&#x22;radio\\&#x22;, so Space is its activator.&#x22;,\n  },\n  {\n    keys: &#x22;Enter&#x22;,\n    action: &#x22;Does nothing&#x22;,\n    notes: &#x22;The primitive cancels Enter, so a form is never submitted by accident.&#x22;,\n  },\n  {\n    keys: &#x22;Home, End&#x22;,\n    action: &#x22;Not bound&#x22;,\n    notes: &#x22;The RadioGroup primitive disables them, so the browser's default applies.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"segmented-control\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"SegmentedControlProps\" />\n\n`value` and `onValueChange` make this controlled, with no internal selection\nstate. A `value` matching no option renders the row with nothing chosen and\nraises a development warning. `label` is required: a radiogroup with no\naccessible name is a defect the type system cannot otherwise prevent.\n\n### Data attributes [#data-attributes]\n\n<DataAttributesTable\n  name=\"segmented-control\"\n  rows=\"[\n  {\n    attribute: &#x22;data-slot&#x22;,\n    condition: &#x22;On the root and every inner part&#x22;,\n    value: &#x22;segmented-control, segmented-control-indicator, segmented-control-segment, segmented-control-label&#x22;,\n  },\n  {\n    attribute: &#x22;data-checked / data-unchecked&#x22;,\n    condition: &#x22;On each segment, one or the other&#x22;,\n    value: &#x22;Present with no value; reflects the choice&#x22;,\n  },\n  {\n    attribute: &#x22;data-glide&#x22;,\n    condition: &#x22;On the root once the puck has been measured and placed&#x22;,\n    value: &#x22;Present with no value; the chosen segment hands its lift to the puck&#x22;,\n  },\n]\"\n/>"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/select",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/select.md",
      "slug": [
        "components",
        "select"
      ],
      "section": "Components",
      "title": "Select",
      "description": "A trigger that opens a floating list to choose one option from, built on Base UI Select and drawing only neutral chrome.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "dropdown",
        "picker"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"select\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;Nobody has heard this in a screen reader, so whether the open, move and choose sequence reads cleanly is unknown.&#x22;,\n  &#x22;No contrast pair has been measured; the trigger ink, the popup ink, the placeholder and the hairline are argued, not checked.&#x22;,\n  &#x22;Whether the popup's one shadow rung still separates the list under forced colours is untested, and no prefers-contrast rule exists.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"select\" unbuilt=\"false\" importPath=\"@/components/ui/select\" dependencies=\"[&#x22;@base-ui/react&#x22;, &#x22;lucide-react&#x22;]\" />\n\n```tsx\nimport { Select } from \"@/components/ui/select\"\n```\n\n```tsx\n<Select\n  label=\"Timezone\"\n  placeholder=\"Choose a timezone\"\n  value={timezone}\n  onValueChange={setTimezone}\n  options={[\n    { value: \"lisbon\", label: \"Lisbon\" },\n    { value: \"berlin\", label: \"Berlin\" },\n    { value: \"tokyo\", label: \"Tokyo\" },\n  ]}\n/>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"select\" />\n\n### Choosing from a list [#choosing-from-a-list]\n\n`options` drives the list, here a set of fictional timezones. A tick and a\nneutral highlight carry the selection, not a colour.\n\n<ComponentPreview name=\"select-choosing-from-a-list\" kind=\"example\" align=\"start\" />\n\n### With a placeholder [#with-a-placeholder]\n\n`placeholder` fills the trigger before anything is chosen: a prompt, not a\nvalue, and it never appears in the list.\n\n<ComponentPreview name=\"select-with-a-placeholder\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;Choosing one value from a list too long to lay flat, such as a timezone.&#x22;,\n  &#x22;A single choice on a dense form, where a closed trigger keeps a long list from pushing fields down.&#x22;,\n  &#x22;A setting the reader changes rarely, so opening the list costs little.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;Fewer than about seven options, easier scanned flat.&#x22;, instead: &#x22;radio-group&#x22; },\n  { case: &#x22;A clinical value with a range and a verdict, needing a control that formats it.&#x22;, instead: &#x22;reading-input&#x22; },\n  { case: &#x22;The options open different views, so choosing one swaps what the reader sees.&#x22;, instead: &#x22;tabs&#x22; },\n]\"\n/>\n\n## Accessibility [#accessibility]\n\nBase UI supplies a combobox trigger, a listbox popup and `aria-selected` options, and\nicons are `aria-hidden`. Selection is shown by a Check glyph and `aria-selected`, not\ncolour. The focus ring, the `--opsin-target-minimum` hit area, neutral chrome colours\nand non-`px` type sizes all hold. The list unfolds from the trigger, and under\n`prefers-reduced-motion` only a short opacity crossfade remains.\n\n**Residual items.**\n\n* The required `label` becomes the trigger's `aria-label`, so once a value fills the\n  trigger a reader can lose its programmatic name. Several wrappers share this gap,\n  and it waits on one system-wide repair.\n* At 200% text a long value truncates in the trigger, with no loss of function, since\n  the full label stays readable in the open list.\n* Contrast pairs and the popup under `forced-colors: active` are still unmeasured.\n\n<KeyboardTable\n  name=\"select\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves focus onto the trigger&#x22;,\n    notes: &#x22;One tab stop; disabled selects are skipped.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Moves focus back off the trigger&#x22;,\n    notes: &#x22;Never enters the list.&#x22;,\n  },\n  {\n    keys: &#x22;Enter, Space, Arrow Down, Arrow Up&#x22;,\n    action: &#x22;Opens the list from the trigger&#x22;,\n    notes: &#x22;Highlight lands on the chosen or first enabled option.&#x22;,\n  },\n  {\n    keys: &#x22;Arrow Down, Arrow Up&#x22;,\n    action: &#x22;Moves the highlight through the open list&#x22;,\n    notes: &#x22;Disabled options are skipped. No wrapping.&#x22;,\n  },\n  {\n    keys: &#x22;Home, End&#x22;,\n    action: &#x22;Moves the highlight to the first or last option&#x22;,\n    notes: &#x22;Both skip disabled options.&#x22;,\n  },\n  {\n    keys: &#x22;Enter&#x22;,\n    action: &#x22;Chooses the highlighted option and closes the list&#x22;,\n    notes: &#x22;Focus returns to the trigger, showing the value.&#x22;,\n  },\n  {\n    keys: &#x22;Escape&#x22;,\n    action: &#x22;Closes the list without choosing&#x22;,\n    notes: &#x22;The value is left as it was.&#x22;,\n  },\n  {\n    keys: &#x22;Type a letter&#x22;,\n    action: &#x22;Jumps to the next option whose label starts with what was typed&#x22;,\n    notes: &#x22;Base UI type-to-find, unchecked against a screen reader.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"select\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"SelectProps\" />\n\n`value` and `onValueChange` make this controlled: no internal selection state,\nand a value matching no option shows the placeholder. `label` is required, so\nthe trigger always has an accessible name."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/sheet",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/sheet.md",
      "slug": [
        "components",
        "sheet"
      ],
      "section": "Components",
      "title": "Sheet",
      "description": "A panel that slides up from the bottom, stops at sensible heights, and can be dragged or dismissed. The one-handed way to act without leaving the page.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "drawer",
        "bottom sheet",
        "modal sheet",
        "detent",
        "side panel",
        "slide over"
      ],
      "implements": [],
      "governedBy": [
        "alerts",
        "consent-and-privacy"
      ],
      "usedIn": [
        "alert-escalation",
        "consent-and-permissions",
        "daily-logging"
      ],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"sheet\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;No prop translates the two English strings Sheet ships. Where does a component's own copy live outside English?&#x22;,\n  &#x22;The software-keyboard handling has never run on a real device, so the uncovered primary action is only argued.&#x22;,\n  &#x22;Nothing here was measured in a browser. What gets measured first: hit areas, a real keyboard, or iOS scrolling?&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"sheet\" unbuilt=\"false\" importPath=\"@/components/ui/sheet\" dependencies=\"[&#x22;@base-ui/react&#x22;, &#x22;lucide-react&#x22;]\" registryDependencies=\"[&#x22;surface&#x22;, &#x22;button&#x22;]\" />\n\n```tsx\nimport { Sheet } from \"@/components/ui/sheet\"\n```\n\n```tsx\n<Sheet open={open} onOpenChange={setOpen} title=\"Add a reading\">\n  <Sheet.Content>\n    <Sheet.Description>What this sheet is for.</Sheet.Description>\n    {/* … */}\n  </Sheet.Content>\n</Sheet>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"sheet\" />\n\n### A form the reader cannot leave by accident [#a-form-the-reader-cannot-leave-by-accident]\n\n`dismissible={false}` cancels the scrim, Escape and a downward drag, and\nreturns focus to the container.\n\n<ComponentPreview name=\"sheet-a-form-that-stays-put\" kind=\"example\" align=\"start\" />\n\n### Two detents, and the button the gesture owes [#two-detents-and-the-button-the-gesture-owes]\n\nA second `detents` entry makes the grabber a real button, moving the sheet\nbetween half and full with no pointer.\n\n<ComponentPreview name=\"sheet-two-detents-and-a-control\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;A focused task started from the current screen, such as capturing a reading.&#x22;,\n  &#x22;Content reachable one-handed, where the thumb is.&#x22;,\n  &#x22;A surface whose height follows its content, not the viewport.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;A repeated daily log entry, with its own contract and ceiling.&#x22;, instead: &#x22;log-sheet&#x22; },\n  { case: &#x22;Asking permission to collect or share data.&#x22;, instead: &#x22;consent-sheet&#x22; },\n  { case: &#x22;A decision the reader must make before continuing, at any width.&#x22;, instead: &#x22;dialog&#x22; },\n  { case: &#x22;A panel that stays put while the reader works behind it.&#x22;, instead: &#x22;surface&#x22; },\n  { case: &#x22;A small menu anchored to a control.&#x22;, instead: &#x22;popover&#x22; },\n]\"\n/>\n\n## Accessibility [#accessibility]\n\nThe rendered pass found no axe, target-size, focus-ring or reflow failure at 320px, and\nnothing was changed. A modal sheet takes the dialog role, named by `Sheet.Title`, and\ntraps focus, with the page behind `aria-hidden`, not `inert`. Every gesture has a\ncontrol: close for drag-to-dismiss, grabber for drag-between-detents. The footer sits\noutside the scrolling region and inside the keyboard inset, keeping the primary action\nvisible. Under `prefers-reduced-motion` the sheet crossfades in place, and the drag\nstill works. Close sinks when pressed, so a tap on the one guaranteed exit shows it\nlanded.\n\n**Residual items.** Focus rings use a negative outline offset to stay visible inside the\nclipped popup, meeting 2.4.7 and 1.4.11. No live region announces the new height. The\ngrabber's accessible name updates to name the next action instead. `modal={false}` pins\nthe sheet to the bottom while the page behind stays focusable, an unchecked obscured-focus\nshape. Default and demo stay modal.\n\n<KeyboardTable\n  name=\"sheet\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves through the sheet's own controls&#x22;,\n    notes: &#x22;Trapped in a modal sheet.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Moves backwards through the same controls&#x22;,\n    notes: &#x22;Reverse order; footer stays last.&#x22;,\n  },\n  {\n    keys: &#x22;Enter&#x22;,\n    action: &#x22;Activates the focused control&#x22;,\n    notes: &#x22;Moves the grabber to the next detent.&#x22;,\n  },\n  {\n    keys: &#x22;Space&#x22;,\n    action: &#x22;Activates the focused button, or scrolls the content&#x22;,\n    notes: &#x22;Scrolls Sheet.Content, not the page.&#x22;,\n  },\n  {\n    keys: &#x22;Escape&#x22;,\n    action: &#x22;Closes a dismissible sheet and returns focus to what opened it&#x22;,\n    notes: &#x22;With dismissible={false}, returns to the container.&#x22;,\n  },\n  {\n    keys: &#x22;Arrow keys&#x22;,\n    action: &#x22;Scroll the content, once focus is in the scrolling region&#x22;,\n    notes: &#x22;Only the grabber changes detent.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"sheet\" />\n\n## Props interface [#props-interface]\n\n### Sheet [#sheet]\n\n<PropsTable name=\"SheetProps\" />\n\n`detents` defaults to `[\"content\"]`; its first entry is where the sheet opens.\n`half` and `full` combine, `content` stands alone. `onOpenChange` receives the\nclose route second, so a product can ask before discarding unsaved work.\n\n### Sheet.Content [#sheetcontent]\n\n<PropsTable name=\"SheetContentProps\" />\n\n### Sheet.Description [#sheetdescription]\n\n<PropsTable name=\"SheetDescriptionProps\" />\n\n### Data attributes [#data-attributes]\n\n<DataAttributesTable\n  name=\"sheet\"\n  rows=\"[\n  {\n    attribute: &#x22;data-slot&#x22;,\n    condition: &#x22;On every rendered part&#x22;,\n    value: &#x22;sheet-container, sheet-grabber, sheet-header, sheet-title, sheet-close, sheet-scrim, sheet-content, sheet-description, sheet-footer&#x22;,\n  },\n  {\n    attribute: &#x22;data-open, data-closed, data-starting-style, data-ending-style&#x22;,\n    condition: &#x22;On the viewport, the scrim and the container&#x22;,\n    value: &#x22;present&#x22;,\n  },\n  {\n    attribute: &#x22;data-expanded&#x22;,\n    condition: &#x22;While the active detent is full&#x22;,\n    value: &#x22;present&#x22;,\n  },\n  {\n    attribute: &#x22;data-swiping, data-swipe-dismiss, data-swipe-direction&#x22;,\n    condition: &#x22;During a drag; dismiss means release would close it&#x22;,\n    value: &#x22;present, direction down&#x22;,\n  },\n  {\n    attribute: &#x22;data-drawer-content&#x22;,\n    condition: &#x22;Always; makes a touch there scroll, not swipe&#x22;,\n    value: &#x22;present&#x22;,\n  },\n]\"\n/>"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/skeleton",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/skeleton.md",
      "slug": [
        "components",
        "skeleton"
      ],
      "section": "Components",
      "title": "Skeleton",
      "description": "A grey placeholder in the shape of the content that is loading, so the page does not jump when it arrives. It is never in the shape of a number.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "loading placeholder",
        "shimmer",
        "loading state",
        "placeholder",
        "ghost"
      ],
      "implements": [],
      "governedBy": [
        "alerts",
        "trends"
      ],
      "usedIn": [
        "empty-and-first-use",
        "trend-review"
      ],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"skeleton\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;Nothing in opsinjs owns the long end of a wait: past the few seconds Data states allows, a skeleton should have become words, and no threshold is measured.&#x22;,\n  &#x22;Shimmer defaults to on because a motionless rectangle can read as stalled content, and nobody has watched an anxious reader look at either state.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"skeleton\" unbuilt=\"false\" importPath=\"@/components/ui/skeleton\" />\n\n```tsx\nimport { Skeleton } from \"@/components/ui/skeleton\"\n```\n\n```tsx\n<Skeleton shape=\"text\" lines={3} appearAfterMs={200} />\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"skeleton\" />\n\n### A list that is still arriving [#a-list-that-is-still-arriving]\n\nThree rows of `aria-hidden` skeletons, with one polite `role=\"status\"` message the\ncaller mounts beside the busy list rather than inside it. Every skeleton passes\n`appearAfterMs`, so a warm cache never shows one.\n\n<ComponentPreview name=\"skeleton-a-loading-list\" kind=\"example\" align=\"start\" />\n\n### A row that may turn out to be empty [#a-row-that-may-turn-out-to-be-empty]\n\nThe label gets a placeholder because every row has one. The value's seat gets\nheight and no shape, because whether a reading exists is what the request will\nanswer.\n\n<ComponentPreview name=\"skeleton-a-row-that-may-be-empty\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;Content whose size and position are known in advance, arriving within roughly a second, where the alternative is the layout jumping when it lands.&#x22;,\n  &#x22;Lists and grids where a known number of items is loading and the reader benefits from seeing the shape of what is coming.&#x22;,\n  &#x22;Any surface where a spinner would replace a whole screen with nothing.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;There is nothing coming. The surface is genuinely empty.&#x22;, instead: &#x22;empty-state&#x22; },\n  { case: &#x22;Loading did not complete.&#x22;, instead: &#x22;alert-banner&#x22; },\n  { case: &#x22;The wait is long enough that the reader needs to know it is a long wait.&#x22;, instead: &#x22;callout&#x22; },\n  { case: &#x22;The shape and size of what is coming are unknown, so the skeleton would guess.&#x22;, instead: &#x22;spinner&#x22; },\n  { case: &#x22;A single control is busy after the reader pressed it.&#x22;, instead: &#x22;button&#x22; },\n]\"\n/>\n\n## Accessibility [#accessibility]\n\nRendered, it shows no violation, target-size hit, missing focus-visible state or\nreflow failure at 320px, and the audit changed nothing. On every commit\n`pnpm run check:a11y` checks that no status colour can reach a skeleton, that every\ncolour is a theme role (`bg-placeholder-fill`, `border-placeholder-line`), and that no\ntype size is in `px`. `pnpm run contrast` measures the placeholder line clearing the\nnon-text floor against the page, a card and the muted ground in both themes.\n\n**Argued from the source, not measured.**\n\n* The root is `aria-hidden`, nothing is focusable or interactive, and it is\n  `print:hidden`.\n* No live region mounts, on purpose. A list of many skeletons should be announced once,\n  not once per block, so the caller owns one `role=\"status\"` message beside the region\n  rather than inside it, as both examples show.\n* The shimmer is declared inside a `prefers-reduced-motion: no-preference` query, so\n  under reduce it never runs and the static tint remains.\n* The shimmer runs two cycles, about 3.2 seconds, then stops on the static tint, so\n  SC 2.2.2 does not engage. The appearance delay is never suppressed.\n* There is no `forced-colors` or `prefers-contrast` override, because the decorative,\n  `aria-hidden` root has no information an override would need to preserve.\n\n**Residual items.** `pnpm run contrast` puts the placeholder line below Lc 45 against\nits own fill in the dark theme, and the fill is published as advisory. No gate checks\nthe 200% and 1.3x layout claims, what a screen reader announces, the dark-theme\nboundary on its own fill, or the text rhythm on a browser without the `lh` unit.\n\n<KeyboardTable\n  name=\"skeleton\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Skips the skeleton&#x22;,\n    notes: &#x22;Nothing inside one is focusable. A stop that vanishes on load is worse than none.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Skips the skeleton&#x22;,\n    notes: &#x22;Same in reverse, at any shape, with or without the shimmer.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"skeleton\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"SkeletonProps\" />\n\n`Skeleton` is a server component: `appearAfterMs` is a CSS `animation-delay`,\nnot a timer, so the placeholder holds the layout before hydration. A `shape`\noutside the four resolves to `text`. `lines` is clamped to 1 to 24. No part is\nexported; style them through `data-slot`."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/slider",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/slider.md",
      "slug": [
        "components",
        "slider"
      ],
      "section": "Components",
      "title": "Slider",
      "description": "A single coarse, non-clinical preference set by dragging a thumb along a track, and never a clinical reading or a precise measurement.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "range input",
        "drag to set"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"slider\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;No contrast pair has been measured: the knob against the accent fill and the muted track, and the focus ring against all three.&#x22;,\n  &#x22;Nobody has heard this in a screen reader, and the thumb carries no aria-valuetext, so it speaks a raw number rather than a described position.&#x22;,\n  &#x22;Forced colours and prefers-contrast: more are unhandled, and whether the thumb still reads as a distinct object on the track is untested.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"slider\" unbuilt=\"false\" importPath=\"@/components/ui/slider\" dependencies=\"[&#x22;@base-ui/react&#x22;]\" />\n\n```tsx\nimport { Slider } from \"@/components/ui/slider\"\n```\n\n```tsx\n<Slider\n  label=\"Screen brightness\"\n  value={brightness}\n  onValueChange={setBrightness}\n/>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"slider\" />\n\n### A coarse preference [#a-coarse-preference]\n\nA fictional notification volume from nought to a hundred, driven by `value` and\n`onValueChange`.\n\n<ComponentPreview name=\"slider-a-coarse-preference\" kind=\"example\" align=\"start\" />\n\n### With steps [#with-steps]\n\n`min`, `max` and `step` snap the thumb to stops: a fictional map zoom running\nfrom one to nine in twos.\n\n<ComponentPreview name=\"slider-with-steps\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;A coarse, non-clinical preference such as a brightness level, where the exact number does not matter.&#x22;,\n  &#x22;A value adjusted by feel, where sliding towards more or less beats typing a figure.&#x22;,\n  &#x22;A setting with a small set of stops the reader can actually mean.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;You are capturing a clinical reading. A slider turns a value the person meant into a value the pixel chose.&#x22;, instead: &#x22;reading-input&#x22; },\n  { case: &#x22;You need a precise non-clinical quantity where the digits matter.&#x22;, instead: &#x22;number-field&#x22; },\n  { case: &#x22;The reader picks one of a small set of named options rather than a point on a continuum.&#x22;, instead: &#x22;segmented-control&#x22; },\n]\"\n/>\n\n## Accessibility [#accessibility]\n\nThe audit found no axe violation, target-size breach or reflow failure, and\nchanged nothing. The thumb wraps Base UI unmodified, so click-to-position plus\nArrow, Home, End and Page keys give every drag a keyboard alternative (SC 2.5.7\nDragging). The role, `aria-valuenow`, `min` and `max` come from the nested real\nrange input, and the `Slider.Label` text is forwarded onto it so the name is\npresent at render (SC 4.1.2 Name, Role, Value). The thumb hit area is floored at\n`--opsin-target-minimum` on both axes, with the knob drawn smaller inside (SC\n2.5.8).\n\n**Residual items.**\n\n* The knob's colour fade on interaction has no reduced-motion guard, but it is a colour change and not positional motion, so any neutralisation belongs in a shared stylesheet.\n* The `Slider.Value` readout renders as an `output` with a polite live region, so while dragging the value is spoken twice, a verbosity and not a defect.\n* Contrast pairs remain unmeasured.\n\n<KeyboardTable\n  name=\"slider\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves focus onto the thumb&#x22;,\n    notes: &#x22;One tab stop, on the thumb's nested range input.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Moves focus back out of the control&#x22;,\n    notes: &#x22;A single stop in reverse too.&#x22;,\n  },\n  {\n    keys: &#x22;Arrow Right, Arrow Up&#x22;,\n    action: &#x22;Increases the value by one step&#x22;,\n    notes: &#x22;The `step` prop. A right-to-left layout swaps Left and Right.&#x22;,\n  },\n  {\n    keys: &#x22;Arrow Left, Arrow Down&#x22;,\n    action: &#x22;Decreases the value by one step&#x22;,\n    notes: &#x22;The `step` prop, and the value stops at `min`.&#x22;,\n  },\n  {\n    keys: &#x22;Home&#x22;,\n    action: &#x22;Sets the value to the minimum&#x22;,\n    notes: &#x22;Jumps the thumb to the start.&#x22;,\n  },\n  {\n    keys: &#x22;End&#x22;,\n    action: &#x22;Sets the value to the maximum&#x22;,\n    notes: &#x22;Jumps the thumb to the end.&#x22;,\n  },\n  {\n    keys: &#x22;Page Up, Page Down&#x22;,\n    action: &#x22;Increases or decreases by a larger step&#x22;,\n    notes: &#x22;Base UI's default of ten, not the `step` prop.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"slider\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"SliderProps\" />\n\n`value` and `onValueChange` make this controlled, so the caller holds the number.\n`label` is required and a missing one raises a development warning. `min`\ndefaults to 0, `max` to 100 and `step` to 1."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/source-citation",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/source-citation.md",
      "slug": [
        "components",
        "source-citation"
      ],
      "section": "Components",
      "title": "SourceCitation",
      "description": "Where a piece of health information came from, in plain words, with an optional link to the fuller citation and an optional date it was last checked.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "citation",
        "evidence link",
        "reviewed by"
      ],
      "implements": [],
      "governedBy": [
        "trends",
        "safety-review"
      ],
      "usedIn": [],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"source-citation\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;Whether printing an admission is right for a value whose provenance went missing, or whether the product should refuse to render that value at all.&#x22;,\n  &#x22;Provenance is visible text near the value, not part of its accessible name, so a screen-reader user reaching the value alone does not hear its origin.&#x22;,\n  &#x22;No contrast pair for the source ink or the quieter date ink has been measured on the surfaces a citation sits on.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"source-citation\" unbuilt=\"false\" importPath=\"@/components/ui/source-citation\" registryDependencies=\"[&#x22;link&#x22;]\" />\n\n```tsx\nimport { SourceCitation } from \"@/components/ui/source-citation\"\n```\n\n```tsx\n<SourceCitation\n  source=\"Estimated by your watch from movement and heart rate.\"\n  more={{ label: \"Read how this is worked out\", href: \"/how-it-works\" }}\n  checkedOn=\"2026-03-14\"\n  locale=\"en-GB\"\n/>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"source-citation\" />\n\n### A device estimate naming its own method [#a-device-estimate-naming-its-own-method]\n\nThe provenance names the device and the class of the figure, so it reads as an estimate. `more` points at the fuller accuracy document.\n\n<ComponentPreview name=\"source-citation-a-device-estimate\" kind=\"example\" align=\"start\" />\n\n### When nobody said where it came from [#when-nobody-said-where-it-came-from]\n\nWith no `source`, the citation prints an admission rather than rendering empty. Markup you wrap a source in is taken at its word.\n\n<ComponentPreview name=\"source-citation-no-source-supplied\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;Beside a health value whose provenance a reader needs to weigh it: a wearable estimate, a home device reading, a typed figure.&#x22;,\n  &#x22;To attribute and link a manufacturer's accuracy document or a study you have read, rather than restating its claim as your own.&#x22;,\n  &#x22;Wherever a number's origin bounds what may be said about it, so origin travels with the number where it is read.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;The message is a standing statement about the whole product, rather than the source of one value.&#x22;, instead: &#x22;disclaimer-note&#x22; },\n  { case: &#x22;You are saying when a reading was taken or synced, rather than where it came from.&#x22;, instead: &#x22;relative-time&#x22; },\n  { case: &#x22;You are explaining what a term means, rather than where a value came from.&#x22;, instead: &#x22;term&#x22; },\n  { case: &#x22;The note is information about the content with no source to attribute.&#x22;, instead: &#x22;callout&#x22; },\n]\"\n/>\n\n## Clinical meaning [#clinical-meaning]\n\n**Asserts.** Where a health value came from, in the product's own plain words, with an optional checked date and a link to the fuller source.\n\n**Never read as.** A guarantee that the source is right, current, or checked by anybody. `checkedOn` is the date the product recorded, and a value old enough to doubt is wrapped in [RelativeTime](./relative-time.mdx) beside it.\n\n**Colour axis.** Neither: no `status` prop and no `category` prop, and a class from either axis raises a development warning. See [Two colour axes](../health/two-colour-axes.mdx).\n\n**Thresholds.** None. No reference range, verdict or clinical number passes through, and the product owns the words. Of the ten provenance rules in [Trends and uncertainty](../health/trends.mdx), rules 22 to 31, this component carries two, provenance in plain words at the value (rule 23) and a manufacturer's claim attributed rather than restated (rule 27). The other eight stay the caller's, and it renders a wrong string as readily as a right one. opsinjs ships no source, date, DOI or study. See [Safety review](../health/safety-review.mdx).\n\n<SafetyCallout severity=\"attention\" evidence=\"opinion\">\n  Never restate a manufacturer's accuracy figure as your own, and never invent one. Attribute the claim and link it through `more`, in the manufacturer's own terms.\n</SafetyCallout>\n\n## Accessibility [#accessibility]\n\nThe audit found no axe violation, missed target size, hidden focus or loss at 320px reflow. Both lines are set at `text-opsin-footnote`, a rem from the generated ramp and never a `px` size, in `--foreground` for the source and `--muted-foreground` for the date, with no raw colour literal or ramp step. `more` carries the label and the href together, so a link cannot be added without a label, and an external href adds an off-screen \"opens in a new tab\". The link is not inside a sentence, so it re-adds `--opsin-target-minimum` on both axes. See [Accessibility](../foundations/accessibility.mdx). It reflows at 200% text with no fixed height, and `min-w-0` with `wrap-break-word` breaks a long device name.\n\n**Residual items.**\n\n* The source line, the last-checked time and the fuller-citation link render as loose siblings with no programmatic group binding them. Reading order keeps the association, so this is not an AA failure.\n* The \"Last checked on\" chrome is always English while the date follows the caller's `locale`, and when they differ the localised date carries no `lang` seam yet, per ADR 0005.\n\n<KeyboardTable\n  name=\"source-citation\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves to the link, when there is one&#x22;,\n    notes: &#x22;The citation is text, not a tab stop. The link is its only focusable element.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Moves back out of the link&#x22;,\n    notes: &#x22;Reverse order matches visual order. The link is last.&#x22;,\n  },\n  {\n    keys: &#x22;Enter&#x22;,\n    action: &#x22;Follows the link&#x22;,\n    notes: &#x22;Only when a link is present. An ordinary anchor, so Enter and not Space.&#x22;,\n  },\n  {\n    keys: &#x22;Space&#x22;,\n    action: &#x22;Scrolls the page, as it does anywhere else&#x22;,\n    notes: &#x22;Nothing here captures Space or activates on it.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"source-citation\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"SourceCitationProps\" />\n\n`source` is typed optional but required by the contract, so the missing state can render. `checkedOn` is a strict `YYYY-MM-DD` string or epoch milliseconds, both pinned to UTC. A value that is not a real calendar date is refused, not rendered as a plausible wrong one."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/spinner",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/spinner.md",
      "slug": [
        "components",
        "spinner"
      ],
      "section": "Components",
      "title": "Spinner",
      "description": "An indeterminate loading ring for a brief in-place wait whose shape is unknown, reached for only where a skeleton cannot say what is arriving.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "loader",
        "busy indicator",
        "activity indicator"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"spinner\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;No contrast pair has been measured, so whether the muted ring clears the non-text floor on a card and on the page is argued rather than checked.&#x22;,\n  &#x22;Nobody has heard the role=\\&#x22;status\\&#x22; region in a screen reader, so whether it announces the wait once by name, rather than twice, is untested.&#x22;,\n  &#x22;Forced colours are unhandled, because the SVG stroke is left where the author set it, and whether the ring stays visible there is untested.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"spinner\" unbuilt=\"false\" importPath=\"@/components/ui/spinner\" />\n\n```tsx\nimport { Spinner } from \"@/components/ui/spinner\"\n```\n\n```tsx\n<span className=\"inline-flex items-center gap-2 text-muted-foreground\">\n  <Spinner label=\"Loading your readings\" />\n  <span>Loading</span>\n</span>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"spinner\" />\n\n### A brief wait [#a-brief-wait]\n\nA ring beside a visible word, for a wait with no known shape. `label` names the\nwait for a screen reader while the visible caption carries it for everyone else.\n\n<ComponentPreview name=\"spinner-a-brief-wait\" kind=\"example\" align=\"start\" />\n\n### Two sizes [#two-sizes]\n\n`size` sets `sm` and `md` side by side. Each is measured in `em`, so the ring\ngrows with the surrounding text rather than pinning at a fixed size.\n\n<ComponentPreview name=\"spinner-two-sizes\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;A brief in-place wait whose result has no known shape, so a skeleton would have no single outline to promise.&#x22;,\n  &#x22;A spot too small to draw an outline in, such as a toolbar slot or a compact inline control.&#x22;,\n  &#x22;A wait short enough that a skeleton would flash in and straight back out.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;The shape of what is arriving is known and can be drawn: a card, a list, a chart, a block of text.&#x22;, instead: &#x22;skeleton&#x22; },\n  { case: &#x22;The wait belongs to a control performing its own action, such as a submit button saving a reading.&#x22;, instead: &#x22;button&#x22; },\n  { case: &#x22;You can measure how far through a known sequence of steps the reader is, so the wait is determinate.&#x22;, instead: &#x22;stepper&#x22; },\n]\"\n/>\n\n## Accessibility [#accessibility]\n\nThe root carries a required `aria-label` plus a visually hidden text twin, and\nthe SVG ring is `aria-hidden`, so the decorative motion stays out of the\naccessibility tree. Sizing is em based throughout with no `px` type step, and\nthe ring draws only in `currentColor`, with no status colour or category colour\nof its own. Axe, target-size and 320px reflow checks were clean, and nothing\nneeded changing.\n\n**Residual items.**\n\n* The ring takes whatever ink colour the caller's context supplies rather than\n  a colour the component sets itself, so its contrast against either theme's\n  surfaces cannot be verified or hardened from source. That gap belongs to the\n  report below.\n* The missing-label warning is development only, so it does not stop a\n  production caller passing an empty or whitespace `label`. `divider` and\n  `segmented-control` follow the same convention.\n\n<KeyboardTable\n  name=\"spinner\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Skips the spinner&#x22;,\n    notes: &#x22;A spinner is status, not a control. Nothing here is focusable.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Skips the spinner&#x22;,\n    notes: &#x22;Same in reverse. A spinner never appears in the focus order.&#x22;,\n  },\n  {\n    keys: &#x22;Arrow keys&#x22;,\n    action: &#x22;Nothing&#x22;,\n    notes: &#x22;There is nothing to select, move or expand. The spinner captures no key.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"spinner\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"SpinnerProps\" />\n\n`label` is required and has no default, because a guessed name would describe the\nwrong wait. `size` defaults to `md` and chooses visual weight only. There is no\ncolour prop: colour reaches the ring only through `className`, and the\ntwo-colour-axes rule applies to that class in full."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/status-pill",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/status-pill.md",
      "slug": [
        "components",
        "status-pill"
      ],
      "section": "Components",
      "title": "StatusPill",
      "description": "A short label that says which of four levels of attention something needs. It is shown as a word, an icon and a colour together, never as a colour alone.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "chip",
        "status chip",
        "status badge",
        "status label",
        "traffic light"
      ],
      "implements": [],
      "governedBy": [
        "two-colour-axes",
        "alerts",
        "high-stakes-moments",
        "safety-review",
        "trends"
      ],
      "usedIn": [
        "alert-escalation",
        "result-disclosure",
        "offline-and-stale-data"
      ],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"status-pill\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;When a pill's level changes on screen, what is announced and how urgently? The component mounts no live region today, on purpose.&#x22;,\n  &#x22;Whether the pill's surface and boundary hold up under prefers-contrast: more and in forced colours; neither response lives in the token layer today.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"status-pill\" unbuilt=\"false\" importPath=\"@/components/ui/status-pill\" dependencies=\"[&#x22;lucide-react&#x22;]\" />\n\n```tsx\nimport { StatusPill } from \"@/components/ui/status-pill\"\n```\n\n```tsx\n<StatusPill status=\"attention\" describes=\"Second example measurement\" />\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"status-pill\" />\n\n### Scanning a column [#scanning-a-column]\n\nFour rows, each graded by `status`, and exactly one `urgent`.\n\n<ComponentPreview name=\"status-pill-in-a-list\" kind=\"example\" align=\"start\" />\n\n### Every size keeps the word [#every-size-keeps-the-word]\n\n`size` sets the type step and padding and nothing else. `sm` and `md` label a status in\nprose and lists, and `lg` matches a heading.\n\n<ComponentPreview name=\"status-pill-sizes\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;Labelling one result, reading or item with the level of attention the product has assigned to it.&#x22;,\n  &#x22;Making a status scannable in a list, a table or a grid, where reading each row in full is not realistic.&#x22;,\n  &#x22;Summarising a surface whose status the reader would otherwise have to infer from its contents.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;The status needs explaining, or the reader needs to know what to do about it.&#x22;, instead: &#x22;care-card&#x22; },\n  { case: &#x22;The status must interrupt what the reader is doing rather than wait to be noticed.&#x22;, instead: &#x22;alert-banner&#x22; },\n  { case: &#x22;The label is a category, a source, a tag, a count or a release phase rather than a level of attention.&#x22;, instead: &#x22;badge&#x22; },\n  { case: &#x22;You want to show where a value sits relative to a range, which is a position rather than a level.&#x22;, instead: &#x22;range-bar&#x22; },\n  { case: &#x22;The message is informational and carries no clinical level at all.&#x22;, instead: &#x22;callout&#x22; },\n]\"\n/>\n\n## Clinical meaning [#clinical-meaning]\n\n**Asserts.** That the product has assigned one of exactly four levels of attention to\nthe thing the pill labels: `steady`, `watch`, `attention` or `urgent`, defined in\n[Two colour axes](../health/two-colour-axes.mdx). It does not say what is wrong, why,\nor what happens next.\n\n**Never read as.** A diagnosis, a severity score or a triage category. The levels\ndescribe what the interface asks of the reader, not the state of their body, so\n`urgent` on a screen is not `urgent` in a clinical handover.\n\n**Colour axis.** Status only, and never alone: every pill renders a word and a glyph\nbeside its colour. A category colour belongs on a [Badge](./badge.mdx), never on a pill,\nand [Two colour axes](../health/two-colour-axes.mdx) says why the two never share an element.\n\n**Thresholds.** None. The consuming product assigns the level from rules or a clinician,\nand the pill derives nothing.\n\n<SafetyCallout severity=\"urgent\" evidence=\"opinion\">\n  At most one `urgent` pill may be visible on a screen. If the product's rules produce\n  two, the screen needs an [AlertBanner](./alert-banner.mdx) for the most serious one.\n  See [Alerts](../health/alerts.mdx).\n</SafetyCallout>\n\n## Accessibility [#accessibility]\n\nThe icon is `aria-hidden` and sized in `em`, so the word carries the meaning and the\nglyph grows with it. At 200% text the pill grows and wraps, and the word is never\ntruncated or replaced by the icon alone. The pill is an enamel plate, the same in both\nthemes: white on the deep Steady, Needs attention and Urgent plates, deep brown on the\ngold Watch plate. Every plate's word clears the body-text floor on its face and on the lit\nband along its top, the build refuses a plate that does not, and the report below\nmeasures both pairs. There is no axe, target-size, focus or 320px reflow failure.\n\n`pnpm run check:a11y` checks on every commit that no file paints a status colour\nwithout reading `CLINICAL_STATUS_META` and a glyph, that every status surface carries\n`data-status`, and that status words come from `CLINICAL_STATUS_META[level].word`, never\na literal. The four levels name four distinct glyphs: circle, ringed dot, diamond and\noctagon, the last two filled so each silhouette is heavier than the one below it. A11Y017\nfails the build when two levels share one. The glyph takes the word's colour.\n\n**Residual items.**\n\n* The consuming product must pass `describes` when the pill floats free of its subject,\n  in a table cell reached by column navigation or a card corner, because the component\n  cannot know the reading context.\n* With `describes`, the pill announces as *Needs attention, Second example measurement*.\n  Omit it when the subject is visible text in the same reading unit.\n* The pill is a `span`. One made into a filter is a Button and owes a Button's target\n  and name.\n* No live region is mounted, on purpose. A static read-only label is not a message, so\n  a `role=\"status\"` announcement would be wrong.\n* Steady and Urgent are both deep plates with a white word, so in greyscale and under\n  some colour-vision deficiencies they differ by word and glyph shape, not by colour.\n* On paper the plate, its light and its shadow go, and the pill prints as the level's tint\n  with its ink and a full-strength boundary. Forced colours drop the plate's light; that\n  rendering is not measured. The boundary and the shadow are decorative and not measured.\n\n<KeyboardTable\n  name=\"status-pill\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Skips the pill&#x22;,\n    notes: &#x22;Not focusable. A label with a tab stop is a stop every row pays for.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Skips the pill&#x22;,\n    notes: &#x22;Same in reverse. Never in the focus order in either direction.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"status-pill\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"StatusPillProps\" />\n\n`status` has no default, and a value outside the four, including `unknown`, renders no\npill and warns in development. `className` is merged last and can strip the\nfill or the line, so change `size` instead. It cannot recolour the word; a rule on\n`[data-slot=\"status-pill\"]` can.\n\n### Data attributes [#data-attributes]\n\n<DataAttributesTable\n  name=\"status-pill\"\n  rows=\"[\n  {\n    attribute: &#x22;data-slot&#x22;,\n    condition: &#x22;On the root and both inner parts, always&#x22;,\n    value: &#x22;status-pill, status-pill-icon, status-pill-label&#x22;,\n  },\n  {\n    attribute: &#x22;data-status&#x22;,\n    condition: &#x22;On the root, always, because status is required&#x22;,\n    value: &#x22;steady | watch | attention | urgent&#x22;,\n  },\n]\"\n/>"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/stepper",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/stepper.md",
      "slug": [
        "components",
        "stepper"
      ],
      "section": "Components",
      "title": "Stepper",
      "description": "Progress through a sequence of steps, drawn as a read-only indicator showing which steps are complete, which one is current, and which are still to come.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "wizard",
        "step indicator",
        "multi step"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"stepper\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;No contrast pair has been measured, neither the marker fills against the page nor the muted description ink against the surfaces this indicator sits on.&#x22;,\n  &#x22;Nobody has listened to this in a screen reader, so whether aria-current and the sr-only \\&#x22;Current step\\&#x22; double-announce the current step is unchecked.&#x22;,\n  &#x22;Forced colours and prefers-contrast: more are unhandled, so whether complete, current and upcoming stay apart once the platform substitutes its own fills is untested.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"stepper\" unbuilt=\"false\" importPath=\"@/components/ui/stepper\" dependencies=\"[&#x22;lucide-react&#x22;]\" />\n\n```tsx\nimport { Stepper } from \"@/components/ui/stepper\"\n```\n\n```tsx\n<Stepper\n  current={1}\n  steps={[\n    { label: \"Your details\" },\n    { label: \"Your preferences\" },\n    { label: \"Review\" },\n  ]}\n/>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"stepper\" />\n\n### A setup flow in progress [#a-setup-flow-in-progress]\n\nFive steps, two complete, one current, two to come, driven by `current`.\n\n<ComponentPreview name=\"stepper-setup-flow\" kind=\"example\" align=\"start\" />\n\n### Steps with supporting descriptions [#steps-with-supporting-descriptions]\n\nEach step's optional `description` rides beneath its label in muted footnote\nink. Use it to clarify what a step covers, never to give an instruction: this\nindicator cannot be operated.\n\n<ComponentPreview name=\"stepper-with-descriptions\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;Showing a reader where they are in a short, fixed sequence, beside the current step's own content.&#x22;,\n  &#x22;Giving a multi step flow a sense of length, so the reader sees how many steps remain.&#x22;,\n  &#x22;Reflecting progress the product already tracks, where each step's state comes from the product.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;You want several questions on one screen, with a bar of steps standing in for a real form.&#x22;, instead: &#x22;field&#x22; },\n  { case: &#x22;The items are separate views the reader switches between at will, not a sequence taken in order.&#x22;, instead: &#x22;tabs&#x22; },\n  { case: &#x22;You need one continuous measure of how far through a single task the reader is.&#x22;, instead: &#x22;progress&#x22; },\n]\"\n/>\n\n## Accessibility [#accessibility]\n\nThe root is an `<ol>` with `<li>` steps, so a screen reader announces a list of\nknown length, in order, and the current step carries `aria-current=\"step\"`. State\nnever rests on colour alone: glyph, fill weight, border weight, label weight,\nlist position, and an sr-only \"Completed\", \"Current step\" or \"Upcoming\" all carry\nit. The check glyph is `aria-hidden`, and the indicator takes no tab stop, since\nit has nothing to operate. The audit fixed the root list's missing accessible\nname: an optional `label` now forwards to the root `<ol>` as `aria-label`, set on\nthe default and both examples. When it is omitted, the attribute is dropped\nrather than shipping empty.\n\n**Residual items.**\n\n* The upcoming marker's hairline border against the page is an unmeasured contrast pair. Meaning does not rest on it, because number, position, the sr-only word and label weight already carry upcoming state.\n* No live region announces a change of `current`. The parent flow owns focus and announces each new page, so `aria-live` would fire on unrelated renders.\n* A consumer who omits `label` ships an unnamed list. The default and both examples set it, the recommended usage.\n\n<KeyboardTable\n  name=\"stepper\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Skips the stepper&#x22;,\n    notes: &#x22;Nothing to operate, so no tab stop; focus lands on the next interactive element.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Skips the stepper&#x22;,\n    notes: &#x22;Passed in reverse, moving focus to the previous interactive element.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"stepper\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"StepperProps\" />\n\n`current` is a 0-based index into `steps`; the product owns position, the\ncomponent keeps no state of its own. An out-of-range or non-integer value is\nclamped to the nearest real step and raises a development warning."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/surface",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/surface.md",
      "slug": [
        "components",
        "surface"
      ],
      "section": "Components",
      "title": "Surface",
      "description": "The primitive behind every panel, sheet and card. It decides how solid or translucent a layer looks, and guarantees whatever sits on it stays readable.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "material",
        "blur",
        "translucency",
        "glass",
        "vibrancy",
        "elevation",
        "layer"
      ],
      "implements": [],
      "governedBy": [
        "two-colour-axes"
      ],
      "usedIn": [
        "daily-logging",
        "result-disclosure",
        "onboarding-and-first-run"
      ],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"surface\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;Nothing measures the tint composited at its published floor, so every figure here is a rung's opaque fallback and `minScrimOpacity` is asserted rather than derived.&#x22;,\n  &#x22;Whether `prefers-contrast: more` belongs in this component at all, since the edge widens and keeps its published alpha against an unmeasured non-text floor.&#x22;,\n  &#x22;Nobody has opened the site under a real Windows contrast theme, and the scrim's dimming does not survive there because the palette replaces the tint with Canvas.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"surface\" unbuilt=\"false\" importPath=\"@/components/ui/surface\" />\n\n```tsx\nimport { Surface } from \"@/components/ui/surface\"\n```\n\n```tsx\n<Surface rung=\"sheet\">Everything the surface holds</Surface>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"surface\" />\n\n### Chrome that content scrolls beneath [#chrome-that-content-scrolls-beneath]\n\n`rung=\"overlay\"` on a panel that opens already scrolled, so a dark row sits under\nthe pinned header and the scrim holds the heading legible over it.\n\n<ComponentPreview name=\"surface-over-scrolling-content\" kind=\"example\" align=\"start\" />\n\n### The degraded path, without changing a setting [#the-degraded-path-without-changing-a-setting]\n\n`opaque` renders the same fallback that reduced transparency, `prefers-contrast:\nmore` and a missing `backdrop-filter` reach. The border, shadow and geometry\nstay, because they carry the layering once translucency goes.\n\n<ComponentPreview name=\"surface-opaque-fallback\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;Building a layered component at a defined rung: a custom panel, a floating bar or a persistent header.&#x22;,\n  &#x22;Any surface that overlays scrolling content and must stay readable whatever passes beneath it.&#x22;,\n  &#x22;Expressing depth through material rather than shadow, which is how this system shows layering.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;You need a bounded group of related content with padding and a border, on the page rather than over it.&#x22;, instead: &#x22;card&#x22; },\n  { case: &#x22;You are building a bottom sheet with detents and drag.&#x22;, instead: &#x22;sheet&#x22; },\n  { case: &#x22;You are building a modal that traps focus.&#x22;, instead: &#x22;dialog&#x22; },\n  { case: &#x22;You are reaching for a fourth composited translucent layer on one screen, which stutters on mid-range Android.&#x22;, instead: &#x22;card&#x22; },\n  { case: &#x22;A number a person must read is going on `sheet` or `overlay`. A health value never sits on a translucent rung above `raised`.&#x22;, instead: &#x22;card&#x22; },\n]\"\n/>\n\n## Accessibility [#accessibility]\n\nThe audit found zero axe violations, no target-size or focus-visible finding and\nno horizontal scroll at 320px, and changed nothing. The surface is\npresentational, with no role, name or tab stop, and its three decorative layers\nare empty and `aria-hidden`. The Backdrop renders only where the Scrim is\nunconditional, so no text sits over an unscrimmed blur. Reduced\ntransparency, `prefers-contrast: more`, `forced-colors: active` and a missing\n`backdrop-filter` each reach a defined\n[opaque fallback](../foundations/accessibility.mdx) that keeps the border,\nshadow and geometry. The boundary is an outline, so `forced-colors` preserves it\nwhere a shadow would be dropped.\n\n**Residual items.** Both belong to the token owner, not to this file.\n\n* Under `prefers-contrast: more` the edge [widens](../foundations/accessibility.mdx) from a hairline to an emphasis width but keeps its published `--opsin-material-*-border` colour, and several rungs publish a low alpha, so whether it clears 3:1 for SC 1.4.11 is unmeasured. A solid colour would give `canvas` and `scrim` an edge they are specified not to have, so the fix sits in `tokens/material.json`.\n* `className` is merged unrestricted, so a caller can put a category tint and a status tint on one Surface, which the component cannot detect at render time. The [two colour axes](../health/two-colour-axes.mdx) rule and its repair are stated on the API, and no element the component itself renders mixes them.\n\n<KeyboardTable\n  name=\"surface\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Passes through the surface&#x22;,\n    notes: &#x22;Surface is presentational, with no role, no focus and no tab stop.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Passes through the surface&#x22;,\n    notes: &#x22;Same in reverse. A Surface never joins the focus order, at any rung.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"surface\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"SurfaceProps\" />\n\n`rung` is required, because no default depth is safe to guess. There is no\n`blur`, `opacity`, `tint`, radius or `as` prop, and no `contentWeight`, because\nno large-text scrim floor has been measured. A rung outside the six is refused.\nDevelopment warns and the children still render, with no material. `className`\nis merged unrestricted, so the [two colour axes](../health/two-colour-axes.mdx)\nrule applies in full."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/switch",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/switch.md",
      "slug": [
        "components",
        "switch"
      ],
      "section": "Components",
      "title": "Switch",
      "description": "A labelled on-or-off control that commits the moment it is flipped, for a single setting rather than a form value submitted later.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "toggle"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"switch\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;No contrast pair has been measured: the card thumb against the accent fill when on, against the muted fill when off, and the hairline round both.&#x22;,\n  &#x22;Nobody has listened to this switch in a screen reader, so whether role=\\&#x22;switch\\&#x22; with its label and helper line reads usefully is reasoned, not heard.&#x22;,\n  &#x22;Forced colours, prefers-contrast: more and right-to-left layout are unhandled, and the reduced-motion thumb has been checked only in an emulated browser.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"switch\" unbuilt=\"false\" importPath=\"@/components/ui/switch\" dependencies=\"[&#x22;@base-ui/react&#x22;]\" />\n\n```tsx\nimport { Switch } from \"@/components/ui/switch\"\n```\n\n```tsx\n<Switch\n  label=\"Larger text\"\n  checked={largerText}\n  onCheckedChange={setLargerText}\n/>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"switch\" />\n\n### A setting that applies now [#a-setting-that-applies-now]\n\n`checked` and `onCheckedChange` commit \"Larger text\" on the flip, not on a later\nsubmit. No helper line, because the label alone says what the setting does.\n\n<ComponentPreview name=\"switch-a-setting-that-applies-now\" kind=\"example\" align=\"start\" />\n\n### A setting with a helper line [#a-setting-with-a-helper-line]\n\n`description` adds one sentence under the label saying what turning the switch on\nchanges. It is read as the description, so the accessible name stays the label.\n\n<ComponentPreview name=\"switch-with-a-description\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;A single setting, such as a Larger text preference, that takes effect the moment it is flipped.&#x22;,\n  &#x22;A binary state the product commits straight away, with nothing submitted later and the reader free to flip it back.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;The toggle would record that the reader agreed to something. Consent is a decision with a record.&#x22;, instead: &#x22;consent-sheet&#x22; },\n  { case: &#x22;The value is proposed now and submitted later with a form.&#x22;, instead: &#x22;checkbox&#x22; },\n]\"\n/>\n\n## Accessibility [#accessibility]\n\nThe audit found nothing to change in the source.\n\n* `role=\"switch\"` comes from Base UI's Switch.Root, the accessible name is a visible\n  label span tied by `aria-labelledby`, and state rides `aria-checked`.\n* On and off are carried by thumb position and `aria-checked`, not the fill alone,\n  and a `border-border` hairline survives `forced-colors: active` and a stripped fill.\n* The 24px AA target floor is met by the track, and the 44pt house floor by the\n  enclosing label row, which toggles the control.\n* Focus sits on the track with the house ring. While the row is held the thumb\n  squashes towards where it will go, and it travels on `spring-snap`. Under\n  `prefers-reduced-motion: reduce` it does not squash and reaches the other side in one\n  frame.\n* It uses only neutral chrome and the accent fill, and `pnpm run check:a11y`\n  confirms on every commit that no colour literal, `px` type size or banned word appears.\n\n**Residual items.** No contrast pair has been read yet, so the report below stands in for\nnumbers nobody has produced.\n\n<KeyboardTable\n  name=\"switch\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves focus onto the switch&#x22;,\n    notes: &#x22;A single tab stop. A disabled switch is skipped.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Moves focus back off the switch&#x22;,\n    notes: &#x22;One stop in reverse too.&#x22;,\n  },\n  {\n    keys: &#x22;Space&#x22;,\n    action: &#x22;Flips the switch&#x22;,\n    notes: &#x22;onCheckedChange fires with the new boolean.&#x22;,\n  },\n  {\n    keys: &#x22;Enter&#x22;,\n    action: &#x22;Flips the switch&#x22;,\n    notes: &#x22;Base UI binds Enter as well as Space.&#x22;,\n  },\n  {\n    keys: &#x22;Arrow keys&#x22;,\n    action: &#x22;Nothing&#x22;,\n    notes: &#x22;Nothing to move focus between.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"switch\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"SwitchProps\" />\n\n`checked` and `onCheckedChange` make this a controlled component with no internal\nstate. `label` is required: a missing or empty label raises a development warning.\n`disabled` keeps the switch visible and labelled while refusing focus and every\nkey. `className` is merged onto the root row and must carry neither colour axis.\n\n### Data attributes [#data-attributes]\n\n<DataAttributesTable\n  name=\"switch\"\n  rows=\"[\n  {\n    attribute: &#x22;data-slot&#x22;,\n    condition: &#x22;On the root and every inner part&#x22;,\n    value: &#x22;switch, switch-label, switch-description, switch-control, switch-thumb&#x22;,\n  },\n  {\n    attribute: &#x22;data-checked / data-unchecked&#x22;,\n    condition: &#x22;On the control and the thumb, one or the other&#x22;,\n    value: &#x22;Present with no value; reflects checked&#x22;,\n  },\n  {\n    attribute: &#x22;data-disabled&#x22;,\n    condition: &#x22;On the control while disabled&#x22;,\n    value: &#x22;Present with no value&#x22;,\n  },\n]\"\n/>"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/symptom-picker",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/symptom-picker.md",
      "slug": [
        "components",
        "symptom-picker"
      ],
      "section": "Components",
      "title": "SymptomPicker",
      "description": "A multi-select over a symptom list the product supplies, recording which options a reader ticks and never checking, triaging or interpreting them.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "symptoms",
        "how are you feeling",
        "symptom checker"
      ],
      "implements": [],
      "governedBy": [
        "health/index",
        "safety-review"
      ],
      "usedIn": [],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"symptom-picker\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;No contrast pair has been measured. This component sets no surface of its own, so the box fill, the check glyph and the field border sit on the host's ground.&#x22;,\n  &#x22;Nothing stops a product wiring the returned values into a checker or a triage flow, and no lint rule on a consumer's own code holds that line.&#x22;,\n  &#x22;Nobody has listened to this in a screen reader, so whether the filter's changing result count is announced as rows appear and disappear is unheard.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"symptom-picker\" unbuilt=\"false\" importPath=\"@/components/ui/symptom-picker\" dependencies=\"[&#x22;@base-ui/react&#x22;, &#x22;lucide-react&#x22;]\" />\n\n```tsx\nimport { SymptomPicker } from \"@/components/ui/symptom-picker\"\n```\n\n```tsx\n<SymptomPicker\n  label=\"Which of these apply to you right now?\"\n  value={selected}\n  onValueChange={setSelected}\n  options={[\n    { value: \"example-one\", label: \"Example symptom one\" },\n    { value: \"example-two\", label: \"Example symptom two\" },\n    { value: \"example-three\", label: \"Example symptom three\" },\n  ]}\n/>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"symptom-picker\" />\n\n### Choosing from a list [#choosing-from-a-list]\n\nDriven by `options`. The labels are fictional placeholders, because opsinjs ships\nno symptom list and an example must never be mistaken for a real vocabulary.\n\n<ComponentPreview name=\"symptom-picker-choosing-from-a-list\" kind=\"example\" align=\"start\" />\n\n### Filtering a long list [#filtering-a-long-list]\n\nWith `searchable` on, the filter narrows the visible rows by a match on their\nlabel, and the ticked values stay ticked as it narrows.\n\n<ComponentPreview name=\"symptom-picker-with-search\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;Recording which items from a product-owned list apply, where more than one can apply and the caller wants the set back.&#x22;,\n  &#x22;A short list the reader scans in place before a consultation, stored against the reader's own record.&#x22;,\n  &#x22;A longer product-owned list, with searchable on so the reader filters the rows by typing rather than scrolling.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;There is one thing to confirm, a single yes or no. A whole picker for one option is read twice.&#x22;, instead: &#x22;checkbox&#x22; },\n  { case: &#x22;Exactly one option applies and the rest exclude it, so the choice is one-of-many rather than any-of-many.&#x22;, instead: &#x22;radio-group&#x22; },\n  { case: &#x22;The reader describes something in their own words rather than picking from a list the product wrote.&#x22;, instead: &#x22;textarea&#x22; },\n]\"\n/>\n\n## Clinical meaning [#clinical-meaning]\n\n**Asserts.** These are the values a reader ticked from the list you supplied.\nNothing about what an option means, how the ticked set reads together, or what\nhappens next.\n\n**Never read as.** A symptom checker, a triage or a diagnosis. Feeding the\nreturned array into a rule that reaches a clinical conclusion moves the product\nonto the pathway [Safety review](../health/safety-review.mdx) describes.\n\n**Colour axis.** Neither. A selection is not a clinical level, so the component\ncarries no `data-status` and no `data-category`. The ticked state travels as a\ncheck shape and a quiet fill, so it survives greyscale.\n\n**Thresholds.** The consuming product owns them. opsinjs ships no symptom list,\noption labels or default text, because a controlled vocabulary is product\nspecific, and [Health](../health/index.mdx) is why the picker records and never\ninterprets.\n\n## Accessibility [#accessibility]\n\nEach option is a real checkbox with its icon `aria-hidden`, the pressable row\nfloors at `--opsin-target-minimum` in rem, and axe, target-size and 320px reflow\nchecks were clean. The audit fixed one gap under SC 4.1.3 Status Messages: with\n`searchable` on, the count change sat in no live region, so a screen reader never\nheard the result count or that nothing matched. A persistent visually hidden\n`role=\"status\"` region now announces the filtered count.\n\n**Residual items.**\n\n* `forced-colors` stays unchecked.\n* The group and filter names are forwarded only as `aria-label`, with no persistent visible label. A required `label` prop keeps the group from being nameless, but a visible label is a recommended enhancement, deferred for one repair across the whole set.\n\n<KeyboardTable\n  name=\"symptom-picker\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves to the next control, the filter field or an option&#x22;,\n    notes: &#x22;Each checkbox is its own tab stop. A disabled option is skipped.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Moves to the previous control&#x22;,\n    notes: &#x22;The same stops in reverse, then out of the picker.&#x22;,\n  },\n  {\n    keys: &#x22;Space&#x22;,\n    action: &#x22;Ticks or unticks the focused option&#x22;,\n    notes: &#x22;An option is a checkbox, so Space activates it. Focus stays put.&#x22;,\n  },\n  {\n    keys: &#x22;Enter&#x22;,\n    action: &#x22;Does nothing on an option&#x22;,\n    notes: &#x22;The primitive cancels it, so a picker never submits its form.&#x22;,\n  },\n  {\n    keys: &#x22;Typing&#x22;,\n    action: &#x22;Filters the list, in the filter field only&#x22;,\n    notes: &#x22;Present only when searchable is set. It changes no ticked value.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"symptom-picker\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"SymptomPickerProps\" />\n\n`options` is the product's vocabulary and the whole of what the picker draws, so\nan empty array renders nothing and warns in development. `value` and\n`onValueChange` make this controlled, with no selection state of its own. A value\nmatching no option is kept and named by a warning. `label` is required, because a\ngroup with no accessible name is a defect.\n\n### Data attributes [#data-attributes]\n\n<DataAttributesTable\n  name=\"symptom-picker\"\n  rows=\"[\n  {\n    attribute: &#x22;data-slot&#x22;,\n    condition: &#x22;On the root and every inner part, always&#x22;,\n    value: &#x22;symptom-picker, symptom-picker-search, symptom-picker-option, symptom-picker-option-label, symptom-picker-empty&#x22;,\n  },\n  {\n    attribute: &#x22;data-checked, data-unchecked&#x22;,\n    condition: &#x22;On an option, one or the other, by whether it is ticked&#x22;,\n    value: &#x22;Stamped by Base UI's Checkbox primitive&#x22;,\n  },\n  {\n    attribute: &#x22;data-disabled&#x22;,\n    condition: &#x22;On an option the product marked disabled&#x22;,\n    value: &#x22;The row drops to the muted ink and takes no pointer or key&#x22;,\n  },\n]\"\n/>"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/tab-bar",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/tab-bar.md",
      "slug": [
        "components",
        "tab-bar"
      ],
      "section": "Components",
      "title": "TabBar",
      "description": "The persistent bar of top-level destinations at the foot of a phone screen. It marks the current one with a heavier label and a top indicator, not colour.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "bottom navigation",
        "nav bar"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"tab-bar\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;No contrast pair has been measured for the current-destination treatment against the overlay material, so whether it reads as current in greyscale is unverified.&#x22;,\n  &#x22;Nobody has listened to this bar in a screen reader, so whether the landmark, the item count and the current state are announced is unchecked.&#x22;,\n  &#x22;Forced colours and prefers-contrast: more are unhandled, and whether the current destination survives a palette that replaces both carriers has not been tested.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"tab-bar\" unbuilt=\"false\" importPath=\"@/components/ui/tab-bar\" dependencies=\"[&#x22;lucide-react&#x22;]\" registryDependencies=\"[&#x22;surface&#x22;]\" />\n\n```tsx\nimport { TabBar } from \"@/components/ui/tab-bar\"\n```\n\n```tsx\n<TabBar\n  label=\"Main sections\"\n  value={section}\n  onValueChange={setSection}\n  items={[\n    { key: \"home\", label: \"Home\", icon: <House /> },\n    { key: \"trends\", label: \"Trends\", icon: <Activity /> },\n    { key: \"learn\", label: \"Learn\", icon: <BookOpen /> },\n    { key: \"settings\", label: \"Settings\", icon: <Settings /> },\n  ]}\n/>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"tab-bar\" />\n\n### Four destinations [#four-destinations]\n\nFour peer destinations, each an icon over a one-word label, with one current.\n`onValueChange` reports the chosen key, which the screen passes back as\n`value`.\n\n<ComponentPreview name=\"tab-bar-four-destinations\" kind=\"example\" align=\"start\" />\n\n### Destinations as links [#destinations-as-links]\n\nAn `href` on each item builds the bar from anchors, so a product router acts on\nthe navigation. Pinned through `className`, with safe-area padding clearing the\nhome indicator.\n\n<ComponentPreview name=\"tab-bar-with-links\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;Moving between two to five top-level sections of a phone app, where the destinations are peers.&#x22;,\n  &#x22;Keeping the whole set of destinations in view, so any section is one tap away.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;Switching between views that live inside one screen and share its space.&#x22;, instead: &#x22;tabs&#x22; },\n  { case: &#x22;Setting one parameter of a single view, such as a chart's day or week window.&#x22;, instead: &#x22;segmented-control&#x22; },\n  { case: &#x22;More than five destinations, or a \\&#x22;More\\&#x22; tab, which buries a safety relevant action.&#x22;, instead: &#x22;menu&#x22; },\n]\"\n/>\n\n## Accessibility [#accessibility]\n\nConfirmed: a real `nav` landmark named by `label`, and icons `aria-hidden` with the\nlabel as the accessible name. The current destination carries `aria-current=\"page\"`,\na heavier label and a top indicator, so no cue rides on colour. Every target is\nfloored at the 44pt minimum in rem. Axe, target-size, focus and 320px reflow checks\nwere clean, and the audit changed nothing.\n\n**Residual items.**\n\n* The colour and opacity fades carry no `prefers-reduced-motion` guard, which still\n  meets AA because that guard is an AAA item.\n* A `forced-colors` repaint may flatten the indicator bar, but `font-weight` and\n  `aria-current` keep the current state legible.\n* A bottom-fixed bar can obscure focused content, but this component owns no\n  position, so SC 2.4.11 is the product's concern.\n* Contrast for the current treatment on the overlay material is still unmeasured.\n  See the report below.\n\n<KeyboardTable\n  name=\"tab-bar\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves focus to the next destination&#x22;,\n    notes: &#x22;Each destination is its own tab stop, not a roving one.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Moves focus to the previous destination&#x22;,\n    notes: &#x22;Focus steps back one destination at a time, in reverse order.&#x22;,\n  },\n  {\n    keys: &#x22;Enter&#x22;,\n    action: &#x22;Activates the focused destination&#x22;,\n    notes: &#x22;An anchor follows its href; a button reports the key through onValueChange.&#x22;,\n  },\n  {\n    keys: &#x22;Space&#x22;,\n    action: &#x22;Activates a button destination&#x22;,\n    notes: &#x22;Native anchor behaviour, so Space does not activate a link destination.&#x22;,\n  },\n  {\n    keys: &#x22;Home, End&#x22;,\n    action: &#x22;Not bound&#x22;,\n    notes: &#x22;The bar adds no roving-focus keys, so the browser default stands.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"tab-bar\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"TabBarProps\" />\n\n`value` makes this controlled, with no internal selection state, and a `value`\nmatching no item renders nothing current and warns in development.\n`onValueChange` is optional, because a bar of links can leave navigation to the\n`href`. `label` is required: an unnamed navigation landmark is a defect."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/table",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/table.md",
      "slug": [
        "components",
        "table"
      ],
      "section": "Components",
      "title": "Table",
      "description": "Rows and columns in a real semantic table, the readable twin a chart ships with, with a required caption, right-aligned numeric columns and its own scroll.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "data table",
        "grid",
        "rows and columns"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [
        "trend-review"
      ],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"table\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;No contrast pair for the header ink, the caption ink or the hairline borders has been measured.&#x22;,\n  &#x22;Nobody has listened to it in a screen reader, so the scopes and the caption are argued rather than heard.&#x22;,\n  &#x22;Whether the bare focus stop on the scroll container should be a labelled region, or a stop at all when the table fits, is unresolved.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"table\" unbuilt=\"false\" importPath=\"@/components/ui/table\" />\n\n```tsx\nimport { Table } from \"@/components/ui/table\"\n```\n\n```tsx\n<Table\n  caption=\"Example figures by period, and not a real record\"\n  columns={[\n    { key: \"period\", header: \"Period\" },\n    { key: \"count\", header: \"Count\", numeric: true },\n  ]}\n  rows={[\n    { period: \"Period one\", count: \"12\" },\n    { period: \"Period two\", count: \"1,000\" },\n  ]}\n/>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"table\" />\n\n### The readable twin of a chart [#the-readable-twin-of-a-chart]\n\nThe chart draws the shape; the table carries the figures. `captionHidden` hides\nthe caption the heading above already supplies.\n\n<ComponentPreview name=\"table-a-chart-twin\" kind=\"example\" align=\"start\" />\n\n### Numeric columns line up on their digits [#numeric-columns-line-up-on-their-digits]\n\n`numeric` right-aligns two columns in tabular figures while the first column\nlabels each row.\n\n<ComponentPreview name=\"table-numeric-columns\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;The accessible twin of a chart: the same figures a screen reader user can read.&#x22;,\n  &#x22;A small set of rows and columns a reader compares directly.&#x22;,\n  &#x22;A comparison read down a column, where lining the digits up is the point.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;One reading with a label, a time and a surface of its own.&#x22;, instead: &#x22;metric-tile&#x22; },\n  { case: &#x22;A trend read as a shape rather than as figures.&#x22;, instead: &#x22;trend-sparkline&#x22; },\n  { case: &#x22;The data has not arrived and you are holding the layout open.&#x22;, instead: &#x22;skeleton&#x22; },\n  { case: &#x22;There are no rows, because the result is genuinely empty.&#x22;, instead: &#x22;empty-state&#x22; },\n  { case: &#x22;An interactive grid with sorting, selection and virtualised scrolling.&#x22;, instead: &#x22;card&#x22; },\n]\"\n/>\n\n## Accessibility [#accessibility]\n\nThe audit changed nothing and found no axe violation, target-size failure,\nfocus-visible gap or sideways page scroll at 320px. A real `<caption>` always renders,\nheaders carry `scope=\"col\"`, and the first body cell carries `scope=\"row\"` when\n`rowHeader` is on. The `overflow-x-auto` container is `tabIndex=0`, reachable and\nscrollable by keyboard, and padding-based spacing with no fixed cell heights keeps\ntext-spacing overrides from clipping. There is no colour prop, no `data-status`, no\n`data-category` and no transition.\n\n**Residual items.**\n\n* An empty `caption` renders an empty `<caption>`, warning only in development.\n* The scroll container has no `role` and no accessible name; adding `role=\"region\"`\n  would require one, so it is left to the consuming page.\n* Contrast for the header ink, caption ink and hairlines has not been measured.\n\n<KeyboardTable\n  name=\"table\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves focus onto the scrollable table, then past it&#x22;,\n    notes: &#x22;Present even when the table fits.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Moves back out of the table&#x22;,\n    notes: &#x22;Cells are never focus stops.&#x22;,\n  },\n  {\n    keys: &#x22;Left, Right&#x22;,\n    action: &#x22;Scroll the table sideways when the container has focus&#x22;,\n    notes: &#x22;Native to a focusable scroll region.&#x22;,\n  },\n  {\n    keys: &#x22;Space&#x22;,\n    action: &#x22;Scrolls the page, as anywhere else&#x22;,\n    notes: &#x22;No control here captures it.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"table\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"TableProps\" />\n\n`caption` is a required `string`. `rowHeader` defaults to true, so the first\ncell of each row is a `th`. There is no `onSort`, no `selectedRows` and no\n`virtualized`.\n\n### Data attributes [#data-attributes]\n\n<DataAttributesTable\n  name=\"table\"\n  rows=\"[\n  {\n    attribute: &#x22;data-slot&#x22;,\n    condition: &#x22;On the container, the table and every inner part, always&#x22;,\n    value: &#x22;table-container, table, table-caption, table-header, table-head, table-body, table-row, table-cell&#x22;,\n  },\n  {\n    attribute: &#x22;data-opsinjs-value&#x22;,\n    condition: &#x22;On a td in a numeric column&#x22;,\n    value: &#x22;The empty string, deliberately: a tabular-figures hook, not a magnitude&#x22;,\n  },\n]\"\n/>"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/tabs",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/tabs.md",
      "slug": [
        "components",
        "tabs"
      ],
      "section": "Components",
      "title": "Tabs",
      "description": "A row of tabs that switches between panels sharing one region. The list is one tab stop with a roving focus, and choosing a tab swaps the panel.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "tab list",
        "view switcher"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"tabs\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;No contrast pair has been measured: the active tab against the row, the tab-list rail, or the indicator bar against its ground.&#x22;,\n  &#x22;Nobody has listened to this control in a screen reader, so the roving focus and the panel association are untested.&#x22;,\n  &#x22;Forced colours and prefers-contrast: more are unhandled, so whether the selection survives the platform's own pair has not been tested.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"tabs\" unbuilt=\"false\" importPath=\"@/components/ui/tabs\" dependencies=\"[&#x22;@base-ui/react&#x22;]\" />\n\n```tsx\nimport { Tabs } from \"@/components/ui/tabs\"\n```\n\n```tsx\n<Tabs\n  label=\"Reading detail\"\n  value={panel}\n  onValueChange={setPanel}\n  items={[\n    { value: \"overview\", label: \"Overview\", panel: <Overview /> },\n    { value: \"history\", label: \"History\", panel: <History /> },\n    { value: \"notes\", label: \"Notes\", panel: <Notes /> },\n  ]}\n/>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"tabs\" />\n\n### Switching between panels [#switching-between-panels]\n\nThree panels share one region, from `items`. Choosing a tab swaps the whole\npanel, not one setting of a view.\n\n<ComponentPreview name=\"tabs-switching-panels\" kind=\"example\" align=\"start\" />\n\n### Tabs in a card [#tabs-in-a-card]\n\nThe card header names the subject and `items` fills its body, so a tab swaps the\nbody without the card moving.\n\n<ComponentPreview name=\"tabs-in-a-card\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;Two or three distinct panels share one region and only one is worth showing at a time.&#x22;,\n  &#x22;Folding secondary views of one subject, such as an overview, a history and notes, behind their own tabs.&#x22;,\n  &#x22;Views a reader moves between often and expects to find in a familiar bar.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;The choice sets one parameter of a view that stays on the surface, such as a chart's week window.&#x22;, instead: &#x22;segmented-control&#x22; },\n  { case: &#x22;The choice is a small set of exclusive options taken as a form input, submitted as a value.&#x22;, instead: &#x22;radio-group&#x22; },\n  { case: &#x22;The panels are steps in a sequence, where progress and a next action matter most.&#x22;, instead: &#x22;stepper&#x22; },\n]\"\n/>\n\n## Accessibility [#accessibility]\n\nBase UI's Tabs carries the tested WAI-ARIA pattern and the wrapper overrides none of\nit. Activation is manual, three sighted carriers plus `aria-selected` mark the active\ntab, and the row draws neutral chrome with no status or category axis. The indicator\nglides to the chosen tab on `spring-snap`, and under `prefers-reduced-motion` it moves in\none frame. Rendered, it\nshows no axe violation, target-size breach, focus gap or 320px reflow, and the audit\nchanged nothing.\n\n**Residual items.**\n\n* Each tab floors its height at `--opsin-target-minimum` with padding but sets no\n  `min-w`, the house treatment for a word-labelled target under SC 2.5.8.\n* The `label` prop applies only as the tablist's `aria-label`, which is right here\n  because every tab shows its own text.\n* Contrast pairs for the active ink, the rail and the indicator stay unmeasured.\n\n<KeyboardTable\n  name=\"tabs\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves focus into the tab list, onto the active tab&#x22;,\n    notes: &#x22;One tab stop for the list. The active panel is the next stop.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Moves focus back out of the tab list&#x22;,\n    notes: &#x22;One stop in reverse too, so focus leaves the row.&#x22;,\n  },\n  {\n    keys: &#x22;Arrow Right, Arrow Down&#x22;,\n    action: &#x22;Moves the highlight to the next tab&#x22;,\n    notes: &#x22;No panel swap. Wraps around, skips disabled tabs, mirrored under right-to-left.&#x22;,\n  },\n  {\n    keys: &#x22;Arrow Left, Arrow Up&#x22;,\n    action: &#x22;Moves the highlight to the previous tab&#x22;,\n    notes: &#x22;Wraps to the last tab, skips disabled tabs, swaps no panel.&#x22;,\n  },\n  {\n    keys: &#x22;Home, End&#x22;,\n    action: &#x22;Moves the highlight to the first or last tab&#x22;,\n    notes: &#x22;Both skip disabled tabs and neither swaps the panel.&#x22;,\n  },\n  {\n    keys: &#x22;Enter, Space&#x22;,\n    action: &#x22;Activates the highlighted tab and shows its panel&#x22;,\n    notes: &#x22;The commit step of manual activation.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"tabs\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"TabsProps\" />\n\n`value` and `onValueChange` make this controlled, with no internal selection\nstate. A `value` matching no item renders no active tab and warns in\ndevelopment. `items` holds each tab's value, label and panel together."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/term",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/term.md",
      "slug": [
        "components",
        "term"
      ],
      "section": "Components",
      "title": "Term",
      "description": "A clinical word shown with its everyday meaning attached, so you can read a sentence without having to look anything up.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "glossary term",
        "jargon",
        "plain english",
        "definition",
        "tooltip term",
        "plain word"
      ],
      "implements": [],
      "governedBy": [
        "health/index",
        "consent-and-privacy",
        "high-stakes-moments",
        "safety-review"
      ],
      "usedIn": [
        "ask-users-for",
        "consent-and-permissions",
        "result-disclosure"
      ],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"term\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;A collapsed definition reaches a reader only through the trigger's accessible description, and no real screen reader on a real phone has ever tested that claim.&#x22;,\n  &#x22;The inline trigger never reaches a 44 by 44 hit area, and whether that exception is the right trade for a reader with a tremor is untested.&#x22;,\n  &#x22;The glossary's policy rule says the plain wording should be the visible text and the clinical word the annotation, which is the opposite of this component's shape.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"term\" unbuilt=\"false\" importPath=\"@/components/ui/term\" />\n\n```tsx\nimport { Term, TermGlossaryProvider } from \"@/components/ui/term\"\n```\n\n```tsx\n<TermGlossaryProvider glossary={GLOSSARY}>\n  <p>\n    An <Term id=\"acute\" /> problem started suddenly.\n  </p>\n</TermGlossaryProvider>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"term\" />\n\n### Reading a paragraph without leaving it [#reading-a-paragraph-without-leaving-it]\n\nTwo terms is near the ceiling for one paragraph. A third carries `once`, so the word stays\nmarked and reachable but its definition is not reprinted.\n\n<ComponentPreview name=\"term-in-a-sentence\" kind=\"example\" align=\"start\" />\n\n### An abbreviation needs two things [#an-abbreviation-needs-two-things]\n\nThe expansion says what the letters stand for, the definition what the thing is. Both\nentries are marked `showBoth: \"always\"`, so both arrive inline, and `SpO2` adds `speech`.\n\n<ComponentPreview name=\"term-an-abbreviation\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;A clinical word the reader will meet on a letter, in a consultation, or on a test result, so a plainer word cannot replace it.&#x22;,\n  &#x22;An abbreviation whose expansion the reader needs at least once: HbA1c, eGFR, BP, SpO2.&#x22;,\n  &#x22;A word whose everyday meaning differs from its clinical one, such as 'chronic' or 'acute'.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;The explanation runs past a sentence or two, or carries a caveat as well as a definition.&#x22;, instead: &#x22;callout&#x22; },\n  { case: &#x22;The point is a standing statement about what this product is and is not.&#x22;, instead: &#x22;disclaimer-note&#x22; },\n  { case: &#x22;You need general help text for a non-clinical interface control.&#x22;, instead: &#x22;tooltip&#x22; },\n  { case: &#x22;The reader needs to browse or search every definition rather than read one in place.&#x22;, instead: &#x22;table&#x22; },\n  { case: &#x22;What needs explaining is a number, a unit or a precision rather than a word.&#x22;, instead: &#x22;value&#x22; },\n]\"\n/>\n\n## Clinical meaning [#clinical-meaning]\n\n**Asserts.** That this word has this everyday meaning in the product's glossary. That\ntranslation is the product's claim, not a clinician's, and opsinjs ships an empty glossary.\nSee [Health](../health/index.mdx).\n\n**Never read as.** A statement about the reader's condition, or advice. *Chronic means\nlong-lasting* is a translation; *chronic means you will have this for life* is a prognosis\nthe glossary is not for.\n\n**Colour axis.** Neither. The mark is a dotted underline that survives greyscale. See\n[Health](../health/index.mdx).\n\n**Thresholds.** None. Term puts no reading on the screen, so it holds no threshold and\nstamps no value.\n\n**Gap you must build around.** A call site naming a `plain-only` entry gets the authored\nsentence and a development warning, because a runtime cannot rewrite one. No lint rule\ncatches it.\n\n<SafetyCallout severity=\"attention\" evidence=\"opinion\">\n  Review the glossary as clinical content, not as microcopy. A definition that slides into\n  guidance has nobody behind it, and nothing catches the drift.\n</SafetyCallout>\n\n## Accessibility [#accessibility]\n\nThe disclosure is a real button named by its visible word, meeting SC 2.5.3 Label in\nName. `present` has no `hover` value, so the definition never depends on hover, and\ncollapsed it is `display: none` yet still reaches the reader as the trigger's\ndescription. The mark changes form, not colour: dotted at rest, solid while open. The\naudit made the trigger's focus ring honour `--opsin-border-focus` and\n`--opsin-border-focus-offset` in place of a hardcoded 2px width and offset, so the\nindicator grows with a reader's focus width.\n\n**Residual items.**\n\n* The inline trigger falls under the 44 by 44 floor and relies on the SC 2.5.8 inline\n  exception, and adjacent wrapped triggers can overlap.\n* `aria-controls` deliberately points at the closed `display: none` panel. No assistive\n  technology has been tested against it, so the lived experience is unverified.\n\n<KeyboardTable\n  name=\"term\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Move focus to the disclosure control&#x22;,\n    notes: &#x22;One tab stop per term. The inline presentation has none.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Move focus backwards to it&#x22;,\n    notes: &#x22;Reverse order matches where the word sits in the sentence.&#x22;,\n  },\n  {\n    keys: &#x22;Enter&#x22;,\n    action: &#x22;Show or hide the definition&#x22;,\n    notes: &#x22;Native activation. The definition appears beside the word, not over it.&#x22;,\n  },\n  {\n    keys: &#x22;Space&#x22;,\n    action: &#x22;Show or hide the definition&#x22;,\n    notes: &#x22;Native activation, which is what stops the page scrolling.&#x22;,\n  },\n  {\n    keys: &#x22;Escape&#x22;,\n    action: &#x22;Hide the definition&#x22;,\n    notes: &#x22;Consumed only while open, so the sheet around it survives.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"term\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"TermProps\" />\n\n<PropsTable name=\"TermGlossaryProviderProps\" />\n\nThere is no way to supply a definition at a call site. Definitions live in the glossary\nand arrive once through `TermGlossaryProvider`, so they stay consistent and reviewable.\nAn `id` the glossary does not hold renders unmarked and warns in development, printing\n`children` where a call site supplied any and otherwise the raw `id`."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/textarea",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/textarea.md",
      "slug": [
        "components",
        "textarea"
      ],
      "section": "Components",
      "title": "Textarea",
      "description": "A multi-line box for a free-text note, a native textarea wearing the opsinjs tokens rather than a Base UI primitive, that takes neither colour axis.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "long text",
        "notes input"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"textarea\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;Whether the body ink, the muted placeholder and the neutral border clear the text and non-text contrast floors is argued from the roles, not measured.&#x22;,\n  &#x22;Nobody has heard the box in a screen reader, so whether an unnamed box is caught rests on a development warning that only fires in development.&#x22;,\n  &#x22;Whether a standalone invalid box is noticeable with only aria-invalid and the neutral border, before Field places a visible message, has not been tested with a reader.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"textarea\" unbuilt=\"false\" importPath=\"@/components/ui/textarea\" />\n\n```tsx\nimport { Textarea } from \"@/components/ui/textarea\"\n```\n\n```tsx\n<Textarea\n  aria-label=\"Anything you want to add?\"\n  placeholder=\"A sentence or two is plenty.\"\n  rows={4}\n/>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"textarea\" />\n\n### A notes field [#a-notes-field]\n\nOutside a Field, `aria-label` carries the prompt and the placeholder shows the kind of\nanswer wanted rather than repeating the question.\n\n<ComponentPreview name=\"textarea-a-notes-field\" kind=\"example\" align=\"start\" />\n\n### With a character limit [#with-a-character-limit]\n\n`maxLength` caps the text, and the footnote states the limit in words, because the\nnative attribute refuses the next keystroke in silence. A real `<label htmlFor>` pointed\nat its `id` names this box.\n\n<ComponentPreview name=\"textarea-with-a-character-limit\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;Collecting a free-text note the reader writes in their own words, such as how a day went.&#x22;,\n  &#x22;A question whose answer runs to a sentence or more, where a single-line box would hide the start.&#x22;,\n  &#x22;The control inside a Field for a long-answer question, where the field owns the label and the error.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;The answer is a single short line, such as a name or a place.&#x22;, instead: &#x22;field&#x22; },\n  { case: &#x22;The reader is entering a measurement with a unit, which needs the number formatted and the unit shown.&#x22;, instead: &#x22;reading-input&#x22; },\n  { case: &#x22;The reader is choosing from a fixed set of answers rather than writing one.&#x22;, instead: &#x22;field&#x22; },\n]\"\n/>\n\n## Accessibility [#accessibility]\n\nOnly neutral chrome roles reach the box, never a status colour, literal or ramp step,\nand its type is the `body` step, not a pixel size. The focus ring rides in the box's own\nclasses, so it survives without the product stylesheet, and the height floors at the\nhouse target. There is no axe, target-size, focus-visible or 320px reflow failure.\n\n**Residual items.**\n\n* The box needs an accessible name and invents none. A Field label, an `aria-label` alone\n  or an `id` with a real `<label htmlFor>` gives it one, and with none of `aria-label`,\n  `id` or `name` a development warning names the gap.\n* A persistent visible label is recommended, not required, and the default export uses\n  one.\n* `invalid` sets `aria-invalid` and leaves the border neutral, because a form error is\n  not a clinical status. [Field](./field.mdx) places the message, so a standalone box\n  cannot associate an external message id.\n* `maxLength` is forwarded with no visible counter or live remaining-count region, so\n  pair the limit with a visible count near the box, as the Content guidelines say.\n* Disabled state is a muted fill, not an opacity wash, so the text stays legible, and\n  WCAG exempts disabled controls from the contrast floor.\n* No gate checks contrast, or the box under `forced-colors: active` and\n  `prefers-contrast: more`, including the browser's resize handle.\n\n<KeyboardTable\n  name=\"textarea\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves focus into the box&#x22;,\n    notes: &#x22;One tab stop. The box does not trap Tab, so a second Tab moves out.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Moves focus back out of the box&#x22;,\n    notes: &#x22;A single stop in reverse too, so focus leaves rather than stepping inside.&#x22;,\n  },\n  {\n    keys: &#x22;Enter&#x22;,\n    action: &#x22;Inserts a line break&#x22;,\n    notes: &#x22;Native multi-line behaviour, so Enter adds a line rather than submitting.&#x22;,\n  },\n  {\n    keys: &#x22;Arrow keys, Home, End&#x22;,\n    action: &#x22;Move the cursor through the text&#x22;,\n    notes: &#x22;The browser's own text editing bindings, not ones this component adds.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"textarea\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"TextareaProps\" />\n\n`value` with `onChange` makes the box controlled, and `defaultValue` leaves it\nuncontrolled. `rows` sets the resting height and defaults to three. `className` is\nmerged last and must resolve no `--opsin-status-*` or `--opsin-category-*` role."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/timeline-entry",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/timeline-entry.md",
      "slug": [
        "components",
        "timeline-entry"
      ],
      "section": "Components",
      "title": "TimelineEntry",
      "description": "One dated event in a vertical history, with a neutral rail and marker, the time written as people say it, and any clinical status shown as a nested pill.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "history item",
        "event list",
        "activity feed"
      ],
      "implements": [],
      "governedBy": [
        "trends"
      ],
      "usedIn": [
        "daily-logging"
      ],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"timeline-entry\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;No contrast pair has been measured. The neutral marker and the hairline connector are painted on whatever ground the host provides, and that pairing is unchecked.&#x22;,\n  &#x22;No screen reader has met this component, so whether an entry reads well inside a product's own list has not been listened to by anybody.&#x22;,\n  &#x22;No locale is forwarded to the composed RelativeTime, so the recorded time takes the runtime default and a server render can disagree with a browser.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"timeline-entry\" unbuilt=\"false\" importPath=\"@/components/ui/timeline-entry\" registryDependencies=\"[&#x22;relative-time&#x22;, &#x22;status-pill&#x22;]\" />\n\n```tsx\nimport { TimelineEntry } from \"@/components/ui/timeline-entry\"\n```\n\n```tsx\n<ol>\n  <TimelineEntry\n    when=\"2026-03-14T08:12:00+00:00\"\n    now={new Date().toISOString()}\n    title=\"Repeat prescription issued\"\n    status=\"watch\"\n    isLast\n  >\n    Issued by the example clinic.\n  </TimelineEntry>\n</ol>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"timeline-entry\" />\n\n### A history on one rail [#a-history-on-one-rail]\n\nEvery row names and dates its event, the connector runs to the last entry and\nstops, and one row carries a status the product assigned.\n\n<ComponentPreview name=\"timeline-entry-in-a-history\" kind=\"example\" align=\"start\" />\n\n### The status rides the pill [#the-status-rides-the-pill]\n\nTwo entries alike but for `status`. The rail, the marker and the entry stay\nneutral, and status changes only the pill beside the title.\n\n<ComponentPreview name=\"timeline-entry-with-a-status\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;Showing one recorded event in a history the product lays out: a prescription issued, a test booked, a note added.&#x22;,\n  &#x22;Placing a single dated entry on a vertical rail, where the product owns the list around it.&#x22;,\n  &#x22;A row that needs the recorded time in words, with an optional status beside the event.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;You want one component to own the whole history, its ordering and its data model.&#x22;, instead: &#x22;card&#x22; },\n  { case: &#x22;You are charting one reading as it moves over time rather than listing distinct events.&#x22;, instead: &#x22;trend-sparkline&#x22; },\n  { case: &#x22;You only need to say when a single thing happened, with no rail, marker or event around it.&#x22;, instead: &#x22;relative-time&#x22; },\n  { case: &#x22;You are recording medicine doses taken and missed, which has its own shape.&#x22;, instead: &#x22;dose-tracker&#x22; },\n  { case: &#x22;You need the reader to write down what happened rather than read a recorded event.&#x22;, instead: &#x22;log-sheet&#x22; },\n]\"\n/>\n\n## Clinical meaning [#clinical-meaning]\n\n**Asserts.** That the named event was recorded at the given instant, and nothing\nmore. A gap between two entries is not evidence that nothing happened in it.\n\n**Never read as.** A diagnosis, a verdict, or a guarantee that the history is\ncomplete or current. The entry never triages, diagnoses or advises, and every\nword in it is the product's.\n\n**Colour axis.** Neither, on the entry. The rail and the marker are neutral\nchrome. A supplied `status` is delegated to a nested StatusPill, which carries\nthe status axis with a word and a glyph. See\n[Two colour axes](../health/two-colour-axes.mdx).\n\n**Thresholds.** The product owns them all. The entry holds no threshold, no\nstaleness boundary and no event text.\n[Trends and uncertainty](../health/trends.mdx) covers why it never guesses\nwhether a recorded time is too old to trust, and why one entry is one event,\nnot a direction.\n\n## Accessibility [#accessibility]\n\nThe rail and the marker carry `aria-hidden`, so a screen reader meets the time,\nthe title, any status word and the body in reading order. The recorded time is\nthe system RelativeTime, a semantic `time` element, so the exact instant stays\nin the accessibility tree when only the phrase shows. Nothing in the entry is\nfocusable, so keyboard, focus and target size do not apply. Axe, target-size,\nfocus-visible and 320px reflow checks were clean, and the audit changed nothing.\n\n**Residual items.**\n\n* The marker and the connector are decorative chrome under `aria-hidden`, so\n  they are exempt from Non-text Contrast (1.4.11). They use role tokens anyway.\n* The root renders a bare `li`, so the product must supply the `ol` or `ul`\n  around it for list semantics to hold.\n* On Safari with VoiceOver a `list-style: none` list can drop its list role, a\n  platform quirk shared by every list based component here rather than a fault\n  in this one.\n\n<KeyboardTable\n  name=\"timeline-entry\"\n  rows=\"[\n  { keys: &#x22;Tab&#x22;, action: &#x22;Skips the entry&#x22;, notes: &#x22;Nothing here is focusable, so a long history costs a keyboard user no stops.&#x22; },\n  { keys: &#x22;Shift + Tab&#x22;, action: &#x22;Skips the entry&#x22;, notes: &#x22;Same in reverse. The time, the title and the body are reached by reading.&#x22; },\n]\"\n/>\n\n<ContrastReport component=\"timeline-entry\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"TimelineEntryProps\" />\n\n`when` is ISO 8601 with an offset, the contract RelativeTime enforces on its\n`at`. `now` is required because this component never reads the clock, so read\nthe clock once per screen and pass one value to every entry. The event word is\nfixed and no `locale` is forwarded, so a product needing either composes\nRelativeTime directly."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/toast",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/toast.md",
      "slug": [
        "components",
        "toast"
      ],
      "section": "Components",
      "title": "Toast",
      "description": "A brief, self-dismissing confirmation of the reader's own action, built on Base UI Toast.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "snackbar",
        "transient message",
        "notification toast"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"toast\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;Whether a self-dismissing confirmation is announced in full before it leaves has been reasoned about from the Base UI roles rather than heard in a screen reader.&#x22;,\n  &#x22;Whether the default five seconds is long enough for a reader who reads slowly, uses a switch device, or is partway through another task is unmeasured.&#x22;,\n  &#x22;Whether the title, the description and the close control clear the text and non-text contrast floors has been argued from the roles rather than measured.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"toast\" unbuilt=\"false\" importPath=\"@/components/ui/toast\" dependencies=\"[&#x22;@base-ui/react&#x22;, &#x22;lucide-react&#x22;]\" />\n\n```tsx\nimport { Toast } from \"@/components/ui/toast\"\nimport { Toast as ToastManager } from \"@base-ui/react/toast\"\n```\n\n```tsx\nfunction SaveButton() {\n  const manager = ToastManager.useToastManager()\n  return (\n    <button onClick={() => manager.add({ title: \"Saved\" })}>Save note</button>\n  )\n}\n\nfunction Screen() {\n  return (\n    <Toast position=\"bottom-right\">\n      <SaveButton />\n    </Toast>\n  )\n}\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"toast\" />\n\n### A save confirmation [#a-save-confirmation]\n\nA button pushes a \"Saved\" toast that stays a few seconds and then leaves. The words are fictional and name nothing measured.\n\n<ComponentPreview name=\"toast-a-save-confirmation\" kind=\"example\" align=\"start\" />\n\n### With an action [#with-an-action]\n\n`actionProps` adds one quiet control beside the message, so a reader who removed a note by mistake can reverse it. Here Undo only closes the toast.\n\n<ComponentPreview name=\"toast-with-an-action\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;Confirming an action the reader took, such as a note saved or a reminder set, where missing it costs nothing.&#x22;,\n  &#x22;Acknowledging a background action that completed, such as a sync finishing, which the reader loses nothing by missing.&#x22;,\n  &#x22;Offering a brief optional way to reverse the action, such as an Undo the reader may take or ignore.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;The message is a reading, a result, or anything about the reader's health they must not miss.&#x22;, instead: &#x22;alert-banner&#x22; },\n  { case: &#x22;The message needs attention now and stays until the reader has dealt with it.&#x22;, instead: &#x22;alert-banner&#x22; },\n  { case: &#x22;The information is a standing explanation, note or caveat that belongs on the surface while they read.&#x22;, instead: &#x22;callout&#x22; },\n]\"\n/>\n\n## Accessibility [#accessibility]\n\nRoles, names, the polite live region, pause on hover and focus, Escape and focus return\nall come correctly from `@base-ui/react`. The X icon is `aria-hidden` and the close\ncarries a translatable `aria-label`. Colours are role tokens, type sizes are\n`text-opsin-*` tokens, and the controls floor their hit area at `--opsin-target-minimum`.\nThere is no axe, target-size or 320px reflow failure. A toast follows a finger that\nswipes it, springs back if let go early and leaves the way it was thrown. The close\ncontrol does the same job for a reader who cannot swipe. Under `prefers-reduced-motion`\nits arrival is a short fade with no travel.\n\n**Residual items.**\n\n* A toast pushed with a description and no title yields a dialog with no accessible\n  name, because `ToastList` rightly emits no empty title. The live region still\n  announces it through `aria-describedby`, and the default and both examples always\n  pass a title.\n* Whether an appearing toast overlaps a control focused elsewhere is a product-layout\n  question outside component scope.\n* Contrast pairs are unmeasured, so the report below carries what was measured.\n\n<KeyboardTable\n  name=\"toast\"\n  rows=\"[\n  {\n    keys: &#x22;F6&#x22;,\n    action: &#x22;Moves focus to the toast viewport&#x22;,\n    notes: &#x22;A Base UI global shortcut, so the stack is reachable without tabbing the page.&#x22;,\n  },\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves between the controls in the focused toast&#x22;,\n    notes: &#x22;Two stops with an action, one without. Focus stays in the toast.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Moves back through the controls in the focused toast&#x22;,\n    notes: &#x22;The same stops in reverse.&#x22;,\n  },\n  {\n    keys: &#x22;Enter, Space&#x22;,\n    action: &#x22;Activates the focused control&#x22;,\n    notes: &#x22;The close control or the action, both native buttons.&#x22;,\n  },\n  {\n    keys: &#x22;Escape&#x22;,\n    action: &#x22;Dismisses the focused toast&#x22;,\n    notes: &#x22;So a reader never waits on the auto-dismiss timer.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"toast\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"ToastProps\" />\n\n`position` defaults to `bottom-right`, `limit` to three and `timeout` to 5000ms. A toast swipes away from the edge it is docked to and towards its own corner, so a top-docked toast is thrown up rather than down, and a centred one either way. Passing `timeout={0}` stops every toast dismissing itself and raises a development warning, because a message that must persist is an AlertBanner or a Callout. `label` and `closeLabel` are props so they can be translated, and both default to English."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/tooltip",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/tooltip.md",
      "slug": [
        "components",
        "tooltip"
      ],
      "section": "Components",
      "title": "Tooltip",
      "description": "A short supplementary label that appears when a pointer rests on a control or a keyboard moves focus to it, for information a reader can do without.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "hover label"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"tooltip\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;No contrast pair has been measured: footnote ink on the card fill, and the arrow's fill against whatever surface sits behind it, are argued from the roles only.&#x22;,\n  &#x22;Nobody has listened to a tooltip in a screen reader, so whether the aria-describedby label is announced as a description, or at all on touch, is unheard.&#x22;,\n  &#x22;Nothing stops a caller putting the one fact a control cannot be used without behind a hover a phone reader never triggers; no lint catches it.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"tooltip\" unbuilt=\"false\" importPath=\"@/components/ui/tooltip\" dependencies=\"[&#x22;@base-ui/react&#x22;]\" />\n\n```tsx\nimport { Tooltip } from \"@/components/ui/tooltip\"\n```\n\n```tsx\n<Tooltip content=\"A rolling mean across the nights you have logged.\">\n  <button type=\"button\">Overnight average</button>\n</Tooltip>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"tooltip\" />\n\n### On an icon button [#on-an-icon-button]\n\nEach icon button carries its own name through `aria-label`; `content` repeats it\nvisibly. The labels name fictional actions.\n\n<ComponentPreview name=\"tooltip-on-an-icon-button\" kind=\"example\" align=\"start\" />\n\n### A supplementary hint [#a-supplementary-hint]\n\nThe setting is named in plain words, so a touch reader needs no hover, and\n`content` adds one optional sentence.\n\n<ComponentPreview name=\"tooltip-a-supplementary-hint\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;Expanding an icon-only control's name, already carried through aria-label.&#x22;,\n  &#x22;Adding a short optional note beside a label that already stands on its own.&#x22;,\n  &#x22;Surfacing a value's full form on demand, where the reading is already on screen.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;The label carries something a touch reader needs. A phone has no hover, so the tooltip never opens for them.&#x22;, instead: &#x22;callout&#x22; },\n  { case: &#x22;You are explaining what a clinical word means. That belongs inline, in the accessibility tree.&#x22;, instead: &#x22;term&#x22; },\n  { case: &#x22;You are attaching a hint to a form control, such as a date format. A field hint is always visible.&#x22;, instead: &#x22;field&#x22; },\n]\"\n/>\n\n## Accessibility [#accessibility]\n\nBase UI wires the popup through `aria-describedby`, so the label is a\ndescription, never a replacement for the control's own name. Focus opens the\ntooltip, Escape dismisses it without moving focus, and the label follows focus\noff the trigger. On hover it unfolds from the trigger, while a tooltip opened by focus,\nor moved to from a neighbour, appears at once. Under `prefers-reduced-motion` only a\nshort crossfade remains. Text sits at the `footnote` step with no `px` size, and it\ntakes neither colour axis: no status colour, no colour literal and no ramp step.\nAxe, target-size, focus-visible and 320px clipping checks were clean, and\n`tooltip.tsx` needed no change.\n\n**Residual items.**\n\n* A tooltip is unreachable on a hover-less touch device, so `content` stays\n  supplementary.\n* The popup's non-text contrast (SC 1.4.11) is the shared `border-border` role\n  token, reasoned rather than measured.\n* The popup staying hoverable across the gap (SC 1.4.13) is a Base UI 1.7.0\n  default, not a manual trace.\n\n<KeyboardTable\n  name=\"tooltip\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Moves focus onto the trigger and shows the tooltip&#x22;,\n    notes: &#x22;No open delay on focus.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Moves focus off the trigger and hides the tooltip&#x22;,\n    notes: &#x22;The label follows focus.&#x22;,\n  },\n  {\n    keys: &#x22;Escape&#x22;,\n    action: &#x22;Dismisses the tooltip&#x22;,\n    notes: &#x22;Focus stays on the trigger and reopens it on the next pointer rest.&#x22;,\n  },\n  {\n    keys: &#x22;Enter, Space&#x22;,\n    action: &#x22;Activates the underlying control&#x22;,\n    notes: &#x22;The tooltip binds neither key.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"tooltip\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"TooltipProps\" />\n\n`content` is required; an empty one raises a development warning. `children`\nmust be focusable. `side` defaults to `top` and Base UI flips it at the screen\nedge. `delay` defaults to 600 and governs the pointer only; focus opens the\ntooltip at once."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/trend-sparkline",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/trend-sparkline.md",
      "slug": [
        "components",
        "trend-sparkline"
      ],
      "section": "Components",
      "title": "TrendSparkline",
      "description": "A small line showing how one measurement has moved over time, with a caption that says what changed and leaves the verdict to you.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "chart",
        "graph",
        "sparkline",
        "over time",
        "trend",
        "mini chart",
        "line chart"
      ],
      "implements": [],
      "governedBy": [
        "trends",
        "numbers",
        "two-colour-axes",
        "alerts"
      ],
      "usedIn": [
        "trend-review"
      ],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"trend-sparkline\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;Accessible charts requires a data-table twin beside every chart, and this component has none, so nothing checks a caller placed one.&#x22;,\n  &#x22;window is a display string, so two sparklines compare only where their series cover the same span.&#x22;,\n  &#x22;minimumPoints is required with no default, so the copied demo carries a threshold-shaped number A11Y014 cannot see.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"trend-sparkline\" unbuilt=\"false\" importPath=\"@/components/ui/trend-sparkline\" registryDependencies=\"[&#x22;status-pill&#x22;, &#x22;value&#x22;]\" />\n\n```tsx\nimport { TrendSparkline } from \"@/components/ui/trend-sparkline\"\n```\n\n```tsx\n<TrendSparkline\n  label=\"Example measurement\"\n  unit=\"steps\"\n  precision={0}\n  locale=\"en-GB\"\n  window=\"the last 6 entries\"\n  series={series}\n  minimumPoints={readingsATrendNeeds}\n/>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"trend-sparkline\" />\n\n### A band behind the line, and one marked reading [#a-band-behind-the-line-and-one-marked-reading]\n\n`range` shades a band only where it carries a source and both bounds. The one-sided\nrange beside it is stated in words, drawn as nothing.\n\n<ComponentPreview name=\"trend-sparkline-a-band-and-a-marked-reading\" kind=\"example\" align=\"start\" />\n\n### Not enough readings [#not-enough-readings]\n\n`minimumPoints` of four, against series of four and three. The short one draws nothing\nand appends its `caption` to the refusal.\n\n<ComponentPreview name=\"trend-sparkline-not-enough-readings\" kind=\"example\" align=\"start\" />\n\n### A row of tiles [#a-row-of-tiles]\n\nWhat `category` is for: finding one line among several. Greyscale loses no fact.\n\n<ComponentPreview name=\"trend-sparkline-a-row-of-tiles\" kind=\"example\" align=\"start\" />\n\n### States [#states]\n\n| Data state | What TrendSparkline renders                                                                 |\n| ---------- | ------------------------------------------------------------------------------------------- |\n| Error      | A non-finite value is counted apart from gaps and called unreadable in the caption.         |\n| Loading    | None. The surface fetching the series owns the skeleton.                                    |\n| Empty      | Below `minimumPoints` it draws no line and prints the refusal, naming count and minimum.    |\n| Partial    | A `{ value: null }` entry is a real break, counted in the caption. Nothing is interpolated. |\n| Stale      | The caption prints the last reading's date. No boundary invented, no verdict passed.        |\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;One measurement over time, where the shape of the change is the point.&#x22;,\n  &#x22;A compact companion to a reading, showing whether today's number fits a pattern.&#x22;,\n  &#x22;Anywhere a reader would otherwise ask 'is this new?' about a value shown.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;Fewer readings than your product's minimum, so a line would imply an unsupported pattern.&#x22;, instead: &#x22;empty-state&#x22; },\n  { case: &#x22;The reader compares one value with a reference range, not its own history.&#x22;, instead: &#x22;range-bar&#x22; },\n  { case: &#x22;The reader needs which day a value belongs to, so axes and hover are required.&#x22;, instead: &#x22;table&#x22; },\n  { case: &#x22;You show one number and its change since last time, without a line.&#x22;, instead: &#x22;metric-tile&#x22; },\n  { case: &#x22;The trend crossed a threshold and the reader must do something about it.&#x22;, instead: &#x22;care-card&#x22; },\n]\"\n/>\n\n## Clinical meaning [#clinical-meaning]\n\n**Asserts.** That these readings, in this unit, were recorded at these times. Nothing\nabout cause.\n\n**Never read as.** A prediction, an explanation or a verdict. Upward is not worse and\ndownward is not better, so the line shows direction only\n([Trends and uncertainty](../health/trends.mdx)).\n\n**Colour axis.** Category, on the line alone\n([Two colour axes](../health/two-colour-axes.mdx)). Status is never drawn: the\nmarked reading is neutral and its verdict is a [StatusPill](./status-pill.mdx) in the\ncaption.\n\n**Thresholds.** None. `changeThreshold` is required before any direction word prints,\nand `minimumPoints` before any line is drawn\n([Numbers and units](../health/numbers.mdx)).\n\n**Gaps and age.** A `{ value: null }` entry breaks the path and is never interpolated.\nThe caption prints the last reading's date and invents no staleness boundary\n([Trends and uncertainty](../health/trends.mdx)).\n\n## Accessibility [#accessibility]\n\nThe rendered pass found no serious axe, target-size or focus breach at 320px, and nothing\nneeded changing. The two colour axes stay apart, status is carried by the caption\n[StatusPill](./status-pill.mdx) and never by colour alone, and the committed `check:a11y`\ngate reruns the literal, bound, colour and axis rules.\n\n**Residual items.**\n\n* No per-point data table twin. The text alternative is the `role=\"img\"` name plus the\n  visible caption. A full table is an enhancement, not an AA requirement.\n* `className` merges onto the whole subtree, so an `sr-only` variant can hide the\n  caption, the only text carrier. A documented API risk; keep it visible.\n* Under forced colours the line drops its category tint to `CanvasText`. Category is\n  identity only, so nothing else is lost, and this is intentional.\n\n<KeyboardTable\n  name=\"trend-sparkline\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Skips the whole component&#x22;,\n    notes: &#x22;Nothing is focusable. focusable=\\&#x22;false\\&#x22; covers engines that made SVG focusable.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Skips the whole component&#x22;,\n    notes: &#x22;Never enters the focus order, in either direction.&#x22;,\n  },\n  {\n    keys: &#x22;Any other key&#x22;,\n    action: &#x22;Nothing&#x22;,\n    notes: &#x22;No hover, no tooltip, no point-by-point navigation. Days belong in a table.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"trend-sparkline\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"TrendSparklineProps\" />\n\n`precision`, `series` and `minimumPoints` are required with no default, because none is a\nnumber opsinjs could supply. `TrendPoint` and `ReferenceRange` come from `@/lib/opsinjs`,\nso no second copy can drift.\n\n### Data attributes [#data-attributes]\n\n<DataAttributesTable\n  name=\"trend-sparkline\"\n  rows=\"[\n  {\n    attribute: &#x22;data-slot&#x22;,\n    condition: &#x22;On the root and every rendered part&#x22;,\n    value: &#x22;trend-sparkline, trend-sparkline-window, trend-sparkline-plot, trend-sparkline-baseline, trend-sparkline-band, trend-sparkline-line, trend-sparkline-gap-edge, trend-sparkline-point, trend-sparkline-caption&#x22;,\n  },\n  {\n    attribute: &#x22;data-category&#x22;,\n    condition: &#x22;On the line, for a known category&#x22;,\n    value: &#x22;sleep | heart | activity | nutrition | mind | labs&#x22;,\n  },\n  {\n    attribute: &#x22;data-status&#x22;,\n    condition: &#x22;On the marked reading alone&#x22;,\n    value: &#x22;steady | watch | attention | urgent&#x22;,\n  },\n  {\n    attribute: &#x22;data-opsinjs-value&#x22;,\n    condition: &#x22;On the marked reading and every caption Value. De-duplicate before scraping&#x22;,\n    value: &#x22;The unrounded number behind that reading&#x22;,\n  },\n]\"\n/>"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/value",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/value.md",
      "slug": [
        "components",
        "value"
      ],
      "section": "Components",
      "title": "Value",
      "description": "A number and its unit, formatted one way everywhere. It is rounded honestly, spoken correctly, and never shown to more precision than the measurement has.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "number",
        "unit",
        "format",
        "formatted number",
        "format a number",
        "numeric display",
        "figure"
      ],
      "implements": [],
      "governedBy": [
        "numbers",
        "health/index",
        "trends",
        "consent-and-privacy",
        "reference-ranges",
        "safety-review"
      ],
      "usedIn": [
        "daily-logging",
        "forms",
        "result-disclosure",
        "onboarding-and-first-run",
        "sharing-with-a-clinician",
        "trend-review"
      ],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"value\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;Whether a per-language spoken unit form belongs in tokens/units.json, in the product, or in neither, given that only an English reader hears words today.&#x22;,\n  &#x22;Whether a hero value should move from title1 up to largeTitle, an answer that changes every hero number in MetricTile, ResultCard, ScoreDial and RangeBar at once.&#x22;,\n  &#x22;Whether the muted absence at the display size clears contrast, and how the value behaves at 200% text, since neither has been looked at in either theme.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"value\" unbuilt=\"false\" importPath=\"@/components/ui/value\" />\n\n```tsx\nimport { Value } from \"@/components/ui/value\"\n```\n\n```tsx\n<Value value={1000.2} unit=\"kg\" precision={1} />\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"value\" />\n\n### Zero is a reading. Absence is not. [#zero-is-a-reading-absence-is-not]\n\nThree rows share a unit and a precision and differ only in the reading: a\nnumber, a `null`, and a number that arrived broken. Rule 12 of\n[Numbers and units](../health/numbers.mdx) keeps them apart.\n\n<ComponentPreview name=\"value-zero-is-not-absence\" kind=\"example\" align=\"start\" />\n\n### One precision makes a column comparable [#one-precision-makes-a-column-comparable]\n\nFour readings of one metric at one `precision`, aligned by the layout and by\ntabular figures.\n\n<ComponentPreview name=\"value-aligned-in-a-column\" kind=\"example\" align=\"start\" />\n\n### What a screen reader is actually given [#what-a-screen-reader-is-actually-given]\n\nOne magnitude with six units, and beside each the phrase that reaches speech.\n\n<ComponentPreview name=\"value-spoken-units\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;Any number displayed to a reader that has a unit, a precision, or both.&#x22;,\n  &#x22;Inside other components: the reading in a MetricTile, the number beside a RangeBar tick, the score in a ScoreDial.&#x22;,\n  &#x22;Anywhere the same measurement appears on more than one screen and must look identical on all of them.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;The number needs its reference range shown alongside it to mean anything.&#x22;, instead: &#x22;range-bar&#x22; },\n  { case: &#x22;The number is a point in time rather than a quantity.&#x22;, instead: &#x22;relative-time&#x22; },\n  { case: &#x22;You are collecting the number rather than displaying it.&#x22;, instead: &#x22;reading-input&#x22; },\n  { case: &#x22;The number needs a label, a timestamp and a surface of its own.&#x22;, instead: &#x22;metric-tile&#x22; },\n  { case: &#x22;The number is a proportion or a risk that needs a denominator and a natural-frequency framing.&#x22;, instead: &#x22;callout&#x22; },\n]\"\n/>\n\n## Clinical meaning [#clinical-meaning]\n\n**Asserts.** That this quantity has this magnitude in this unit, to this\nprecision. `1000.2` and `1000.20` claim different things.\n\n**Never read as.** A judgement. Value carries no status and no band; a bare\nnumber means nothing without the context its surface supplies.\n\n**Colour axis.** Neither. A reading inherits the text colour of its context. An\nabsence at `display` takes the muted theme role.\n\n**Thresholds.** None here, and none in `tokens/units.json`, which holds no\nreference range, no plausibility bound and no default precision. Precision\nbelongs to the metric, so `precision` is required. See\n[Numbers and units](../health/numbers.mdx) and\n[Reference ranges](../health/reference-ranges.mdx).\n\n**Masking.** [Consent and privacy](../health/consent-and-privacy.mdx) lists this\namong the components that implement a fixed-width mask. Value has no `masked`\nprop and reserves no width, so masking a reading today moves the layout.\n\n<SafetyCallout severity=\"attention\" evidence=\"opinion\" title=\"The unit table says what a number is measured in. It never says what a number should be.\">\n  `mmol/L` to `mg/dL` is refused, because the factor is a property of the analyte\n  rather than of either unit. `convertUnit` returns nothing rather than a\n  substituted default. See [Numbers and units](../health/numbers.mdx).\n</SafetyCallout>\n\n## Accessibility [#accessibility]\n\nThe unit symbol is `aria-hidden` only when a spoken form exists and the words\nfollow it, so an English reader hears *1000.2 kilograms* as one phrase. Absence\nis spoken in words, never drawn at hero weight, and carries no decorative glyph.\nThe component imposes no truncation, no fixed height and no `whitespace-nowrap`.\nAxe, target-size, focus-visible and 320px reflow checks came back empty, and the\naudit changed nothing in source.\n\n**Residual items.**\n\n* A Value must never be the sole accessible name of a tappable control, because\n  the visible symbol and the spoken words share no substring. The control owes\n  its own name carrying the symbol (WCAG 2.2 SC 2.5.3).\n* The only path to a clipped reading is a caller passing a truncating class\n  through `className`, which `twMerge` lets win, so truncation is a caller\n  responsibility documented on `ValueProps.className`.\n* The spoken span uses `select-none` to keep the words off the clipboard while\n  leaving them in the accessibility tree, untested by a copy test.\n\n<KeyboardTable\n  name=\"value\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Skips the value&#x22;,\n    notes: &#x22;Not focusable, by contract. Thirty readings would otherwise be thirty tab stops doing nothing.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Skips the value&#x22;,\n    notes: &#x22;Same in reverse. A tappable row owes its own name and its own 44 by 44.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"value\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"ValueProps\" />\n\n`precision` is required and nothing is defaulted in its place. `unit={null}`\ndeclares a dimensionless number. Omitting `unit` raises OPSIN-0003 instead.\nUnder server rendering, pass `locale` explicitly, or the server's own ICU\ndefault formats the first paint and hydration reformats it.\n\n### Data attributes [#data-attributes]\n\n<DataAttributesTable\n  name=\"value\"\n  rows=\"[\n  {\n    attribute: &#x22;data-slot&#x22;,\n    condition: &#x22;On the root and every inner part, when that part renders&#x22;,\n    value: &#x22;value, value-number, value-unit, value-spoken, value-absence&#x22;,\n  },\n  {\n    attribute: &#x22;data-opsinjs-value&#x22;,\n    condition: &#x22;On the root, always&#x22;,\n    value: &#x22;The unrounded reading, or an empty string when there is no reading&#x22;,\n  },\n]\"\n/>"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/components/visually-hidden",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/components/visually-hidden.md",
      "slug": [
        "components",
        "visually-hidden"
      ],
      "section": "Components",
      "title": "VisuallyHidden",
      "description": "Content that screen readers announce and eyes do not see, such as the name of a button that shows only an icon.",
      "status": "shipped",
      "implemented": true,
      "kind": "component",
      "aliases": [
        "sr only",
        "screen reader only",
        "clip"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-09-20",
      "markdown": "<StubNotice\n  name=\"visually-hidden\"\n  status=\"shipped\"\n  questions=\"[\n  &#x22;Nobody has listened to this component in VoiceOver, NVDA, JAWS or TalkBack, so announcement everywhere is argued from the clip pattern rather than measured.&#x22;,\n  &#x22;Whether the component should refuse or warn when a focusable control sits inside it is unsettled, so an always-hidden keyboard trap is not prevented.&#x22;,\n  &#x22;The contrast report is empty because nothing is painted, so a reviewer must read it as nothing to measure rather than a gap left unfilled.&#x22;,\n]\"\n>\n  Audited against WCAG 2.2 AA. Clinical review pending.\n</StubNotice>\n\n## Usage [#usage]\n\n<ComponentInstall name=\"visually-hidden\" unbuilt=\"false\" importPath=\"@/components/ui/visually-hidden\" />\n\n```tsx\nimport { VisuallyHidden } from \"@/components/ui/visually-hidden\"\n```\n\n```tsx\n<button type=\"button\">\n  <XIcon aria-hidden=\"true\" />\n  <VisuallyHidden>Close the panel</VisuallyHidden>\n</button>\n```\n\n## Examples [#examples]\n\n<ComponentPreview name=\"visually-hidden\" />\n\n### A name for an icon-only button [#a-name-for-an-icon-only-button]\n\nThe button shows only a cross. The words inside VisuallyHidden become its accessible\nname, and the icon is `aria-hidden`.\n\n<ComponentPreview name=\"visually-hidden-a-name-for-an-icon-button\" kind=\"example\" align=\"start\" />\n\n### Context for a repeated link [#context-for-a-repeated-link]\n\nThree rows end in the same two words, which a screen reader can list out of context.\nAppending the subject inside VisuallyHidden names each link without changing a pixel.\n\n<ComponentPreview name=\"visually-hidden-context-for-a-repeated-link\" kind=\"example\" align=\"start\" />\n\n## When to use it [#when-to-use-it]\n\n<WhenToUse\n  use=\"[\n  &#x22;Give an icon-only control an accessible name, by putting the words the icon stands for inside it.&#x22;,\n  &#x22;Add context a sighted reader gets from layout, such as the subject of a repeated \\&#x22;Read more\\&#x22; link.&#x22;,\n  &#x22;Provide a heading or a label for a region that reads clearly to the eye without one.&#x22;,\n]\"\n  avoid=\"[\n  { case: &#x22;The content must become visible when it receives focus, which is how a skip link works.&#x22;, instead: &#x22;link&#x22; },\n  { case: &#x22;You are labelling a form input and want the label, the hint and the error wired together.&#x22;, instead: &#x22;field&#x22; },\n  { case: &#x22;The words explain jargon and should be readable by everyone, not only by assistive technology.&#x22;, instead: &#x22;term&#x22; },\n]\"\n/>\n\n## Accessibility [#accessibility]\n\nContent is announced because the span is clipped, not `display:none`,\n`visibility:hidden` or the `hidden` attribute, each of which removes content from the\ntree. The clip was checked against the WebAIM sr-only reference and stays hidden\nthrough 200% text and increased text spacing, because neither touches its overflow and\nclip-path. It\npaints nothing and sets no colour or type size, so there is nothing to reflow at 200%\ntext, and as text rather than a control it is never focusable or a tab stop. Axe,\ntarget size, focus visibility and reflow at 320px raised nothing.\n\nThe audit added a development-only warning when a focusable control sits inside the\nalways hidden clip, a keyboard trap with no visible focus ring. The component walks\nits children to find one, and the warning changes no markup, class or visual output.\n\n**Residual items.**\n\n* No gate checks whether VoiceOver, NVDA, JAWS and TalkBack announce the content.\n* Whether hidden text duplicates a visible name beside it is a per-usage question the\n  component cannot see, so it stays a concern for the caller.\n\n<KeyboardTable\n  name=\"visually-hidden\"\n  rows=\"[\n  {\n    keys: &#x22;Tab&#x22;,\n    action: &#x22;Skips the hidden text&#x22;,\n    notes: &#x22;Never a tab stop. A control placed inside keeps its own place in the order.&#x22;,\n  },\n  {\n    keys: &#x22;Shift + Tab&#x22;,\n    action: &#x22;Skips the hidden text in reverse&#x22;,\n    notes: &#x22;Reverse order matches forward order, because there is nothing to stop on.&#x22;,\n  },\n]\"\n/>\n\n<ContrastReport component=\"visually-hidden\" />\n\n## Props interface [#props-interface]\n\n<PropsTable name=\"VisuallyHiddenProps\" />\n\n`children` is required. Empty children, an empty string, `undefined` or `false` raise\na development warning naming the mistake, and the span still renders. `className`\nreaches the span for positioning, and a class that makes the content visible defeats\nthe component."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/health",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/health.md",
      "slug": [
        "health"
      ],
      "section": "Health",
      "title": "Health",
      "description": "What opsinjs decides, what your product decides, and the ten rules every health screen must pass.",
      "kind": "health",
      "evidence": "mixed",
      "aliases": [],
      "implements": [
        "result-card",
        "range-bar",
        "status-pill",
        "alert-banner",
        "care-card",
        "value",
        "disclaimer-note",
        "term",
        "scale-input",
        "questionnaire",
        "symptom-picker",
        "score-dial",
        "trend-sparkline",
        "metric-tile",
        "relative-time",
        "consent-sheet",
        "dose-tracker"
      ],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-10-08",
      "markdown": "opsinjs decides how health information is presented. It never decides what that information means. No component has had an independent accessibility review or any clinical review, and nothing here is for a production health surface.\n\n## The ten rules [#the-ten-rules]\n\nCheck each on the rendered screen before merging anything that shows, interprets or collects health data.\n\n1. **Never carry clinical status in colour alone.** [Two colour axes](./two-colour-axes.mdx)\n2. **Never mix the category axis with the status axis** on one element. [Two colour axes](./two-colour-axes.mdx)\n3. **Never use \"normal\" or \"abnormal\" about a person's own result.** [Reference ranges](./reference-ranges.mdx)\n4. **Never show a number without its unit, its scale and when it was measured.** [Numbers and units](./numbers.mdx)\n5. **Never show more digits than the measurement supports.** [Numbers and units](./numbers.mdx)\n6. **Never draw a trend from fewer points than the metric's minimum window.** [Trends and uncertainty](./trends.mdx)\n7. **Never put more than one `urgent` surface on a screen.** [Alerts](./alerts.mdx)\n8. **Never convey urgency with motion, sound or haptics alone.** [Alerts](./alerts.mdx)\n9. **Never present a result without saying what, if anything, to do**, even when the answer is \"nothing\". [High-stakes moments](./high-stakes-moments.mdx)\n10. **Never collect health data without saying what it is for and how to stop.** [Consent and privacy](./consent-and-privacy.mdx)\n\nTo break a rule, record which, why, who agreed and the compensating control. Lint rules for rules 2, 3 and 4 are planned, not written, so all ten are human checks today. [Safety review](./safety-review.mdx) holds the checklist.\n\n## Who this is for [#who-this-is-for]\n\nSomeone with no clinical training, reading their own result on their own phone with nobody to ask. New to the unit, they give the screen 3 to 15 seconds. Months later they want only the figure, from the same screen.\n\n1. Expand every clinical term in place on first encounter, with [Term](../components/term.mdx).\n2. Give every value its scale, its unit and a sentence on what it means.\n3. Treat a four-year-old phone, low brightness, the largest text size, reduced motion, reduced transparency, increased contrast and greyscale as the expected case. Never fix the height of a card holding a clinical sentence.\n4. Never carry anything important once, quickly, or on a single channel.\n5. Order a result as value, meaning, then next step.\n\n## Scope and safety [#scope-and-safety]\n\n**opsinjs renders decisions. It does not make them.** It never triages, diagnoses or advises, and it is not a medical device. Every clinical judgement on screen originates outside opsinjs, where your organisation can name, review, version and audit it.\n\n1. No component derives a clinical status from a value. There is no `threshold` prop and there will not be one, because your product owns every threshold. Pass `status` in from one mapping your clinical owner approved, versioned and tested at its boundaries, never from code in or beside a component.\n2. No component supplies a reference range. Ranges arrive with their source, and whoever issued one owns it.\n3. No component's wording asserts a clinical meaning. Your clinical content owner writes that sentence.\n4. No component escalates on its own.\n\n**You are responsible for every clinical claim your interface makes, including the ones made by colour, icon, order and emphasis rather than by words.** Your organisation and its regulator decide whether your product is a medical device.\n\n<SafetyCallout severity=\"urgent\" evidence=\"opinion\">\n  If any part of your product would be a medical device without opsinjs, it is\n  still a medical device with opsinjs. Using this design system does not create,\n  transfer, reduce or satisfy any regulatory obligation. Nothing here has been\n  submitted to, reviewed by, or cleared by any regulator, and no conformity\n  assessment of any kind has been performed on it.\n</SafetyCallout>\n\n[DisclaimerNote](../components/disclaimer-note.mdx), [ConsentSheet](../components/consent-sheet.mdx), [AlertBanner](../components/alert-banner.mdx) and [CareCard](../components/care-card.mdx) are not compliance controls, and a disclaimer is necessary and insufficient. Keep a visible route to a human wherever a reader may be frightened, even offline or with the value missing. No component notices distress. If DCB0129 or DCB0160 apply, they apply whole, and opsinjs produces no hazard log or clinical safety case report. Nothing here is legal advice.\n\n## Evidence [#evidence]\n\nEach instrument is named, not paraphrased, because a design system's summary of a regulation is a second-hand reading of a text you must legally read directly. Confirm the current version of each, because they are amended.\n\n* **Regulation (EU) 2017/745 (the Medical Device Regulation, \"MDR\")** is the EU framework under which software may itself qualify as a medical device.\n* **MDCG 2019-11** is the Medical Device Coordination Group guidance on qualification and classification of software under MDR and IVDR.\n* **IMDRF, \"Software as a Medical Device (SaMD): Key Definitions\"** is the international definition the term SaMD comes from, and the vocabulary most regulators build on.\n* **DCB0129, \"Clinical Risk Management: its Application in the Manufacture of Health IT Systems\"** is the NHS England information standard placing clinical risk-management obligations on the *manufacturer* of health IT.\n* **DCB0160, \"Clinical Risk Management: its Application in the Deployment and Use of Health IT Systems\"** is the companion standard, placing obligations on the *deploying organisation*.\n* **WCAG 2.2 (W3C Recommendation)** is the accessibility standard opsinjs measures itself against; see [Accessibility](../foundations/accessibility.mdx). Success criteria 1.4.1 (Use of Colour) and 2.2.2 (Pause, Stop, Hide) are the normative basis for rules 1 and 8.\n* The systematic review of laboratory-result presentation formats in JMIR (2024), [10.2196/53993](https://doi.org/10.2196/53993), anchors rules 3, 4 and 5 in the claim that a number needs a scale, not in any visual treatment.\n* The patient-portal presentation study in BMC Medical Informatics and Decision Making (2018), [10.1186/s12911-018-0589-7](https://doi.org/10.1186/s12911-018-0589-7), is cited for the same claim.\n\nRules 2, 6, 7, 9 and 10 are opinion, as are the audience model and the position that no component derives severity from a value.\n\n<Todo>\n  External clinical review of the whole Health section. Until it happens, no page here may be described as clinically approved.\n</Todo>"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/health/alerts",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/health/alerts.md",
      "slug": [
        "health",
        "alerts"
      ],
      "section": "Health",
      "title": "Alerts",
      "description": "The escalation budget, the five-rung ladder, push notifications, and why motion may support a message but never be one.",
      "kind": "health",
      "evidence": "mixed",
      "aliases": [],
      "implements": [
        "alert-banner",
        "care-card",
        "status-pill",
        "relative-time",
        "score-dial",
        "trend-sparkline",
        "skeleton",
        "sheet",
        "dialog",
        "goal-ring"
      ],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-10-08",
      "markdown": "Alarm fatigue comes from the total of individually reasonable alerts, which no single screen's review sees, so escalation is budgeted per screen, session and day.\n\n## The rules [#the-rules]\n\n### Budget [#budget]\n\n1. Per screen, at most one `urgent` surface and at most two `attention` surfaces.\n2. Per session, at most one interruptive modal the reader did not initiate.\n3. Per day, at most one non-clinical push notification.\n4. `urgent` is reserved for clinical urgency, on every surface.\n5. No parallel escalation. One fact occupies the highest rung it justifies, and the surfaces below it are suppressed.\n6. When a value returns to `steady`, the surface that escalated it is removed and the reader is told once that it has gone.\n7. A surface re-raises on a change of state, never on a timer.\n8. Engagement, retention and commercial messages get a quiet channel, visually and structurally separate from the clinical one.\n\n### Notifications [#notifications]\n\nA notification discloses in public, cannot be recalled, and is switched off wholesale.\n\n9. The title names the subject at category level, such as \"Blood pressure\". The body adds an action, never a value, diagnosis, medication or condition, which stay in the app behind authentication.\n10. The body stays accurate and non-disclosing when a car, watch or smart speaker reads it aloud.\n11. A per-user disclosure setting defaults to the least, and the product never raises it for the reader.\n12. Clinical and non-clinical messages use separate operating-system channels where the platform allows, such as \"Health alerts\" and \"Reminders and updates\".\n13. A `steady` result is pushed only when the reader asked to be told.\n14. A push opens the in-app surface carrying the full message at the same level, never a dashboard. That surface is authoritative, and says so if the state has changed since sending.\n15. A push is stamped with the time the reading was taken, never the delivery time.\n16. Clearing a notification acknowledges nothing, and the in-app alert survives it.\n17. Quiet hours and interruption levels are respected. The highest level is for the clinical `urgent` path only, never a reminder, a digest or a `steady` result.\n18. Nothing is sent at 03:00 unless it is actionable at 03:00, and a clinical alert is never batched into a digest.\n19. The badge count is a disclosure surface, so a badge never appears only when something needs attention. A locked widget shows category-level information only, wherever the platform can hide the rest.\n\n### Motion [#motion]\n\nMotion may support a message. It may never be the message.\n\n20. Urgency is never conveyed by motion. Nothing pulses, flashes, shakes or bounces to show status.\n21. A value is never revealed by animation, so there is no count-up, no dial sweep on first paint and no progressive reveal.\n22. Nothing that carries clinical meaning auto-dismisses.\n23. Nothing flashes. More than three flashes per second is a seizure risk and prohibited outright.\n24. Every animation has a reduced-motion behaviour, stated per token, that is instant, complete and equally informative and still shows where a surface came from.\n25. Motion never delays access to a result.\n26. A surface morphs rather than being swapped.\n\nMotion may confirm an input, show where a surface came from, keep scroll position clear and bound a loading state. A [Skeleton](../components/skeleton.mdx) reserves the exact layout and never implies a number, and no spinner keeps running after a request fails. Streak and reward animation never uses the status channel. Sound and haptics get a smaller budget than the visual one; see [Motion](../foundations/motion.mdx).\n\n<SafetyCallout severity=\"urgent\" evidence=\"opinion\">\n  A value that may need emergency care outranks every ceiling here and\n  suppresses all other alerts on the screen. A notification is never its only\n  channel, because notifications fail silently. See\n  [High-stakes moments](./high-stakes-moments.mdx).\n</SafetyCallout>\n\n## The escalation ladder [#the-escalation-ladder]\n\nMove up a rung only when the one below has proved insufficient, never because a rung looks more important. The staged pattern is [Alert escalation](../patterns/alert-escalation.mdx).\n\n1. **Ambient.** A [StatusPill](../components/status-pill.mdx) on the value. The default.\n2. **In-place.** A [CareCard](../components/care-card.mdx) beside the value, when it needs a named action.\n3. **Screen-level.** An [AlertBanner](../components/alert-banner.mdx) at the top, when rung 2 has proved insufficient.\n4. **Interruptive.** A modal or sheet the reader must dismiss, when the message is time-critical and cannot wait.\n5. **Off-screen.** A push notification, when rung 4 has proved insufficient. Never a first attempt.\n\n## In code [#in-code]\n\n* Nothing counts `urgent` or `attention` surfaces across a screen, so rule 1 is enforced by review today.\n* [Value](../components/value.mdx), [RangeBar](../components/range-bar.mdx) and [ScoreDial](../components/score-dial.mdx) never animate, and each motion token declares its own reduced-motion behaviour.\n* opsinjs renders no notifications. It provides the in-app surface a push opens, and no opsinjs tooling checks rules 9 to 19.\n* Track alert volume per user against a ceiling. Click-through alone measures novelty.\n\n<Todo>\n  Specify the watch and wearable surface: what may appear on a wrist, and how the haptic budget interacts with the visual one.\n</Todo>\n\n## Evidence [#evidence]\n\n* The Joint Commission's Sentinel Event Alert on medical device alarm safety in hospitals (Issue 50) is cited for alarm fatigue as a documented hospital patient-safety problem.\n* ECRI's annual health technology hazards lists, in which alarm-related hazards have appeared repeatedly, are cited for the same.\n* WCAG 2.2 success criteria 2.2.2 (Pause, Stop, Hide), 2.3.1 (Three Flashes or Below Threshold) and 2.3.3 (Animation from Interactions) are normative for the motion rules, and 1.4.1 (Use of Colour) also underlies rule 20.\n* Apple's Human Interface Guidelines and Android's notification documentation are cited, not restated, for current lock-screen and permission behaviour, because it changes.\n\nThe first two are named to be read, not quoted, and their transfer to a consumer phone app is our opinion. So are rules 1 to 19, whose numbers were chosen rather than derived, and rule 21."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/health/consent-and-privacy",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/health/consent-and-privacy.md",
      "slug": [
        "health",
        "consent-and-privacy"
      ],
      "section": "Health",
      "title": "Consent and privacy",
      "description": "Consent per purpose, revocable where the data appears, and how much of that data a screen shows the room.",
      "kind": "health",
      "evidence": "mixed",
      "aliases": [
        "withdraw consent",
        "shoulder surfing"
      ],
      "implements": [
        "consent-sheet",
        "care-card",
        "disclaimer-note",
        "term",
        "field",
        "log-sheet",
        "value",
        "result-card",
        "metric-tile",
        "sheet",
        "dialog",
        "empty-state"
      ],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-10-08",
      "markdown": "Nothing here is legal advice or a compliance checklist, or a substitute for your data protection lead or your regulator's guidance. Which lawful basis applies is your organisation's decision. For direct care it is often not consent, and asking consent for processing that will happen anyway misrepresents the decision as optional. Research consent and records management are out of scope.\n\n## Consent [#consent]\n\n1. One decision per purpose. \"Store my readings\", \"share with my GP\", \"improve the app\" and \"send me health tips\" are four questions, never bundled.\n2. Ask when the feature that uses the data is first used, not during onboarding.\n3. Collect no field without a stated purpose, shown where the field is asked. \"For future use\" is not a purpose.\n4. Name the recipient, the data and the reason in plain words ([Plain English A to Z](../reference/plain-english.mdx)): \"so your GP can see your blood pressure readings in your record\", not \"to improve your experience\".\n5. Declining a secondary purpose keeps every primary function and takes no more effort than accepting. No pre-ticked box, no consent carried by a Continue button, and accept and decline at equal visual weight.\n6. The withdrawal control sits on the screen showing the data, not only in settings.\n7. Before the reader withdraws, state what stops, what is deleted, what is kept and what cannot be undone.\n8. Record the purpose, the decision, the time and the version of the wording.\n9. A materially changed purpose is a new consent, and the request names what changed. Continued use is never agreement.\n10. Disclose sharing wherever the shared data is visible: \"Your GP can see this\" belongs on the data screen, not in a policy.\n11. Ask for, store and display sexual health, mental health, reproductive health, substance use, HIV status and genetic data separately, under the privacy rules below.\n12. The interface does not assess understanding. Write so that misunderstanding is unlikely, not so that agreement is likely.\n\nRule 7, for sharing readings with a GP: \"If you stop sharing: no new readings are sent, and nothing already sent is deleted. Your GP keeps the readings they have already seen. Your own history in the app is unchanged.\"\n\n## On-screen privacy [#on-screen-privacy]\n\n13. A per-user privacy setting, easy to find. Private is the default, and categories the reader marks sensitive start at the more private option.\n14. Replace a hidden value with a fixed-width mask, never a blurred, shortened or distorted version of it.\n15. A masked value takes the same space as the real one, so revealing shifts nothing.\n16. Hide the label where the label is the disclosure: \"Sexual health\" collapses to \"Results\".\n17. On backgrounding, blur or replace the content before the system snapshot, and restore it on return.\n18. The reveal control has an accessible name (\"Show your result\") and requires re-authentication: the platform's biometric or passcode flow, a timeout short enough to matter, and always a non-biometric route.\n19. Never block screenshots. Warn once when a sensitive screen is captured, never on later captures, and make a redacted share the easier path.\n20. Notifications, badges and widgets follow the same rules ([Alerts](./alerts.mdx)).\n21. A reveal applies to one value and expires with the session.\n22. The app is fully usable with values masked, never requiring a reveal.\n23. Review every screen showing a sensitive category for what is legible at a metre and at an angle.\n\n## Components [#components]\n\n[ConsentSheet](../components/consent-sheet.mdx) asks one purpose per sheet. It requires `purpose`, `scope`, `withdrawalPath`, `textVersion` and both control labels, and when any required wording is missing it withholds both controls and says nothing was asked. Accept and decline have equal weight by construction, and closing the sheet without choosing calls nothing. `onDecision` receives the decision, its time, `consentId`, `textVersion` and scope; you store the record.\n\nNo component has a masking, hiding or sensitivity prop, so rules 13 to 23 are built on each screen; one that keeps none of them looks exactly like one that keeps all. The screens are in [Consent and permissions](../patterns/consent-and-permissions.mdx).\n\n<Todo>\n  Specify the masked state on \n\n  `Value`\n\n   and the sensitivity flag as real props, including what a mask renders as at every size and what the reveal control is called for a screen reader.\n</Todo>\n\n<Todo>\n  Specify proxy and carer consent: what changes when the person using the app is not the person the data is about.\n</Todo>\n\n## Evidence [#evidence]\n\n* UK GDPR and EU GDPR special-category provisions (legislation): health data is a special category with additional conditions on processing, and consent as a lawful basis must be freely given, specific, informed, unambiguous, and as easy to withdraw as to give. Rules 1, 4, 5, 6 and 8 restate those requirements. Read the legislation and your regulator's current guidance; we name the frame and do not summarise the law.\n\nRules 2, 3, 10 and 12 and every privacy rule are opinion, and rules 7, 9 and 11 cite nothing. Check two platform behaviours behind rules 17 and 20 against current platform documentation: the system snapshots the screen on backgrounding, and lock screens show notification content without authentication by default. Rule 19's warning is held weakly."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/health/high-stakes-moments",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/health/high-stakes-moments.md",
      "slug": [
        "health",
        "high-stakes-moments"
      ],
      "section": "Health",
      "title": "High-stakes moments",
      "description": "Handling an emergency, a disclosure of self-harm and a difficult result.",
      "kind": "health",
      "evidence": "opinion",
      "aliases": [],
      "implements": [
        "alert-banner",
        "care-card",
        "status-pill",
        "dialog",
        "disclaimer-note",
        "questionnaire",
        "consent-sheet",
        "result-card",
        "term"
      ],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-10-08",
      "markdown": "opsinjs ships no emergency numbers, crisis services, opening hours or clinical wording, and no instrument, scoring, threshold or triage. Which values are emergencies, which answers disclose risk, what a result means, and whether and when it is released are your organisation's decisions, each reviewed by someone clinically accountable, written down and version controlled. Contacting services for the reader, safeguarding and legal duties sit outside a presentation layer. Children and young people, results about someone else and free-text moderation are out of scope.\n\n## Emergency and escalation [#emergency-and-escalation]\n\nWhen your clinical rules flag a possible emergency or same-day need, a distinct, unmistakable path overrides every alert budget, engagement, brand, layout and notification preference.\n\n1. **Action first.** \"Call 999 now\" precedes \"Your reading was 210/125\".\n2. **One action**, with no competing choice.\n3. **Configured, never hardcoded.** The product sets the route per region and names the service, with a way to reach it for readers who cannot call.\n4. **Everything else suppressed.** No other banner, alert, marketing, rating prompt or cookie notice.\n5. **It persists.** No auto-dismiss, timeout or accidental swipe; the calling screen keeps it through backgrounding and relaunch until explicitly acknowledged, and timestamps the acknowledgement.\n6. **Redundant.** In-app, push and on next open, since any channel can fail silently.\n7. **No diagnosis.** \"This reading needs to be checked urgently\" is the limit. Name no condition.\n8. **A route for disagreement.** The product supplies re-measurement, a non-emergency contact, or continuing. Never a dead end.\n\nAnnounce it assertively, make it reachable and operable by keyboard and switch control, hold focus without trapping, meet the contrast floor with no material translucency, and keep every sentence whole at 200% text. Never convey it by colour, motion or sound alone, gate it behind a paywall, login or onboarding, or raise it from an estimated or stale value, which needs a confirming measurement ([Trends and uncertainty](./trends.mdx)).\n\nTest it every release: a forcing fixture, a real device, 200% text, a screen reader, offline.\n\n## Crisis and self-harm [#crisis-and-self-harm]\n\nA disclosure of risk of harm is never scored silently, never congratulated and never a dead end.\n\n<SafetyCallout severity=\"attention\" evidence=\"opinion\">\n  The organisation must design the response to any item that can elicit a disclosure of risk of harm with clinical mental health expertise, and record it as a specified pathway. Without that expertise, removing the item is the safer course: asking a question the product has no response to is itself a harm.\n</SafetyCallout>\n\n9. **Acknowledge first**, in place, immediately and without alarm, before any score, progress bar or thank-you.\n10. **Plain, warm, unshocked**: no clinical register, alarm, exclamation mark or red.\n11. **Off the escalation ladder.** Calm, prominent and distinct, sharing no `urgent` status, token, colour or icon with a clinical alert.\n12. **Four kinds of route**: someone now, someone later, something to read, and a way to tell a clinician already involved. Say which are open now; keep them reachable later from a quiet, persistent entry point.\n13. **Configured per region and kept current** by the product owner. A wrong or stale number is worse than none.\n14. **Free to continue, leave or say nothing more.** Nothing blocks, traps or compels an answer.\n15. **No gate.** Support sits outside every sign-in, payment and profile-completion gate.\n16. **Safe messaging.** No method detail, lethality information or graphic imagery, and no framing of suicide as a solution or an inevitability.\n17. **Say what happens to the answer**, before the item and on the response: who is contacted, who sees it, what else is triggered.\n18. **Write the repeat case before release**, for a second, fifth and twentieth disclosure: never the same interstitial weekly, never nothing.\n19. **No engagement mechanics**: no streak, badge or reward on a mood questionnaire, completed or abandoned.\n\nThe product owner writes rules 17 and 18 with clinical, information-governance and mental health input.\n\n## Difficult results [#difficult-results]\n\nA result that may distress is disclosed deliberately, under the reader's control, and always ends in a route to a person.\n\n20. Announce an unrequested result before showing it, stating its weight, and open it only by a deliberate action.\n21. No notification opens straight into a full result, and no dashboard opened for something else shows one.\n22. Plain-language summary first, numbers behind a deliberate step, clinical detail behind another. Never reversed.\n23. Say what happens next, who arranges it and how to reach someone. The last element is never the number.\n24. State the finding: \"Your result shows X\", not \"your result requires further discussion\".\n25. Never \"this is very serious\" or \"don't worry\".\n26. Never \"you failed to\", \"your poor control\" or \"you should have\".\n27. Report the result and the next step, nothing about what it means for the reader's life.\n28. Short sentences, ordinary words, one idea each ([Writing](../foundations/writing.mdx)).\n29. Name what the result does not establish.\n30. Give the next step the result's type scale, reachable without scrolling.\n31. No cross-sell, rating prompt, streak or unrelated alert on that screen, under the suppression rules in [Alerts](./alerts.mdx).\n32. The result stays findable in the same words and shareable with someone the reader trusts ([Sharing with a clinician](../patterns/sharing-with-a-clinician.mdx)).\n33. Offer deferral where clinically appropriate, never where delay could cause harm. An emergency finding takes the emergency path instead.\n\n## Components [#components]\n\nNo component implements these paths whole. [AlertBanner](../components/alert-banner.mdx) at `urgent` uses `role=\"alert\"`, never removes itself, and is dismissed only through an `onAcknowledge` callback the product records. No component can see or silence a sibling, so rule 4 is product code with a named owner, tested on every screen reaching the path. [Questionnaire](../components/questionnaire.mdx) has no risk-response slot, so the product owns the pathway and its testing. [ResultCard](../components/result-card.mdx)'s `actions` are optional, so rule 23 is the caller's.\n\n<Todo>\n  Specify the suppression mechanism rule 4 needs: entering the emergency state, handling an alert already announced, and unwinding on acknowledgement.\n</Todo>\n\n<Todo>\n  Specify, with clinical input, what a person who discloses weekly sees on the second, fifth and twentieth occasion.\n</Todo>\n\n<Todo>\n  Find or commission patient-preference research on receiving results without a clinician, then move rules 20 to 33 to \n\n  `evidence: mixed`\n\n  .\n</Todo>\n\n## Evidence [#evidence]\n\nEvery rule here is opinion; no study is cited.\n\nRule 16 follows established practice: the World Health Organization's guidance on responsible communication about suicide and the Samaritans media guidelines. Read them directly; we name them and never paraphrase them, because paraphrase dilutes them. A clinical mental health specialist's written pathway outranks rules 9 to 12 and 18, and regulation outranks this page ([Safety review](./safety-review.mdx))."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/health/numbers",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/health/numbers.md",
      "slug": [
        "health",
        "numbers"
      ],
      "section": "Health",
      "title": "Numbers and units",
      "description": "The canonical rules for precision, rounding, units, unit systems and risk in any health number.",
      "kind": "health",
      "evidence": "mixed",
      "aliases": [],
      "implements": [
        "value",
        "result-card",
        "metric-tile",
        "range-bar",
        "reading-input",
        "score-dial",
        "log-sheet",
        "relative-time",
        "trend-sparkline",
        "goal-ring",
        "scale-input",
        "care-card",
        "disclaimer-note"
      ],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-10-08",
      "markdown": "Every health value is formatted by an explicit rule stating its precision, unit and locale, never by default float rendering. Other pages defer to this one.\n\n## The rules [#the-rules]\n\n### Precision [#precision]\n\n1. Never show more precision than the source carries, not even to align a column.\n2. One metric shows the same number of decimal places everywhere, every time.\n3. Round half away from zero, once, at display. Never round twice, and never before a threshold comparison.\n4. Round derived and estimated values harder than measured ones, and label them as estimates.\n5. Never pad with false zeros. `5` shows as `5`, or `5.0` where the metric has one fixed decimal place, never `5.00`.\n\nPrecision means decimal places, not significant figures, whose decimal places shift with magnitude and break rule 2.\n\n### Units and format [#units-and-format]\n\n6. Never show a value without its unit, including in tooltips, table headers and accessible names.\n7. The unit never wraps away from its number and is never styled as a footnote.\n8. The unit is spoken in words, so `mmHg` is \"millimetres of mercury\".\n9. Decimal and grouping marks come from the reader's locale and are never hand-rolled, because a misread `1,5` becomes `15`.\n10. Composite values stay whole, such as `118/76 mmHg` or a height in feet and inches.\n11. A span takes the word \"to\" and one unit, after the second number: `3.9 to 5.6 mmol/L`, or \"up to 5.6 mmol/L\". No dash joins two numbers.\n12. Zero, none and unknown differ. `0 steps` is a measurement, \"No readings yet\" an absence and \"Not available\" a failure. An absence is words alone, never a glyph, a blank or `0`.\n13. Show negative and out-of-scale values unclamped: \"218 mmHg. That is above the top of this scale.\"\n14. Numerals are digits, even in prose: \"You have 3 readings\".\n15. Numbers in a column or updating in place use tabular figures.\n16. The value is the largest thing in its container.\n\n### Unit systems [#unit-systems]\n\n17. Store one canonical unit per metric and convert once, at display, never round-tripping through storage.\n18. The unit system is the reader's stored preference, per metric family where readers differ, such as kilograms for weight with feet and inches for height.\n19. Locale sets the first default, never the settled answer, so ask once.\n20. Never convert silently. Label a converted value: \"Converted from 98 mg/dL.\"\n21. Ranges, thresholds and statuses convert with the value, and comparisons run on canonical units only.\n22. Round after conversion, at the destination metric's precision. Never re-derive an original from a rounded value.\n23. The unit is part of the entry field, always visible, switchable in place and remembered.\n24. Stones and pounds, or feet and inches, are entered as two inputs, because `11.3` st is 11 st 4 lb and not 11 st 3 lb.\n25. Entry is checked against the entered unit. A figure far from the reader's usual readings prompts a question, never a rejection: \"Is it in mg/dL?\"\n26. Exports, shares and print state the unit unambiguously.\n\nopsinjs ships no factor that depends on the analyte. [ReadingInput](../components/reading-input.mdx) converts only what is exact by definition, such as kg, lb and st, or °C and °F, and refuses mmol/L to mg/dL, mmol/mol to % and kcal to kJ by name. If your product calculates a dose, this page is not enough. Treat a non-SI unit as its own metric.\n\n### Risk [#risk]\n\nState a risk as an absolute frequency, for a stated population, over a stated window, beside its baseline.\n\n27. Never give a relative figure alone. Both absolute figures appear, more prominent than the ratio.\n28. Prefer natural frequencies, \"about 3 in every 100 people\", to percentages, with one denominator across every figure compared.\n29. Always name the population, such as \"people of your age with a similar reading\".\n30. Always state the time window inside the figure, such as \"in the next 10 years\".\n31. Always give the baseline for the group the reader is compared with.\n32. Show both halves: \"about 97 in every 100 do not\".\n33. A bare percentage is never the headline of a tile, a notification or a dial.\n34. A small probability is never an area or an angle. Use a countable array, such as 100 marks with 3 highlighted, plus a text equivalent.\n35. A population figure says it describes a group, not the reader.\n36. A model's output is labelled as one. Its confidence is not the reader's risk.\n\nopsinjs ships no risk models or scores. Whether to show a risk at all is a clinical and ethical decision; see [High-stakes moments](./high-stakes-moments.mdx).\n\n<Todo>\n  Write the screening-statistics guidance: why a positive result on a good test for a rare condition is usually a false positive, and how to say so.\n</Todo>\n\n## In code [#in-code]\n\n[Value](../components/value.mdx) enforces the formatting rules, and its `precision` is required with no default.\n\n```tsx\n<Value value={1000.2} unit=\"kg\" precision={1} />\n```\n\n`value={null}` renders the absence form, never `0`. A missing `unit` raises OPSIN-0003 in development, and `unit={null}` marks a number that has no unit by design. Pass `locale` on any server-rendered surface.\n\n## Evidence [#evidence]\n\n* The systematic review of laboratory-result presentation formats in JMIR, 2024, [10.2196/53993](https://doi.org/10.2196/53993), is cited only for the general claim that presentation format changes what a lay reader takes from a result.\n\nRules 1 to 5 restate significant-figure discipline from measurement science, and enforcing them at the component is our decision. Rules 27, 28 and 32 follow a risk-communication literature on natural frequencies and absolute versus relative risk, which several major medical journals reflect by requiring absolute figures beside relative ones. That literature is named, not cited. Every other rule is opinion, and rule 34 is untested.\n\n<Todo>\n  Replace the described risk-communication literature with specific, read, dated citations.\n</Todo>"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/health/reference-ranges",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/health/reference-ranges.md",
      "slug": [
        "health",
        "reference-ranges"
      ],
      "section": "Health",
      "title": "Reference ranges",
      "description": "What a reference range is, who owns it, how opsinjs draws one and what it refuses to draw.",
      "kind": "health",
      "evidence": "mixed",
      "aliases": [],
      "implements": [
        "range-bar",
        "result-card",
        "metric-tile",
        "value",
        "range-legend",
        "disclaimer-note",
        "score-dial"
      ],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-10-08",
      "markdown": "A reference range is a statistical statement about a population, usually built so that a defined majority of an apparently healthy reference group falls inside it. The laboratory, device maker or clinical team that issued it owns it, for its own assay and population, and ranges differ between laboratories for the same test. A value inside it is not proof of health, and one outside it is not disease.\n\n## The rules [#the-rules]\n\nShow the value, show the range it is compared against, name whose range it is, and never characterise the person.\n\n1. The range is attributed where the comparison is made: \"your laboratory's usual range\", or \"the range this device uses\".\n2. The range is shown, not merely applied. Its endpoints sit beside the value.\n3. A small change near the boundary makes a small change on screen, so \"just outside\" and \"far outside\" can be told apart.\n4. Direction is stated in words, such as \"higher than the usual range\", not only by a dot's position.\n5. Nothing asserts a cause. \"Higher than the usual range\" is an observation, and \"You may be dehydrated\" is a diagnosis.\n6. Only a range built for the reader's population is shown, such as \"usual range for adults over 18\". Where none covers the reader, none is shown.\n7. The raw value and its unit stay visible beside any gauge, bar or dial.\n8. No banned word appears in any string about a person's own result.\n9. With no defensible range, show the value alone and say so. Never invent one from a search result or a textbook.\n10. Never draw a red-to-green gradient without numbers. It asserts a quality scale that ranges do not have.\n11. Being outside a range is not automatically `attention`. Your product assigns the status.\n12. A composite score with no reference interval discloses that its band names are the product's own.\n\n## Banned words [#banned-words]\n\nEach describes the person rather than the measurement, or means something else to a lay reader.\n\n| Banned             | Use instead                                          |\n| ------------------ | ---------------------------------------------------- |\n| normal, abnormal   | \"in the usual range\", \"outside the usual range\"      |\n| healthy, unhealthy | \"in the usual range\", \"higher than the usual range\"  |\n| good, bad          | The direction, \"higher\" or \"lower\"                   |\n| poor, failed       | \"lower than expected\"                                |\n| perfect, optimal   | \"in the usual range\"                                 |\n| positive, negative | Name the finding, \"X was found\" or \"X was not found\" |\n| elevated           | \"higher than\"                                        |\n\n`pnpm check` fails when one of these, or \"just\", \"don't worry\" or \"diagnosis\" from the full list in `tokens/glossary.json`, reaches a shipped component. The lint rule `opsinjs/no-banned-word` is specified and not written, so your own copy is checked in review. Fuller replacements are in the [Plain English A to Z](../reference/plain-english.mdx).\n\n## How opsinjs draws a range [#how-opsinjs-draws-a-range]\n\nopsinjs ships no reference range, and [RangeBar](../components/range-bar.mdx) has no default, no population fallback and no range inferred from the reader's history.\n\n```tsx\n<RangeBar\n  label=\"Example measurement\"\n  value={14}\n  unit=\"mg/dL\"\n  precision={0}\n  locale=\"en-GB\"\n  range={{ low: 10, high: 20, source: \"Example data rather than a reference range\" }}\n/>\n```\n\n* `range.source` is required. A range without one raises OPSIN-0004 and draws nothing, because a plausible band is worse than none.\n* A range with no bounds, or reversed bounds, is discarded entirely.\n* A bar needs two bounds. A one-sided range, such as \"up to 20\", renders the sentence and no bar.\n* An omitted `range.asOf` reads as \"we do not know\", never as today's date.\n* `status` is an input and colours only the tick. RangeBar never turns \"above the range\" into a status, and nothing in it animates.\n* The summary sentence always renders, even when no bar can be drawn.\n\n<RangeDemo label=\"Illustrative only\" unit=\"units\" />\n\nDemonstration values in these docs are placeholders, not reference ranges, and must never be copied into a product.\n\n## Evidence [#evidence]\n\n* The 2024 systematic review of laboratory-result presentation formats in JMIR, [10.2196/53993](https://doi.org/10.2196/53993), examines the formats used to communicate results to patients and their effects on comprehension.\n* The 2018 study in BMC Medical Informatics and Decision Making, [10.1186/s12911-018-0589-7](https://doi.org/10.1186/s12911-018-0589-7), examines patient-portal presentation of results.\n\nBoth anchor the claim that presentation format materially changes what a lay reader takes from a number, and that a bare value beside a reference interval suits a lay reader badly. This page extracts no effect size and no recommendation from either. Both are short and are cited to be read rather than summarised. The banned-word list and rule 3 are opinion, and neither paper backs any single rule."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/health/safety-review",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/health/safety-review.md",
      "slug": [
        "health",
        "safety-review"
      ],
      "section": "Health",
      "title": "Safety review",
      "description": "Pre-ship checklist, regulatory boundary and evidence standard. No screen that displays, interprets or collects health information ships without it.",
      "kind": "health",
      "evidence": "mixed",
      "aliases": [],
      "implements": [
        "result-card",
        "range-bar",
        "status-pill",
        "alert-banner",
        "care-card",
        "value",
        "relative-time",
        "consent-sheet",
        "disclaimer-note",
        "source-citation",
        "dose-tracker",
        "questionnaire",
        "symptom-picker",
        "term"
      ],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-10-08",
      "markdown": "No screen that displays, interprets or collects health information ships without this checklist completed, dated and attributable to a person. Run it before design review and at release, never by the screen's author alone. Passing it is not clinical sign-off: it never checks whether thresholds, ranges or clinical content are correct. Nor does it replace clinical risk management, security, privacy, data protection or usability work, or the independent accessibility and clinical reviews no component has had ([Accessibility](../foundations/accessibility.mdx)).\n\n## Checklist [#checklist]\n\n### Values [#values]\n\n1. Every value shows its unit, adjacent and in its accessible name ([Numbers](./numbers.mdx)).\n2. Precision matches the source, never an unformatted float.\n3. Units follow the reader's stored preference; conversions are labelled.\n4. Zero, absent and failed are distinct; none renders as a number ([Trends](./trends.mdx)).\n5. Out-of-scale values show at magnitude, never clamped to a gauge.\n6. Listed or live-updating numbers use tabular figures.\n\n### Ranges [#ranges]\n\n7. A compared range is shown, naming whose it is ([Reference ranges](./reference-ranges.mdx)).\n8. No string about the reader's result says *normal*, *abnormal*, *healthy*, *good*, *bad*, *poor* or *optimal*.\n9. The range fits this reader's age, sex and other qualifiers, or none is shown.\n10. No surface asserts a cause, diagnosis or prognosis.\n11. Risk figures are absolute, with a population, time window and baseline.\n\n### Status [#status]\n\n12. Status is one of the four levels, used as defined ([Two colour axes](./two-colour-axes.mdx)).\n13. Status carries colour, icon and word, verified in greyscale.\n14. No element takes colour from both category and status namespaces.\n15. Category colour never changes with the value.\n16. At most one `urgent` and two `attention` surfaces per screen ([Alerts](./alerts.mdx)).\n17. Non-clinical messages never use the clinical status palette.\n\n### Trends [#trends]\n\n18. Every value shows when it was measured; staleness shows without a caption.\n19. No trend below the metric's minimum window; gaps drawn as gaps.\n20. Direction and valence are distinct; no coloured arrow asserts an unsupported judgement.\n21. Nothing is extrapolated or projected.\n\n### Provenance [#provenance]\n\n22. Every value's provenance class is recorded and shown in plain words.\n23. No estimated or self-reported value drives a clinical status alone.\n24. No manufacturer accuracy claim is restated as the product's own.\n\n### Escalation [#escalation]\n\n25. No escalation rung is skipped; no fact escalates in parallel.\n26. De-escalation is communicated when a value returns to `steady`.\n27. Any possible emergency finding has a complete emergency path, tested this release ([High-stakes moments](./high-stakes-moments.mdx)).\n28. Any self-harm disclosure question has a clinically reviewed response pathway that always leads somewhere.\n29. A result that may distress is announced first and ends in a route to a person.\n\n### Motion and privacy [#motion-and-privacy]\n\n30. No urgency rides on motion, sound or haptics; nothing flashes; no clinical value animates on reveal.\n31. Every animation has a reduced-motion behaviour that preserves information.\n32. Notifications carry no value or diagnosis and open this screen.\n33. Sensitive values mask without reflow; content is obscured on backgrounding ([Privacy](./consent-and-privacy.mdx)).\n\n### Consent and language [#consent-and-language]\n\n34. Anything collected has a stated purpose, plain-language explanation and revocation where the data appears.\n35. Declining is possible, unpunished and no harder than accepting.\n36. Every clinical term has a plain-English expansion in place.\n37. Copy was read aloud by someone who did not write it.\n\n### Accessibility [#accessibility]\n\n38. Contrast meets the published floor in both themes, measured, not assumed.\n39. Fully keyboard operable, with visible focus and sensible order.\n40. Screen-reader pass done; status changes announced at the right politeness.\n41. Legible and complete at 200% text, no clinical sentence clipped.\n42. Touch targets meet the floor with adequate separation.\n43. Comprehensible in greyscale and under colour-vision simulation.\n\n### Governance [#governance]\n\n44. Every threshold traces to a dated, written clinical rule with a named owner.\n45. Every hazard found is in the hazard log.\n46. Every no is fixed or an accepted exception with a name, reason and review date; every \"not applicable\" has a reason.\n47. Reviewer name and date recorded.\n\n## Regulation [#regulation]\n\nNothing here is legal, regulatory or clinical advice, or a compliance assessment. Before designing surfaces that could trigger a regime, establish with advisers which apply in current form, including HIPAA and accessibility law. Your copy evidences the intended purpose that decides device class.\n\nopsinjs confers, implies and supports no regulatory status, is not a clinical safety case, hazard log or evidence of clinical risk management, and never makes a product a non-device or keeps it one. Cite it as design rationale, not compliance evidence.\n\n## Evidence [#evidence]\n\nNever invent a citation, statistic, date or study; prefer honest opinion. Health pages declare `evidence` in frontmatter. `cited` means an opened source that says what we say: a DOI, a URL or a named published standard. `mixed` marks which sentence is which; the rest is `opinion`. Sources are linked, never pasted or paraphrased.\n\n* Systematic review of laboratory-result presentation formats, JMIR, 2024, DOI [10.2196/53993](https://doi.org/10.2196/53993): format changes what lay readers take away.\n* Presentation of results in patient portals, BMC Medical Informatics and Decision Making, 2018, DOI [10.1186/s12911-018-0589-7](https://doi.org/10.1186/s12911-018-0589-7): the same, for portals.\n* WCAG 2.2, in particular SC 1.4.1 Use of Colour, SC 2.2.2 Pause Stop Hide, SC 2.3.1 Three Flashes, SC 2.3.3 Animation from Interactions and SC 2.5.8 Target Size: checkable requirements, not reader research.\n* APCA and the WCAG 3 draft contrast work: a second contrast measure, not conformance.\n* NHS England information standards DCB0129 and DCB0160, on clinical risk management in the manufacture and in the deployment of health IT: that the obligations exist.\n* Regulation (EU) 2017/745 on medical devices, and the UK medical devices regime: software can be a medical device.\n* The FDA's clinical decision support guidance, and the software provisions of the 21st Century Cures Act: where US consumer health products sit.\n* UK GDPR and EU GDPR special-category provisions: special category; statutory consent requirements.\n* World Health Organization guidance on responsible communication about suicide, and the Samaritans media guidelines: safe-messaging practice outranks a design system.\n* The Joint Commission's Sentinel Event Alert on medical device alarm safety in hospitals (Issue 50), and ECRI's health technology hazards lists: clinical alarm fatigue is documented; app transfer is opinion.\n* The NHS Digital Service Manual: a comparison point; Crown copyright, never copied.\n* Apple's Human Interface Guidelines: platform behaviour, checked, not restated.\n\n<Todo>\n  Generate this register from page frontmatter, not by hand.\n</Todo>\n\nThe checklist is opinion; the evidence standard is policy. That design rationale can feed a safety case is opinion no clinical safety officer has assessed."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/health/trends",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/health/trends.md",
      "slug": [
        "health",
        "trends"
      ],
      "section": "Health",
      "title": "Trends and uncertainty",
      "description": "What a screen may say about change over time, about old, estimated or missing values, and about where a number came from.",
      "kind": "health",
      "evidence": "opinion",
      "aliases": [],
      "implements": [
        "trend-sparkline",
        "metric-tile",
        "result-card",
        "relative-time",
        "status-pill",
        "timeline-entry",
        "value",
        "skeleton",
        "empty-state",
        "disclaimer-note",
        "reading-input",
        "dose-tracker",
        "source-citation"
      ],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-10-08",
      "markdown": "opsinjs publishes no minimum window, change threshold, freshness window or accuracy figure for any metric. The metric's clinical owner supplies each one.\n\n## Trends [#trends]\n\n1. Direction (up, down, unchanged) is arithmetic. Valence (better, worse) is a clinical judgement about one metric for one person, often unavailable. Keep them apart.\n2. Where no valence is defined, show direction only: no colour, status or adjective on the arrow.\n3. Draw no trend below the metric's declared minimum window. Two readings give a difference, not a direction.\n4. Below the metric's declared change threshold, say no change: \"About the same as your average over the last 4 weeks.\"\n5. Name the baseline and window on screen, never a bare delta.\n6. Plot readings at their real times, show gaps, and never truncate the axis to steepen a slope ([Data visualisation](../foundations/data-visualisation.mdx)).\n7. A trend never sets a status. Status comes from the latest value against its range, so rising inside the usual range is not `attention`.\n8. Never extrapolate: no projected line, no \"at this rate\", no predicted value.\n9. Every chart has a text twin stating the same baseline, window and direction.\n10. Draw missing readings as missing, never interpolated or plotted as zero: \"No readings between 3 and 17 March.\"\n11. A smoothed series keeps its raw points visible.\n\nThe product owns the baseline and the sentence. The screen is [Trend review](../patterns/trend-review.mdx).\n\n## Staleness and missing data [#staleness-and-missing-data]\n\nA value is fresh, stale, partial, estimated or absent ([States](../foundations/states.mdx)), and the reader must be able to tell which.\n\n12. Every value has a timestamp: relative for recency, absolute on demand.\n13. Each metric declares its own freshness window; none is defaulted.\n14. Staleness is shown by de-emphasising the value itself, not only in a caption.\n15. A stale value shows its age and a way to refresh, neither at full weight nor withheld.\n16. An estimate is labelled at the number with its source and rounded more coarsely ([Numbers and units](./numbers.mdx)): \"Estimated from your watch. Roughly 7 hours 30 minutes.\"\n17. A failed fetch and an empty history get different sentences and next actions. Neither is ever rendered as a number.\n18. A loading placeholder implies no value: no plausible number, chart shape or status colour.\n19. Status degrades with certainty. Check it first: a value of unestablished recency, completeness or provenance never drives `attention` or `urgent`.\n20. State a partial result; never average over the gap: \"3 of your 4 devices have reported today.\"\n21. Offline is a state of its own: say the device is offline rather than showing last values as current ([Offline and stale data](../patterns/offline-and-stale-data.mdx)).\n\nYour data layer supplies each reading's time, marks estimates, separates failure from absence and names the reporting sources.\n\n<Todo>\n  Specify the presentation of an explicit uncertainty interval: a measured value with a stated error bound, in text and in a chart.\n</Todo>\n\n## Provenance [#provenance]\n\nEach class bounds what the interface may assert:\n\n* **Clinically measured** (a laboratory result): compare against an attributed range and carry a status.\n* **Device measured** (a validated home cuff, a scale): compare against a range where the device's method supports it, and carry a status where a clinical rule says so.\n* **Device estimated** (optical heart rate in motion, sleep stages): show as an estimate and as trends, never with a clinical status on its own.\n* **Self-reported** (a typed weight, a remembered dose): record and display as reported, never as measured.\n\n22. Record provenance at capture; it travels with the value, never reconstructed or defaulted.\n23. Show it in plain words at the value and in its accessible name: \"from your cuff\", \"estimated by your watch\", \"you entered this\".\n24. Status is bounded by class. An estimate never escalates on its own, so a wrist reading taken mid-run raises no cardiac alert, and may prompt a cuff reading instead.\n25. Never combine classes in one figure, such as a weekly average, without saying so.\n26. Name the device (\"your Model X cuff\"), never marketing (\"clinically validated technology\").\n27. Attribute and link a manufacturer's accuracy claim. Never restate it as the product's own, strengthen it, or invent a figure.\n28. State once, at the number, what the device does not do: a wrist sensor does not measure blood pressure.\n29. Label a model output as one, with its inputs.\n30. Never silently correct self-reported data. Query an implausible entry with the reader.\n31. Exports carry provenance ([Sharing with a clinician](../patterns/sharing-with-a-clinician.mdx)).\n\n## Components [#components]\n\n[TrendSparkline](../components/trend-sparkline.mdx) requires `minimumPoints`, and below it draws nothing and says so. `changeThreshold` has no default, and without it the caption names no direction. A gap is an explicit `value: null`. [RelativeTime](../components/relative-time.mdx) has no staleness default; `staleAfterHours` adds the stale words and muted treatment. [Value](../components/value.mdx) renders `null` as an absence, never `0`.\n\nNo component carries a provenance class, so rules 22 to 31 are the caller's. [ResultCard](../components/result-card.mdx) takes provenance as free text, so never pass it a `status` derived from an estimate or a self-report. [MetricTile](../components/metric-tile.mdx)'s `event` defaults to `measured`, unchecked against how the figure was obtained. [SourceCitation](../components/source-citation.mdx) renders provenance beside a value, not in its accessible name, and checks nothing.\n\n<Todo>\n  Specify the four provenance classes as a shared type and a prop on every component that renders a health value, so that rule 24 is enforced rather than reviewed.\n</Todo>\n\n## Evidence [#evidence]\n\nEvery rule here is opinion; no study is cited. Rules 3 and 4 follow from measurement variability. The four classes are our model, coarse so a non-expert can assign them.\n\nTake any accuracy claim from the manufacturer's current documentation or a study you have read. Differences in optical sensing across skin tones are discussed in research and by regulators. We give no figure or citation: ask your supplier, and apply rule 28."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/health/two-colour-axes",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/health/two-colour-axes.md",
      "slug": [
        "health",
        "two-colour-axes"
      ],
      "section": "Health",
      "title": "Two colour axes",
      "description": "Category colour says what a measurement is about and status colour says how urgent it is. They never meet on one element.",
      "kind": "health",
      "evidence": "mixed",
      "aliases": [
        "status levels",
        "category colour"
      ],
      "implements": [
        "status-pill",
        "alert-banner",
        "range-bar",
        "result-card",
        "care-card",
        "metric-tile",
        "score-dial",
        "trend-sparkline",
        "range-legend",
        "body-map",
        "goal-ring",
        "card",
        "surface"
      ],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-10-08",
      "markdown": "Identity lets a reader find the sleep tile at a glance, and status says whether its reading needs anything. Each axis has its own palette and its own token namespace.\n\n## The rules [#the-rules]\n\n### Axes [#axes]\n\n1. No element is tinted by both axes or resolves a colour from both `--opsin-category-*` and `--opsin-status-*`. A card may have a category-tinted header and a status-tinted badge, but never a blend.\n2. A category colour never changes with a value or a status, and a status colour never changes hue with a category.\n3. Status is never expressed by colour alone. Every status carries a colour, an icon and a word together, and an element that drops the icon or the word has dropped the status.\n4. Motion, sound and haptics never carry a level on their own.\n\n### Status [#status]\n\n5. There are exactly four levels. They are ordinal and their meanings are fixed. `unknown` is the absence of an assertion, not a fifth level, and is never coloured near `watch`.\n6. The level's word appears in full on every status surface and in its accessible name, never as the token name.\n7. One element carries one level. A container never inherits its children's highest status by default.\n8. A change of level is stated in words, saying that it changed and why.\n9. A status change is announced to assistive technology politely, and assertively only at `urgent`.\n10. `urgent` is reserved for clinical urgency and never carries a product's own problem. Informational messages go in [Callout](../components/callout.mdx), which has no `status`, `severity` or `color` prop.\n11. The levels are not a triage scale and are never mapped onto one. No level asserts a condition.\n\n### Category [#category]\n\n12. A category colour identifies a family. It never expresses value, quality, severity, direction, urgency or brand.\n13. A category colour is never the only cue. Every category-coloured element names the family in text.\n14. A category namespace never gains a role that carries a verdict, such as `--opsin-category-heart-danger`.\n15. A category colour is never a brand accent or a chart series colour. Series use the ramps in [Data visualisation](../foundations/data-visualisation.mdx).\n16. One metric takes one category on every surface in the product.\n\n<StatusAxisDemo />\n\n## Status levels [#status-levels]\n\n<CvdSimulator>\n  <StatusLadder />\n</CvdSimulator>\n\n| Level       | Word and icon            | Asserts, and its tone                                                                                                                        | Never means                                                                               |\n| ----------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |\n| `steady`    | Steady, Circle           | Inside the range set for this reader. Neutral, never congratulatory                                                                          | Healthy, safe, normal, good, \"you are fine\"                                               |\n| `watch`     | Watch, CircleDot         | Slightly outside the usual range, or moving in a direction worth noticing. Informative, and says what happens next or that nothing is needed | A mild diagnosis, or a hint to act without saying how                                     |\n| `attention` | Needs attention, Diamond | Someone qualified should look, reasonably soon. Direct and calm, with one named action first, and incomplete without it                      | An emergency, a diagnosis, \"you have X\"                                                   |\n| `urgent`    | Urgent, Octagon          | The value may need help today. Short and unambiguous, with the action in the first line                                                      | Anything merely important to the product, such as an expiring trial or an unsynced device |\n| `unknown`   | Not known, Minus         | Nothing. No reading, a stale one, or a range the product does not own                                                                        | \"Probably fine\"                                                                           |\n\nYour clinically accountable role assigns every level, and opsinjs ships no threshold for any metric, in any population, ever. `steady` and `watch` come from a reference range your product owns, `attention` from a clinically reviewed threshold, and `urgent` from one with a named clinical owner. Each traces to a rule written down outside the component with its source, owner and population. Use a device's or laboratory's own flag where one exists and say whose it is, and label a model's output as an estimate.\n\n## Category identity [#category-identity]\n\n| Category  | Covers                                                                           |\n| --------- | -------------------------------------------------------------------------------- |\n| Heart     | Blood pressure, heart rate, resting heart rate, rhythm, variability, circulation |\n| Activity  | Steps, workouts, active minutes, movement, energy expenditure                    |\n| Sleep     | Duration, timing, consistency, disturbance, sleep-derived recovery               |\n| Nutrition | Intake, hydration, glucose, cholesterol, weight, body composition                |\n| Mind      | Mood, stress, cognition, wellbeing check-ins                                     |\n| Labs      | Test results, panels, assays, anything a laboratory reports                      |\n\nA result's interpretation is status, never Labs. Where a metric fits two families, as weight and glucose do, your product picks one and opsinjs does not adjudicate. Symptoms, medications and appointments take no category colour. There is no Cycle category, and adding a seventh is a design-system decision shown in [Theming](../theming.mdx).\n\n## Tokens [#tokens]\n\nBoth axes expose four roles, under `--opsin-category-<name>-*` and `--opsin-status-<level>-*`: `-surface` for the ground, `-line` for strokes and badge edges, `-ink` for text and meaningful icons, and `-accent` for identity fills and chart marks. Only `-ink` carries text, and text on a `-surface` is always the matching `-ink`. A bare `bg-status-urgent` resolves to the **line** and a bare `bg-category-heart` to the **accent**, so spell every other role out. Contrast floors are in [Colour](../foundations/colour.mdx).\n\n## Enforcement [#enforcement]\n\n* The two namespaces are disjoint, so a mixed colour has to be assembled by hand.\n* A component that takes a `status` takes no `category` for the same painted surface.\n* Every component that accepts a status, [StatusPill](../components/status-pill.mdx) included, takes it from the exported `ClinicalStatus` union in [Types](../reference/generated/types.mdx), so an invalid level is a type error.\n* `scripts/check-contrast.mts` projects both axes through protanopia, deuteranopia, tritanopia and greyscale, and lists every collapsing pair in [Contrast](../reference/generated/contrast.mdx).\n* The lint rule `opsinjs/no-mixed-axes` is specified and not written, so a mixed axis on a hand-written surface is caught in review or not at all.\n\n## Evidence [#evidence]\n\n* WCAG 2.2 success criterion 1.4.1 (Use of Colour), with the requirement that information is not conveyed through a single sensory characteristic, is the basis for rules 3 and 4.\n* The ARIA live-region model is the basis for rule 9, because an assertive announcement interrupts.\n\nEverything else is opinion, including the two axes, the six categories and the four levels. No study comparing a two-axis palette with a merged one is cited, and the recognition speed category colour is kept for is unmeasured."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/patterns",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/patterns.md",
      "slug": [
        "patterns"
      ],
      "section": "Patterns",
      "title": "Patterns",
      "description": "Multi-screen sequences a health product keeps rebuilding, each followed from entry to exit with its components, copy and failure cases",
      "kind": "pattern",
      "aliases": [
        "pattern library",
        "user flows",
        "multi-screen sequences"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "A pattern is one user task followed across the screens it takes: the sequence, its states, the components it is built from and where the person can leave. A component page covers one part. A pattern covers the second screen, where the result arrives or validation fires. Patterns apply the rules in [Health](../health/index.mdx) rather than restating them.\n\n## The patterns [#the-patterns]\n\n| Pattern                                                    | Use it for                                                                                   |\n| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------- |\n| [Result disclosure](./result-disclosure.mdx)               | Showing a result the reader may not want to see, from notification to number to next step    |\n| [Daily logging](./daily-logging.mdx)                       | Repeated entry of the same reading, designed for the ninetieth entry rather than the first   |\n| [Trend review](./trend-review.mdx)                         | Reading change over time without over-interpreting noise                                     |\n| [Alert escalation](./alert-escalation.mdx)                 | Moving a message from ambient to interruptive only as far as it has earned                   |\n| [Onboarding and first run](./onboarding-and-first-run.mdx) | Collecting the minimum before the reader has seen anything about them                        |\n| [Consent and permissions](./consent-and-permissions.mdx)   | Asking for access when it is needed, and making withdrawal as easy as agreement              |\n| [Empty and first use](./empty-and-first-use.mdx)           | The surface before there is anything to show, and which kind of nothing it is                |\n| [Offline and stale data](./offline-and-stale-data.mdx)     | What a screen shows when it cannot vouch for its numbers                                     |\n| [Sharing with a clinician](./sharing-with-a-clinician.mdx) | Exports and summaries a clinician can read in ninety seconds, with no interpretation implied |\n| [Forms](./forms.mdx)                                       | How a question behaves: questions per page, when validation fires, where errors go           |\n| [Ask users for…](./ask-users-for.mdx)                      | One kind of detail at a time, such as a name, a date of birth or a list of medicines         |\n\n## The joins between screens [#the-joins-between-screens]\n\nEvery screen can pass its own audit while the journey fails, because the failures live in the joins.\n\n* **Focus across a transition.** When a step replaces the last one, focus lands on the new heading.\n* **Announcing change.** A value that updates in place is a status message (WCAG 2.2 SC 4.1.3).\n* **Recovery.** Going back a step keeps what the person typed (WCAG 2.2 SC 3.3.7).\n* **Leaving.** Every pattern states where the exit is.\n\n## What is built [#what-is-built]\n\nA pattern carries no `status`. Every component it names is shipped, which means it installs and renders. None has had an independent accessibility review or any clinical review, so nothing here is for a production health surface. A page whose sequence nobody has assembled carries a not-built marker. Three screen specimens render today: the results screen, the medicines app and the patient record portal. The daily log, trends, consent and onboarding screens are still specifications.\n\n## Whole-app specimens [#whole-app-specimens]\n\n[/showcase](/showcase) holds the whole screens opsinjs has built from its own components: the results screen above, the [diabetes medicines app](/showcase/diabetes-medicines-app) and the [patient record portal](/showcase/patient-record-portal). Each opens on its own at `/showcase/<slug>`, with nothing round it but a bar in the top right corner that leads back to the showcase and switches between light and dark and between phone, tablet and desktop sizes.\n\nThe medicines app has four destinations, five overlays and a working form built from thirty-five shipped components. It calculates no dose, changes no dose, never marks a dose as missed and stores nothing.\n\nThe portal is a patient's view of the record their hospitals write, built from twenty-four shipped components: five destinations, a share a doctor opens once, and an emergency card with no navigation on it. It shows what doctors wrote and explains none of it, changes nothing medical, keeps every control it cannot offer on screen with the reason beside it, and stores nothing. Its layout switches on the width of the app in rem, so a phone gets TabBar, a desktop window gets a sidebar and two columns, and 200% text gets the narrower layout it needs. Below 19rem the five destinations move into a menu sheet, because TabBar cannot fit them there ([#16](https://github.com/prashantonomy/opsinjs/issues/16)).\n\nNeither composition has had a clinical safety review, so do not ship either to readers. Copy their refusals."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/patterns/alert-escalation",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/patterns/alert-escalation.md",
      "slug": [
        "patterns",
        "alert-escalation"
      ],
      "section": "Patterns",
      "title": "Alert escalation",
      "description": "Moving a message from ambient to interruptive only as far as it has earned, with a budget per screen and an announced de-escalation",
      "kind": "pattern",
      "aliases": [
        "escalation ladder",
        "interruptive alerts",
        "alert budget",
        "when to interrupt"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "The unit of design is the ladder rather than the alert. It has four surfaces of rising cost, and rules for which one a message may occupy. opsinjs never decides that something is urgent. A clinical rule your product owns assigns the level.\n\n## When to use it [#when-to-use-it]\n\nUse it when the product says something the reader did not ask for and several things could claim their attention. Use something else for:\n\n* a result that is the whole screen's purpose: [Result disclosure](./result-disclosure.mdx);\n* an emergency, which is never a banner: [High-stakes moments](../health/high-stakes-moments.mdx);\n* information with nothing to do, or a system fault: a [Callout](../components/callout.mdx), off the status axis;\n* a commercial prompt, which belongs on no rung.\n\n## How it works [#how-it-works]\n\nA message enters at the lowest rung that can do its job and climbs only on a written trigger, such as \"three days and the section is still unopened\".\n\n1. **Ambient.** A [StatusPill](../components/status-pill.mdx) on the [MetricTile](../components/metric-tile.mdx). Most status belongs here.\n2. **In-context.** An [AlertBanner](../components/alert-banner.mdx) above the content it concerns, in normal flow, covering nothing.\n3. **Top of screen.** A persistent [CareCard](../components/care-card.mdx) above the fold, with a named action and owner.\n4. **Interruptive.** A [Dialog](../components/dialog.mdx) or [Sheet](../components/sheet.mdx) that must be answered, only for information whose absence would cause harm before the next likely session.\n\nThe assigned level caps the rung. `steady` and `watch` stay ambient. `attention` reaches a banner with the action inside it. `urgent` adds a CareCard with the action and its timing, and interrupts only where a documented rule requires it.\n\n### The budget [#the-budget]\n\n* One urgent surface per screen, and at most two banners. A second urgent message is merged with the first, demoted or moved to its own screen, never stacked.\n* Interruption is metered per session, not per event.\n* Two messages at one rung are ranked by clinical consequence, never by recency.\n* Repetition is suppressed by identity and state, never by count. No rung is a toast.\n\n### Dismissal and clearing [#dismissal-and-clearing]\n\n* An alert at `attention` or above carries one specific primary action, listed first: \"Call your clinic\", never \"Learn more\". Without one, it is information.\n* Decide per rung whether dismissal lasts for the session, until the value changes, or for good. Dismissing never resolves the underlying state, and an interruptive surface closes only on an answer.\n* Say when a condition clears. An alert that silently disappears teaches the reader that alerts were never real.\n* Stale data degrades an alert to [Offline and stale data](./offline-and-stale-data.mdx) rather than letting it assert a current fact.\n\n<NotBuiltYet />\n\n## Components [#components]\n\n* [StatusPill](../components/status-pill.mdx): rung 1.\n* [AlertBanner](../components/alert-banner.mdx): rung 2, with no category colour and no transition.\n* [CareCard](../components/care-card.mdx): rung 3.\n* [Dialog](../components/dialog.mdx) and [Sheet](../components/sheet.mdx): rung 4. On Dialog, `severity=\"alert\"` removes the close control and stops <Kbd>Escape</Kbd> and the scrim from closing it.\n* [Callout](../components/callout.mdx): information, off the ladder.\n\n## Escalate in stages [#escalate-in-stages]\n\n```tsx\nimport { AlertBanner } from \"@/components/ui/alert-banner\"\n\n<AlertBanner\n  status=\"urgent\"\n  heading=\"Your example measurement needs someone to look at it today\"\n  detectedAt=\"2026-03-14T10:55:00+00:00\"\n  dismissible\n  onAcknowledge={() => setAcknowledged(true)}\n  dismissLabel=\"I have read this\"\n  actions={[{ label: \"Call your clinic\", href: \"#example-clinic\" }]}\n>\n  Call your clinic today. This reading is outside the range they asked\n  us to tell you about. Your clinic has not been contacted for you.\n</AlertBanner>\n```\n\n`dismissible` needs `onAcknowledge`, which at `urgent` is your record of who saw the banner and when. Removing the banner drops focus to `<body>`, which the product must recover. To clear an alert, render a `steady` banner that says so.\n\n## Content [#content]\n\nState the fact in the reader's words, then the action and its timing, then the boundary if your rule requires one. The higher the rung, the shorter the sentence and the more specific the action. Never carry severity with capitals, exclamation marks or emoji.\n\n## Accessibility [#accessibility]\n\n* A new alert on the current screen is a status message (WCAG 2.2 SC 4.1.3). Rungs 1 to 3 announce politely and never move focus.\n* Rung 4 takes and traps focus. If <Kbd>Escape</Kbd> is disabled, announce why.\n* AlertBanner mounts no live region at `steady` or `watch`, so announcing a de-escalation is yours.\n* Nothing pulses or flashes, and every rung reads in greyscale by position, icon and wording."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/patterns/ask-users-for",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/patterns/ask-users-for.md",
      "slug": [
        "patterns",
        "ask-users-for"
      ],
      "section": "Patterns",
      "title": "Ask users for…",
      "description": "What to ask, how to ask it and which component to use for the personal details a health product collects.",
      "kind": "pattern",
      "aliases": [
        "asking for personal data",
        "what to collect",
        "data collection patterns",
        "field-level guidance"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "The cheapest field is the one you do not collect, and the next cheapest is a coarser one, such as an age band rather than a birth date.\n\n## When to use it [#when-to-use-it]\n\nUse it before adding any field below. For how forms behave, see [Forms](./forms.mdx), and for when to ask, [Onboarding and first run](./onboarding-and-first-run.mdx). For wording, see [Writing](../foundations/writing.mdx).\n\nDo not use it for a daily reading, which is [Daily logging](./daily-logging.mdx). Nothing here is legal advice.\n\n## How it works [#how-it-works]\n\n1. Name the decision the answer changes. If you cannot, do not ask.\n2. Ask for the coarsest answer that decides it, and defer to the surface that needs it where you can.\n3. Say why in one sentence beside the question. \"A more personalised experience\" is not a reason.\n4. Say what skipping costs, and offer free text where a fixed list will not fit.\n5. Never ask again for something already given (WCAG 2.2 SC 3.3.7). Let the reader edit it instead.\n\n## Components [#components]\n\n* [Field](../components/field.mdx) holds every typed answer, with its label, hint and error.\n* [ReadingInput](../components/reading-input.mdx) takes height and weight with the unit beside the number.\n* [RadioGroup](../components/radio-group.mdx) takes one answer from a short list, and [Checkbox](../components/checkbox.mdx) any number.\n* [Combobox](../components/combobox.mdx) searches a list the product supplies.\n* [Term](../components/term.mdx) explains any clinical or administrative word.\n\n## Name [#name]\n\nAsk for what the reader wants to be called, to address them. Ask for the name a clinic or insurer holds only to match a record, and say so.\n\n* Use one free-text Field with `autocomplete=\"name\"`. Split into `given-name` and `family-name` only when a receiving system demands parts, and never require a family name.\n* Do not limit length or characters, change capitalisation, or trim more than the outer spaces.\n* Address the reader by their preferred name everywhere. Use the record name only where a system requires it, and say so.\n* An empty field gets \"Enter your name\", never \"invalid name\".\n\n## Date of birth [#date-of-birth]\n\nAsk for an age band unless a decision needs the exact date, such as matching a clinical record. To check that someone is an adult, ask exactly that.\n\n* Use three Fields, Day, Month and Year, in the reader's locale order, inside a `fieldset` whose `legend` is the question.\n* Give each `inputmode=\"numeric\"` and `autocomplete` of `bday-day`, `bday-month` or `bday-year`. Accept a month name, and require four-digit years.\n* Never use a calendar picker as the only path, and never auto-advance between boxes.\n* An error names the missing part and clears nothing. If your system accepts a year alone, say so.\n\n## Sex and gender [#sex-and-gender]\n\nThese are two questions, or none. Ask sex only when a reference range, screening or calculation depends on it, and prefer the specific clinical question, such as whether the reader has periods. Ask gender or pronouns only to address the reader.\n\n* Ask it with a RadioGroup labelled for its purpose: \"Sex used for reference ranges\".\n* Never offer a closed list of two. Include intersex and \"prefer not to say\", and a route to a person.\n* Take pronouns as free text with common options in a Field.\n* Never derive one answer from the other, and keep both editable at any time.\n\n## Ethnicity [#ethnicity]\n\nAsk only for equity monitoring with an analysis plan, or for a clinical adjustment a named clinician owns. If you cannot name which, do not ask. Never ask on a results screen or in a symptom flow.\n\n* Make it optional, self-identified and multi-select, with \"prefer not to say\" and free text. Use Checkboxes in a `fieldset`.\n* Use a recognised national classification and name it. Never infer ethnicity from a name or a postcode.\n* If it adjusts a number, the reader sees the adjustment and who owns it.\n\n## Contact details [#contact-details]\n\nAsk for a channel only when you have a message to send on it. A message is a disclosure, because it may arrive on a lock screen somebody else can see.\n\n* One channel per purpose, chosen by the reader. Use `type=\"email\"` with `autocomplete=\"email\"`, or `type=\"tel\"` with `autocomplete=\"tel\"`.\n* Verify before relying on a channel, without locking the reader out. A code field takes `autocomplete=\"one-time-code\"`, and paste works.\n* The message says only that there is something to see, never the substance.\n* Check an email for an `@` and let delivery test the rest. Store phone numbers as entered.\n\n## Height and weight [#height-and-weight]\n\nAsk only when a named calculation needs it, and ask adult height once. Weight is a hard question for some readers, so never require it unless that calculation cannot run without it.\n\n* Use ReadingInput with `units={[\"kg\", \"lb\", \"st\"]}`, so switching converts what was typed.\n* Compound units such as feet and inches take separate boxes under one legend.\n* Bounds are physical, never typical. No praise, comparison or target the reader did not set.\n* If you derive BMI, show its limits beside it, never show its category as a clinical status, and let the reader turn it off. If you cannot do all three, do not derive it.\n\n## Medications [#medications]\n\nAsk only when the product does something specific with them. A self-entered list is what the reader believes they take, never a clinical record, and opsinjs does not support interaction checking against it.\n\n* Search, do not spell. Use a Combobox over the product's own list, matching brand and generic names, because opsinjs ships no vocabulary.\n* Keep a free-text Field always available. Never auto-select a result or autocorrect a name.\n* Take strength as a number and a unit separately, then form and schedule in the reader's words.\n* Show a read-back before storing, mark every entry self-reported or imported, and keep a stopped medicine with its dates.\n\n## Symptoms [#symptoms]\n\nRecord symptoms, never assess them, because assessment is a regulated clinical function opsinjs does not support. A symptom that needs action now, or any question that touches self-harm, belongs to [High-stakes moments](../health/high-stakes-moments.mdx).\n\n* Put a [Textarea](../components/textarea.mdx) first and largest, inside a Field. [SymptomPicker](../components/symptom-picker.mdx), [BodyMap](../components/body-map.mdx) beside a checkbox list, and [ScaleInput](../components/scale-input.mdx) with written anchors are optional assists.\n* Ask duration in relative words: \"since this morning\".\n* A red-flag rule signposts help and never diagnoses, and the entry is saved either way.\n* Show the entry back word for word, with no status colour."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/patterns/consent-and-permissions",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/patterns/consent-and-permissions.md",
      "slug": [
        "patterns",
        "consent-and-permissions"
      ],
      "section": "Patterns",
      "title": "Consent and permissions",
      "description": "Ask for one permission at the moment it is needed, record what was agreed, and make refusing and withdrawing as easy as agreeing.",
      "kind": "pattern",
      "aliases": [
        "permission priming",
        "asking for consent",
        "permission prompt sequence",
        "revoking access",
        "data sharing prompt"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "Consent is specific, informed, freely given, and withdrawable as easily as it was granted. A prompt that hides withdrawal in a settings sub-page is a subscription, not consent. [Consent and privacy](../health/consent-and-privacy.mdx) holds the doctrine.\n\n## When to use it [#when-to-use-it]\n\nUse it whenever the product wants something it cannot take: health data from the device, notifications, sharing a record with a clinician, or a secondary use such as research.\n\nDo not use it when:\n\n* The screen cannot exist without the permission. Say what it needs and let the reader leave, because a prompt with one real option is not a choice.\n* You are telling the reader what you already hold. That is [Result disclosure](./result-disclosure.mdx).\n* It is a legal notice with no choice. Accepting terms is not consent to processing.\n* A question could disclose self-harm, abuse or a diagnosis. That is a distinct flow. See [High-stakes moments](../health/high-stakes-moments.mdx).\n\n<Todo>\n  A pattern for disclosure inside a questionnaire and for crisis signposting. It needs clinical review, not only design.\n</Todo>\n\n## How it works [#how-it-works]\n\n1. Ask at the moment of need, from the surface that needs it. Never ask at first launch.\n2. Explain in your own sheet first: what is collected, what it is for, who else sees it, how long it is kept, and what still works without it.\n3. Trigger the operating system's dialog only after the reader agrees to yours, because most platforms cannot re-ask after a refusal. Never style your sheet to look like that dialog.\n4. Ask one scope per sheet, with nothing pre-ticked. Three permissions are three sheets, each asked when it becomes useful.\n5. Record what was granted, when, by whom, and which version of the wording the reader saw.\n6. Deliver what the grant bought at once. After a refusal, keep the degraded but working surface, and re-offer only where it is needed.\n7. Put withdrawal at the same depth as agreement. It takes effect immediately and says what happens to data already shared, because revoked and deleted are different.\n\nRe-ask when the scope or the wording changes, never on a timer.\n\n## Components [#components]\n\n* [ConsentSheet](../components/consent-sheet.mdx) asks one question, with refusing exactly as easy as agreeing.\n* [Sheet](../components/sheet.mdx) is the surface ConsentSheet extends.\n* [Term](../components/term.mdx) explains any legal or clinical word inline.\n* [DisclaimerNote](../components/disclaimer-note.mdx) says what this consent does not cover.\n* [EmptyState](../components/empty-state.mdx) is the declined outcome, saying what still works and the way back.\n\n## Ask before collecting [#ask-before-collecting]\n\n```tsx\nimport { ConsentSheet } from \"@/components/ui/consent-sheet\"\n```\n\n```tsx\n<ConsentSheet\n  open={open}\n  onOpenChange={setOpen}\n  consentId=\"example-consent\"\n  textVersion={copy.version}\n  heading={copy.question}\n  purpose={copy.purpose}\n  scope={copy.scope}\n  withdrawalPath={copy.withdrawal}\n  acceptLabel={copy.accept}\n  declineLabel={copy.decline}\n  onDecision={store}\n/>\n```\n\n* opsinjs ships no consent wording. Every string is a prop, and `scope` takes three sentences: `collected`, `sharedWith` and `retention`.\n* If any required string is missing or blank, the sheet refuses to ask and draws no controls.\n* `onDecision` fires only when a control is pressed. Escape, the scrim, a drag or Close call nothing, so a dismissal is never stored as an answer.\n* Store the `ConsentDecision` it returns: `granted`, `at`, `consentId`, `textVersion` and `scope`.\n* Pass `consequenceOfDeclining` whenever refusing costs the reader something.\n\n<ComponentPreview name=\"consent-sheet-two-questions-two-sheets\" kind=\"example\" align=\"start\" />\n\n## Example [#example]\n\n<IframePreview kind=\"screen\" name=\"consent-flow\" />\n\nThe whole-screen flow is not built yet, so the frame shows only its placeholder. The ConsentSheet example above is the shipped specimen.\n\n## Content [#content]\n\n* Describe the consequence, not the mechanism: who can see what, for how long, and how to stop it. \"Enable data sharing to unlock the full experience\" says none of that.\n* Both labels name an outcome. Never label the decline control \"not now\" when it means no. ConsentSheet warns about it in development.\n* Never make refusal sound reckless, and never write \"by continuing you agree\".\n\n## Accessibility [#accessibility]\n\n* The explanation precedes the two controls in the DOM, so a screen reader meets the question first.\n* Both answers are one component used twice: the same size, contrast and target, adjacent in the tab order. Check in greyscale, and at 200% text, where both must stay visible together.\n* Focus enters the sheet, <Kbd>Escape</Kbd> closes it with no answer given, and focus returns to the opener.\n* Nothing times out, auto-advances or dismisses itself."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/patterns/daily-logging",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/patterns/daily-logging.md",
      "slug": [
        "patterns",
        "daily-logging"
      ],
      "section": "Patterns",
      "title": "Daily logging",
      "description": "Repeated entry designed for the ninetieth entry rather than the first, where every saved second compounds and every extra field costs adherence",
      "kind": "pattern",
      "aliases": [
        "logging a reading",
        "repeated entry",
        "diary entry",
        "tracking flow",
        "quick add"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "The same person records the same thing for months, such as a blood pressure reading each morning or a dose taken. The target is three taps from the screen they are on: open, enter, save.\n\n## When to use it [#when-to-use-it]\n\nUse it when the reader knows what the fields mean, most entries resemble the last one, and a missed day is expected rather than an error. Use something else for:\n\n* the first entry, which has to teach units: [Onboarding and first run](./onboarding-and-first-run.mdx);\n* a validated questionnaire, whose item order is fixed: [Questionnaire](../components/questionnaire.mdx);\n* values a device syncs: [Offline and stale data](./offline-and-stale-data.mdx);\n* correcting history, which deserves a slower flow.\n\n## How it works [#how-it-works]\n\n1. **Start where the person is.** The log action sits on the metric's tile or detail screen as one target, at least 44pt, in the lower third.\n2. **Open a sheet, not a screen.** The field is focused with the right keyboard (`inputmode=\"decimal\"` for a number), and the context stays visible behind it.\n3. **Default the time, unit and metric.** The time is now and editable, and the unit is the last one used. Never pre-fill the measurement, because that is how a log fills with numbers nobody measured.\n4. **Warn, never block.** A surprising value gets a question and still saves, because a real reading outside your expected span matters most.\n5. **Confirm in place.** The entry appears where it will live, with undo. No \"Saved!\" dialog, no detour to a trends screen, and no streak or praise for a body reading.\n6. **Draw gaps as gaps.** A missed day is never interpolated, carried forward or styled as a status.\n\nDecide per metric whether a second entry for one slot replaces the first, sits beside it or is refused. Say which before the person types.\n\n| State          | Behaviour                                                               |\n| -------------- | ----------------------------------------------------------------------- |\n| Draft          | Kept through an interruption and restored with \"you had started this\"   |\n| Queued offline | Visible, marked as not yet synced, with the time it was made            |\n| Conflict       | Entries from two devices are both kept and shown, never silently merged |\n| Failed         | The value is never lost. The reader is told, and the retry is automatic |\n\n<NotBuiltYet />\n\n## Components [#components]\n\n* [LogSheet](../components/log-sheet.mdx): the bottom sheet. It blocks no save and records every entry as self-reported.\n* [ReadingInput](../components/reading-input.mdx): one measurement with its unit, a unit switch and your warning.\n* [Field](../components/field.mdx), [Button](../components/button.mdx) and [Sheet](../components/sheet.mdx): label, save action, keyboard-safe detents.\n* [Value](../components/value.mdx), [RelativeTime](../components/relative-time.mdx) and [TimelineEntry](../components/timeline-entry.mdx): the saved entry and its dated history.\n* [EmptyState](../components/empty-state.mdx): before anything is logged.\n* [ScaleInput](../components/scale-input.mdx) and [DoseTracker](../components/dose-tracker.mdx): a rated scale such as pain, and a dose taken.\n\n## Build a log entry [#build-a-log-entry]\n\n```tsx\nimport { LogSheet } from \"@/components/ui/log-sheet\"\nimport { ReadingInput } from \"@/components/ui/reading-input\"\n\n<LogSheet\n  open={open}\n  onOpenChange={setOpen}\n  title=\"An example entry\"\n  values={{ reading }}\n  saveLabel=\"Save the example entry\"\n  onSave={(entry) => store(entry)}\n>\n  <ReadingInput\n    label=\"Example measurement\"\n    unit={unit}\n    units={[\"kg\", \"lb\", \"st\"]}\n    precision={1}\n    value={reading}\n    warning={warning}\n    onChange={(next) => {\n      setReading(next.value)\n      setUnit(next.unit)\n    }}\n  />\n</LogSheet>\n```\n\n* LogSheet never reads its children. `onSave` receives your `values` verbatim, so an empty entry still arrives and the emptiness check is yours.\n* `warning` is a sentence you write from bounds you own. It never marks the field invalid or blocks the save.\n* A unit switch can convert or clear the number without anybody typing, and ReadingInput mounts no live region. Announce `next.effectText` politely whenever it is not null.\n\n## Example [#example]\n\n<IframePreview kind=\"screen\" name=\"daily-log-screen\" />\n\nThe daily log screen is still a specification, so its frame shows the not-built notice. Its one lifted surface holds today's reading or an honest empty state.\n\n## Accessibility [#accessibility]\n\n* Focus moves into the sheet on open and is trapped while it is modal. <Kbd>Escape</Kbd> dismisses it, and focus returns to the control that opened it.\n* The unit is part of the field's accessible name, as in \"Systolic, in millimetres of mercury\".\n* The save is announced politely, and undo stays reachable by keyboard while it is offered.\n* The keyboard never covers the save, and typed input survives rotation and backgrounding.\n* Every gesture has a labelled control, and a stepper is never the only way to enter a number."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/patterns/empty-and-first-use",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/patterns/empty-and-first-use.md",
      "slug": [
        "patterns",
        "empty-and-first-use"
      ],
      "section": "Patterns",
      "title": "Empty and first use",
      "description": "What a health surface shows when it has no value, and why the different kinds of nothing must never look alike.",
      "kind": "pattern",
      "aliases": [
        "empty state",
        "zero data",
        "nothing to show",
        "first use screen",
        "no readings yet"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "A blank tile, a dash and a \"0\" are three different assertions. \"0 steps yesterday\" is not the same fact as \"no step data for yesterday\".\n\n## When to use it [#when-to-use-it]\n\nUse it whenever a health surface renders with no value to show.\n\nDo not use it when:\n\n* The data exists but is old. That is [Offline and stale data](./offline-and-stale-data.mdx).\n* The reader has never opened the product. That is [Onboarding and first run](./onboarding-and-first-run.mdx).\n* A trend has too few points to support a direction. See [Trend review](./trend-review.mdx).\n\n## How it works [#how-it-works]\n\nA measured zero is a value, shown with its unit. Every other absence renders its reason:\n\n| Kind of nothing        | Render                                       | Never imply                    |\n| ---------------------- | -------------------------------------------- | ------------------------------ |\n| Loading                | A skeleton in the final layout's shape       | A value                        |\n| Never collected        | One sentence of value and exactly one action | Nothing to worry about         |\n| Nothing in this filter | Say so, and offer to widen it                | They stopped logging           |\n| Pending                | What is expected, and by when                | It is late or lost             |\n| Failed to load         | An error with a retry                        | The value is zero or unchanged |\n| Withheld               | What is off, and how to turn it back on      | The data was deleted           |\n\n* Never render an absent value as a number: no zero, no dash styled as data, no last-known value dressed as current.\n* Never present a failed request as \"no data yet\". That is a fact about your network, not about the reader.\n* Absence has no clinical status, so an empty tile carries no status colour. See [Two colour axes](../health/two-colour-axes.mdx).\n* Loading has a floor and a ceiling. Never flash a skeleton, and after a stated timeout show an honest error.\n\n## Components [#components]\n\n* [EmptyState](../components/empty-state.mdx) requires a `reason`: `nothing-yet`, `no-matches`, `nothing-left`, `not-enough` or `could-not-load`. Only `could-not-load` draws a marker of its own, and its action is mandatory.\n* [Skeleton](../components/skeleton.mdx) holds the layout while loading, and `appearAfterMs` stops it flashing on a fast load.\n* [CareCard](../components/care-card.mdx) says when a pending result is expected.\n* [MetricTile](../components/metric-tile.mdx) with `value={null}` keeps its label and never shows a zero.\n\n## Content [#content]\n\n* One fact, one action, one reason: \"No blood-pressure readings yet. Log one and we'll show it against your range.\" \"No data\" says nothing.\n* No jokes about missing health data.\n* An error owns the problem: \"We couldn't load your readings. This is a problem on our side. Try again.\"\n\n## Accessibility [#accessibility]\n\n* The empty state has a heading at the level the content would have had, so the outline keeps its shape.\n* Skeletons are `aria-hidden`, and the caller mounts one polite status message for the change. An error the reader might act on is announced assertively (WCAG 2.2 SC 4.1.3).\n* The single action is the first focusable element after the heading.\n* Illustrations are decorative, and nothing animates to fill the space."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/patterns/forms",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/patterns/forms.md",
      "slug": [
        "patterns",
        "forms"
      ],
      "section": "Patterns",
      "title": "Forms",
      "description": "How a question behaves in a health product, from how many go on a page to when validation runs, and how Field wires it.",
      "kind": "pattern",
      "aliases": [
        "form design",
        "one question per page",
        "validation timing",
        "error summary",
        "required and optional",
        "react hook form"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "The first decision is whether to ask at all. A field you do not ask for cannot be mistyped, fail validation, leak or need a retention policy.\n\n## When to use it [#when-to-use-it]\n\nUse it for every form. For one specific detail, see [Ask users for…](./ask-users-for.mdx).\n\nDo not use it for:\n\n* A reading logged every day. That is [Daily logging](./daily-logging.mdx).\n* Consent, which is never a form field. See [Consent and permissions](./consent-and-permissions.mdx).\n* A validated questionnaire, whose layout is fixed. Never re-paginate it.\n\n## How it works [#how-it-works]\n\nDecide in this order:\n\n1. Whether to ask at all.\n2. Questions per page.\n3. Required or optional.\n4. Input type and autofill token.\n5. The answer's shape and unit.\n6. When validation runs.\n7. What a failed submit does.\n\n## Components [#components]\n\n* [Field](../components/field.mdx) gives one control a visible label, hint and error, wired together.\n* [ReadingInput](../components/reading-input.mdx) takes a measurement with its unit beside it.\n* [Stepper](../components/stepper.mdx) shows read-only progress through question pages.\n* [Button](../components/button.mdx) submits, and needs `type=\"submit\"` because it defaults to `type=\"button\"`.\n\n## Question pages [#question-pages]\n\n* Ask one question per page when it is hard, sensitive or unfamiliar, when a mistake has a consequence, or when the answer changes what comes next.\n* Group fields that are one thing to the reader, such as a systolic and diastolic reading, or that are copied from a meter or entered daily.\n* The question is the page's `<h1>`, and focus moves to it on navigation.\n* A grouped page is a `fieldset` with a `legend`.\n* State progress in text, such as \"Step 3 of 6\".\n* Back always works and keeps every answer (WCAG 2.2 SC 3.3.7).\n* Split a grouped page that branches. Never auto-advance.\n\n## Validation timing [#validation-timing]\n\nStay silent while the reader first types, validate when they leave the field, then live while they fix it, and check everything on submit.\n\n* Never block a save because a value is implausible. Ask, keep the entry, and store what the reader confirms.\n* Reject only the impossible. A negative weight is an error, and a weight far below yesterday's is a question.\n* Never move focus to an error, and never announce success.\n* Clear `aria-invalid` the moment the error clears.\n\nField's `validateOn` covers only native constraints, and its default needs `Field.Form`. With a form library, pass its message as `error`.\n\n## Error summaries [#error-summaries]\n\nAfter a failed submit, unless the form is one question with one error:\n\n* Put the summary first in the form's DOM, with a heading that states the count as a fact: \"There are 2 problems\".\n* Move focus to it, with `tabindex=\"-1\"`. It is the only error that takes focus.\n* Link each entry to its control's `id`, in DOM order, using the same words as the inline message.\n* Keep the inline errors, and put server errors in the same summary.\n* Update the summary without taking focus again, and announce politely when it clears.\n* Do not put `role=\"alert\"` on a summary that also takes focus.\n\nopsinjs has no error-summary component. A form error is not a clinical status, so the summary takes no status colour.\n\n## Required and optional [#required-and-optional]\n\nMark one convention across the product, never both. opsinjs recommends marking optional, so that every required field has to be defended.\n\n* Use the word, not an asterisk. Field's `optionality=\"optional\"` puts \"(optional)\" inside the label, so it joins the accessible name.\n* The `required` attribute matches the label.\n* When skipping costs the reader something, say what next to the field.\n* Never make a field required to improve your data.\n\n## Autocomplete and input types [#autocomplete-and-input-types]\n\n* A field about the reader takes its HTML autofill token, such as `name`, `bday-day`, `email`, `tel`, `postal-code` or `one-time-code` (WCAG 2.2 SC 1.3.5).\n* No token exists for a health reading or a medication. Use `autocomplete=\"off\"`, prefill from the reader's previous entry, and never invent a token.\n* For numbers, use `type=\"text\"` with `inputmode=\"decimal\"`, or `\"numeric\"` for whole numbers. `type=\"number\"` lets the scroll wheel change a reading and mishandles a decimal comma.\n* Turn off autocapitalisation and spellcheck on codes, and autocorrect on medication names.\n* Never disable paste.\n\nField.Control sets neither `autoComplete` nor `inputMode`, so pass both.\n\n## Units and numeric entry [#units-and-numeric-entry]\n\n* Never make the reader type the unit into the value. Show it beside the field, or make it a control, and spell it out in the accessible name: \"Weight in kilograms\".\n* Remember the unit per measure. Switching converts the entered value visibly, so 12 st becomes 76.2 kg rather than 12 kg.\n* Compound units are separate fields under one legend.\n* When a glucose value fits one unit and not the other, ask which the reader meant. Never convert silently.\n* Accept a comma or a point as the decimal separator, and store in one canonical unit.\n\nReadingInput converts kg, lb and st, and °C and °F. It refuses mmol/L to mg/dL, because the factor depends on the substance, and clears the entry. It rejects nothing. Pass the product's question as `warning`, which never blocks a save. Route its `effectText` to your own polite announcer.\n\n## Wiring a form [#wiring-a-form]\n\n```tsx\nimport { Field } from \"@/components/ui/field\"\n```\n\n```tsx\n<Field label=\"Example measurement\" hint=\"For example, 14\">\n  <Field.Control name=\"example-measurement\" inputMode=\"decimal\" autoComplete=\"off\" />\n</Field>\n```\n\n* Field owns the label, hint, error, `aria-describedby` and `aria-invalid`. Your form library owns state and validation.\n* The error appears above the control and never replaces the hint.\n* Keep the submit control enabled, and preserve values across a failed submit.\n* Map server errors onto the same fields and summary, and never reset the form.\n* A wrapper that drops `ref` breaks React Hook Form silently."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/patterns/offline-and-stale-data",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/patterns/offline-and-stale-data.md",
      "slug": [
        "patterns",
        "offline-and-stale-data"
      ],
      "section": "Patterns",
      "title": "Offline and stale data",
      "description": "What a health screen shows when it cannot vouch for its numbers. The value stays, and every claim about now is withdrawn.",
      "kind": "pattern",
      "aliases": [
        "offline mode",
        "stale readings screen",
        "last synced",
        "cached readings",
        "no connection"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "Staleness degrades assertions, not values. The number stays, because the reader is entitled to it. Its status, trend, range comparison and alerts are claims about now, which the product no longer knows.\n\n## When to use it [#when-to-use-it]\n\nUse it when the product shows a value it can no longer stand behind, because the network is gone, a device has not synced or a refresh failed.\n\nDo not use it when:\n\n* There is no value at all. That is [Empty and first use](./empty-and-first-use.mdx).\n* The value is old by design. A March blood test is dated, not stale, so show its date.\n\n[Trends and uncertainty](../health/trends.mdx) holds the doctrine on staleness and provenance.\n\n## How it works [#how-it-works]\n\n1. Every measure has a freshness window, set by the team that owns its thresholds.\n2. Beyond the window, keep the value and its timestamp and withdraw the status axis: no [StatusPill](../components/status-pill.mdx), no colour-coded verdict, no trend arrow.\n3. Suspend alerts computed from stale data rather than firing them. See [Alert escalation](./alert-escalation.mdx).\n4. Refresh quietly. Success restores full assertions without a banner. Failure says what being offline means here.\n5. Show an offline entry at once, marked unsynced, with the time it was made.\n6. Show conflicts and never merge them. Two devices writing one slot make two entries the reader resolves.\n\n| State           | Status axis              | Timestamp                              |\n| --------------- | ------------------------ | -------------------------------------- |\n| Fresh           | Full                     | De-emphasised                          |\n| Ageing          | Full                     | Visible, age promoted                  |\n| Stale           | Withdrawn                | Prominent                              |\n| Offline, cached | Withdrawn                | Prominent, with an offline notice      |\n| Unsynced write  | None yet                 | Time of entry, marked unsynced         |\n| Conflict        | Withdrawn until resolved | Both times shown                       |\n| Unknown age     | Withdrawn                | \"We don't know when this was measured\" |\n\nThe value shows in every state. Never hide the timestamp, and never stamp an imported value with the import time.\n\n## Components [#components]\n\n* [RelativeTime](../components/relative-time.mdx) writes the age. The product supplies `staleAfterHours`, which has no default, and `event` separates measured from synced.\n* [MetricTile](../components/metric-tile.mdx) mutes past `staleAfterHours` and adds \"may be out of date\".\n* [StatusPill](../components/status-pill.mdx) is removed once the value is stale, never greyed.\n* [AlertBanner](../components/alert-banner.mdx) carries a screen-wide condition, such as a queued write that failed to send.\n\n## Content [#content]\n\n* Name what is uncertain: \"Last synced 4 hours ago. Your monitor may have taken readings since then. We can't show a current status until it reconnects.\" Not \"Some data may be out of date.\"\n* Tell the reader their entry is safe: \"Saved on your phone. It will sync when you're back online.\"\n\n## Accessibility [#accessibility]\n\n* Entering the stale state is one polite status message per transition, not one per tile (WCAG 2.2 SC 4.1.3).\n* The offline notice is announced, never modal, and never takes focus.\n* Never grey a value out to show staleness, because it fails the contrast floor. Use words and position.\n* Retry is a focusable, labelled control, even where pull-to-refresh exists."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/patterns/onboarding-and-first-run",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/patterns/onboarding-and-first-run.md",
      "slug": [
        "patterns",
        "onboarding-and-first-run"
      ],
      "section": "Patterns",
      "title": "Onboarding and first run",
      "description": "The minimum you may collect before the reader has seen anything of value, and how to defer everything else to the moment it earns its keep",
      "kind": "pattern",
      "aliases": [
        "first run",
        "signup flow",
        "setup wizard",
        "minimum collection",
        "time to first value"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "Every question asked before the first moment of value is asked on credit, and health questions are expensive. Some frighten, some are private, and some need a piece of paper to answer.\n\n## When to use it [#when-to-use-it]\n\nUse it between the reader first opening the app and first seeing something about them. A setup bar with more than four steps is a warning sign. Use something else for:\n\n* a returning reader with an empty screen: [Empty and first use](./empty-and-first-use.mdx), never a re-run of setup;\n* a device permission: [Consent and permissions](./consent-and-permissions.mdx);\n* a validated questionnaire, even one that runs first: [Forms](./forms.mdx);\n* how to ask for one detail, such as a date of birth: [Ask users for…](./ask-users-for.mdx).\n\n## How it works [#how-it-works]\n\n1. **Scope first.** One screen says what the product does, and that it is not a medical device or a substitute for advice. Late disclosure reads as concealment.\n2. **Gate every field.** Answer in writing: can the first useful screen render without this? If it can, ask on the surface that needs it, where the reader sees why.\n3. **Ask one question at a time, with a reason.** \"Why we ask: your age changes the range we compare your readings to.\"\n4. **Name the consequence of every skip.** \"Skip. We will show ranges for adults generally rather than for your age.\" Skipping still arrives at a usable screen.\n5. **Show the first value.** The reader's own number comes back with no status, no range verdict and no reassurance, because a first reading is not a baseline.\n6. **Defer the rest.** Consent comes when a feature needs it, profile fields when a calculation needs them, and an account when something must be kept or synced.\n\nNothing that arrives later blocks the first value, and nothing is timed or advances by itself.\n\n| State               | Behaviour                                                                   |\n| ------------------- | --------------------------------------------------------------------------- |\n| Resumed             | Returns to the exact question with earlier answers intact                   |\n| Skipped fields      | Recorded as skipped and re-asked later in context, never on the next launch |\n| Declined everything | An honest screen, never a locked one with no exit                           |\n\n<NotBuiltYet />\n\n## Components [#components]\n\n* [DisclaimerNote](../components/disclaimer-note.mdx): the scope statement, inside the orientation.\n* [Field](../components/field.mdx) and [ReadingInput](../components/reading-input.mdx): one measurement or one choice, not a form.\n* [Button](../components/button.mdx): continue, and a real \"Skip for now\".\n* [Value](../components/value.mdx) and [CareCard](../components/care-card.mdx): the reader's own number, and a next step only if one is real.\n* [EmptyState](../components/empty-state.mdx): the honest payoff when every input was skipped.\n* [ConsentSheet](../components/consent-sheet.mdx): later, when a feature needs it.\n\n## Example [#example]\n\n<IframePreview kind=\"screen\" name=\"onboarding-screen\" />\n\nThe onboarding screen is still a specification, so its frame shows the not-built notice. The payoff step, which shows the reader's own number, is its only lifted surface.\n\n## Content [#content]\n\nSpend the reader's attention on scope and the next step, not on features. \"Understand your heart\" is a description. \"Improve your heart health\" is a health claim, and a reader remembers a claim made at first run. No status colour appears, because first run has no clinical state to grade.\n\n## Accessibility [#accessibility]\n\n* Each step has one heading, and focus moves to it on advance, never to the continue button.\n* Progress is stated in text, such as \"Step 2 of 4\", not by dots alone.\n* Back never destroys input (WCAG 2.2 SC 3.3.7), and no step has a time limit (SC 2.2.1).\n* Sign-in needs no memory test (SC 3.3.8), so pasting a one-time code must work.\n* Skip is a labelled, focusable control of at least 44pt that stays beside continue at 200% text."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/patterns/result-disclosure",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/patterns/result-disclosure.md",
      "slug": [
        "patterns",
        "result-disclosure"
      ],
      "section": "Patterns",
      "title": "Result disclosure",
      "description": "Showing someone a result they may not want to see, without ambush, from notification to number to next step",
      "kind": "pattern",
      "aliases": [
        "showing a result",
        "lab result flow",
        "disclosing a test result",
        "result ambush"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "The reader knows a result is coming but not what it says, and your notification schedule picks the moment they find out. This pattern designs that moment.\n\n## When to use it [#when-to-use-it]\n\nUse it for a value the reader did not create and cannot interpret on sight, such as a lab result or a risk score. Use something else for:\n\n* a number the reader typed: [Daily logging](./daily-logging.mdx);\n* a value whose next step is emergency services, or a score with a self-harm item: [High-stakes moments](../health/high-stakes-moments.mdx);\n* change over time: [Trend review](./trend-review.mdx);\n* a pending result: [Empty and first use](./empty-and-first-use.mdx), never a card with dashes in it.\n\n## How it works [#how-it-works]\n\n1. **Notification.** \"Your ferritin result is ready.\" Never the value, the status word or a colour that encodes one, because someone else may read the lock screen.\n2. **Landing.** One plain-English sentence on what the test measures, before the number.\n3. **The value.** Number, unit and range together on first paint. Nothing animates in, and the status never arrives after the value.\n4. **Next step.** Something to do, including \"nothing, and here is why\". A result outside its range names a route to a human.\n\n| State      | Shows                                         | Never                             |\n| ---------- | --------------------------------------------- | --------------------------------- |\n| Pending    | The test and when to expect it                | A dash or zero styled as a value  |\n| Partial    | What arrived, marked incomplete               | Interpretation of a partial panel |\n| Superseded | The current value, the previous one reachable | A silent replacement              |\n| Withdrawn  | A statement that it was retracted             | The value quietly disappearing    |\n\n<Todo>\n  No screen shows the whole sequence yet. The results screen below covers the value and the next step. The notification and the landing surface have no specimen.\n</Todo>\n\n## Components [#components]\n\n* [ResultCard](../components/result-card.mdx): value, range, meaning and next step as one unit.\n* [RangeBar](../components/range-bar.mdx): where the value sits against its range, as position only.\n* [StatusPill](../components/status-pill.mdx): the level, only when a rule your product owns assigned one.\n* [Term](../components/term.mdx): a plain-English expansion of a clinical word.\n* [CareCard](../components/care-card.mdx): the next step, only when there is a real action with real timing.\n* [DisclaimerNote](../components/disclaimer-note.mdx): the boundary note, in the same place on every result screen.\n\n## Value against a range [#value-against-a-range]\n\n1. Write down the range's source, population, unit and date. Without all four you have two numbers, not a range. opsinjs supplies no ranges.\n2. Convert units once, where data enters your system. A range in one unit drawn against a value in another looks plausible and is wrong.\n3. Draw position, not a verdict: one continuous band, a marker told apart by shape, no truncated axis. Any status goes in the pill, never on the band.\n4. Write the sentence first. The bar adds speed, never information. With no range, say so and draw no bar, because an empty bar reads as a missing result.\n\n```tsx\nimport { ResultCard } from \"@/components/ui/result-card\"\nimport { EXAMPLE_SOURCE } from \"@/lib/opsinjs\"\n\n<ResultCard\n  title=\"Example measurement\"\n  value={14}\n  unit=\"mg/dL\"\n  precision={0}\n  measuredAt=\"2026-03-14T08:12:00+00:00\"\n  now=\"2026-03-14T11:12:00+00:00\"\n  range={{ low: 10, high: 20, source: EXAMPLE_SOURCE }}\n  status=\"steady\"\n  category=\"labs\"\n  meaning=\"Two or three short sentences, in the second person, written by the product.\"\n/>\n```\n\nResultCard derives no level, so `status` is always your rule's output. Category reaches only the title and status only the pill, as [Two colour axes](../health/two-colour-axes.mdx) requires.\n\n## Build a metric card [#build-a-metric-card]\n\nA [MetricTile](../components/metric-tile.mdx) identifies and reports, and opens the detail screen where interpretation lives.\n\n* Label what was measured in the reader's words: \"Resting heart rate\", not \"Heart health\" or \"RHR\".\n* `measuredAt` is the measurement time, never the sync time. `staleAfterHours` is yours, per metric, with no default.\n* Default to no `status`. Add one only when your rule assigned it and the screen is inside its [alarm budget](../health/alerts.mdx), and pair `attention` or `urgent` with an `href`.\n* Decide all five [states](../foundations/states.mdx) first. Stale and partial are the two that mislead.\n\n```tsx\nimport { MetricTile } from \"@/components/ui/metric-tile\"\n\n<MetricTile\n  label=\"Example measurement\"\n  value={14}\n  unit=\"steps\"\n  precision={0}\n  measuredAt=\"2026-04-06T07:15:00+00:00\"\n  now={now}\n  href=\"/results/example\"\n/>\n```\n\n## Example [#example]\n\n<IframePreview kind=\"screen\" name=\"results-screen\" />\n\nEvery part of the results screen ships, but its composition has had no clinical review. It is not served from `/r`, so there is no `shadcn add` for it.\n\n## Content [#content]\n\nCopy runs in a fixed order: what this is, what it says, what it means, what to do, who to ask.\n\n> Your `<measurement>` was `<value> <unit>`, measured `<when>`. The usual range for this test is `<low>` to `<high>` `<unit>`. `<what this does or does not mean>` `<what happens next>`\n\nNever write *normal*, *abnormal*, *good* or *bad*. Describe the position, such as \"above the usual range\", and not the person. [Reference ranges](../health/reference-ranges.mdx) owns the rule. DOM order follows the same sequence, because a pill placed first announces a verdict before the fact."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/patterns/sharing-with-a-clinician",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/patterns/sharing-with-a-clinician.md",
      "slug": [
        "patterns",
        "sharing-with-a-clinician"
      ],
      "section": "Patterns",
      "title": "Sharing with a clinician",
      "description": "Export and hand-off surfaces a clinician can read in ninety seconds, without the product implying it has interpreted anything.",
      "kind": "pattern",
      "aliases": [
        "export my data",
        "share with doctor",
        "appointment summary",
        "printable report",
        "hand-off"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "The export answers to the clinician, who wants the fewest facts that change a decision. The screen before it answers to the reader.\n\n## When to use it [#when-to-use-it]\n\nUse it when the reader takes their logs to an appointment, a clinic asks for readings between visits, or a referral needs their history.\n\nDo not use it for:\n\n* Continuous clinical monitoring, a regulated surface with alerting obligations that opsinjs is not built for. See [Safety review](../health/safety-review.mdx).\n* Sharing with a family member or carer, which needs its own design.\n* Raw data portability, which is a different artefact. Offer both.\n* Granting and revoking access. That is [Consent and permissions](./consent-and-permissions.mdx).\n\n## How it works [#how-it-works]\n\n1. The reader picks a window and the measures to include. With nothing to share, say what would be needed rather than producing an empty document.\n2. The preview is the artefact itself, and the reader can still change the dates or remove a measure.\n3. In person, the product prints a one-page summary that depends on no colour.\n4. Sending needs consent naming the recipient, scope and duration, and a record of what was sent, to whom and when.\n5. The reader sees what was shared, to whom and until when. Expiry is visible, and revoking is immediate and says what the recipient may already hold.\n\nThe export itself:\n\n* Fits one page, and the first third is the answer: identity, window, measures included and a summary sentence.\n* States values, ranges and dates, never the product's status words. Those are written for a layperson and would read as a clinical assessment.\n* Declares completeness: \"42 of a possible 60 mornings, none between 12 and 19 August.\" Gaps are declared, never filled.\n* Carries provenance: which device, which method, and whether each value was measured or self-entered.\n* Marks each stale value, as in [Offline and stale data](./offline-and-stale-data.mdx).\n\n## Components [#components]\n\nopsinjs ships no export or summary component. The product builds the document from these:\n\n* [Table](../components/table.mdx) carries each chart's table twin into the export.\n* [Value](../components/value.mdx) and [RelativeTime](../components/relative-time.mdx) format every number and date.\n* [ConsentSheet](../components/consent-sheet.mdx) asks before anything is sent.\n* [DisclaimerNote](../components/disclaimer-note.mdx) says what the document is, because it will outlive the app.\n\n## Content [#content]\n\n* Write the export for the clinician: \"Home blood pressure, 3 May to 2 June 2026. 42 morning readings of a possible 60. Self-measured, upper-arm cuff.\" Never \"your amazing progress\".\n* Write the screen for the reader: \"This is what Dr Ellis will see. You can change the dates or remove a metric before sending.\"\n\n## Accessibility [#accessibility]\n\n* The export is a document, not a screenshot: real text, real headings, real tables.\n* Nothing in it depends on colour, because it will be printed in monochrome and photocopied.\n* The share control names the recipient: \"Send summary to Dr Ellis's clinic\", not \"Send\".\n* Test the print styles: page breaks between sections, and URLs printed where link text is not self-describing."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/patterns/trend-review",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/patterns/trend-review.md",
      "slug": [
        "patterns",
        "trend-review"
      ],
      "section": "Patterns",
      "title": "Trend review",
      "description": "Reading change over time without over-interpreting noise, with minimum windows, honest axes and direction kept apart from valence",
      "kind": "pattern",
      "aliases": [
        "trends over time",
        "change over time",
        "chart review",
        "is it going up",
        "noise vs signal"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "The reader's question is \"is this getting better or worse\", not \"what is my number\". By default, charts mislead here. Three points make a line, an axis fitted to the data turns a small drift into a cliff, and a nightly average changes direction twice a week.\n\n## When to use it [#when-to-use-it]\n\nUse it when the reader compares a value with their own history, the measure varies day to day, and someone might change a behaviour or a dose because of the line. Use something else for:\n\n* one value against one range: [Result disclosure](./result-disclosure.mdx);\n* a sustained change that needs action: [Alert escalation](./alert-escalation.mdx);\n* chart mechanics or the doctrine: [Data visualisation](../foundations/data-visualisation.mdx) and [Trends and uncertainty](../health/trends.mdx).\n\n## How it works [#how-it-works]\n\n1. **Count the readings.** Below the metric's minimum, show the points with no line and no direction word, and say how many more are needed. Your product owns that minimum.\n2. **Fix an honest axis.** Zero where zero means something, otherwise the reference band or a fixed span. Keep it stable, and never fit it to the data.\n3. **Compare the change with the noise.** A change smaller than the measure's own variation is \"about the same\", with no direction named.\n4. **Name direction, never valence.** Up, down or about the same. Down is not worse. A status your rule assigned appears in words beside the chart and never recolours the line.\n5. **Write the caption.** Direction, size, unit and window, in words. The caption is the deliverable and the chart illustrates it.\n6. **Ship the table twin,** with the same numbers, on the page, in every state.\n\nGaps are drawn as gaps, never interpolated. A stale series promotes its last-updated stamp and demotes the direction. Series in different units are split, never rescaled onto one axis. No causal language: \"your sleep improved because you walked more\" is a claim self-tracked data cannot support.\n\n<NotBuiltYet />\n\n## Components [#components]\n\n* [TrendSparkline](../components/trend-sparkline.mdx): the series and its caption, with category colour on the line only.\n* [Table](../components/table.mdx): the readable twin, which TrendSparkline does not supply.\n* [RangeLegend](../components/range-legend.mdx): the key to a band behind the series.\n* [SegmentedControl](../components/segmented-control.mdx): the window, such as 7 days, 30 days or 12 months.\n* [Value](../components/value.mdx) and [MetricTile](../components/metric-tile.mdx): the latest reading, and related metrics.\n* [Skeleton](../components/skeleton.mdx) and [EmptyState](../components/empty-state.mdx): never a flat line at zero.\n\n## Trend with an honest caption [#trend-with-an-honest-caption]\n\n```tsx\nimport { TrendSparkline } from \"@/components/ui/trend-sparkline\"\n\n<TrendSparkline\n  label=\"Example measurement\"\n  unit=\"steps\"\n  precision={0}\n  locale=\"en-GB\"\n  window=\"the last 6 entries\"\n  series={series}\n  minimumPoints={readingsATrendNeeds}\n/>\n```\n\n`minimumPoints` is required and has no default. Below it nothing is drawn, and the caption says why. `changeThreshold` is the smallest difference your metric counts as a change, and without it the caption names no direction. A gap is an entry with `value: null`, never an omitted one.\n\nTo write your own sentence, pass `caption`. The count of readings and of missing entries is still appended. Keep to this shape:\n\n> `<metric>` `<direction>` `<magnitude> <unit>` over `<window>`, compared with `<comparison window>`. `<what a change of this size does not mean>`\n\n\"Your resting heart rate was about 4 bpm lower over the last 7 days than the 7 days before. Day-to-day variation of this size is common and does not on its own mean anything has changed.\" Lead with absolute change, because a percentage of a small number makes a trivial change sound large. Never congratulate or commiserate.\n\n<Todo>\n  Marking an event on the line itself, such as a medication change or an illness, has no component and no guidance yet. [TimelineEntry](../components/timeline-entry.mdx) covers a dated history list, not the chart.\n</Todo>\n\n## Example [#example]\n\n<IframePreview kind=\"screen\" name=\"trends-screen\" />\n\nThe trends screen is still a specification, so its frame shows the not-built notice. Its caption sits inside the card with the chart, so the two cannot be screenshotted apart.\n\n## Accessibility [#accessibility]\n\n* The caption is the chart's accessible description, not \"line chart showing resting heart rate\".\n* Changing the metric or window announces the new summary politely and does not move focus.\n* A focused point announces its value, unit and date, and every value is in the table without a gesture.\n* No draw-on animation carries meaning, and at 200% text the sentence is never truncated."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/reference",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/reference.md",
      "slug": [
        "reference"
      ],
      "section": "Reference",
      "title": "Reference",
      "description": "Generated tables of every token, variable, attribute, key, contrast pair and type, with the error codes and both glossaries.",
      "kind": "reference",
      "aliases": [
        "generated reference",
        "what is generated"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "The generated pages are written by scripts from the same sources the build ships, so a row cannot describe a token the build does not have. `pnpm run check` regenerates them and diffs the result, so a page that drifts from its source fails the build. To change a row, change the source. An edit between a page's generated markers is erased by the next `pnpm run generate`. A program should read the same lists from `/llms.txt`, the `.md` twin of each page, or `/r/index.json`.\n\n| Page                                               | Contents                                                                                         |\n| -------------------------------------------------- | ------------------------------------------------------------------------------------------------ |\n| [Tokens](./generated/tokens.mdx)                   | Every design token, what it controls and what reads it                                           |\n| [CSS variables](./generated/css-variables.mdx)     | Every `--opsin-*` custom property, with its light and dark defaults                              |\n| [Data attributes](./generated/data-attributes.mdx) | Every `data-*` attribute the components emit. Empty until the script reads the component sources |\n| [Keyboard](./generated/keyboard.mdx)               | Every keyboard interaction. Empty until the script reads each component page's table             |\n| [Contrast](./generated/contrast.mdx)               | Measured WCAG 2.2 ratios and APCA Lc for every token pair, in both themes                        |\n| [Types](./generated/types.mdx)                     | Every TypeScript symbol the site's `lib/` exports. Not an installable API                        |\n| [Error codes](./error-codes.mdx)                   | Every development warning, its stable code and the page that prevents it                         |\n| [Glossary](./glossary.mdx)                         | The words opsinjs uses about itself, written by hand                                             |\n| [Plain English A to Z](./plain-english.mdx)        | The clinical terms a reader meets, and the plain words to use instead                            |"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/reference/error-codes",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/reference/error-codes.md",
      "slug": [
        "reference",
        "error-codes"
      ],
      "section": "Reference",
      "title": "Error codes",
      "description": "Every development-mode warning opsinjs emits, its stable code, what causes it and the page that prevents it.",
      "kind": "reference",
      "aliases": [
        "warning codes",
        "dev warnings",
        "OPSIN error",
        "console warning",
        "what does this warning mean"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "Every warning opsinjs emits in development carries a stable code, a sentence saying what to do instead, and a link to the page that explains the rule. `warnOnce()` ships in `lib/opsinjs.ts`, which `shadcn add` copies into your project with the components. Several built components call it, and the remaining codes are allocated with no caller yet. Message wording, severity and which component raises which code may change while the components are unreviewed. The code a message carries does not.\n\n## How the codes work [#how-the-codes-work]\n\n* **Flat and permanent.** Codes run from `OPSIN-0001` in allocation order, and the digits carry no meaning. A code is never reused, renumbered or removed. Adding a code is not a breaking change.\n* **One code, one page.** Each code links the page that explains its rule.\n* **Once per session.** A warning fires once per code and message, not once per render. The message includes the values the component passed, so two components making the same mistake print two warnings, and the second render in Strict Mode prints nothing.\n* **Development only.** No warning throws. A production build strips them when your bundler applies the `NODE_ENV` guard, and where `process` is undefined the channel stays silent. Validate anything you need at runtime in your own code.\n* **One source.** `tokens/errors.json` is the only place a code is authored. `scripts/build-tokens.mts` writes it into `lib/opsinjs.ts`, `lib/generated/tokens.ts` and the table below, and the next `pnpm run generate` undoes an edit to any of them.\n\n## Handling a warning [#handling-a-warning]\n\n* Treat a `safety` code as an error. The screen looks right and tells a reader the wrong thing about their own health.\n* Search and parse by code, never by message text. Messages get clearer between versions, and codes do not change.\n* Never work around a warning you have not read.\n* Turn warnings into failures in CI if you want them enforced.\n* Do not silence the console to hide them, because that silences React's hydration warnings too.\n* A warning raised during server rendering appears in the server log, not the browser console.\n* A message with a `{brace}` still in it is a second bug, because the component did not supply that value.\n* Report a warning that fires when it should not.\n\n## The codes [#the-codes]\n\n{/* opsinjs:errors:begin. Everything below is replaced by scripts/build-tokens.mts from tokens/errors.json */}\n\nA warning is one `console.warn` call, and it looks like this. The braces are\nfilled from what the component passed; this is the template as authored, so\nwhat you see below is what the code emits and not a paraphrase of it.\n\n```text\n[opsinjs] OPSIN-0001 (safety): <{component}> received both `category=\"{category}\"` and `status=\"{status}\"`. A surface carries one axis. Set the category on the surface and render the status as a StatusPill inside it.\n  → https://opsinjs.pensievelabs.org/docs/health/two-colour-axes\n```\n\n### Severities [#severities]\n\n3 classes, and they are a statement about consequence rather than about\nhow noisy the warning is.\n\n| Severity      | Codes | What it means                                                                                     |\n| ------------- | ----- | ------------------------------------------------------------------------------------------------- |\n| `safety`      | 8     | A defect that can mislead a reader about their own health. Treat as a bug, not as a lint warning. |\n| `correctness` | 9     | The component will render something, but not what the author meant.                               |\n| `hygiene`     | 4     | Works today, will not survive an upgrade.                                                         |\n\n### Every code [#every-code]\n\n21 codes, in allocation order. \"Values in the message\" names the\n`{braced}` spans a component has to supply; a missing one is reported in the\nwarning itself rather than swallowed.\n\n| Code         | Severity    | What went wrong                                         | Values in the message                        | Prevented by                                                            |\n| ------------ | ----------- | ------------------------------------------------------- | -------------------------------------------- | ----------------------------------------------------------------------- |\n| `OPSIN-0001` | safety      | Both a category and a status were given to one surface  | `component`, `category`, `status`            | [health/two-colour-axes](../health/two-colour-axes.mdx)                 |\n| `OPSIN-0002` | safety      | A status was rendered without a word                    | `component`, `status`                        | [health/two-colour-axes](../health/two-colour-axes.mdx)                 |\n| `OPSIN-0003` | safety      | A value was rendered without a unit                     | `value`, `null`                              | [health/numbers](../health/numbers.mdx)                                 |\n| `OPSIN-0004` | safety      | A reference range was rendered without a source         | `component`                                  | [health/reference-ranges](../health/reference-ranges.mdx)               |\n| `OPSIN-0005` | safety      | More than one urgent surface on a screen                | `count`                                      | [health/alerts](../health/alerts.mdx)                                   |\n| `OPSIN-0006` | safety      | A banned word appeared in a component's copy            | `text`, `word`, `replacement`                | [reference/plain-english](../reference/plain-english.mdx)               |\n| `OPSIN-0007` | safety      | A health value was animated                             | `component`, `token`                         | [health/alerts](../health/alerts.mdx)                                   |\n| `OPSIN-0008` | correctness | A raw colour value was passed where a token is required | `component`, `prop`, `value`                 | [theming](../theming.mdx)                                               |\n| `OPSIN-0009` | correctness | A primitive token was referenced from a component       | `token`                                      | [theming](../theming.mdx)                                               |\n| `OPSIN-0010` | correctness | An unknown category was requested                       | `category`, `known`                          | [theming](../theming.mdx)                                               |\n| `OPSIN-0011` | correctness | `unknown` was used as a status level                    | none                                         | [health/trends](../health/trends.mdx)                                   |\n| `OPSIN-0012` | correctness | A trend was drawn from too few points                   | `count`, `minimum`                           | [health/trends](../health/trends.mdx)                                   |\n| `OPSIN-0013` | correctness | A chart's y-axis was truncated                          | `component`, `min`                           | [foundations/data-visualisation](../foundations/data-visualisation.mdx) |\n| `OPSIN-0014` | correctness | Category colours were used as chart series colours      | `count`                                      | [foundations/data-visualisation](../foundations/data-visualisation.mdx) |\n| `OPSIN-0015` | correctness | A touch target is below the floor                       | `component`, `width`, `height`               | [foundations/accessibility](../foundations/accessibility.mdx)           |\n| `OPSIN-0016` | correctness | A stale reading was rendered as current                 | `component`, `age`                           | [health/trends](../health/trends.mdx)                                   |\n| `OPSIN-0017` | hygiene     | More than three translucent surfaces are composited     | `count`                                      | [foundations/materials](../foundations/materials.mdx)                   |\n| `OPSIN-0018` | hygiene     | A deprecated token was referenced                       | `token`, `version`, `replacement`, `removal` | [changelog](../changelog.mdx)                                           |\n| `OPSIN-0019` | hygiene     | The token stylesheet was not loaded                     | none                                         | [theming](../theming.mdx)                                               |\n| `OPSIN-0020` | hygiene     | Two theme providers are mounted                         | none                                         | [theming](../theming.mdx)                                               |\n| `OPSIN-0021` | safety      | A status outside the four levels was passed             | `component`, `status`                        | [health/two-colour-axes](../health/two-colour-axes.mdx)                 |\n\n{/* opsinjs:errors:end */}"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/reference/generated/accents",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/reference/generated/accents.md",
      "slug": [
        "reference",
        "generated",
        "accents"
      ],
      "section": "Reference",
      "title": "Accent contrast",
      "description": "Measured APCA Lc and WCAG 2.2 contrast for every accent theme and accent in both modes, against each theme's own floors.",
      "kind": "reference",
      "aliases": [
        "accent contrast",
        "accent measurements",
        "stryk contrast",
        "vibes contrast"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-11-08",
      "markdown": "Measured by `scripts/check-contrast.mts` from `tokens/accent.json`, read through `scripts/accent-plan.mts`, with the hand-written maths in `lib/color/apca.ts` and `lib/color/wcag.ts`, into `lib/generated/accent-contrast.json`. `pnpm run contrast` measures and `pnpm run contrast:verify` fails on a failing or moved pair. `scripts/build-tokens.mts` measures the same pairs before it writes a token and refuses one below its floor, so a failing accent never reaches `app/tokens.generated.css`. No figure here was typed by a person.\n\nNormal and vibes are held to the system's floors. Stryk is held to enhanced floors: WCAG 2.2 AAA (7:1) and APCA Lc 85 for text, 4.5:1 and Lc 60 for boundaries and rings. An exempt pair is a bright fill whose edge carries the boundary instead, and the edge is measured in its place. [Accent](../../foundations/accent.mdx) explains the themes.\n\n{/* opsinjs:generated:begin - everything below is replaced by scripts/build-reference.mts */}\n\n## Measured accents [#measured-accents]\n\nMeasured on 2026-11-10. 680 pairs: 648 pass, 0 fail, and 32 exempt, each an accent fill bounded by a rim that is measured in its place.\n\nEach row is one accent in one mode. Action is the filled action, Fill the selected state of a selection control, Ink accent text on the page and Ring the focus ring. Weakest text is the lowest of the label, tick and accent text pairs, and weakest boundary the lowest of the fill, rim and ring pairs.\n\n### Normal [#normal]\n\nHeld to the standard floors: text at APCA Lc 75 and WCAG 4.5:1, boundaries and rings at Lc 45 and 3:1.\n\n| Accent   | Mode  | Action                   | Fill                     | Ink                      | Ring                     | Weakest text     | Weakest boundary | Verdict |\n| -------- | ----- | ------------------------ | ------------------------ | ------------------------ | ------------------------ | ---------------- | ---------------- | ------- |\n| Cobalt   | light | `oklch(0.145 0.005 250)` | `oklch(0.53 0.155 250)`  | `oklch(0.5 0.142 250)`   | `oklch(0.53 0.155 250)`  | Lc 76.3, 5.25:1  | Lc 72.3, 5.02:1  | pass    |\n| Cobalt   | dark  | `oklch(0.985 0.002 250)` | `oklch(0.845 0.079 250)` | `oklch(0.855 0.074 250)` | `oklch(0.75 0.13 250)`   | Lc 76.7, 11.62:1 | Lc 57.7, 8.11:1  | pass    |\n| Sky      | light | `oklch(0.145 0.005 250)` | `oklch(0.55 0.096 212)`  | `oklch(0.495 0.086 212)` | `oklch(0.55 0.096 212)`  | Lc 76.1, 4.66:1  | Lc 68.7, 4.46:1  | pass    |\n| Sky      | dark  | `oklch(0.985 0.002 250)` | `oklch(0.83 0.13 212)`   | `oklch(0.84 0.13 212)`   | `oklch(0.7 0.121 212)`   | Lc 76.1, 11.49:1 | Lc 51.6, 7.04:1  | pass    |\n| Jade     | light | `oklch(0.145 0.005 250)` | `oklch(0.545 0.143 152)` | `oklch(0.485 0.128 152)` | `oklch(0.545 0.143 152)` | Lc 76.2, 4.62:1  | Lc 68.3, 4.42:1  | pass    |\n| Jade     | dark  | `oklch(0.985 0.002 250)` | `oklch(0.83 0.13 152)`   | `oklch(0.84 0.13 152)`   | `oklch(0.7 0.13 152)`    | Lc 76.6, 11.54:1 | Lc 51.5, 7.08:1  | pass    |\n| Volt     | light | `oklch(0.145 0.005 250)` | `oklch(0.555 0.135 122)` | `oklch(0.495 0.121 122)` | `oklch(0.555 0.135 122)` | Lc 76.3, 4.62:1  | Lc 68.8, 4.42:1  | pass    |\n| Volt     | dark  | `oklch(0.985 0.002 250)` | `oklch(0.84 0.13 122)`   | `oklch(0.845 0.13 122)`  | `oklch(0.7 0.13 122)`    | Lc 76.6, 11.53:1 | Lc 50.5, 6.94:1  | pass    |\n| Rose     | light | `oklch(0.145 0.005 250)` | `oklch(0.56 0.16 354)`   | `oklch(0.52 0.16 354)`   | `oklch(0.56 0.16 354)`   | Lc 76.1, 5.09:1  | Lc 71.3, 4.87:1  | pass    |\n| Rose     | dark  | `oklch(0.985 0.002 250)` | `oklch(0.855 0.089 354)` | `oklch(0.865 0.082 354)` | `oklch(0.7 0.13 354)`    | Lc 76.3, 11.55:1 | Lc 46.5, 6.30:1  | pass    |\n| Orchid   | light | `oklch(0.145 0.005 250)` | `oklch(0.56 0.16 326)`   | `oklch(0.52 0.16 326)`   | `oklch(0.56 0.16 326)`   | Lc 76.2, 5.06:1  | Lc 71.4, 4.84:1  | pass    |\n| Orchid   | dark  | `oklch(0.985 0.002 250)` | `oklch(0.86 0.129 326)`  | `oklch(0.87 0.12 326)`   | `oklch(0.7 0.13 326)`    | Lc 76.4, 11.56:1 | Lc 46.6, 6.33:1  | pass    |\n| Violet   | light | `oklch(0.145 0.005 250)` | `oklch(0.56 0.16 300)`   | `oklch(0.52 0.16 300)`   | `oklch(0.56 0.16 300)`   | Lc 76.2, 5.00:1  | Lc 71.2, 4.79:1  | pass    |\n| Violet   | dark  | `oklch(0.985 0.002 250)` | `oklch(0.85 0.086 300)`  | `oklch(0.86 0.08 300)`   | `oklch(0.7 0.13 300)`    | Lc 76.0, 11.51:1 | Lc 47.2, 6.44:1  | pass    |\n| Iris     | light | `oklch(0.145 0.005 250)` | `oklch(0.56 0.16 278)`   | `oklch(0.515 0.16 278)`  | `oklch(0.56 0.16 278)`   | Lc 76.3, 4.86:1  | Lc 70.4, 4.65:1  | pass    |\n| Iris     | dark  | `oklch(0.985 0.002 250)` | `oklch(0.85 0.074 278)`  | `oklch(0.855 0.071 278)` | `oklch(0.7 0.13 278)`    | Lc 76.2, 11.47:1 | Lc 47.9, 6.54:1  | pass    |\n| Graphite | light | `oklch(0.145 0.005 250)` | `oklch(0.269 0.007 250)` | `oklch(0.205 0.006 250)` | `oklch(0.439 0.009 250)` | Lc 98.2, 10.42:1 | Lc 83.9, 7.42:1  | pass    |\n| Graphite | dark  | `oklch(0.985 0.002 250)` | `oklch(0.929 0.004 250)` | `oklch(0.967 0.003 250)` | `oklch(0.708 0.008 250)` | Lc 81.1, 13.44:1 | Lc 50.1, 6.91:1  | pass    |\n\n### Vibes [#vibes]\n\nHeld to the standard floors: text at APCA Lc 75 and WCAG 4.5:1, boundaries and rings at Lc 45 and 3:1.\n\n| Accent   | Mode  | Action                   | Fill                     | Ink                      | Ring                     | Weakest text     | Weakest boundary | Verdict |\n| -------- | ----- | ------------------------ | ------------------------ | ------------------------ | ------------------------ | ---------------- | ---------------- | ------- |\n| Cobalt   | light | `oklch(0.56 0.158 250)`  | `oklch(0.56 0.158 250)`  | `oklch(0.5 0.142 250)`   | `oklch(0.56 0.158 250)`  | Lc 76.3, 4.65:1  | Lc 68.5, 4.45:1  | pass    |\n| Cobalt   | dark  | `oklch(0.56 0.158 250)`  | `oklch(0.56 0.158 250)`  | `oklch(0.855 0.074 250)` | `oklch(0.855 0.074 250)` | Lc 77.0, 4.65:1  | Lc 77.0, 11.62:1 | pass    |\n| Sky      | light | `oklch(0.85 0.129 212)`  | `oklch(0.85 0.129 212)`  | `oklch(0.495 0.086 212)` | `oklch(0.495 0.086 212)` | Lc 76.1, 5.69:1  | Lc 76.1, 5.69:1  | pass    |\n| Sky      | dark  | `oklch(0.85 0.129 212)`  | `oklch(0.85 0.129 212)`  | `oklch(0.835 0.142 212)` | `oklch(0.85 0.129 212)`  | Lc 76.1, 11.34:1 | Lc 78.6, 11.85:1 | pass    |\n| Jade     | light | `oklch(0.85 0.221 152)`  | `oklch(0.85 0.221 152)`  | `oklch(0.485 0.128 152)` | `oklch(0.485 0.128 152)` | Lc 76.2, 5.73:1  | Lc 76.2, 5.73:1  | pass    |\n| Jade     | dark  | `oklch(0.85 0.221 152)`  | `oklch(0.85 0.221 152)`  | `oklch(0.83 0.216 152)`  | `oklch(0.85 0.221 152)`  | Lc 77.0, 11.48:1 | Lc 81.3, 12.32:1 | pass    |\n| Volt     | light | `oklch(0.9 0.216 122)`   | `oklch(0.9 0.216 122)`   | `oklch(0.495 0.121 122)` | `oklch(0.495 0.121 122)` | Lc 76.3, 5.66:1  | Lc 76.3, 5.66:1  | pass    |\n| Volt     | dark  | `oklch(0.9 0.216 122)`   | `oklch(0.9 0.216 122)`   | `oklch(0.84 0.202 122)`  | `oklch(0.9 0.216 122)`   | Lc 76.5, 11.48:1 | Lc 88.6, 13.90:1 | pass    |\n| Rose     | light | `oklch(0.585 0.239 354)` | `oklch(0.585 0.239 354)` | `oklch(0.515 0.212 354)` | `oklch(0.585 0.239 354)` | Lc 76.1, 4.80:1  | Lc 67.7, 4.59:1  | pass    |\n| Rose     | dark  | `oklch(0.585 0.239 354)` | `oklch(0.585 0.239 354)` | `oklch(0.865 0.082 354)` | `oklch(0.865 0.082 354)` | Lc 76.3, 4.80:1  | Lc 76.7, 11.55:1 | pass    |\n| Orchid   | light | `oklch(0.59 0.273 326)`  | `oklch(0.59 0.273 326)`  | `oklch(0.52 0.241 326)`  | `oklch(0.59 0.273 326)`  | Lc 76.0, 4.78:1  | Lc 67.6, 4.57:1  | pass    |\n| Orchid   | dark  | `oklch(0.59 0.273 326)`  | `oklch(0.59 0.273 326)`  | `oklch(0.87 0.12 326)`   | `oklch(0.87 0.12 326)`   | Lc 76.2, 4.78:1  | Lc 76.8, 11.56:1 | pass    |\n| Violet   | light | `oklch(0.59 0.262 300)`  | `oklch(0.59 0.262 300)`  | `oklch(0.52 0.276 300)`  | `oklch(0.59 0.262 300)`  | Lc 76.6, 4.69:1  | Lc 68.4, 4.48:1  | pass    |\n| Violet   | dark  | `oklch(0.59 0.262 300)`  | `oklch(0.59 0.262 300)`  | `oklch(0.86 0.08 300)`   | `oklch(0.86 0.08 300)`   | Lc 76.4, 4.69:1  | Lc 76.4, 11.51:1 | pass    |\n| Iris     | light | `oklch(0.58 0.23 278)`   | `oklch(0.58 0.23 278)`   | `oklch(0.52 0.269 278)`  | `oklch(0.58 0.23 278)`   | Lc 76.8, 4.65:1  | Lc 68.6, 4.45:1  | pass    |\n| Iris     | dark  | `oklch(0.58 0.23 278)`   | `oklch(0.58 0.23 278)`   | `oklch(0.855 0.071 278)` | `oklch(0.855 0.071 278)` | Lc 76.2, 4.65:1  | Lc 76.2, 11.47:1 | pass    |\n| Graphite | light | `oklch(0.145 0.005 250)` | `oklch(0.145 0.005 250)` | `oklch(0.145 0.005 250)` | `oklch(0.439 0.009 250)` | Lc 98.2, 10.42:1 | Lc 83.9, 7.42:1  | pass    |\n| Graphite | dark  | `oklch(0.985 0.002 250)` | `oklch(0.985 0.002 250)` | `oklch(0.985 0.002 250)` | `oklch(0.871 0.005 250)` | Lc 92.0, 16.09:1 | Lc 79.8, 12.19:1 | pass    |\n\n### Stryk [#stryk]\n\nHeld to the enhanced floors: text at APCA Lc 85 and WCAG 7:1, boundaries and rings at Lc 60 and 4.5:1.\n\n| Accent   | Mode  | Action                   | Fill                     | Ink                      | Ring                     | Weakest text     | Weakest boundary  | Verdict |\n| -------- | ----- | ------------------------ | ------------------------ | ------------------------ | ------------------------ | ---------------- | ----------------- | ------- |\n| Cobalt   | light | `oklch(0.46 0.132 250)`  | `oklch(0.46 0.132 250)`  | `oklch(0.44 0.126 250)`  | `oklch(0.44 0.126 250)`  | Lc 86.4, 7.10:1  | Lc 84.0, 7.10:1   | pass    |\n| Cobalt   | dark  | `oklch(0.9 0.05 250)`    | `oklch(0.9 0.05 250)`    | `oklch(0.9 0.05 250)`    | `oklch(0.9 0.05 250)`    | Lc 86.5, 14.73:1 | Lc 86.5, 14.73:1  | pass    |\n| Sky      | light | `oklch(0.45 0.079 212)`  | `oklch(0.45 0.079 212)`  | `oklch(0.435 0.077 212)` | `oklch(0.435 0.077 212)` | Lc 86.1, 7.23:1  | Lc 84.6, 7.23:1   | pass    |\n| Sky      | dark  | `oklch(0.89 0.093 212)`  | `oklch(0.89 0.093 212)`  | `oklch(0.89 0.093 212)`  | `oklch(0.89 0.093 212)`  | Lc 86.6, 14.71:1 | Lc 86.6, 14.71:1  | pass    |\n| Jade     | light | `oklch(0.445 0.118 152)` | `oklch(0.445 0.118 152)` | `oklch(0.425 0.113 152)` | `oklch(0.425 0.113 152)` | Lc 86.7, 7.13:1  | Lc 84.2, 7.13:1   | pass    |\n| Jade     | dark  | `oklch(0.87 0.226 152)`  | `oklch(0.87 0.226 152)`  | `oklch(0.875 0.227 152)` | `oklch(0.875 0.227 152)` | Lc 86.2, 14.67:1 | Lc 86.0, 14.43:1  | pass    |\n| Volt     | light | `oklch(0.45 0.111 122)`  | `oklch(0.45 0.111 122)`  | `oklch(0.44 0.108 122)`  | `oklch(0.44 0.108 122)`  | Lc 86.1, 7.24:1  | Lc 85.0, 7.24:1   | pass    |\n| Volt     | dark  | `oklch(0.885 0.212 122)` | `oklch(0.885 0.212 122)` | `oklch(0.885 0.212 122)` | `oklch(0.885 0.212 122)` | Lc 86.1, 14.56:1 | Lc 86.1, 14.56:1  | pass    |\n| Rose     | light | `oklch(0.485 0.2 354)`   | `oklch(0.485 0.2 354)`   | `oklch(0.45 0.186 354)`  | `oklch(0.45 0.186 354)`  | Lc 86.1, 7.17:1  | Lc 82.5, 7.17:1   | pass    |\n| Rose     | dark  | `oklch(0.905 0.055 354)` | `oklch(0.905 0.055 354)` | `oklch(0.91 0.052 354)`  | `oklch(0.91 0.052 354)`  | Lc 86.2, 14.89:1 | Lc 86.0, 14.59:1  | pass    |\n| Orchid   | light | `oklch(0.49 0.228 326)`  | `oklch(0.49 0.228 326)`  | `oklch(0.455 0.212 326)` | `oklch(0.455 0.212 326)` | Lc 86.2, 7.14:1  | Lc 82.4, 7.14:1   | pass    |\n| Orchid   | dark  | `oklch(0.91 0.081 326)`  | `oklch(0.91 0.081 326)`  | `oklch(0.91 0.081 326)`  | `oklch(0.91 0.081 326)`  | Lc 86.5, 14.70:1 | Lc 86.5, 14.70:1  | pass    |\n| Violet   | light | `oklch(0.495 0.263 300)` | `oklch(0.495 0.263 300)` | `oklch(0.46 0.245 300)`  | `oklch(0.46 0.245 300)`  | Lc 86.0, 7.16:1  | Lc 82.4, 7.16:1   | pass    |\n| Violet   | dark  | `oklch(0.905 0.054 300)` | `oklch(0.905 0.054 300)` | `oklch(0.905 0.054 300)` | `oklch(0.905 0.054 300)` | Lc 86.5, 14.71:1 | Lc 86.5, 14.71:1  | pass    |\n| Iris     | light | `oklch(0.495 0.286 278)` | `oklch(0.495 0.286 278)` | `oklch(0.455 0.278 278)` | `oklch(0.455 0.278 278)` | Lc 86.5, 7.11:1  | Lc 82.7, 7.11:1   | pass    |\n| Iris     | dark  | `oklch(0.9 0.048 278)`   | `oklch(0.9 0.048 278)`   | `oklch(0.9 0.048 278)`   | `oklch(0.9 0.048 278)`   | Lc 86.2, 14.64:1 | Lc 86.2, 14.64:1  | pass    |\n| Graphite | light | `oklch(0 0 0)`           | `oklch(0 0 0)`           | `oklch(0 0 0)`           | `oklch(0 0 0)`           | Lc 98.2, 10.42:1 | Lc 106.0, 21.00:1 | pass    |\n| Graphite | dark  | `oklch(1 0 0)`           | `oklch(1 0 0)`           | `oklch(1 0 0)`           | `oklch(1 0 0)`           | Lc 92.2, 17.06:1 | Lc 107.7, 19.80:1 | pass    |\n\n{/* opsinjs:generated:end */}"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/reference/generated/contrast",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/reference/generated/contrast.md",
      "slug": [
        "reference",
        "generated",
        "contrast"
      ],
      "section": "Reference",
      "title": "Contrast",
      "description": "Measured APCA Lc and WCAG 2.2 ratios for every token pair the system defines, in both themes, dated.",
      "kind": "reference",
      "aliases": [
        "contrast measurements",
        "generated contrast",
        "Lc table"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-09-02",
      "markdown": "Measured by `scripts/check-contrast.mts` from `tokens/color.json` and `tokens/material.json`, with the hand-written maths in `lib/color/apca.ts` and `lib/color/wcag.ts`, into `lib/generated/contrast.json`. `pnpm run contrast` measures and `pnpm run contrast:verify` fails on a regression; the nightly job runs both. No figure here was typed by a person.\n\nEvery pair is measured in light and dark with both metrics: the WCAG 2.2 ratio, which a conformance claim is written against, and APCA Lc. Each verdict is against the floor for the pair's role, so body text, large text and non-text boundaries differ. `pass` clears both floors, `FAIL` is a gated pair that does not, and `advisory` is an ungated pair, such as an identity accent or a chart mark, whether or not it clears anything; do not read it as a quieter `pass`. The headline count is gated failures only. These figures describe the shipped preset, not a theme derived from your brand colour, which you measure as [Theming](../../theming.mdx) describes. [Colour](../../foundations/colour.mdx) explains the two metrics.\n\n{/* opsinjs:generated:begin - everything below is replaced by scripts/build-reference.mts */}\n\n## Measured contrast [#measured-contrast]\n\nMeasured on 2026-11-10. 244 pairs: 158 pass, 12 fail, 74 advisory, and 28 of the advisory pairs measure below the floor for their role. Advisory pairs are not gated, so none of those is a build failure; each is an accent that has to be bounded by `line` or labelled in `ink` rather than read as text.\n\n### category [#category]\n\n#### Light theme [#light-theme]\n\n| Pair                                  | Role    | APCA Lc | WCAG 2.2 | Verdict                |\n| ------------------------------------- | ------- | ------- | -------- | ---------------------- |\n| activity ink on activity surface      | body    | 88.5    | 9.61:1   | pass                   |\n| activity line on activity surface     | nonText | 67.6    | 4.42:1   | pass                   |\n| activity accent on activity surface   | nonText | 44.1    | 2.34:1   | advisory - below floor |\n| activity accent on the page           | nonText | 46.1    | 2.41:1   | advisory - below floor |\n| activity ink on the page              | body    | 90.5    | 9.90:1   | pass                   |\n| activity line on the band             | nonText | 66.1    | 4.32:1   | pass                   |\n| heart ink on heart surface            | body    | 89.1    | 10.51:1  | pass                   |\n| heart line on heart surface           | nonText | 70.4    | 5.05:1   | pass                   |\n| heart accent on heart surface         | nonText | 60.3    | 3.64:1   | advisory               |\n| heart accent on the page              | nonText | 63.2    | 3.81:1   | advisory               |\n| heart ink on the page                 | body    | 92.0    | 10.97:1  | pass                   |\n| heart line on the band                | nonText | 69.9    | 5.01:1   | pass                   |\n| labs ink on labs surface              | body    | 88.8    | 9.78:1   | pass                   |\n| labs line on labs surface             | nonText | 67.9    | 4.51:1   | pass                   |\n| labs accent on labs surface           | nonText | 59.3    | 3.49:1   | advisory               |\n| labs accent on the page               | nonText | 61.5    | 3.60:1   | advisory               |\n| labs ink on the page                  | body    | 90.9    | 10.09:1  | pass                   |\n| labs line on the band                 | nonText | 66.5    | 4.42:1   | pass                   |\n| mind ink on mind surface              | body    | 89.9    | 10.36:1  | pass                   |\n| mind line on mind surface             | nonText | 70.7    | 4.94:1   | pass                   |\n| mind accent on mind surface           | nonText | 60.0    | 3.55:1   | advisory               |\n| mind accent on the page               | nonText | 62.8    | 3.70:1   | advisory               |\n| mind ink on the page                  | body    | 92.7    | 10.80:1  | pass                   |\n| mind line on the band                 | nonText | 70.0    | 4.89:1   | pass                   |\n| nutrition ink on nutrition surface    | body    | 89.3    | 10.06:1  | pass                   |\n| nutrition line on nutrition surface   | nonText | 69.7    | 4.78:1   | pass                   |\n| nutrition accent on nutrition surface | nonText | 39.2    | 2.11:1   | advisory - below floor |\n| nutrition accent on the page          | nonText | 41.8    | 2.19:1   | advisory - below floor |\n| nutrition ink on the page             | body    | 91.9    | 10.44:1  | pass                   |\n| nutrition line on the band            | nonText | 68.8    | 4.71:1   | pass                   |\n| sleep ink on sleep surface            | body    | 89.6    | 10.19:1  | pass                   |\n| sleep line on sleep surface           | nonText | 70.0    | 4.80:1   | pass                   |\n| sleep accent on sleep surface         | nonText | 64.6    | 4.05:1   | advisory               |\n| sleep accent on the page              | nonText | 67.3    | 4.22:1   | advisory               |\n| sleep ink on the page                 | body    | 92.3    | 10.60:1  | pass                   |\n| sleep line on the band                | nonText | 69.1    | 4.75:1   | pass                   |\n| activity ink on the card material     | body    | 93.6    | 10.34:1  | pass                   |\n| heart ink on the card material        | body    | 95.1    | 11.47:1  | pass                   |\n| labs ink on the card material         | body    | 94.0    | 10.54:1  | pass                   |\n| mind ink on the card material         | body    | 95.7    | 11.28:1  | pass                   |\n| nutrition ink on the card material    | body    | 95.0    | 10.91:1  | pass                   |\n| sleep ink on the card material        | body    | 95.4    | 11.08:1  | pass                   |\n\n#### Dark theme [#dark-theme]\n\n| Pair                                  | Role    | APCA Lc | WCAG 2.2 | Verdict  |\n| ------------------------------------- | ------- | ------- | -------- | -------- |\n| activity ink on activity surface      | body    | -83.1   | 12.58:1  | pass     |\n| activity line on activity surface     | nonText | -69.0   | 9.93:1   | pass     |\n| activity accent on activity surface   | nonText | -53.3   | 7.26:1   | advisory |\n| activity accent on the page           | nonText | -54.6   | 8.22:1   | advisory |\n| activity ink on the page              | body    | -84.4   | 14.24:1  | pass     |\n| activity line on the band             | nonText | -67.4   | 8.60:1   | pass     |\n| heart ink on heart surface            | body    | -80.5   | 12.55:1  | pass     |\n| heart line on heart surface           | nonText | -64.5   | 9.46:1   | pass     |\n| heart accent on heart surface         | nonText | -48.2   | 6.68:1   | advisory |\n| heart accent on the page              | nonText | -49.5   | 7.27:1   | advisory |\n| heart ink on the page                 | body    | -81.8   | 13.65:1  | pass     |\n| heart line on the band                | nonText | -62.8   | 7.88:1   | pass     |\n| labs ink on labs surface              | body    | -83.1   | 12.69:1  | pass     |\n| labs line on labs surface             | nonText | -68.4   | 9.90:1   | pass     |\n| labs accent on labs surface           | nonText | -52.7   | 7.21:1   | advisory |\n| labs accent on the page               | nonText | -53.9   | 8.07:1   | advisory |\n| labs ink on the page                  | body    | -84.3   | 14.22:1  | pass     |\n| labs line on the band                 | nonText | -66.7   | 8.49:1   | pass     |\n| mind ink on mind surface              | body    | -81.3   | 12.56:1  | pass     |\n| mind line on mind surface             | nonText | -65.4   | 9.54:1   | pass     |\n| mind accent on mind surface           | nonText | -49.1   | 6.77:1   | advisory |\n| mind accent on the page               | nonText | -50.0   | 7.42:1   | advisory |\n| mind ink on the page                  | body    | -82.2   | 13.77:1  | pass     |\n| mind line on the band                 | nonText | -63.4   | 8.00:1   | pass     |\n| nutrition ink on nutrition surface    | body    | -81.9   | 12.55:1  | pass     |\n| nutrition line on nutrition surface   | nonText | -66.7   | 9.66:1   | pass     |\n| nutrition accent on nutrition surface | nonText | -50.2   | 6.88:1   | advisory |\n| nutrition accent on the page          | nonText | -51.3   | 7.63:1   | advisory |\n| nutrition ink on the page             | body    | -82.9   | 13.91:1  | pass     |\n| nutrition line on the band            | nonText | -64.8   | 8.19:1   | pass     |\n| sleep ink on sleep surface            | body    | -81.9   | 12.60:1  | pass     |\n| sleep line on sleep surface           | nonText | -66.4   | 9.65:1   | pass     |\n| sleep accent on sleep surface         | nonText | -50.4   | 6.94:1   | advisory |\n| sleep accent on the page              | nonText | -51.4   | 7.67:1   | advisory |\n| sleep ink on the page                 | body    | -82.9   | 13.92:1  | pass     |\n| sleep line on the band                | nonText | -64.5   | 8.16:1   | pass     |\n| activity ink on the card material     | body    | -83.5   | 12.91:1  | pass     |\n| heart ink on the card material        | body    | -80.9   | 12.38:1  | pass     |\n| labs ink on the card material         | body    | -83.5   | 12.90:1  | pass     |\n| mind ink on the card material         | body    | -81.4   | 12.49:1  | pass     |\n| nutrition ink on the card material    | body    | -82.0   | 12.61:1  | pass     |\n| sleep ink on the card material        | body    | -82.1   | 12.62:1  | pass     |\n\n### status [#status]\n\n#### Light theme [#light-theme-1]\n\n| Pair                                         | Role    | APCA Lc | WCAG 2.2 | Verdict                |\n| -------------------------------------------- | ------- | ------- | -------- | ---------------------- |\n| attention ink on attention surface           | body    | 89.4    | 10.35:1  | pass                   |\n| attention line on attention surface          | nonText | 70.0    | 4.90:1   | pass                   |\n| attention accent on attention surface        | nonText | 65.1    | 4.18:1   | advisory               |\n| attention ink on the attention band          | nonText | 22.4    | 2.48:1   | FAIL                   |\n| attention accent on the page                 | nonText | 67.8    | 4.35:1   | advisory               |\n| attention ink on the page                    | body    | 92.2    | 10.77:1  | pass                   |\n| steady ink on steady surface                 | body    | 88.3    | 9.62:1   | pass                   |\n| steady line on steady surface                | nonText | 67.5    | 4.45:1   | pass                   |\n| steady accent on steady surface              | nonText | 56.4    | 3.21:1   | advisory               |\n| steady ink on the steady band                | nonText | 30.0    | 3.00:1   | FAIL                   |\n| steady accent on the page                    | nonText | 58.6    | 3.31:1   | advisory               |\n| steady ink on the page                       | body    | 90.6    | 9.94:1   | pass                   |\n| unknown ink on unknown surface               | body    | 89.5    | 9.98:1   | pass                   |\n| unknown line on unknown surface              | nonText | 69.2    | 4.64:1   | pass                   |\n| unknown accent on unknown surface            | nonText | 43.1    | 2.29:1   | advisory - below floor |\n| unknown accent on the page                   | nonText | 45.6    | 2.37:1   | advisory - below floor |\n| unknown ink on the page                      | body    | 92.0    | 10.34:1  | pass                   |\n| urgent ink on urgent surface                 | body    | 88.2    | 10.58:1  | pass                   |\n| urgent line on urgent surface                | nonText | 70.0    | 5.09:1   | pass                   |\n| urgent accent on urgent surface              | nonText | 72.3    | 5.58:1   | advisory               |\n| urgent ink on the urgent band                | nonText | 13.9    | 1.90:1   | FAIL                   |\n| urgent accent on the page                    | nonText | 75.3    | 5.84:1   | advisory               |\n| urgent ink on the page                       | body    | 91.2    | 11.06:1  | pass                   |\n| watch ink on watch surface                   | body    | 89.4    | 10.02:1  | pass                   |\n| watch line on watch surface                  | nonText | 69.5    | 4.72:1   | pass                   |\n| watch accent on watch surface                | nonText | 61.7    | 3.72:1   | advisory               |\n| watch ink on the watch band                  | nonText | 25.7    | 2.70:1   | FAIL                   |\n| watch accent on the page                     | nonText | 64.2    | 3.85:1   | advisory               |\n| watch ink on the page                        | body    | 91.9    | 10.38:1  | pass                   |\n| attention surface on the card material       | nonText | 0.0     | 1.09:1   | advisory - below floor |\n| steady surface on the card material          | nonText | 0.0     | 1.08:1   | advisory - below floor |\n| urgent surface on the card material          | nonText | 0.0     | 1.09:1   | advisory - below floor |\n| watch surface on the card material           | nonText | 0.0     | 1.08:1   | advisory - below floor |\n| the focus ring on the attention surface      | nonText | 69.5    | 4.83:1   | advisory               |\n| attention ink on the neutral hover fill      | body    | 88.6    | 10.23:1  | pass                   |\n| the focus ring on the steady surface         | nonText | 70.0    | 4.86:1   | advisory               |\n| steady ink on the neutral hover fill         | body    | 87.0    | 9.43:1   | pass                   |\n| the focus ring on the urgent surface         | nonText | 69.3    | 4.81:1   | advisory               |\n| urgent ink on the neutral hover fill         | body    | 87.7    | 10.50:1  | pass                   |\n| the focus ring on the watch surface          | nonText | 69.8    | 4.85:1   | advisory               |\n| watch ink on the neutral hover fill          | body    | 88.3    | 9.86:1   | pass                   |\n| steady plate word on the plate's face        | body    | -83.2   | 5.69:1   | pass                   |\n| steady plate word on the plate's lit band    | body    | -78.1   | 4.77:1   | pass                   |\n| watch plate word on the plate's face         | body    | 76.4    | 11.33:1  | pass                   |\n| watch plate word on the plate's lit band     | body    | 81.9    | 12.50:1  | pass                   |\n| attention plate word on the plate's face     | body    | -81.4   | 5.43:1   | pass                   |\n| attention plate word on the plate's lit band | body    | -77.0   | 4.66:1   | pass                   |\n| urgent plate word on the plate's face        | body    | -85.9   | 6.63:1   | pass                   |\n| urgent plate word on the plate's lit band    | body    | -81.7   | 5.59:1   | pass                   |\n\n#### Dark theme [#dark-theme-1]\n\n| Pair                                         | Role    | APCA Lc | WCAG 2.2 | Verdict                |\n| -------------------------------------------- | ------- | ------- | -------- | ---------------------- |\n| attention ink on attention surface           | body    | -81.1   | 12.54:1  | pass                   |\n| attention line on attention surface          | nonText | -65.5   | 9.54:1   | pass                   |\n| attention accent on attention surface        | nonText | -49.4   | 6.80:1   | advisory               |\n| attention ink on the attention band          | nonText | -31.0   | 1.84:1   | FAIL                   |\n| attention accent on the page                 | nonText | -50.5   | 7.47:1   | advisory               |\n| attention ink on the page                    | body    | -82.3   | 13.76:1  | pass                   |\n| steady ink on steady surface                 | body    | -82.9   | 12.56:1  | pass                   |\n| steady line on steady surface                | nonText | -68.9   | 9.91:1   | pass                   |\n| steady accent on steady surface              | nonText | -53.2   | 7.25:1   | advisory               |\n| steady ink on the steady band                | nonText | -28.8   | 1.73:1   | FAIL                   |\n| steady accent on the page                    | nonText | -54.5   | 8.19:1   | advisory               |\n| steady ink on the page                       | body    | -84.2   | 14.20:1  | pass                   |\n| unknown ink on unknown surface               | body    | -82.2   | 12.56:1  | pass                   |\n| unknown line on unknown surface              | nonText | -67.2   | 9.72:1   | pass                   |\n| unknown accent on unknown surface            | nonText | -51.3   | 7.05:1   | advisory               |\n| unknown accent on the page                   | nonText | -52.3   | 7.84:1   | advisory               |\n| unknown ink on the page                      | body    | -83.1   | 13.97:1  | pass                   |\n| urgent ink on urgent surface                 | body    | -80.3   | 12.52:1  | pass                   |\n| urgent line on urgent surface                | nonText | -64.8   | 9.52:1   | pass                   |\n| urgent accent on urgent surface              | nonText | -48.0   | 6.63:1   | advisory               |\n| urgent ink on the urgent band                | nonText | -31.5   | 1.89:1   | FAIL                   |\n| urgent accent on the page                    | nonText | -49.5   | 7.24:1   | advisory               |\n| urgent ink on the page                       | body    | -81.8   | 13.66:1  | pass                   |\n| watch ink on watch surface                   | body    | -82.1   | 12.58:1  | pass                   |\n| watch line on watch surface                  | nonText | -66.8   | 9.68:1   | pass                   |\n| watch accent on watch surface                | nonText | -50.7   | 6.95:1   | advisory               |\n| watch ink on the watch band                  | nonText | -30.6   | 1.81:1   | FAIL                   |\n| watch accent on the page                     | nonText | -51.7   | 7.71:1   | advisory               |\n| watch ink on the page                        | body    | -83.1   | 13.95:1  | pass                   |\n| attention surface on the card material       | nonText | 0.0     | 1.00:1   | advisory - below floor |\n| steady surface on the card material          | nonText | 0.0     | 1.03:1   | advisory - below floor |\n| urgent surface on the card material          | nonText | 0.0     | 1.01:1   | advisory - below floor |\n| watch surface on the card material           | nonText | 0.0     | 1.01:1   | advisory - below floor |\n| the focus ring on the attention surface      | nonText | -57.5   | 8.14:1   | advisory               |\n| attention ink on the neutral hover fill      | body    | -79.3   | 10.53:1  | pass                   |\n| the focus ring on the steady surface         | nonText | -57.3   | 7.91:1   | advisory               |\n| steady ink on the neutral hover fill         | body    | -81.3   | 10.86:1  | pass                   |\n| the focus ring on the urgent surface         | nonText | -57.1   | 8.19:1   | advisory               |\n| urgent ink on the neutral hover fill         | body    | -78.9   | 10.46:1  | pass                   |\n| the focus ring on the watch surface          | nonText | -57.6   | 8.07:1   | advisory               |\n| watch ink on the neutral hover fill          | body    | -80.1   | 10.67:1  | pass                   |\n| steady plate word on the plate's face        | body    | -83.2   | 5.69:1   | pass                   |\n| steady plate word on the plate's lit band    | body    | -78.1   | 4.77:1   | pass                   |\n| watch plate word on the plate's face         | body    | 76.4    | 11.33:1  | pass                   |\n| watch plate word on the plate's lit band     | body    | 81.9    | 12.50:1  | pass                   |\n| attention plate word on the plate's face     | body    | -81.4   | 5.43:1   | pass                   |\n| attention plate word on the plate's lit band | body    | -77.0   | 4.66:1   | pass                   |\n| urgent plate word on the plate's face        | body    | -85.9   | 6.63:1   | pass                   |\n| urgent plate word on the plate's lit band    | body    | -81.7   | 5.59:1   | pass                   |\n\n### surfaces [#surfaces]\n\n#### Light theme [#light-theme-2]\n\n| Pair                      | Role    | APCA Lc | WCAG 2.2 | Verdict                |\n| ------------------------- | ------- | ------- | -------- | ---------------------- |\n| the band fill on the page | nonText | 0.0     | 1.05:1   | advisory - below floor |\n| the band edge on the page | nonText | 83.9    | 7.42:1   | pass                   |\n| the band edge on the band | nonText | 80.4    | 7.05:1   | pass                   |\n\n#### Dark theme [#dark-theme-2]\n\n| Pair                      | Role    | APCA Lc | WCAG 2.2 | Verdict                |\n| ------------------------- | ------- | ------- | -------- | ---------------------- |\n| the band fill on the page | nonText | 0.0     | 1.31:1   | advisory - below floor |\n| the band edge on the page | nonText | -80.7   | 13.44:1  | pass                   |\n| the band edge on the band | nonText | -77.8   | 10.28:1  | pass                   |\n\n### neutral [#neutral]\n\n#### Light theme [#light-theme-3]\n\n| Pair                                       | Role    | APCA Lc | WCAG 2.2 | Verdict                |\n| ------------------------------------------ | ------- | ------- | -------- | ---------------------- |\n| body text on the page                      | body    | 101.6   | 17.18:1  | pass                   |\n| body text on a card                        | body    | 104.7   | 17.96:1  | pass                   |\n| body text on the muted ground              | body    | 98.1    | 16.32:1  | pass                   |\n| secondary text on the page                 | body    | 83.9    | 7.42:1   | pass                   |\n| secondary text on a card                   | body    | 87.0    | 7.76:1   | pass                   |\n| secondary text on the muted ground         | body    | 80.4    | 7.05:1   | pass                   |\n| a hairline boundary on the page            | nonText | 19.3    | 1.41:1   | advisory - below floor |\n| a hairline boundary on a card              | nonText | 22.4    | 1.47:1   | advisory - below floor |\n| a hairline boundary on the muted ground    | nonText | 15.8    | 1.34:1   | advisory - below floor |\n| a placeholder boundary on the page         | nonText | 69.8    | 4.52:1   | pass                   |\n| a placeholder boundary on a card           | nonText | 72.8    | 4.72:1   | pass                   |\n| a placeholder boundary on the muted ground | nonText | 66.2    | 4.29:1   | pass                   |\n| a placeholder fill on the page             | nonText | 8.3     | 1.18:1   | advisory - below floor |\n| a placeholder fill on a card               | nonText | 11.4    | 1.23:1   | advisory - below floor |\n| a placeholder fill on the muted ground     | nonText | 0.0     | 1.12:1   | advisory - below floor |\n| a placeholder boundary on its own fill     | nonText | 58.9    | 3.84:1   | pass                   |\n| the card hairline on the page              | nonText | 69.8    | 4.52:1   | pass                   |\n| the card hairline on a card                | nonText | 72.8    | 4.72:1   | pass                   |\n\n#### Dark theme [#dark-theme-3]\n\n| Pair                                       | Role    | APCA Lc | WCAG 2.2 | Verdict                |\n| ------------------------------------------ | ------- | ------- | -------- | ---------------------- |\n| body text on the page                      | body    | -100.5  | 18.00:1  | pass                   |\n| body text on a card                        | body    | -99.6   | 16.32:1  | pass                   |\n| body text on the muted ground              | body    | -97.5   | 13.77:1  | pass                   |\n| secondary text on the page                 | body    | -80.7   | 13.44:1  | pass                   |\n| secondary text on a card                   | body    | -79.8   | 12.19:1  | pass                   |\n| secondary text on the muted ground         | body    | -77.8   | 10.28:1  | pass                   |\n| a hairline boundary on the page            | nonText | -8.2    | 1.90:1   | advisory - below floor |\n| a hairline boundary on a card              | nonText | -7.3    | 1.72:1   | advisory - below floor |\n| a hairline boundary on the muted ground    | nonText | 0.0     | 1.45:1   | advisory - below floor |\n| a placeholder boundary on the page         | nonText | -51.0   | 7.62:1   | pass                   |\n| a placeholder boundary on a card           | nonText | -50.1   | 6.91:1   | pass                   |\n| a placeholder boundary on the muted ground | nonText | -48.1   | 5.83:1   | pass                   |\n| a placeholder fill on the page             | nonText | -8.2    | 1.90:1   | advisory - below floor |\n| a placeholder fill on a card               | nonText | -7.3    | 1.72:1   | advisory - below floor |\n| a placeholder fill on the muted ground     | nonText | 0.0     | 1.45:1   | advisory - below floor |\n| a placeholder boundary on its own fill     | nonText | -41.5   | 4.01:1   | FAIL                   |\n| the card hairline on the page              | nonText | -28.7   | 4.19:1   | FAIL                   |\n| the card hairline on a card                | nonText | -27.9   | 3.80:1   | FAIL                   |\n\n### chrome [#chrome]\n\n#### Light theme [#light-theme-4]\n\n| Pair                       | Role    | APCA Lc | WCAG 2.2 | Verdict |\n| -------------------------- | ------- | ------- | -------- | ------- |\n| the focus ring on the page | nonText | 72.3    | 5.02:1   | pass    |\n| the focus ring on a card   | nonText | 75.3    | 5.25:1   | pass    |\n\n#### Dark theme [#dark-theme-4]\n\n| Pair                       | Role    | APCA Lc | WCAG 2.2 | Verdict |\n| -------------------------- | ------- | ------- | -------- | ------- |\n| the focus ring on the page | nonText | -58.6   | 8.94:1   | pass    |\n| the focus ring on a card   | nonText | -57.7   | 8.11:1   | pass    |\n\n### materials [#materials]\n\n#### Light theme [#light-theme-5]\n\n| Pair                                                         | Role | APCA Lc | WCAG 2.2 | Verdict |\n| ------------------------------------------------------------ | ---- | ------- | -------- | ------- |\n| body text on the canvas material                             | body | 104.7   | 17.96:1  | pass    |\n| body text on the inset material                              | body | 98.1    | 16.32:1  | pass    |\n| body text on the card material                               | body | 104.7   | 17.96:1  | pass    |\n| body text on the raised material                             | body | 104.7   | 17.96:1  | pass    |\n| body text on the sheet material over the darkest backdrop    | body | 99.9    | 16.76:1  | pass    |\n| body text on the sheet material over the lightest backdrop   | body | 104.7   | 17.96:1  | pass    |\n| body text on the overlay material over the darkest backdrop  | body | 85.9    | 13.48:1  | pass    |\n| body text on the overlay material over the lightest backdrop | body | 104.7   | 17.96:1  | pass    |\n\n#### Dark theme [#dark-theme-5]\n\n| Pair                                                         | Role | APCA Lc | WCAG 2.2 | Verdict |\n| ------------------------------------------------------------ | ---- | ------- | -------- | ------- |\n| body text on the canvas material                             | body | -100.5  | 18.00:1  | pass    |\n| body text on the inset material                              | body | -100.1  | 17.18:1  | pass    |\n| body text on the card material                               | body | -99.6   | 16.32:1  | pass    |\n| body text on the raised material                             | body | -97.5   | 13.77:1  | pass    |\n| body text on the sheet material over the darkest backdrop    | body | -99.7   | 16.47:1  | pass    |\n| body text on the sheet material over the lightest backdrop   | body | -80.8   | 6.07:1   | pass    |\n| body text on the overlay material over the darkest backdrop  | body | -99.9   | 16.77:1  | pass    |\n| body text on the overlay material over the lightest backdrop | body | -54.2   | 2.69:1   | FAIL    |\n\n## Colour-vision audit [#colour-vision-audit]\n\nPairs that fall below Lc 15 as flat fills - that is, pairs a reader with this form of colour vision cannot tell apart by colour alone.\n\n| Axis     | Simulation   | Pair                                   | Lc   |\n| -------- | ------------ | -------------------------------------- | ---- |\n| status   | protanopia   | steady-surface and watch-surface       | 0.0  |\n| status   | protanopia   | steady-surface and attention-surface   | 0.0  |\n| status   | protanopia   | steady-surface and urgent-surface      | 0.0  |\n| status   | protanopia   | steady-surface and unknown-surface     | 0.0  |\n| status   | protanopia   | steady-line and steady-accent          | 9.6  |\n| status   | protanopia   | steady-line and watch-line             | 0.0  |\n| status   | protanopia   | steady-line and watch-accent           | 0.0  |\n| status   | protanopia   | steady-line and attention-line         | 12.1 |\n| status   | protanopia   | steady-line and attention-accent       | 7.8  |\n| status   | protanopia   | steady-line and unknown-line           | 0.0  |\n| status   | protanopia   | steady-ink and watch-line              | 13.3 |\n| status   | protanopia   | steady-ink and watch-ink               | 0.0  |\n| status   | protanopia   | steady-ink and attention-line          | 7.5  |\n| status   | protanopia   | steady-ink and attention-ink           | 0.0  |\n| status   | protanopia   | steady-ink and attention-accent        | 12.1 |\n| status   | protanopia   | steady-ink and urgent-line             | 0.0  |\n| status   | protanopia   | steady-ink and urgent-ink              | 0.0  |\n| status   | protanopia   | steady-ink and urgent-accent           | 0.0  |\n| status   | protanopia   | steady-ink and unknown-ink             | 0.0  |\n| status   | protanopia   | steady-accent and watch-accent         | 10.9 |\n| status   | protanopia   | steady-accent and unknown-accent       | 8.1  |\n| status   | protanopia   | watch-surface and attention-surface    | 0.0  |\n| status   | protanopia   | watch-surface and urgent-surface       | 0.0  |\n| status   | protanopia   | watch-surface and unknown-surface      | 0.0  |\n| status   | protanopia   | watch-line and watch-accent            | 0.0  |\n| status   | protanopia   | watch-line and attention-line          | 0.0  |\n| status   | protanopia   | watch-line and attention-accent        | 0.0  |\n| status   | protanopia   | watch-line and urgent-line             | 9.3  |\n| status   | protanopia   | watch-line and urgent-accent           | 12.2 |\n| status   | protanopia   | watch-line and unknown-line            | 0.0  |\n| status   | protanopia   | watch-ink and attention-line           | 11.2 |\n| status   | protanopia   | watch-ink and attention-ink            | 0.0  |\n| status   | protanopia   | watch-ink and urgent-line              | 0.0  |\n| status   | protanopia   | watch-ink and urgent-ink               | 0.0  |\n| status   | protanopia   | watch-ink and urgent-accent            | 0.0  |\n| status   | protanopia   | watch-ink and unknown-ink              | 0.0  |\n| status   | protanopia   | watch-accent and attention-line        | 12.1 |\n| status   | protanopia   | watch-accent and attention-accent      | 7.7  |\n| status   | protanopia   | watch-accent and unknown-line          | 0.0  |\n| status   | protanopia   | attention-surface and urgent-surface   | 0.0  |\n| status   | protanopia   | attention-surface and unknown-surface  | 0.0  |\n| status   | protanopia   | attention-line and attention-ink       | 13.5 |\n| status   | protanopia   | attention-line and attention-accent    | 0.0  |\n| status   | protanopia   | attention-line and urgent-line         | 0.0  |\n| status   | protanopia   | attention-line and urgent-accent       | 0.0  |\n| status   | protanopia   | attention-line and unknown-line        | 0.0  |\n| status   | protanopia   | attention-line and unknown-ink         | 9.7  |\n| status   | protanopia   | attention-ink and urgent-line          | 9.1  |\n| status   | protanopia   | attention-ink and urgent-ink           | 0.0  |\n| status   | protanopia   | attention-ink and urgent-accent        | 0.0  |\n| status   | protanopia   | attention-ink and unknown-ink          | 0.0  |\n| status   | protanopia   | attention-accent and urgent-line       | 8.2  |\n| status   | protanopia   | attention-accent and urgent-accent     | 11.0 |\n| status   | protanopia   | attention-accent and unknown-line      | 0.0  |\n| status   | protanopia   | attention-accent and unknown-ink       | 14.1 |\n| status   | protanopia   | urgent-surface and unknown-surface     | 0.0  |\n| status   | protanopia   | urgent-line and urgent-ink             | 11.0 |\n| status   | protanopia   | urgent-line and urgent-accent          | 0.0  |\n| status   | protanopia   | urgent-line and unknown-line           | 11.6 |\n| status   | protanopia   | urgent-line and unknown-ink            | 0.0  |\n| status   | protanopia   | urgent-ink and urgent-accent           | 8.7  |\n| status   | protanopia   | urgent-ink and unknown-ink             | 0.0  |\n| status   | protanopia   | urgent-accent and unknown-line         | 14.7 |\n| status   | protanopia   | urgent-accent and unknown-ink          | 0.0  |\n| status   | deuteranopia | steady-surface and watch-surface       | 0.0  |\n| status   | deuteranopia | steady-surface and attention-surface   | 0.0  |\n| status   | deuteranopia | steady-surface and urgent-surface      | 0.0  |\n| status   | deuteranopia | steady-surface and unknown-surface     | 0.0  |\n| status   | deuteranopia | steady-line and steady-accent          | 8.7  |\n| status   | deuteranopia | steady-line and watch-line             | 0.0  |\n| status   | deuteranopia | steady-line and watch-accent           | 7.6  |\n| status   | deuteranopia | steady-line and attention-line         | 0.0  |\n| status   | deuteranopia | steady-line and attention-accent       | 0.0  |\n| status   | deuteranopia | steady-line and urgent-line            | 0.0  |\n| status   | deuteranopia | steady-line and urgent-accent          | 0.0  |\n| status   | deuteranopia | steady-line and unknown-line           | 0.0  |\n| status   | deuteranopia | steady-ink and watch-ink               | 0.0  |\n| status   | deuteranopia | steady-ink and attention-ink           | 0.0  |\n| status   | deuteranopia | steady-ink and urgent-ink              | 0.0  |\n| status   | deuteranopia | steady-ink and unknown-ink             | 0.0  |\n| status   | deuteranopia | steady-accent and watch-line           | 8.5  |\n| status   | deuteranopia | steady-accent and watch-accent         | 0.0  |\n| status   | deuteranopia | steady-accent and attention-line       | 8.0  |\n| status   | deuteranopia | steady-accent and attention-accent     | 0.0  |\n| status   | deuteranopia | steady-accent and urgent-line          | 8.0  |\n| status   | deuteranopia | steady-accent and urgent-accent        | 10.2 |\n| status   | deuteranopia | steady-accent and unknown-line         | 10.0 |\n| status   | deuteranopia | steady-accent and unknown-accent       | 13.4 |\n| status   | deuteranopia | watch-surface and attention-surface    | 0.0  |\n| status   | deuteranopia | watch-surface and urgent-surface       | 0.0  |\n| status   | deuteranopia | watch-surface and unknown-surface      | 0.0  |\n| status   | deuteranopia | watch-line and watch-accent            | 0.0  |\n| status   | deuteranopia | watch-line and attention-line          | 0.0  |\n| status   | deuteranopia | watch-line and attention-accent        | 0.0  |\n| status   | deuteranopia | watch-line and urgent-line             | 0.0  |\n| status   | deuteranopia | watch-line and urgent-accent           | 0.0  |\n| status   | deuteranopia | watch-line and unknown-line            | 0.0  |\n| status   | deuteranopia | watch-ink and attention-ink            | 0.0  |\n| status   | deuteranopia | watch-ink and urgent-ink               | 0.0  |\n| status   | deuteranopia | watch-ink and unknown-ink              | 0.0  |\n| status   | deuteranopia | watch-accent and attention-line        | 0.0  |\n| status   | deuteranopia | watch-accent and attention-accent      | 0.0  |\n| status   | deuteranopia | watch-accent and urgent-line           | 0.0  |\n| status   | deuteranopia | watch-accent and urgent-accent         | 9.0  |\n| status   | deuteranopia | watch-accent and unknown-line          | 8.8  |\n| status   | deuteranopia | watch-accent and unknown-accent        | 14.6 |\n| status   | deuteranopia | attention-surface and urgent-surface   | 0.0  |\n| status   | deuteranopia | attention-surface and unknown-surface  | 0.0  |\n| status   | deuteranopia | attention-line and attention-accent    | 0.0  |\n| status   | deuteranopia | attention-line and urgent-line         | 0.0  |\n| status   | deuteranopia | attention-line and urgent-accent       | 0.0  |\n| status   | deuteranopia | attention-line and unknown-line        | 0.0  |\n| status   | deuteranopia | attention-ink and urgent-ink           | 0.0  |\n| status   | deuteranopia | attention-ink and unknown-ink          | 0.0  |\n| status   | deuteranopia | attention-accent and urgent-line       | 0.0  |\n| status   | deuteranopia | attention-accent and urgent-accent     | 0.0  |\n| status   | deuteranopia | attention-accent and unknown-line      | 0.0  |\n| status   | deuteranopia | urgent-surface and unknown-surface     | 0.0  |\n| status   | deuteranopia | urgent-line and urgent-accent          | 0.0  |\n| status   | deuteranopia | urgent-line and unknown-line           | 0.0  |\n| status   | deuteranopia | urgent-ink and unknown-ink             | 0.0  |\n| status   | deuteranopia | urgent-accent and unknown-line         | 0.0  |\n| status   | tritanopia   | steady-surface and watch-surface       | 0.0  |\n| status   | tritanopia   | steady-surface and attention-surface   | 0.0  |\n| status   | tritanopia   | steady-surface and urgent-surface      | 0.0  |\n| status   | tritanopia   | steady-surface and unknown-surface     | 0.0  |\n| status   | tritanopia   | steady-line and steady-accent          | 0.0  |\n| status   | tritanopia   | steady-line and watch-line             | 0.0  |\n| status   | tritanopia   | steady-line and watch-accent           | 10.3 |\n| status   | tritanopia   | steady-line and attention-line         | 7.4  |\n| status   | tritanopia   | steady-line and attention-ink          | 14.1 |\n| status   | tritanopia   | steady-line and attention-accent       | 13.6 |\n| status   | tritanopia   | steady-line and urgent-line            | 11.7 |\n| status   | tritanopia   | steady-line and urgent-ink             | 11.3 |\n| status   | tritanopia   | steady-line and urgent-accent          | 9.3  |\n| status   | tritanopia   | steady-line and unknown-line           | 0.0  |\n| status   | tritanopia   | steady-ink and watch-ink               | 0.0  |\n| status   | tritanopia   | steady-ink and attention-ink           | 0.0  |\n| status   | tritanopia   | steady-ink and urgent-ink              | 0.0  |\n| status   | tritanopia   | steady-ink and unknown-ink             | 0.0  |\n| status   | tritanopia   | steady-accent and watch-line           | 0.0  |\n| status   | tritanopia   | steady-accent and watch-accent         | 0.0  |\n| status   | tritanopia   | steady-accent and attention-line       | 0.0  |\n| status   | tritanopia   | steady-accent and attention-accent     | 0.0  |\n| status   | tritanopia   | steady-accent and urgent-line          | 0.0  |\n| status   | tritanopia   | steady-accent and urgent-accent        | 0.0  |\n| status   | tritanopia   | steady-accent and unknown-line         | 9.4  |\n| status   | tritanopia   | steady-accent and unknown-accent       | 13.8 |\n| status   | tritanopia   | watch-surface and attention-surface    | 0.0  |\n| status   | tritanopia   | watch-surface and urgent-surface       | 0.0  |\n| status   | tritanopia   | watch-surface and unknown-surface      | 0.0  |\n| status   | tritanopia   | watch-line and watch-accent            | 0.0  |\n| status   | tritanopia   | watch-line and attention-line          | 0.0  |\n| status   | tritanopia   | watch-line and attention-accent        | 10.2 |\n| status   | tritanopia   | watch-line and urgent-line             | 8.3  |\n| status   | tritanopia   | watch-line and urgent-ink              | 14.7 |\n| status   | tritanopia   | watch-line and urgent-accent           | 0.0  |\n| status   | tritanopia   | watch-line and unknown-line            | 0.0  |\n| status   | tritanopia   | watch-ink and attention-ink            | 0.0  |\n| status   | tritanopia   | watch-ink and urgent-ink               | 0.0  |\n| status   | tritanopia   | watch-ink and unknown-ink              | 0.0  |\n| status   | tritanopia   | watch-accent and attention-line        | 0.0  |\n| status   | tritanopia   | watch-accent and attention-accent      | 0.0  |\n| status   | tritanopia   | watch-accent and urgent-line           | 0.0  |\n| status   | tritanopia   | watch-accent and urgent-accent         | 0.0  |\n| status   | tritanopia   | watch-accent and unknown-line          | 12.6 |\n| status   | tritanopia   | watch-accent and unknown-accent        | 10.5 |\n| status   | tritanopia   | attention-surface and urgent-surface   | 0.0  |\n| status   | tritanopia   | attention-surface and unknown-surface  | 0.0  |\n| status   | tritanopia   | attention-line and attention-accent    | 0.0  |\n| status   | tritanopia   | attention-line and urgent-line         | 0.0  |\n| status   | tritanopia   | attention-line and urgent-accent       | 0.0  |\n| status   | tritanopia   | attention-line and unknown-line        | 9.8  |\n| status   | tritanopia   | attention-line and unknown-accent      | 13.4 |\n| status   | tritanopia   | attention-ink and urgent-ink           | 0.0  |\n| status   | tritanopia   | attention-ink and unknown-line         | 12.6 |\n| status   | tritanopia   | attention-ink and unknown-ink          | 0.0  |\n| status   | tritanopia   | attention-accent and urgent-line       | 0.0  |\n| status   | tritanopia   | attention-accent and urgent-accent     | 0.0  |\n| status   | tritanopia   | attention-accent and unknown-accent    | 0.0  |\n| status   | tritanopia   | urgent-surface and unknown-surface     | 0.0  |\n| status   | tritanopia   | urgent-line and urgent-accent          | 0.0  |\n| status   | tritanopia   | urgent-line and unknown-line           | 14.1 |\n| status   | tritanopia   | urgent-line and unknown-accent         | 9.1  |\n| status   | tritanopia   | urgent-ink and unknown-line            | 9.5  |\n| status   | tritanopia   | urgent-ink and unknown-ink             | 0.0  |\n| status   | tritanopia   | urgent-accent and unknown-line         | 11.7 |\n| status   | tritanopia   | urgent-accent and unknown-accent       | 11.5 |\n| status   | grayscale    | steady-surface and watch-surface       | 0.0  |\n| status   | grayscale    | steady-surface and attention-surface   | 0.0  |\n| status   | grayscale    | steady-surface and urgent-surface      | 0.0  |\n| status   | grayscale    | steady-surface and unknown-surface     | 0.0  |\n| status   | grayscale    | steady-line and steady-accent          | 9.4  |\n| status   | grayscale    | steady-line and watch-line             | 0.0  |\n| status   | grayscale    | steady-line and watch-accent           | 0.0  |\n| status   | grayscale    | steady-line and attention-line         | 0.0  |\n| status   | grayscale    | steady-line and attention-accent       | 0.0  |\n| status   | grayscale    | steady-line and urgent-line            | 0.0  |\n| status   | grayscale    | steady-line and urgent-accent          | 0.0  |\n| status   | grayscale    | steady-line and unknown-line           | 0.0  |\n| status   | grayscale    | steady-ink and watch-ink               | 0.0  |\n| status   | grayscale    | steady-ink and attention-ink           | 0.0  |\n| status   | grayscale    | steady-ink and urgent-line             | 14.2 |\n| status   | grayscale    | steady-ink and urgent-ink              | 0.0  |\n| status   | grayscale    | steady-ink and urgent-accent           | 11.6 |\n| status   | grayscale    | steady-ink and unknown-ink             | 0.0  |\n| status   | grayscale    | steady-accent and watch-line           | 12.3 |\n| status   | grayscale    | steady-accent and watch-accent         | 0.0  |\n| status   | grayscale    | steady-accent and attention-line       | 13.6 |\n| status   | grayscale    | steady-accent and attention-accent     | 8.8  |\n| status   | grayscale    | steady-accent and urgent-line          | 14.9 |\n| status   | grayscale    | steady-accent and unknown-line         | 11.9 |\n| status   | grayscale    | steady-accent and unknown-accent       | 11.6 |\n| status   | grayscale    | watch-surface and attention-surface    | 0.0  |\n| status   | grayscale    | watch-surface and urgent-surface       | 0.0  |\n| status   | grayscale    | watch-surface and unknown-surface      | 0.0  |\n| status   | grayscale    | watch-line and watch-accent            | 0.0  |\n| status   | grayscale    | watch-line and attention-line          | 0.0  |\n| status   | grayscale    | watch-line and attention-accent        | 0.0  |\n| status   | grayscale    | watch-line and urgent-line             | 0.0  |\n| status   | grayscale    | watch-line and urgent-accent           | 0.0  |\n| status   | grayscale    | watch-line and unknown-line            | 0.0  |\n| status   | grayscale    | watch-ink and attention-ink            | 0.0  |\n| status   | grayscale    | watch-ink and urgent-ink               | 0.0  |\n| status   | grayscale    | watch-ink and urgent-accent            | 12.7 |\n| status   | grayscale    | watch-ink and unknown-ink              | 0.0  |\n| status   | grayscale    | watch-accent and attention-line        | 8.3  |\n| status   | grayscale    | watch-accent and attention-accent      | 0.0  |\n| status   | grayscale    | watch-accent and urgent-line           | 9.6  |\n| status   | grayscale    | watch-accent and urgent-accent         | 12.1 |\n| status   | grayscale    | watch-accent and unknown-line          | 0.0  |\n| status   | grayscale    | attention-surface and urgent-surface   | 0.0  |\n| status   | grayscale    | attention-surface and unknown-surface  | 0.0  |\n| status   | grayscale    | attention-line and attention-accent    | 0.0  |\n| status   | grayscale    | attention-line and urgent-line         | 0.0  |\n| status   | grayscale    | attention-line and urgent-accent       | 0.0  |\n| status   | grayscale    | attention-line and unknown-line        | 0.0  |\n| status   | grayscale    | attention-ink and urgent-ink           | 0.0  |\n| status   | grayscale    | attention-ink and urgent-accent        | 13.4 |\n| status   | grayscale    | attention-ink and unknown-ink          | 0.0  |\n| status   | grayscale    | attention-accent and urgent-line       | 0.0  |\n| status   | grayscale    | attention-accent and urgent-accent     | 7.9  |\n| status   | grayscale    | attention-accent and unknown-line      | 0.0  |\n| status   | grayscale    | urgent-surface and unknown-surface     | 0.0  |\n| status   | grayscale    | urgent-line and urgent-accent          | 0.0  |\n| status   | grayscale    | urgent-line and unknown-line           | 0.0  |\n| status   | grayscale    | urgent-line and unknown-ink            | 14.8 |\n| status   | grayscale    | urgent-ink and urgent-accent           | 14.1 |\n| status   | grayscale    | urgent-ink and unknown-ink             | 0.0  |\n| status   | grayscale    | urgent-accent and unknown-line         | 0.0  |\n| status   | grayscale    | urgent-accent and unknown-ink          | 12.2 |\n| category | protanopia   | sleep-surface and heart-surface        | 0.0  |\n| category | protanopia   | sleep-surface and activity-surface     | 0.0  |\n| category | protanopia   | sleep-surface and nutrition-surface    | 0.0  |\n| category | protanopia   | sleep-surface and mind-surface         | 0.0  |\n| category | protanopia   | sleep-surface and labs-surface         | 0.0  |\n| category | protanopia   | sleep-line and sleep-accent            | 0.0  |\n| category | protanopia   | sleep-line and heart-line              | 9.2  |\n| category | protanopia   | sleep-line and heart-accent            | 0.0  |\n| category | protanopia   | sleep-line and activity-line           | 0.0  |\n| category | protanopia   | sleep-line and nutrition-line          | 0.0  |\n| category | protanopia   | sleep-line and mind-line               | 0.0  |\n| category | protanopia   | sleep-line and mind-accent             | 0.0  |\n| category | protanopia   | sleep-line and labs-line               | 0.0  |\n| category | protanopia   | sleep-line and labs-accent             | 11.7 |\n| category | protanopia   | sleep-ink and heart-line               | 7.5  |\n| category | protanopia   | sleep-ink and heart-ink                | 0.0  |\n| category | protanopia   | sleep-ink and activity-ink             | 0.0  |\n| category | protanopia   | sleep-ink and nutrition-line           | 14.4 |\n| category | protanopia   | sleep-ink and nutrition-ink            | 0.0  |\n| category | protanopia   | sleep-ink and mind-line                | 13.9 |\n| category | protanopia   | sleep-ink and mind-ink                 | 0.0  |\n| category | protanopia   | sleep-ink and labs-ink                 | 0.0  |\n| category | protanopia   | sleep-accent and heart-line            | 14.3 |\n| category | protanopia   | sleep-accent and heart-accent          | 0.0  |\n| category | protanopia   | sleep-accent and activity-line         | 0.0  |\n| category | protanopia   | sleep-accent and nutrition-line        | 7.9  |\n| category | protanopia   | sleep-accent and mind-line             | 8.4  |\n| category | protanopia   | sleep-accent and mind-accent           | 0.0  |\n| category | protanopia   | sleep-accent and labs-line             | 0.0  |\n| category | protanopia   | sleep-accent and labs-accent           | 0.0  |\n| category | protanopia   | heart-surface and activity-surface     | 0.0  |\n| category | protanopia   | heart-surface and nutrition-surface    | 0.0  |\n| category | protanopia   | heart-surface and mind-surface         | 0.0  |\n| category | protanopia   | heart-surface and labs-surface         | 0.0  |\n| category | protanopia   | heart-line and heart-ink               | 12.3 |\n| category | protanopia   | heart-line and heart-accent            | 7.4  |\n| category | protanopia   | heart-line and activity-line           | 13.7 |\n| category | protanopia   | heart-line and activity-ink            | 0.0  |\n| category | protanopia   | heart-line and nutrition-line          | 0.0  |\n| category | protanopia   | heart-line and nutrition-ink           | 9.0  |\n| category | protanopia   | heart-line and mind-line               | 0.0  |\n| category | protanopia   | heart-line and mind-ink                | 9.4  |\n| category | protanopia   | heart-line and mind-accent             | 14.8 |\n| category | protanopia   | heart-line and labs-line               | 13.5 |\n| category | protanopia   | heart-line and labs-ink                | 0.0  |\n| category | protanopia   | heart-ink and activity-ink             | 0.0  |\n| category | protanopia   | heart-ink and nutrition-ink            | 0.0  |\n| category | protanopia   | heart-ink and mind-ink                 | 0.0  |\n| category | protanopia   | heart-ink and labs-ink                 | 0.0  |\n| category | protanopia   | heart-accent and activity-line         | 0.0  |\n| category | protanopia   | heart-accent and activity-ink          | 14.1 |\n| category | protanopia   | heart-accent and nutrition-line        | 0.0  |\n| category | protanopia   | heart-accent and mind-line             | 0.0  |\n| category | protanopia   | heart-accent and mind-accent           | 0.0  |\n| category | protanopia   | heart-accent and labs-line             | 0.0  |\n| category | protanopia   | heart-accent and labs-ink              | 14.6 |\n| category | protanopia   | heart-accent and labs-accent           | 12.9 |\n| category | protanopia   | activity-surface and nutrition-surface | 0.0  |\n| category | protanopia   | activity-surface and mind-surface      | 0.0  |\n| category | protanopia   | activity-surface and labs-surface      | 0.0  |\n| category | protanopia   | activity-line and nutrition-line       | 7.8  |\n| category | protanopia   | activity-line and mind-line            | 8.3  |\n| category | protanopia   | activity-line and mind-accent          | 0.0  |\n| category | protanopia   | activity-line and labs-line            | 0.0  |\n| category | protanopia   | activity-line and labs-accent          | 0.0  |\n| category | protanopia   | activity-ink and nutrition-line        | 11.5 |\n| category | protanopia   | activity-ink and nutrition-ink         | 0.0  |\n| category | protanopia   | activity-ink and mind-line             | 10.9 |\n| category | protanopia   | activity-ink and mind-ink              | 0.0  |\n| category | protanopia   | activity-ink and labs-ink              | 0.0  |\n| category | protanopia   | activity-accent and nutrition-accent   | 0.0  |\n| category | protanopia   | nutrition-surface and mind-surface     | 0.0  |\n| category | protanopia   | nutrition-surface and labs-surface     | 0.0  |\n| category | protanopia   | nutrition-line and mind-line           | 0.0  |\n| category | protanopia   | nutrition-line and mind-accent         | 8.0  |\n| category | protanopia   | nutrition-line and labs-line           | 0.0  |\n| category | protanopia   | nutrition-line and labs-ink            | 12.1 |\n| category | protanopia   | nutrition-ink and mind-ink             | 0.0  |\n| category | protanopia   | nutrition-ink and labs-ink             | 0.0  |\n| category | protanopia   | nutrition-accent and labs-accent       | 11.2 |\n| category | protanopia   | mind-surface and labs-surface          | 0.0  |\n| category | protanopia   | mind-line and mind-accent              | 8.5  |\n| category | protanopia   | mind-line and labs-line                | 0.0  |\n| category | protanopia   | mind-line and labs-ink                 | 11.6 |\n| category | protanopia   | mind-ink and labs-ink                  | 0.0  |\n| category | protanopia   | mind-accent and labs-line              | 0.0  |\n| category | protanopia   | mind-accent and labs-accent            | 0.0  |\n| category | protanopia   | labs-line and labs-accent              | 0.0  |\n| category | deuteranopia | sleep-surface and heart-surface        | 0.0  |\n| category | deuteranopia | sleep-surface and activity-surface     | 0.0  |\n| category | deuteranopia | sleep-surface and nutrition-surface    | 0.0  |\n| category | deuteranopia | sleep-surface and mind-surface         | 0.0  |\n| category | deuteranopia | sleep-surface and labs-surface         | 0.0  |\n| category | deuteranopia | sleep-line and sleep-accent            | 0.0  |\n| category | deuteranopia | sleep-line and heart-line              | 0.0  |\n| category | deuteranopia | sleep-line and heart-accent            | 11.1 |\n| category | deuteranopia | sleep-line and activity-line           | 0.0  |\n| category | deuteranopia | sleep-line and nutrition-line          | 0.0  |\n| category | deuteranopia | sleep-line and mind-line               | 0.0  |\n| category | deuteranopia | sleep-line and mind-accent             | 9.4  |\n| category | deuteranopia | sleep-line and labs-line               | 0.0  |\n| category | deuteranopia | sleep-line and labs-accent             | 0.0  |\n| category | deuteranopia | sleep-ink and heart-ink                | 0.0  |\n| category | deuteranopia | sleep-ink and activity-ink             | 0.0  |\n| category | deuteranopia | sleep-ink and nutrition-ink            | 0.0  |\n| category | deuteranopia | sleep-ink and mind-ink                 | 0.0  |\n| category | deuteranopia | sleep-ink and labs-ink                 | 0.0  |\n| category | deuteranopia | sleep-accent and heart-line            | 0.0  |\n| category | deuteranopia | sleep-accent and heart-accent          | 0.0  |\n| category | deuteranopia | sleep-accent and activity-line         | 0.0  |\n| category | deuteranopia | sleep-accent and nutrition-line        | 0.0  |\n| category | deuteranopia | sleep-accent and mind-line             | 0.0  |\n| category | deuteranopia | sleep-accent and mind-accent           | 0.0  |\n| category | deuteranopia | sleep-accent and labs-line             | 0.0  |\n| category | deuteranopia | sleep-accent and labs-accent           | 0.0  |\n| category | deuteranopia | heart-surface and activity-surface     | 0.0  |\n| category | deuteranopia | heart-surface and nutrition-surface    | 0.0  |\n| category | deuteranopia | heart-surface and mind-surface         | 0.0  |\n| category | deuteranopia | heart-surface and labs-surface         | 0.0  |\n| category | deuteranopia | heart-line and heart-accent            | 8.8  |\n| category | deuteranopia | heart-line and activity-line           | 0.0  |\n| category | deuteranopia | heart-line and nutrition-line          | 0.0  |\n| category | deuteranopia | heart-line and mind-line               | 0.0  |\n| category | deuteranopia | heart-line and mind-accent             | 0.0  |\n| category | deuteranopia | heart-line and labs-line               | 0.0  |\n| category | deuteranopia | heart-line and labs-accent             | 0.0  |\n| category | deuteranopia | heart-ink and activity-ink             | 0.0  |\n| category | deuteranopia | heart-ink and nutrition-ink            | 0.0  |\n| category | deuteranopia | heart-ink and mind-ink                 | 0.0  |\n| category | deuteranopia | heart-ink and labs-ink                 | 0.0  |\n| category | deuteranopia | heart-accent and activity-line         | 10.8 |\n| category | deuteranopia | heart-accent and activity-accent       | 9.3  |\n| category | deuteranopia | heart-accent and nutrition-line        | 10.1 |\n| category | deuteranopia | heart-accent and mind-line             | 11.7 |\n| category | deuteranopia | heart-accent and mind-accent           | 0.0  |\n| category | deuteranopia | heart-accent and labs-line             | 11.9 |\n| category | deuteranopia | heart-accent and labs-accent           | 0.0  |\n| category | deuteranopia | activity-surface and nutrition-surface | 0.0  |\n| category | deuteranopia | activity-surface and mind-surface      | 0.0  |\n| category | deuteranopia | activity-surface and labs-surface      | 0.0  |\n| category | deuteranopia | activity-line and nutrition-line       | 0.0  |\n| category | deuteranopia | activity-line and mind-line            | 0.0  |\n| category | deuteranopia | activity-line and mind-accent          | 7.9  |\n| category | deuteranopia | activity-line and labs-line            | 0.0  |\n| category | deuteranopia | activity-line and labs-accent          | 0.0  |\n| category | deuteranopia | activity-ink and nutrition-ink         | 0.0  |\n| category | deuteranopia | activity-ink and mind-ink              | 0.0  |\n| category | deuteranopia | activity-ink and labs-ink              | 0.0  |\n| category | deuteranopia | activity-accent and nutrition-accent   | 0.0  |\n| category | deuteranopia | activity-accent and mind-accent        | 12.5 |\n| category | deuteranopia | nutrition-surface and mind-surface     | 0.0  |\n| category | deuteranopia | nutrition-surface and labs-surface     | 0.0  |\n| category | deuteranopia | nutrition-line and mind-line           | 0.0  |\n| category | deuteranopia | nutrition-line and mind-accent         | 0.0  |\n| category | deuteranopia | nutrition-line and labs-line           | 0.0  |\n| category | deuteranopia | nutrition-line and labs-accent         | 0.0  |\n| category | deuteranopia | nutrition-ink and mind-ink             | 0.0  |\n| category | deuteranopia | nutrition-ink and labs-ink             | 0.0  |\n| category | deuteranopia | mind-surface and labs-surface          | 0.0  |\n| category | deuteranopia | mind-line and mind-accent              | 8.8  |\n| category | deuteranopia | mind-line and labs-line                | 0.0  |\n| category | deuteranopia | mind-line and labs-accent              | 0.0  |\n| category | deuteranopia | mind-ink and labs-ink                  | 0.0  |\n| category | deuteranopia | mind-accent and labs-line              | 10.2 |\n| category | deuteranopia | mind-accent and labs-accent            | 0.0  |\n| category | deuteranopia | labs-line and labs-accent              | 0.0  |\n| category | tritanopia   | sleep-surface and heart-surface        | 0.0  |\n| category | tritanopia   | sleep-surface and activity-surface     | 0.0  |\n| category | tritanopia   | sleep-surface and nutrition-surface    | 0.0  |\n| category | tritanopia   | sleep-surface and mind-surface         | 0.0  |\n| category | tritanopia   | sleep-surface and labs-surface         | 0.0  |\n| category | tritanopia   | sleep-line and sleep-accent            | 0.0  |\n| category | tritanopia   | sleep-line and heart-line              | 10.9 |\n| category | tritanopia   | sleep-line and heart-ink               | 11.1 |\n| category | tritanopia   | sleep-line and activity-line           | 0.0  |\n| category | tritanopia   | sleep-line and nutrition-line          | 0.0  |\n| category | tritanopia   | sleep-line and nutrition-ink           | 14.2 |\n| category | tritanopia   | sleep-line and mind-line               | 0.0  |\n| category | tritanopia   | sleep-line and mind-accent             | 9.0  |\n| category | tritanopia   | sleep-line and labs-line               | 0.0  |\n| category | tritanopia   | sleep-line and labs-accent             | 0.0  |\n| category | tritanopia   | sleep-ink and heart-ink                | 0.0  |\n| category | tritanopia   | sleep-ink and activity-ink             | 0.0  |\n| category | tritanopia   | sleep-ink and nutrition-ink            | 0.0  |\n| category | tritanopia   | sleep-ink and mind-ink                 | 0.0  |\n| category | tritanopia   | sleep-ink and labs-ink                 | 0.0  |\n| category | tritanopia   | sleep-accent and heart-line            | 0.0  |\n| category | tritanopia   | sleep-accent and activity-line         | 0.0  |\n| category | tritanopia   | sleep-accent and nutrition-line        | 0.0  |\n| category | tritanopia   | sleep-accent and mind-line             | 0.0  |\n| category | tritanopia   | sleep-accent and mind-accent           | 0.0  |\n| category | tritanopia   | sleep-accent and labs-line             | 0.0  |\n| category | tritanopia   | sleep-accent and labs-accent           | 0.0  |\n| category | tritanopia   | heart-surface and activity-surface     | 0.0  |\n| category | tritanopia   | heart-surface and nutrition-surface    | 0.0  |\n| category | tritanopia   | heart-surface and mind-surface         | 0.0  |\n| category | tritanopia   | heart-surface and labs-surface         | 0.0  |\n| category | tritanopia   | heart-line and heart-accent            | 10.1 |\n| category | tritanopia   | heart-line and activity-line           | 9.9  |\n| category | tritanopia   | heart-line and activity-accent         | 9.3  |\n| category | tritanopia   | heart-line and nutrition-line          | 0.0  |\n| category | tritanopia   | heart-line and mind-line               | 11.9 |\n| category | tritanopia   | heart-line and mind-accent             | 0.0  |\n| category | tritanopia   | heart-line and labs-line               | 10.3 |\n| category | tritanopia   | heart-line and labs-accent             | 0.0  |\n| category | tritanopia   | heart-ink and activity-line            | 12.8 |\n| category | tritanopia   | heart-ink and activity-ink             | 0.0  |\n| category | tritanopia   | heart-ink and nutrition-ink            | 0.0  |\n| category | tritanopia   | heart-ink and mind-line                | 10.8 |\n| category | tritanopia   | heart-ink and mind-ink                 | 0.0  |\n| category | tritanopia   | heart-ink and labs-line                | 12.4 |\n| category | tritanopia   | heart-ink and labs-ink                 | 0.0  |\n| category | tritanopia   | heart-accent and activity-accent       | 0.0  |\n| category | tritanopia   | heart-accent and nutrition-accent      | 13.9 |\n| category | tritanopia   | heart-accent and mind-accent           | 13.6 |\n| category | tritanopia   | activity-surface and nutrition-surface | 0.0  |\n| category | tritanopia   | activity-surface and mind-surface      | 0.0  |\n| category | tritanopia   | activity-surface and labs-surface      | 0.0  |\n| category | tritanopia   | activity-line and nutrition-line       | 0.0  |\n| category | tritanopia   | activity-line and mind-line            | 0.0  |\n| category | tritanopia   | activity-line and mind-accent          | 0.0  |\n| category | tritanopia   | activity-line and labs-line            | 0.0  |\n| category | tritanopia   | activity-line and labs-accent          | 0.0  |\n| category | tritanopia   | activity-ink and nutrition-ink         | 0.0  |\n| category | tritanopia   | activity-ink and mind-ink              | 0.0  |\n| category | tritanopia   | activity-ink and labs-ink              | 0.0  |\n| category | tritanopia   | activity-accent and nutrition-accent   | 14.7 |\n| category | tritanopia   | activity-accent and mind-accent        | 12.7 |\n| category | tritanopia   | nutrition-surface and mind-surface     | 0.0  |\n| category | tritanopia   | nutrition-surface and labs-surface     | 0.0  |\n| category | tritanopia   | nutrition-line and mind-line           | 0.0  |\n| category | tritanopia   | nutrition-line and mind-accent         | 0.0  |\n| category | tritanopia   | nutrition-line and labs-line           | 0.0  |\n| category | tritanopia   | nutrition-line and labs-accent         | 0.0  |\n| category | tritanopia   | nutrition-ink and mind-line            | 14.2 |\n| category | tritanopia   | nutrition-ink and mind-ink             | 0.0  |\n| category | tritanopia   | nutrition-ink and labs-ink             | 0.0  |\n| category | tritanopia   | mind-surface and labs-surface          | 0.0  |\n| category | tritanopia   | mind-line and mind-accent              | 8.9  |\n| category | tritanopia   | mind-line and labs-line                | 0.0  |\n| category | tritanopia   | mind-line and labs-accent              | 0.0  |\n| category | tritanopia   | mind-ink and labs-ink                  | 0.0  |\n| category | tritanopia   | mind-accent and labs-line              | 8.4  |\n| category | tritanopia   | mind-accent and labs-accent            | 0.0  |\n| category | tritanopia   | labs-line and labs-accent              | 0.0  |\n| category | grayscale    | sleep-surface and heart-surface        | 0.0  |\n| category | grayscale    | sleep-surface and activity-surface     | 0.0  |\n| category | grayscale    | sleep-surface and nutrition-surface    | 0.0  |\n| category | grayscale    | sleep-surface and mind-surface         | 0.0  |\n| category | grayscale    | sleep-surface and labs-surface         | 0.0  |\n| category | grayscale    | sleep-line and sleep-accent            | 0.0  |\n| category | grayscale    | sleep-line and heart-line              | 0.0  |\n| category | grayscale    | sleep-line and heart-accent            | 0.0  |\n| category | grayscale    | sleep-line and activity-line           | 0.0  |\n| category | grayscale    | sleep-line and nutrition-line          | 0.0  |\n| category | grayscale    | sleep-line and mind-line               | 0.0  |\n| category | grayscale    | sleep-line and mind-accent             | 0.0  |\n| category | grayscale    | sleep-line and labs-line               | 0.0  |\n| category | grayscale    | sleep-line and labs-accent             | 8.2  |\n| category | grayscale    | sleep-ink and heart-ink                | 0.0  |\n| category | grayscale    | sleep-ink and activity-ink             | 0.0  |\n| category | grayscale    | sleep-ink and nutrition-ink            | 0.0  |\n| category | grayscale    | sleep-ink and mind-ink                 | 0.0  |\n| category | grayscale    | sleep-ink and labs-ink                 | 0.0  |\n| category | grayscale    | sleep-accent and heart-line            | 0.0  |\n| category | grayscale    | sleep-accent and heart-accent          | 0.0  |\n| category | grayscale    | sleep-accent and activity-line         | 0.0  |\n| category | grayscale    | sleep-accent and nutrition-line        | 0.0  |\n| category | grayscale    | sleep-accent and mind-line             | 0.0  |\n| category | grayscale    | sleep-accent and mind-accent           | 0.0  |\n| category | grayscale    | sleep-accent and labs-line             | 0.0  |\n| category | grayscale    | sleep-accent and labs-accent           | 0.0  |\n| category | grayscale    | heart-surface and activity-surface     | 0.0  |\n| category | grayscale    | heart-surface and nutrition-surface    | 0.0  |\n| category | grayscale    | heart-surface and mind-surface         | 0.0  |\n| category | grayscale    | heart-surface and labs-surface         | 0.0  |\n| category | grayscale    | heart-line and heart-accent            | 8.6  |\n| category | grayscale    | heart-line and activity-line           | 0.0  |\n| category | grayscale    | heart-line and activity-ink            | 14.6 |\n| category | grayscale    | heart-line and nutrition-line          | 0.0  |\n| category | grayscale    | heart-line and mind-line               | 0.0  |\n| category | grayscale    | heart-line and mind-accent             | 9.1  |\n| category | grayscale    | heart-line and labs-line               | 0.0  |\n| category | grayscale    | heart-line and labs-ink                | 14.9 |\n| category | grayscale    | heart-line and labs-accent             | 10.0 |\n| category | grayscale    | heart-ink and activity-ink             | 0.0  |\n| category | grayscale    | heart-ink and nutrition-ink            | 0.0  |\n| category | grayscale    | heart-ink and mind-ink                 | 0.0  |\n| category | grayscale    | heart-ink and labs-ink                 | 0.0  |\n| category | grayscale    | heart-accent and activity-line         | 0.0  |\n| category | grayscale    | heart-accent and nutrition-line        | 7.9  |\n| category | grayscale    | heart-accent and mind-line             | 9.2  |\n| category | grayscale    | heart-accent and mind-accent           | 0.0  |\n| category | grayscale    | heart-accent and labs-line             | 0.0  |\n| category | grayscale    | heart-accent and labs-accent           | 0.0  |\n| category | grayscale    | activity-surface and nutrition-surface | 0.0  |\n| category | grayscale    | activity-surface and mind-surface      | 0.0  |\n| category | grayscale    | activity-surface and labs-surface      | 0.0  |\n| category | grayscale    | activity-line and nutrition-line       | 0.0  |\n| category | grayscale    | activity-line and mind-line            | 0.0  |\n| category | grayscale    | activity-line and mind-accent          | 0.0  |\n| category | grayscale    | activity-line and labs-line            | 0.0  |\n| category | grayscale    | activity-line and labs-accent          | 0.0  |\n| category | grayscale    | activity-ink and nutrition-ink         | 0.0  |\n| category | grayscale    | activity-ink and mind-ink              | 0.0  |\n| category | grayscale    | activity-ink and labs-ink              | 0.0  |\n| category | grayscale    | activity-accent and nutrition-accent   | 0.0  |\n| category | grayscale    | nutrition-surface and mind-surface     | 0.0  |\n| category | grayscale    | nutrition-surface and labs-surface     | 0.0  |\n| category | grayscale    | nutrition-line and mind-line           | 0.0  |\n| category | grayscale    | nutrition-line and mind-accent         | 0.0  |\n| category | grayscale    | nutrition-line and labs-line           | 0.0  |\n| category | grayscale    | nutrition-line and labs-accent         | 8.2  |\n| category | grayscale    | nutrition-ink and mind-ink             | 0.0  |\n| category | grayscale    | nutrition-ink and labs-ink             | 0.0  |\n| category | grayscale    | mind-surface and labs-surface          | 0.0  |\n| category | grayscale    | mind-line and mind-accent              | 8.6  |\n| category | grayscale    | mind-line and labs-line                | 0.0  |\n| category | grayscale    | mind-line and labs-accent              | 9.6  |\n| category | grayscale    | mind-ink and labs-ink                  | 0.0  |\n| category | grayscale    | mind-accent and labs-line              | 0.0  |\n| category | grayscale    | mind-accent and labs-accent            | 0.0  |\n| category | grayscale    | labs-line and labs-accent              | 0.0  |\n\n{/* opsinjs:generated:end */}"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/reference/generated/css-variables",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/reference/generated/css-variables.md",
      "slug": [
        "reference",
        "generated",
        "css-variables"
      ],
      "section": "Reference",
      "title": "CSS variables",
      "description": "Every --opsin-* custom property, its default in both themes, what it controls and which selectors read it.",
      "kind": "reference",
      "aliases": [
        "css vars",
        "opsin variables",
        "generated css variables"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-09-02",
      "markdown": "Generated from `tokens/*.json`: `scripts/build-tokens.mts` compiles them to `app/tokens.generated.css`, and `scripts/build-reference.mts` writes this page from the same data. Run `pnpm run generate`.\n\nEvery opsinjs custom property starts `--opsin-`. Anything else in the cascade belongs to Tailwind, shadcn, fumadocs or the docs chrome, is not covered by the versioning policy in the [Changelog](../../changelog.mdx), and is not listed. *Light* and *Dark* are the computed values in each theme, *Controls* is the one thing a variable decides, and *Read by* names the selectors that consume it. Override at a scope you own, never on `:root` in a library; [Theming](../../theming.mdx) shows how.\n\n{/* opsinjs:generated:begin - everything below is replaced by scripts/build-reference.mts */}\n\n## CSS variables [#css-variables]\n\n### `:root, .opsin-product` [#root-opsin-product]\n\n| Variable                                     | Value                                                                                                                                                                 | Controls                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--opsin-neutral-0`                          | `oklch(1 0 0)`                                                                                                                                                        | Neutral ramp, step 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-neutral-50`                         | `oklch(0.985 0.002 250)`                                                                                                                                              | Neutral ramp, step 50.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-neutral-100`                        | `oklch(0.967 0.003 250)`                                                                                                                                              | Neutral ramp, step 100.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-neutral-200`                        | `oklch(0.929 0.004 250)`                                                                                                                                              | Neutral ramp, step 200.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-neutral-300`                        | `oklch(0.871 0.005 250)`                                                                                                                                              | Neutral ramp, step 300.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-neutral-400`                        | `oklch(0.708 0.008 250)`                                                                                                                                              | Neutral ramp, step 400.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-neutral-500`                        | `oklch(0.556 0.009 250)`                                                                                                                                              | Neutral ramp, step 500.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-neutral-600`                        | `oklch(0.439 0.009 250)`                                                                                                                                              | Neutral ramp, step 600.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-neutral-700`                        | `oklch(0.371 0.008 250)`                                                                                                                                              | Neutral ramp, step 700.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-neutral-800`                        | `oklch(0.269 0.007 250)`                                                                                                                                              | Neutral ramp, step 800.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-neutral-900`                        | `oklch(0.205 0.006 250)`                                                                                                                                              | Neutral ramp, step 900.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-neutral-950`                        | `oklch(0.145 0.005 250)`                                                                                                                                              | Neutral ramp, step 950.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-neutral-1000`                       | `oklch(0 0 0)`                                                                                                                                                        | Neutral ramp, step 1000.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| `--opsin-chrome-background`                  | `oklch(0.985 0.002 250)`                                                                                                                                              | Chrome role background, resolved to the ladder step it names.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |\n| `--opsin-chrome-foreground`                  | `oklch(0.205 0.006 250)`                                                                                                                                              | Chrome role foreground, resolved to the ladder step it names.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |\n| `--opsin-chrome-card`                        | `oklch(1 0 0)`                                                                                                                                                        | Chrome role card, resolved to the ladder step it names.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-chrome-card-foreground`             | `oklch(0.205 0.006 250)`                                                                                                                                              | Chrome role cardForeground, resolved to the ladder step it names.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |\n| `--opsin-chrome-muted`                       | `oklch(0.967 0.003 250)`                                                                                                                                              | Chrome role muted, resolved to the ladder step it names.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| `--opsin-chrome-muted-foreground`            | `oklch(0.439 0.009 250)`                                                                                                                                              | Chrome role mutedForeground, resolved to the ladder step it names.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |\n| `--opsin-chrome-border`                      | `oklch(0.556 0.009 250)`                                                                                                                                              | Chrome role border, resolved to the ladder step it names.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-chrome-input`                       | `oklch(0.556 0.009 250)`                                                                                                                                              | Chrome role input, resolved to the ladder step it names.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| `--opsin-chrome-edge`                        | `oklch(0.205 0.006 250 / 0.1)`                                                                                                                                        | Chrome role edge, resolved to the ladder step it names.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-chrome-ring`                        | `oklch(0.53 0.155 250)`                                                                                                                                               | Chrome role ring, resolved to the ladder step it names.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-chrome-brand`                       | `oklch(0.53 0.155 250)`                                                                                                                                               | Chrome role brand, resolved to the ladder step it names.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| `--opsin-chrome-primary`                     | `oklch(0.145 0.005 250)`                                                                                                                                              | Chrome role primary, resolved to the ladder step it names.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |\n| `--opsin-chrome-primary-foreground`          | `oklch(1 0 0)`                                                                                                                                                        | Chrome role primaryForeground, resolved to the ladder step it names.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-category-sleep-50`                  | `oklch(0.972 0.013 275)`                                                                                                                                              | Sleep ramp, step 50.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-category-sleep-100`                 | `oklch(0.941 0.028 275)`                                                                                                                                              | Sleep ramp, step 100.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-category-sleep-200`                 | `oklch(0.884 0.057 275)`                                                                                                                                              | Sleep ramp, step 200.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-category-sleep-300`                 | `oklch(0.806 0.092 275)`                                                                                                                                              | Sleep ramp, step 300.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-category-sleep-400`                 | `oklch(0.714 0.123 275)`                                                                                                                                              | Sleep ramp, step 400.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-category-sleep-500`                 | `oklch(0.622 0.14 275)`                                                                                                                                               | Sleep ramp, step 500.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-category-sleep-600`                 | `oklch(0.541 0.136 275)`                                                                                                                                              | Sleep ramp, step 600.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-category-sleep-700`                 | `oklch(0.452 0.123 275)`                                                                                                                                              | Sleep ramp, step 700.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-category-sleep-800`                 | `oklch(0.362 0.104 275)`                                                                                                                                              | Sleep ramp, step 800.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-category-sleep-900`                 | `oklch(0.276 0.081 275)`                                                                                                                                              | Sleep ramp, step 900.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-category-sleep-950`                 | `oklch(0.208 0.062 275)`                                                                                                                                              | Sleep ramp, step 950.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-category-sleep-surface`             | `oklch(0.972 0.013 275)`                                                                                                                                              | The tinted background a component in this ramp sits on.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-category-sleep-line`                | `oklch(0.541 0.136 275)`                                                                                                                                              | The boundary, icon stroke or chart mark. The lightest value in the ramp that clears the non-text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-category-sleep-ink`                 | `oklch(0.362 0.104 275)`                                                                                                                                              | Text and text-sized icons on `surface`. Clears the text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `--opsin-category-sleep-accent`              | `oklch(0.58 0.14 275)`                                                                                                                                                | The identity fill: a bar fill, a dial track, a legend dot. Chosen for recognition, not for contrast. It must be bounded by `line` or labelled in `ink`; it is never the only thing that carries the meaning.                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-category-heart-50`                  | `oklch(0.972 0.014 15)`                                                                                                                                               | Heart ramp, step 50.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-category-heart-100`                 | `oklch(0.941 0.03 15)`                                                                                                                                                | Heart ramp, step 100.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-category-heart-200`                 | `oklch(0.884 0.062 15)`                                                                                                                                               | Heart ramp, step 200.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-category-heart-300`                 | `oklch(0.806 0.112 15)`                                                                                                                                               | Heart ramp, step 300.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-category-heart-400`                 | `oklch(0.714 0.15 15)`                                                                                                                                                | Heart ramp, step 400.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-category-heart-500`                 | `oklch(0.622 0.17 15)`                                                                                                                                                | Heart ramp, step 500.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-category-heart-600`                 | `oklch(0.541 0.165 15)`                                                                                                                                               | Heart ramp, step 600.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-category-heart-700`                 | `oklch(0.452 0.15 15)`                                                                                                                                                | Heart ramp, step 700.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-category-heart-800`                 | `oklch(0.362 0.126 15)`                                                                                                                                               | Heart ramp, step 800.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-category-heart-900`                 | `oklch(0.276 0.099 15)`                                                                                                                                               | Heart ramp, step 900.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-category-heart-950`                 | `oklch(0.208 0.075 15)`                                                                                                                                               | Heart ramp, step 950.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-category-heart-surface`             | `oklch(0.972 0.014 15)`                                                                                                                                               | The tinted background a component in this ramp sits on.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-category-heart-line`                | `oklch(0.541 0.165 15)`                                                                                                                                               | The boundary, icon stroke or chart mark. The lightest value in the ramp that clears the non-text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-category-heart-ink`                 | `oklch(0.362 0.126 15)`                                                                                                                                               | Text and text-sized icons on `surface`. Clears the text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `--opsin-category-heart-accent`              | `oklch(0.62 0.17 15)`                                                                                                                                                 | The identity fill: a bar fill, a dial track, a legend dot. Chosen for recognition, not for contrast. It must be bounded by `line` or labelled in `ink`; it is never the only thing that carries the meaning.                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-category-activity-50`               | `oklch(0.972 0.022 140)`                                                                                                                                              | Activity ramp, step 50.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-category-activity-100`              | `oklch(0.941 0.038 140)`                                                                                                                                              | Activity ramp, step 100.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| `--opsin-category-activity-200`              | `oklch(0.884 0.067 140)`                                                                                                                                              | Activity ramp, step 200.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| `--opsin-category-activity-300`              | `oklch(0.806 0.106 140)`                                                                                                                                              | Activity ramp, step 300.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| `--opsin-category-activity-400`              | `oklch(0.714 0.141 140)`                                                                                                                                              | Activity ramp, step 400.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| `--opsin-category-activity-500`              | `oklch(0.622 0.16 140)`                                                                                                                                               | Activity ramp, step 500.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| `--opsin-category-activity-600`              | `oklch(0.541 0.155 140)`                                                                                                                                              | Activity ramp, step 600.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| `--opsin-category-activity-700`              | `oklch(0.452 0.141 140)`                                                                                                                                              | Activity ramp, step 700.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| `--opsin-category-activity-800`              | `oklch(0.362 0.118 140)`                                                                                                                                              | Activity ramp, step 800.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| `--opsin-category-activity-900`              | `oklch(0.276 0.092 140)`                                                                                                                                              | Activity ramp, step 900.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| `--opsin-category-activity-950`              | `oklch(0.208 0.07 140)`                                                                                                                                               | Activity ramp, step 950.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| `--opsin-category-activity-surface`          | `oklch(0.972 0.022 140)`                                                                                                                                              | The tinted background a component in this ramp sits on.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-category-activity-line`             | `oklch(0.541 0.155 140)`                                                                                                                                              | The boundary, icon stroke or chart mark. The lightest value in the ramp that clears the non-text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-category-activity-ink`              | `oklch(0.362 0.118 140)`                                                                                                                                              | Text and text-sized icons on `surface`. Clears the text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `--opsin-category-activity-accent`           | `oklch(0.7 0.16 140)`                                                                                                                                                 | The identity fill: a bar fill, a dial track, a legend dot. Chosen for recognition, not for contrast. It must be bounded by `line` or labelled in `ink`; it is never the only thing that carries the meaning.                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-category-nutrition-50`              | `oklch(0.972 0.02 70)`                                                                                                                                                | Nutrition ramp, step 50.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| `--opsin-category-nutrition-100`             | `oklch(0.941 0.034 70)`                                                                                                                                               | Nutrition ramp, step 100.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-category-nutrition-200`             | `oklch(0.884 0.059 70)`                                                                                                                                               | Nutrition ramp, step 200.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-category-nutrition-300`             | `oklch(0.806 0.092 70)`                                                                                                                                               | Nutrition ramp, step 300.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-category-nutrition-400`             | `oklch(0.714 0.123 70)`                                                                                                                                               | Nutrition ramp, step 400.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-category-nutrition-500`             | `oklch(0.622 0.135 70)`                                                                                                                                               | Nutrition ramp, step 500.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-category-nutrition-600`             | `oklch(0.541 0.118 70)`                                                                                                                                               | Nutrition ramp, step 600.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-category-nutrition-700`             | `oklch(0.452 0.099 70)`                                                                                                                                               | Nutrition ramp, step 700.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-category-nutrition-800`             | `oklch(0.362 0.08 70)`                                                                                                                                                | Nutrition ramp, step 800.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-category-nutrition-900`             | `oklch(0.276 0.062 70)`                                                                                                                                               | Nutrition ramp, step 900.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-category-nutrition-950`             | `oklch(0.208 0.049 70)`                                                                                                                                               | Nutrition ramp, step 950.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-category-nutrition-surface`         | `oklch(0.972 0.02 70)`                                                                                                                                                | The tinted background a component in this ramp sits on.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-category-nutrition-line`            | `oklch(0.541 0.118 70)`                                                                                                                                               | The boundary, icon stroke or chart mark. The lightest value in the ramp that clears the non-text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-category-nutrition-ink`             | `oklch(0.362 0.08 70)`                                                                                                                                                | Text and text-sized icons on `surface`. Clears the text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `--opsin-category-nutrition-accent`          | `oklch(0.75 0.14 70)`                                                                                                                                                 | The identity fill: a bar fill, a dial track, a legend dot. Chosen for recognition, not for contrast. It must be bounded by `line` or labelled in `ink`; it is never the only thing that carries the meaning.                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-category-mind-50`                   | `oklch(0.972 0.018 310)`                                                                                                                                              | Mind ramp, step 50.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |\n| `--opsin-category-mind-100`                  | `oklch(0.941 0.034 310)`                                                                                                                                              | Mind ramp, step 100.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-category-mind-200`                  | `oklch(0.884 0.059 310)`                                                                                                                                              | Mind ramp, step 200.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-category-mind-300`                  | `oklch(0.806 0.092 310)`                                                                                                                                              | Mind ramp, step 300.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-category-mind-400`                  | `oklch(0.714 0.123 310)`                                                                                                                                              | Mind ramp, step 400.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-category-mind-500`                  | `oklch(0.622 0.14 310)`                                                                                                                                               | Mind ramp, step 500.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-category-mind-600`                  | `oklch(0.541 0.136 310)`                                                                                                                                              | Mind ramp, step 600.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-category-mind-700`                  | `oklch(0.452 0.123 310)`                                                                                                                                              | Mind ramp, step 700.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-category-mind-800`                  | `oklch(0.362 0.104 310)`                                                                                                                                              | Mind ramp, step 800.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-category-mind-900`                  | `oklch(0.276 0.081 310)`                                                                                                                                              | Mind ramp, step 900.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-category-mind-950`                  | `oklch(0.208 0.062 310)`                                                                                                                                              | Mind ramp, step 950.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-category-mind-surface`              | `oklch(0.972 0.018 310)`                                                                                                                                              | The tinted background a component in this ramp sits on.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-category-mind-line`                 | `oklch(0.541 0.136 310)`                                                                                                                                              | The boundary, icon stroke or chart mark. The lightest value in the ramp that clears the non-text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-category-mind-ink`                  | `oklch(0.362 0.104 310)`                                                                                                                                              | Text and text-sized icons on `surface`. Clears the text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `--opsin-category-mind-accent`               | `oklch(0.62 0.14 310)`                                                                                                                                                | The identity fill: a bar fill, a dial track, a legend dot. Chosen for recognition, not for contrast. It must be bounded by `line` or labelled in `ink`; it is never the only thing that carries the meaning.                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-category-labs-50`                   | `oklch(0.972 0.015 210)`                                                                                                                                              | Labs ramp, step 50.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |\n| `--opsin-category-labs-100`                  | `oklch(0.941 0.026 210)`                                                                                                                                              | Labs ramp, step 100.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-category-labs-200`                  | `oklch(0.884 0.046 210)`                                                                                                                                              | Labs ramp, step 200.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-category-labs-300`                  | `oklch(0.806 0.073 210)`                                                                                                                                              | Labs ramp, step 300.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-category-labs-400`                  | `oklch(0.714 0.097 210)`                                                                                                                                              | Labs ramp, step 400.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-category-labs-500`                  | `oklch(0.622 0.108 210)`                                                                                                                                              | Labs ramp, step 500.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-category-labs-600`                  | `oklch(0.541 0.094 210)`                                                                                                                                              | Labs ramp, step 600.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-category-labs-700`                  | `oklch(0.452 0.079 210)`                                                                                                                                              | Labs ramp, step 700.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-category-labs-800`                  | `oklch(0.362 0.063 210)`                                                                                                                                              | Labs ramp, step 800.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-category-labs-900`                  | `oklch(0.276 0.049 210)`                                                                                                                                              | Labs ramp, step 900.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-category-labs-950`                  | `oklch(0.208 0.038 210)`                                                                                                                                              | Labs ramp, step 950.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-category-labs-surface`              | `oklch(0.972 0.015 210)`                                                                                                                                              | The tinted background a component in this ramp sits on.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-category-labs-line`                 | `oklch(0.541 0.094 210)`                                                                                                                                              | The boundary, icon stroke or chart mark. The lightest value in the ramp that clears the non-text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-category-labs-ink`                  | `oklch(0.362 0.063 210)`                                                                                                                                              | Text and text-sized icons on `surface`. Clears the text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `--opsin-category-labs-accent`               | `oklch(0.6 0.11 210)`                                                                                                                                                 | The identity fill: a bar fill, a dial track, a legend dot. Chosen for recognition, not for contrast. It must be bounded by `line` or labelled in `ink`; it is never the only thing that carries the meaning.                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-status-steady-50`                   | `oklch(0.972 0.015 178)`                                                                                                                                              | Steady ramp, step 50.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-status-steady-100`                  | `oklch(0.941 0.026 178)`                                                                                                                                              | Steady ramp, step 100.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-status-steady-200`                  | `oklch(0.884 0.046 178)`                                                                                                                                              | Steady ramp, step 200.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-status-steady-300`                  | `oklch(0.806 0.073 178)`                                                                                                                                              | Steady ramp, step 300.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-status-steady-400`                  | `oklch(0.714 0.097 178)`                                                                                                                                              | Steady ramp, step 400.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-status-steady-500`                  | `oklch(0.622 0.11 178)`                                                                                                                                               | Steady ramp, step 500.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-status-steady-600`                  | `oklch(0.541 0.1 178)`                                                                                                                                                | Steady ramp, step 600.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-status-steady-700`                  | `oklch(0.452 0.084 178)`                                                                                                                                              | Steady ramp, step 700.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-status-steady-800`                  | `oklch(0.362 0.067 178)`                                                                                                                                              | Steady ramp, step 800.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-status-steady-900`                  | `oklch(0.276 0.052 178)`                                                                                                                                              | Steady ramp, step 900.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-status-steady-950`                  | `oklch(0.208 0.041 178)`                                                                                                                                              | Steady ramp, step 950.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-status-steady-surface`              | `oklch(0.972 0.015 178)`                                                                                                                                              | The tinted background a component in this ramp sits on.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-status-steady-line`                 | `oklch(0.541 0.1 178)`                                                                                                                                                | The boundary, icon stroke or chart mark. The lightest value in the ramp that clears the non-text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-status-steady-ink`                  | `oklch(0.362 0.067 178)`                                                                                                                                              | Text and text-sized icons on `surface`. Clears the text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `--opsin-status-steady-accent`               | `oklch(0.62 0.11 178)`                                                                                                                                                | The identity fill: a bar fill, a dial track, a legend dot. Chosen for recognition, not for contrast. It must be bounded by `line` or labelled in `ink`; it is never the only thing that carries the meaning.                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-status-steady-plate`                | `oklch(0.5 0.1 167)`                                                                                                                                                  | Steady plate: the enamel face StatusPill is filled with.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| `--opsin-status-steady-plate-lit`            | `oklch(0.54 0.105 165)`                                                                                                                                               | Steady plate: the band along the top edge of the face, where it turns to the light.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |\n| `--opsin-status-steady-plate-rim`            | `oklch(0.41 0.08 168)`                                                                                                                                                | Steady plate: the outline of the plate, and the tint of the shadow it casts.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-status-steady-plate-word`           | `oklch(1 0 0)`                                                                                                                                                        | Steady plate: the word and the glyph on the plate. Clears the body-text floor on the face and on the lit band.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |\n| `--opsin-status-watch-50`                    | `oklch(0.972 0.02 82)`                                                                                                                                                | Watch ramp, step 50.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-status-watch-100`                   | `oklch(0.941 0.034 82)`                                                                                                                                               | Watch ramp, step 100.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-status-watch-200`                   | `oklch(0.884 0.059 82)`                                                                                                                                               | Watch ramp, step 200.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-status-watch-300`                   | `oklch(0.806 0.092 82)`                                                                                                                                               | Watch ramp, step 300.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-status-watch-400`                   | `oklch(0.714 0.123 82)`                                                                                                                                               | Watch ramp, step 400.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-status-watch-500`                   | `oklch(0.622 0.129 82)`                                                                                                                                               | Watch ramp, step 500.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-status-watch-600`                   | `oklch(0.541 0.112 82)`                                                                                                                                               | Watch ramp, step 600.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-status-watch-700`                   | `oklch(0.452 0.094 82)`                                                                                                                                               | Watch ramp, step 700.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-status-watch-800`                   | `oklch(0.362 0.076 82)`                                                                                                                                               | Watch ramp, step 800.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-status-watch-900`                   | `oklch(0.276 0.059 82)`                                                                                                                                               | Watch ramp, step 900.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-status-watch-950`                   | `oklch(0.208 0.046 82)`                                                                                                                                               | Watch ramp, step 950.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-status-watch-surface`               | `oklch(0.972 0.02 82)`                                                                                                                                                | The tinted background a component in this ramp sits on.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-status-watch-line`                  | `oklch(0.541 0.112 82)`                                                                                                                                               | The boundary, icon stroke or chart mark. The lightest value in the ramp that clears the non-text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-status-watch-ink`                   | `oklch(0.362 0.076 82)`                                                                                                                                               | Text and text-sized icons on `surface`. Clears the text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `--opsin-status-watch-accent`                | `oklch(0.60 0.123 82)`                                                                                                                                                | The identity fill: a bar fill, a dial track, a legend dot. Chosen for recognition, not for contrast. It must be bounded by `line` or labelled in `ink`; it is never the only thing that carries the meaning.                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-status-watch-plate`                 | `oklch(0.855 0.148 83)`                                                                                                                                               | Watch plate: the enamel face StatusPill is filled with.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-status-watch-plate-lit`             | `oklch(0.885 0.132 87)`                                                                                                                                               | Watch plate: the band along the top edge of the face, where it turns to the light.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |\n| `--opsin-status-watch-plate-rim`             | `oklch(0.7 0.12 78)`                                                                                                                                                  | Watch plate: the outline of the plate, and the tint of the shadow it casts.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |\n| `--opsin-status-watch-plate-word`            | `oklch(0.21 0.045 68)`                                                                                                                                                | Watch plate: the word and the glyph on the plate. Clears the body-text floor on the face and on the lit band.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |\n| `--opsin-status-attention-50`                | `oklch(0.972 0.015 45)`                                                                                                                                               | Needs attention ramp, step 50.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |\n| `--opsin-status-attention-100`               | `oklch(0.941 0.032 45)`                                                                                                                                               | Needs attention ramp, step 100.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |\n| `--opsin-status-attention-200`               | `oklch(0.884 0.063 45)`                                                                                                                                               | Needs attention ramp, step 200.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |\n| `--opsin-status-attention-300`               | `oklch(0.806 0.099 45)`                                                                                                                                               | Needs attention ramp, step 300.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |\n| `--opsin-status-attention-400`               | `oklch(0.714 0.132 45)`                                                                                                                                               | Needs attention ramp, step 400.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |\n| `--opsin-status-attention-500`               | `oklch(0.622 0.15 45)`                                                                                                                                                | Needs attention ramp, step 500.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |\n| `--opsin-status-attention-600`               | `oklch(0.541 0.145 45)`                                                                                                                                               | Needs attention ramp, step 600.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |\n| `--opsin-status-attention-700`               | `oklch(0.452 0.13 45)`                                                                                                                                                | Needs attention ramp, step 700.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |\n| `--opsin-status-attention-800`               | `oklch(0.362 0.105 45)`                                                                                                                                               | Needs attention ramp, step 800.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |\n| `--opsin-status-attention-900`               | `oklch(0.276 0.082 45)`                                                                                                                                               | Needs attention ramp, step 900.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |\n| `--opsin-status-attention-950`               | `oklch(0.208 0.065 45)`                                                                                                                                               | Needs attention ramp, step 950.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |\n| `--opsin-status-attention-surface`           | `oklch(0.972 0.015 45)`                                                                                                                                               | The tinted background a component in this ramp sits on.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-status-attention-line`              | `oklch(0.541 0.145 45)`                                                                                                                                               | The boundary, icon stroke or chart mark. The lightest value in the ramp that clears the non-text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-status-attention-ink`               | `oklch(0.362 0.105 45)`                                                                                                                                               | Text and text-sized icons on `surface`. Clears the text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `--opsin-status-attention-accent`            | `oklch(0.58 0.15 45)`                                                                                                                                                 | The identity fill: a bar fill, a dial track, a legend dot. Chosen for recognition, not for contrast. It must be bounded by `line` or labelled in `ink`; it is never the only thing that carries the meaning.                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-status-attention-plate`             | `oklch(0.54 0.165 43)`                                                                                                                                                | Needs attention plate: the enamel face StatusPill is filled with.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |\n| `--opsin-status-attention-plate-lit`         | `oklch(0.575 0.16 46)`                                                                                                                                                | Needs attention plate: the band along the top edge of the face, where it turns to the light.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-status-attention-plate-rim`         | `oklch(0.44 0.13 40)`                                                                                                                                                 | Needs attention plate: the outline of the plate, and the tint of the shadow it casts.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-status-attention-plate-word`        | `oklch(1 0 0)`                                                                                                                                                        | Needs attention plate: the word and the glyph on the plate. Clears the body-text floor on the face and on the lit band.                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-status-urgent-50`                   | `oklch(0.972 0.014 27)`                                                                                                                                               | Urgent ramp, step 50.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-status-urgent-100`                  | `oklch(0.941 0.03 27)`                                                                                                                                                | Urgent ramp, step 100.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-status-urgent-200`                  | `oklch(0.884 0.061 27)`                                                                                                                                               | Urgent ramp, step 200.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-status-urgent-300`                  | `oklch(0.806 0.11 27)`                                                                                                                                                | Urgent ramp, step 300.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-status-urgent-400`                  | `oklch(0.714 0.176 27)`                                                                                                                                               | Urgent ramp, step 400.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-status-urgent-500`                  | `oklch(0.622 0.2 27)`                                                                                                                                                 | Urgent ramp, step 500.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-status-urgent-600`                  | `oklch(0.541 0.194 27)`                                                                                                                                               | Urgent ramp, step 600.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-status-urgent-700`                  | `oklch(0.452 0.176 27)`                                                                                                                                               | Urgent ramp, step 700.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-status-urgent-800`                  | `oklch(0.362 0.148 27)`                                                                                                                                               | Urgent ramp, step 800.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-status-urgent-900`                  | `oklch(0.276 0.115 27)`                                                                                                                                               | Urgent ramp, step 900.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-status-urgent-950`                  | `oklch(0.208 0.088 27)`                                                                                                                                               | Urgent ramp, step 950.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-status-urgent-surface`              | `oklch(0.972 0.014 27)`                                                                                                                                               | The tinted background a component in this ramp sits on.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-status-urgent-line`                 | `oklch(0.541 0.194 27)`                                                                                                                                               | The boundary, icon stroke or chart mark. The lightest value in the ramp that clears the non-text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-status-urgent-ink`                  | `oklch(0.362 0.148 27)`                                                                                                                                               | Text and text-sized icons on `surface`. Clears the text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `--opsin-status-urgent-accent`               | `oklch(0.52 0.2 27)`                                                                                                                                                  | The identity fill: a bar fill, a dial track, a legend dot. Chosen for recognition, not for contrast. It must be bounded by `line` or labelled in `ink`; it is never the only thing that carries the meaning.                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-status-urgent-plate`                | `oklch(0.5 0.19 25)`                                                                                                                                                  | Urgent plate: the enamel face StatusPill is filled with.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| `--opsin-status-urgent-plate-lit`            | `oklch(0.54 0.19 26)`                                                                                                                                                 | Urgent plate: the band along the top edge of the face, where it turns to the light.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |\n| `--opsin-status-urgent-plate-rim`            | `oklch(0.4 0.15 24)`                                                                                                                                                  | Urgent plate: the outline of the plate, and the tint of the shadow it casts.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-status-urgent-plate-word`           | `oklch(1 0 0)`                                                                                                                                                        | Urgent plate: the word and the glyph on the plate. Clears the body-text floor on the face and on the lit band.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |\n| `--opsin-status-unknown-50`                  | `oklch(0.972 0.003 250)`                                                                                                                                              | Unknown ramp, step 50.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-status-unknown-100`                 | `oklch(0.941 0.005 250)`                                                                                                                                              | Unknown ramp, step 100.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-status-unknown-200`                 | `oklch(0.884 0.008 250)`                                                                                                                                              | Unknown ramp, step 200.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-status-unknown-300`                 | `oklch(0.806 0.013 250)`                                                                                                                                              | Unknown ramp, step 300.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-status-unknown-400`                 | `oklch(0.714 0.018 250)`                                                                                                                                              | Unknown ramp, step 400.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-status-unknown-500`                 | `oklch(0.622 0.02 250)`                                                                                                                                               | Unknown ramp, step 500.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-status-unknown-600`                 | `oklch(0.541 0.019 250)`                                                                                                                                              | Unknown ramp, step 600.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-status-unknown-700`                 | `oklch(0.452 0.018 250)`                                                                                                                                              | Unknown ramp, step 700.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-status-unknown-800`                 | `oklch(0.362 0.015 250)`                                                                                                                                              | Unknown ramp, step 800.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-status-unknown-900`                 | `oklch(0.276 0.012 250)`                                                                                                                                              | Unknown ramp, step 900.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-status-unknown-950`                 | `oklch(0.208 0.009 250)`                                                                                                                                              | Unknown ramp, step 950.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-status-unknown-surface`             | `oklch(0.972 0.003 250)`                                                                                                                                              | The tinted background a component in this ramp sits on.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-status-unknown-line`                | `oklch(0.541 0.019 250)`                                                                                                                                              | The boundary, icon stroke or chart mark. The lightest value in the ramp that clears the non-text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-status-unknown-ink`                 | `oklch(0.362 0.015 250)`                                                                                                                                              | Text and text-sized icons on `surface`. Clears the text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `--opsin-status-unknown-accent`              | `oklch(0.72 0.02 250)`                                                                                                                                                | The identity fill: a bar fill, a dial track, a legend dot. Chosen for recognition, not for contrast. It must be bounded by `line` or labelled in `ink`; it is never the only thing that carries the meaning.                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-material-canvas-tint`               | `var(--opsin-neutral-0)`                                                                                                                                              | Rung 0 (canvas): the tint over what is behind it. The application background. Nothing is behind it, so nothing shows through it.                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `--opsin-material-canvas-tint-alpha`         | `1`                                                                                                                                                                   | Rung 0 (canvas): how opaque that tint is.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-material-canvas-blur`               | `0px`                                                                                                                                                                 | Rung 0 (canvas): backdrop blur radius.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-material-canvas-saturation`         | `1`                                                                                                                                                                   | Rung 0 (canvas): backdrop saturation multiplier.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `--opsin-material-canvas-border`             | `none`                                                                                                                                                                | Rung 0 (canvas): the boundary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |\n| `--opsin-material-canvas-shadow`             | `none`                                                                                                                                                                | Rung 0 (canvas): the shadow that separates it from what is behind.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |\n| `--opsin-material-canvas-scrim`              | `0`                                                                                                                                                                   | Rung 0 (canvas): the minimum scrim opacity needed for text on this rung to clear the contrast floor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-material-canvas-opaque`             | `var(--opsin-neutral-0)`                                                                                                                                              | Rung 0 (canvas): the opaque substitute used under prefers-reduced-transparency and where backdrop-filter is unsupported.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| `--opsin-material-inset-tint`                | `var(--opsin-neutral-100)`                                                                                                                                            | Rung 0.5 (inset): the tint over what is behind it. The recessed well inside a card: the explanatory note a Callout draws inside the reading it annotates, and the track a RangeBar lays its range along. Its fill sits below the card fill in both themes, so the well reads as carved into the card rather than lifted off it. In light it is neutral-100, one step under the white card, which is where a Callout already sat. In dark it is a value between the page and the card, below the card so the well is a recess and above the page so a Callout used on its own is still visible. |\n| `--opsin-material-inset-tint-alpha`          | `1`                                                                                                                                                                   | Rung 0.5 (inset): how opaque that tint is.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |\n| `--opsin-material-inset-blur`                | `0px`                                                                                                                                                                 | Rung 0.5 (inset): backdrop blur radius.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-material-inset-saturation`          | `1`                                                                                                                                                                   | Rung 0.5 (inset): backdrop saturation multiplier.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |\n| `--opsin-material-inset-border`              | `none`                                                                                                                                                                | Rung 0.5 (inset): the boundary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |\n| `--opsin-material-inset-shadow`              | `none`                                                                                                                                                                | Rung 0.5 (inset): the shadow that separates it from what is behind.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |\n| `--opsin-material-inset-scrim`               | `0`                                                                                                                                                                   | Rung 0.5 (inset): the minimum scrim opacity needed for text on this rung to clear the contrast floor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-material-inset-opaque`              | `var(--opsin-neutral-100)`                                                                                                                                            | Rung 0.5 (inset): the opaque substitute used under prefers-reduced-transparency and where backdrop-filter is unsupported.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-material-card-tint`                 | `var(--opsin-neutral-0)`                                                                                                                                              | Rung 1 (card): the tint over what is behind it. The default home for a health value. Opaque, edged by a decorative line, and lifted off the page by a soft drop and a line of light along its top. The rung every ResultCard, MetricTile and RangeBar sits on.                                                                                                                                                                                                                                                                                                                                 |\n| `--opsin-material-card-tint-alpha`           | `1`                                                                                                                                                                   | Rung 1 (card): how opaque that tint is.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-material-card-blur`                 | `0px`                                                                                                                                                                 | Rung 1 (card): backdrop blur radius.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-material-card-saturation`           | `1`                                                                                                                                                                   | Rung 1 (card): backdrop saturation multiplier.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |\n| `--opsin-material-card-border`               | `var(--opsin-chrome-edge)`                                                                                                                                            | Rung 1 (card): the boundary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-material-card-shadow`               | `inset 0 1px 0 0 oklch(1 0 0 / 0.7), 0 1px 2px 0 oklch(0.205 0.006 250 / 0.05), 0 10px 30px -14px oklch(0.205 0.006 250 / 0.16)`                                      | Rung 1 (card): the shadow that separates it from what is behind.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `--opsin-material-card-scrim`                | `0`                                                                                                                                                                   | Rung 1 (card): the minimum scrim opacity needed for text on this rung to clear the contrast floor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |\n| `--opsin-material-card-opaque`               | `var(--opsin-neutral-0)`                                                                                                                                              | Rung 1 (card): the opaque substitute used under prefers-reduced-transparency and where backdrop-filter is unsupported.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-material-raised-tint`               | `var(--opsin-neutral-0)`                                                                                                                                              | Rung 2 (raised): the tint over what is behind it. Menus, popovers, tooltips, a dragged card. Still opaque: the shadow, not translucency, is what says 'above'.                                                                                                                                                                                                                                                                                                                                                                                                                                 |\n| `--opsin-material-raised-tint-alpha`         | `1`                                                                                                                                                                   | Rung 2 (raised): how opaque that tint is.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-material-raised-blur`               | `0px`                                                                                                                                                                 | Rung 2 (raised): backdrop blur radius.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-material-raised-saturation`         | `1`                                                                                                                                                                   | Rung 2 (raised): backdrop saturation multiplier.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `--opsin-material-raised-border`             | `var(--opsin-chrome-edge)`                                                                                                                                            | Rung 2 (raised): the boundary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |\n| `--opsin-material-raised-shadow`             | `inset 0 1px 0 0 oklch(1 0 0 / 0.8), 0 2px 8px -2px oklch(0.205 0.006 250 / 0.08), 0 22px 52px -20px oklch(0.205 0.006 250 / 0.28)`                                   | Rung 2 (raised): the shadow that separates it from what is behind.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |\n| `--opsin-material-raised-scrim`              | `0`                                                                                                                                                                   | Rung 2 (raised): the minimum scrim opacity needed for text on this rung to clear the contrast floor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-material-raised-opaque`             | `var(--opsin-neutral-0)`                                                                                                                                              | Rung 2 (raised): the opaque substitute used under prefers-reduced-transparency and where backdrop-filter is unsupported.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| `--opsin-material-sheet-tint`                | `var(--opsin-neutral-0)`                                                                                                                                              | Rung 3 (sheet): the tint over what is behind it. A bottom sheet or side panel the reader can dismiss by dragging. Its tint is now near opaque, so the panel lands close to the card colour and a white control inside it no longer floats above a greyer surface. What keeps the covered page recognisable is the scrim around the panel rather than the page reading through the panel, because at this opacity very little of the page shows through the tint.                                                                                                                               |\n| `--opsin-material-sheet-tint-alpha`          | `0.93`                                                                                                                                                                | Rung 3 (sheet): how opaque that tint is.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| `--opsin-material-sheet-blur`                | `20px`                                                                                                                                                                | Rung 3 (sheet): backdrop blur radius.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-material-sheet-saturation`          | `1.6`                                                                                                                                                                 | Rung 3 (sheet): backdrop saturation multiplier.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |\n| `--opsin-material-sheet-border`              | `var(--opsin-chrome-edge)`                                                                                                                                            | Rung 3 (sheet): the boundary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |\n| `--opsin-material-sheet-shadow`              | `inset 0 1px 0 0 oklch(1 0 0 / 0.8), 0 4px 12px -4px oklch(0.205 0.006 250 / 0.1), 0 40px 96px -28px oklch(0.205 0.006 250 / 0.38)`                                   | Rung 3 (sheet): the shadow that separates it from what is behind.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |\n| `--opsin-material-sheet-scrim`               | `0.93`                                                                                                                                                                | Rung 3 (sheet): the minimum scrim opacity needed for text on this rung to clear the contrast floor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |\n| `--opsin-material-sheet-opaque`              | `var(--opsin-neutral-0)`                                                                                                                                              | Rung 3 (sheet): the opaque substitute used under prefers-reduced-transparency and where backdrop-filter is unsupported.                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-material-overlay-tint`              | `var(--opsin-neutral-0)`                                                                                                                                              | Rung 4 (overlay): the tint over what is behind it. A pinned toolbar, a tab bar and a floating action bar are all chrome that content scrolls beneath.                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-material-overlay-tint-alpha`        | `0.74`                                                                                                                                                                | Rung 4 (overlay): how opaque that tint is.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |\n| `--opsin-material-overlay-blur`              | `16px`                                                                                                                                                                | Rung 4 (overlay): backdrop blur radius.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-material-overlay-saturation`        | `1.8`                                                                                                                                                                 | Rung 4 (overlay): backdrop saturation multiplier.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |\n| `--opsin-material-overlay-border`            | `var(--opsin-chrome-edge)`                                                                                                                                            | Rung 4 (overlay): the boundary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |\n| `--opsin-material-overlay-shadow`            | `inset 0 1px 0 0 oklch(1 0 0 / 0.55), 0 1px 2px 0 oklch(0.205 0.006 250 / 0.05), 0 12px 32px -14px oklch(0.205 0.006 250 / 0.2)`                                      | Rung 4 (overlay): the shadow that separates it from what is behind.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |\n| `--opsin-material-overlay-scrim`             | `0.74`                                                                                                                                                                | Rung 4 (overlay): the minimum scrim opacity needed for text on this rung to clear the contrast floor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-material-overlay-opaque`            | `var(--opsin-neutral-0)`                                                                                                                                              | Rung 4 (overlay): the opaque substitute used under prefers-reduced-transparency and where backdrop-filter is unsupported.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-material-scrim-tint`                | `var(--opsin-neutral-950)`                                                                                                                                            | Rung 5 (scrim): the tint over what is behind it. The dimming layer behind a modal dialog or a consent sheet. Its job is to remove the page from consideration, not to look like glass.                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-material-scrim-tint-alpha`          | `0.44`                                                                                                                                                                | Rung 5 (scrim): how opaque that tint is.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| `--opsin-material-scrim-blur`                | `2px`                                                                                                                                                                 | Rung 5 (scrim): backdrop blur radius.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-material-scrim-saturation`          | `1`                                                                                                                                                                   | Rung 5 (scrim): backdrop saturation multiplier.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |\n| `--opsin-material-scrim-border`              | `none`                                                                                                                                                                | Rung 5 (scrim): the boundary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |\n| `--opsin-material-scrim-shadow`              | `none`                                                                                                                                                                | Rung 5 (scrim): the shadow that separates it from what is behind.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |\n| `--opsin-material-scrim-scrim`               | `0.44`                                                                                                                                                                | Rung 5 (scrim): the minimum scrim opacity needed for text on this rung to clear the contrast floor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |\n| `--opsin-material-scrim-opaque`              | `oklch(0.205 0.006 250 / 0.72)`                                                                                                                                       | Rung 5 (scrim): the opaque substitute used under prefers-reduced-transparency and where backdrop-filter is unsupported.                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-ease-spring-snap`                   | `linear(0, 0.0715, 0.2271, 0.4053, 0.5722, 0.7119, 0.8198, 0.8978, 0.9505, 0.9836, 1.0025, 1.0118, 1.015, 1.0147, 1.0126, 1.01, 1.0073, 1.0051, 1.0033, 1.0019, 1)`   | Direct manipulation only: a switch the reader just flipped, a box ticked or a radio chosen, a segmented control or a tab indicator gliding to the new choice, a pressed button settling. It overshoots by 1.5%. That is enough to feel physical but not enough to look playful. The 1.5% is the largest overshoot in the system but not the only one: `spring-settle` overshoots by 0.88%. Only `spring-calm` and `spring-sheet` reach their target without passing it.                                                                                                                        |\n| `--opsin-duration-spring-snap`               | `283ms`                                                                                                                                                               | Settle time for the spring-snap spring, measured from its own parameters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-ease-spring-settle`                 | `linear(0, 0.0742, 0.2328, 0.4113, 0.5758, 0.7116, 0.8157, 0.8905, 0.9412, 0.9736, 0.9928, 1.003, 1.0076, 1.0088, 1.0082, 1.0068, 1.0053, 1.0038, 1.0026, 1.0017, 1)` | The workhorse for chrome: popovers, tooltips, menus, selects and comboboxes unfolding from their anchor, chips and toasts appearing and disappearing, and a swiped toast springing back.                                                                                                                                                                                                                                                                                                                                                                                                       |\n| `--opsin-duration-spring-settle`             | `382ms`                                                                                                                                                               | Settle time for the spring-settle spring, measured from its own parameters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |\n| `--opsin-ease-spring-calm`                   | `linear(0, 0.0829, 0.2457, 0.4157, 0.5642, 0.6832, 0.774, 0.841, 0.8893, 0.9236, 0.9476, 0.9643, 0.9757, 0.9836, 0.9889, 0.9926, 0.995, 0.9967, 0.9978, 0.9985, 1)`   | A health value that changes while it is already on screen: a bar re-filling from one reading to the next, a dial travelling between two values the reader has already been shown. Never a first paint and never a first reveal. A value arrives at its final figure, with no count-up, no dial sweep and no line drawing itself in (health/motion-in-health-ui rule 2). Slightly overdamped (zeta just over 1) so it never overshoots and never bounces.                                                                                                                                       |\n| `--opsin-duration-spring-calm`               | `550ms`                                                                                                                                                               | Settle time for the spring-calm spring, measured from its own parameters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-ease-spring-sheet`                  | `linear(0, 0.0881, 0.2576, 0.431, 0.5798, 0.6971, 0.7854, 0.8497, 0.8958, 0.9282, 0.9508, 0.9664, 0.9771, 0.9845, 0.9895, 0.9929, 0.9952, 0.9967, 0.9978, 0.9985, 1)` | Large surfaces travelling a long distance: sheets, dialogs, full-screen pushes. Overdamped, because a sheet that bounces at the top of its travel reads as a dropped object.                                                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-duration-spring-sheet`              | `483ms`                                                                                                                                                               | Settle time for the spring-sheet spring, measured from its own parameters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |\n| `--opsin-ease-standard`                      | `cubic-bezier(0.2, 0, 0, 1)`                                                                                                                                          | Non-spring transitions where a spring would be overkill: colour, opacity, border. Fast out, slow in.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-ease-enter`                         | `cubic-bezier(0.05, 0.7, 0.1, 1)`                                                                                                                                     | Something arriving from off-screen or from nothing. Decelerating, because an arrival should feel like it is coming to rest.                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |\n| `--opsin-ease-exit`                          | `cubic-bezier(0.3, 0, 0.8, 0.15)`                                                                                                                                     | Something leaving. Accelerating and shorter than its enter, because a reader does not need to watch a dismissal finish.                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-duration-instant`                   | `80ms`                                                                                                                                                                | State change with no travel: hover tint, focus ring. Also the way down of a press, which `foundations/states` applies on pointer-down and `spring-snap` brings back up.                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-duration-fast`                      | `140ms`                                                                                                                                                               | Small elements moving a small distance.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-duration-base`                      | `220ms`                                                                                                                                                               | The default for chrome that is not spring-driven.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |\n| `--opsin-duration-slow`                      | `360ms`                                                                                                                                                               | Layout change: a list reflowing, a card expanding.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |\n| `--opsin-duration-deliberate`                | `560ms`                                                                                                                                                               | The ceiling on a transition a reader is waiting on, such as a first-run reveal or a consent sheet, where the point is that the reader notices. No such transition may exceed it. A looping placeholder period, like the skeleton shimmer, is bounded instead by its iteration count, so a single sweep of it may run longer.                                                                                                                                                                                                                                                                   |\n| `--opsin-duration-shimmer`                   | `1600ms`                                                                                                                                                              | One sweep of a loading placeholder's sheen. This is a period, the time for the sheen to make one pass across the bar, and not a travel time. At 1600ms the movement reads as calm rather than as urgency, which the first motion rule requires of anything that is not a value the reader controls. Its consumer pairs it with a finite iteration count so the total motion stays under the five seconds at which WCAG 2.2 SC 2.2.2 engages.                                                                                                                                                   |\n| `--opsin-font-sans`                          | `system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif`                                                                                   | The sans family stack.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-font-mono`                          | `ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, 'Liberation Mono', monospace`                                                                              | The mono family stack.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-font-numeric`                       | `system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif`                                                                                                            | The numeric family stack.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-text-large-title-size`              | `2.125rem`                                                                                                                                                            | The largest step in the scale, reserved for a surface whose entire subject is one number or one word. No component in the system sets a value at this step yet.                                                                                                                                                                                                                                                                                                                                                                                                                                |\n| `--opsin-text-large-title-leading`           | `1.118`                                                                                                                                                               | Line height for largeTitle, unitless so it scales with the size.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `--opsin-text-large-title-tracking`          | `-0.032em`                                                                                                                                                            | Letter spacing for largeTitle.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |\n| `--opsin-text-large-title-weight`            | `800`                                                                                                                                                                 | Font weight for largeTitle.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |\n| `--opsin-text-title1-size`                   | `1.75rem`                                                                                                                                                             | A screen title, and the hero treatment a value's number takes at size display.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |\n| `--opsin-text-title1-leading`                | `1.143`                                                                                                                                                               | Line height for title1, unitless so it scales with the size.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-text-title1-tracking`               | `-0.026em`                                                                                                                                                            | Letter spacing for title1.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |\n| `--opsin-text-title1-weight`                 | `800`                                                                                                                                                                 | Font weight for title1.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-text-title2-size`                   | `1.375rem`                                                                                                                                                            | Section title; the floor for a primary health value inside a card.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |\n| `--opsin-text-title2-leading`                | `1.227`                                                                                                                                                               | Line height for title2, unitless so it scales with the size.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-text-title2-tracking`               | `-0.018em`                                                                                                                                                            | Letter spacing for title2.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |\n| `--opsin-text-title2-weight`                 | `700`                                                                                                                                                                 | Font weight for title2.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-text-title3-size`                   | `1.25rem`                                                                                                                                                             | A Dialog or Sheet title, and the unit beside a value's number at size display.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |\n| `--opsin-text-title3-leading`                | `1.25`                                                                                                                                                                | Line height for title3, unitless so it scales with the size.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-text-title3-tracking`               | `-0.014em`                                                                                                                                                            | Letter spacing for title3.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |\n| `--opsin-text-title3-weight`                 | `700`                                                                                                                                                                 | Font weight for title3.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-text-headline-size`                 | `1.0625rem`                                                                                                                                                           | An emphasised line of body text, such as a status sentence or a question in a form.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |\n| `--opsin-text-headline-leading`              | `1.412`                                                                                                                                                               | Line height for headline, unitless so it scales with the size.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |\n| `--opsin-text-headline-tracking`             | `-0.006em`                                                                                                                                                            | Letter spacing for headline.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-text-headline-weight`               | `600`                                                                                                                                                                 | Font weight for headline.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-text-body-size`                     | `1.0625rem`                                                                                                                                                           | Everything a reader reads as prose. The anchor of the scale.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-text-body-leading`                  | `1.412`                                                                                                                                                               | Line height for body, unitless so it scales with the size.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |\n| `--opsin-text-body-tracking`                 | `-0.003em`                                                                                                                                                            | Letter spacing for body.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| `--opsin-text-body-weight`                   | `400`                                                                                                                                                                 | Font weight for body.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-text-callout-size`                  | `1rem`                                                                                                                                                                | Secondary prose inside a card or a callout.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |\n| `--opsin-text-callout-leading`               | `1.375`                                                                                                                                                               | Line height for callout, unitless so it scales with the size.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |\n| `--opsin-text-callout-tracking`              | `-0.002em`                                                                                                                                                            | Letter spacing for callout.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |\n| `--opsin-text-callout-weight`                | `400`                                                                                                                                                                 | Font weight for callout.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| `--opsin-text-subheadline-size`              | `0.9375rem`                                                                                                                                                           | A supporting line under a title.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `--opsin-text-subheadline-leading`           | `1.333`                                                                                                                                                               | Line height for subheadline, unitless so it scales with the size.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |\n| `--opsin-text-subheadline-tracking`          | `-0.001em`                                                                                                                                                            | Letter spacing for subheadline.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |\n| `--opsin-text-subheadline-weight`            | `400`                                                                                                                                                                 | Font weight for subheadline.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-text-subheadline-emphasis-size`     | `0.9375rem`                                                                                                                                                           | The emphasised twin of subheadline, for a compact control's label, where the control must read as narrower and never as quieter.                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `--opsin-text-subheadline-emphasis-leading`  | `1.333`                                                                                                                                                               | Line height for subheadlineEmphasis, unitless so it scales with the size.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-text-subheadline-emphasis-tracking` | `-0.001em`                                                                                                                                                            | Letter spacing for subheadlineEmphasis.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-text-subheadline-emphasis-weight`   | `600`                                                                                                                                                                 | Font weight for subheadlineEmphasis.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-text-footnote-size`                 | `0.8125rem`                                                                                                                                                           | Provenance: who measured this, when, with what.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |\n| `--opsin-text-footnote-leading`              | `1.385`                                                                                                                                                               | Line height for footnote, unitless so it scales with the size.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |\n| `--opsin-text-footnote-tracking`             | `0em`                                                                                                                                                                 | Letter spacing for footnote.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-text-footnote-weight`               | `400`                                                                                                                                                                 | Font weight for footnote.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-text-caption1-size`                 | `0.75rem`                                                                                                                                                             | Axis labels, legend text, and legal text.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-text-caption1-leading`              | `1.333`                                                                                                                                                               | Line height for caption1, unitless so it scales with the size.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |\n| `--opsin-text-caption1-tracking`             | `0.002em`                                                                                                                                                             | Letter spacing for caption1.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-text-caption1-weight`               | `400`                                                                                                                                                                 | Font weight for caption1.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-text-caption2-size`                 | `0.6875rem`                                                                                                                                                           | The smallest text the system permits, and only for text that repeats a label already present elsewhere. Never the only place a fact appears.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-text-caption2-leading`              | `1.273`                                                                                                                                                               | Line height for caption2, unitless so it scales with the size.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |\n| `--opsin-text-caption2-tracking`             | `0.01em`                                                                                                                                                              | Letter spacing for caption2.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-text-caption2-weight`               | `600`                                                                                                                                                                 | Font weight for caption2.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-numerals`                           | `tabular-nums`                                                                                                                                                        | Every component that renders a number sets this, so a changing value does not shift its own layout.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |\n| `--opsin-space-0`                            | `0rem`                                                                                                                                                                | 0px.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-space-1`                            | `0.25rem`                                                                                                                                                             | Gap between an icon and its label.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |\n| `--opsin-space-2`                            | `0.5rem`                                                                                                                                                              | Gap between tightly related lines. For the separation between two interactive targets see targets.separation, which is the same number and carries its scope.                                                                                                                                                                                                                                                                                                                                                                                                                                  |\n| `--opsin-space-3`                            | `0.75rem`                                                                                                                                                             | Inner padding of a compact control.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |\n| `--opsin-space-4`                            | `1rem`                                                                                                                                                                | The default gap between elements inside a card.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |\n| `--opsin-space-5`                            | `1.25rem`                                                                                                                                                             | Card inner padding on a phone.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |\n| `--opsin-space-6`                            | `1.5rem`                                                                                                                                                              | Card inner padding on a wide screen; gap between cards.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-space-8`                            | `2rem`                                                                                                                                                                | Gap between sections within a screen.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-space-10`                           | `2.5rem`                                                                                                                                                              | Space above a section heading.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |\n| `--opsin-space-12`                           | `3rem`                                                                                                                                                                | Gap between major regions of a screen.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-space-16`                           | `4rem`                                                                                                                                                                | Top of a screen below the safe area; the space a consent sheet leaves above its first question.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |\n| `--opsin-space-20`                           | `5rem`                                                                                                                                                                | Empty-state vertical rhythm.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-space-24`                           | `6rem`                                                                                                                                                                | The largest step. Beyond this, use a layout, not a gap.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-space-px`                           | `0.0625rem`                                                                                                                                                           | Hairline borders only.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-space-0-5`                          | `0.125rem`                                                                                                                                                            | Optical nudges. Not a layout step.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |\n| `--opsin-target-minimum`                     | `2.75rem`                                                                                                                                                             | The opsinjs floor for any interactive control, applied to the hit area rather than to the visible box.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-target-comfortable`                 | `3rem`                                                                                                                                                                | The default for a primary action in the product theme.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-target-generous`                    | `3.5rem`                                                                                                                                                              | A single primary action on a consent, escalation or emergency surface, where a mis-tap has a real cost.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-target-separation`                  | `0.5rem`                                                                                                                                                              | The minimum gap between two adjacent targets whose visible boxes are smaller than 44px. It is a floor for undersized targets only. Two targets that both meet the 44px minimum are outside its scope, and separating those is governed by the differing cost of a mis-tap between them rather than by a fixed gap.                                                                                                                                                                                                                                                                             |\n| `--opsin-gutter-phone`                       | `16px`                                                                                                                                                                | The screen gutter in the phone responsive mode.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |\n| `--opsin-gutter-tablet`                      | `24px`                                                                                                                                                                | The screen gutter in the tablet responsive mode.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `--opsin-gutter-wide`                        | `32px`                                                                                                                                                                | The screen gutter in the wide responsive mode.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |\n| `--opsin-measure-tight`                      | `45ch`                                                                                                                                                                | A caption or a legend.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-measure-comfortable`                | `66ch`                                                                                                                                                                | The maximum line length for prose anywhere in the product, including a disclaimer nobody wants to read.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-measure-wide`                       | `80ch`                                                                                                                                                                | Code and machine output only.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |\n| `--opsin-graphic-dial`                       | `17rem`                                                                                                                                                               | The maximum width of the ScoreDial arc. This is 16em against the product body of 1.0625rem, which is 17rem and lands on the 4px grid at 68 steps, and it yields to w-full when the column is narrower.                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-safe-top`                           | `env(safe-area-inset-top, 0px)`                                                                                                                                       | The top safe-area inset, for installed web apps where browser chrome does not protect the edge.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |\n| `--opsin-safe-right`                         | `env(safe-area-inset-right, 0px)`                                                                                                                                     | The right safe-area inset, for installed web apps where browser chrome does not protect the edge.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |\n| `--opsin-safe-bottom`                        | `env(safe-area-inset-bottom, 0px)`                                                                                                                                    | The bottom safe-area inset, for installed web apps where browser chrome does not protect the edge.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |\n| `--opsin-safe-left`                          | `env(safe-area-inset-left, 0px)`                                                                                                                                      | The left safe-area inset, for installed web apps where browser chrome does not protect the edge.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `--opsin-radius-base`                        | `1.25rem`                                                                                                                                                             | The one radius the whole ladder is derived from.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `--opsin-radius-none`                        | `0rem`                                                                                                                                                                | Full-bleed media and anything that meets a screen edge.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-radius-xs`                          | `0.3125rem`                                                                                                                                                           | The floor for a nested corner. Tags inside a chip, a swatch inside a legend.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-radius-sm`                          | `0.625rem`                                                                                                                                                            | Inputs, small controls and a well inside a card.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `--opsin-radius-md`                          | `1.25rem`                                                                                                                                                             | The default for a bounded surface: a card, a tile, a callout, a list row.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-radius-lg`                          | `1.875rem`                                                                                                                                                            | A card nearly the width of a phone screen, and a banner.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| `--opsin-radius-xl`                          | `2.5rem`                                                                                                                                                              | Sheets and dialogs. Applied to the leading edge only when the surface meets a screen edge on the other side.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-radius-inner-card`                  | `max(calc(1.25rem - 5 * var(--spacing)), var(--opsin-radius-xs))`                                                                                                     | A box inside a card at the comfortable density (card padding p-5).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |\n| `--opsin-radius-inner-card-compact`          | `max(calc(1.25rem - 4 * var(--spacing)), var(--opsin-radius-xs))`                                                                                                     | A box inside a card at the compact density (card padding p-4).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |\n| `--opsin-corner-shape`                       | `superellipse(2)`                                                                                                                                                     | The squircle curvature. Degrades to `round` where corner-shape is unsupported.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |\n| `--opsin-border-hairline`                    | `1px`                                                                                                                                                                 | Every boundary in the system by default.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| `--opsin-border-emphasis`                    | `2px`                                                                                                                                                                 | The boundary of a surface carrying `attention` or `urgent`, where the boundary is one of the three non-colour carriers of the status.                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-border-focus`                       | `2px`                                                                                                                                                                 | The focus ring. Always 2px with a 2px offset, always in a colour measured against both the surface and the page behind it, and never removed. See /docs/accessibility/keyboard-and-focus.                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-border-focus-offset`                | `2px`                                                                                                                                                                 | Offset for the focus boundary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |\n| `--opsin-accent-action`                      | `oklch(0.145 0.005 250)`                                                                                                                                              | The fill of the one filled action on a surface, Button's primary rung. Read as --primary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-accent-action-foreground`           | `oklch(1 0 0)`                                                                                                                                                        | The label on the action fill. Measured against the fill and both of its states at the body floor. Read as --primary-foreground.                                                                                                                                                                                                                                                                                                                                                                                                                                                                |\n| `--opsin-accent-action-hover`                | `oklch(0.269 0.007 250)`                                                                                                                                              | The action fill under a pointer. It moves away from the label, so the label never loses contrast. Read as --state-primary-hover.                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `--opsin-accent-action-press`                | `oklch(0.371 0.008 250)`                                                                                                                                              | The action fill while pressed or busy. It moves away from the label as well. Read as --state-primary-press.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |\n| `--opsin-accent-action-edge`                 | `transparent`                                                                                                                                                         | The action's boundary. Transparent where the fill alone clears the non-text floor against the page; an ink rim where a bright fill does not. Read as --primary-edge.                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-accent-fill`                        | `oklch(0.53 0.155 250)`                                                                                                                                               | The selected state of a selection control: a switch that is on, a ticked checkbox, a chosen radio, the range of a slider, a progress fill, the current tab. Read as --brand.                                                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-accent-fill-foreground`             | `oklch(1 0 0)`                                                                                                                                                        | A glyph or a label on the accent fill: a checkbox tick, a chosen scale value. Measured at the body floor. Read as --brand-foreground.                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-accent-fill-edge`                   | `transparent`                                                                                                                                                         | The boundary of an accent fill, for the same reason as actionEdge. Read as --brand-edge.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| `--opsin-accent-ink`                         | `oklch(0.5 0.142 250)`                                                                                                                                                | Accent-coloured text on the page and on a card: a quiet button, an alternative action. Measured at the body floor on both. Read as --brand-ink.                                                                                                                                                                                                                                                                                                                                                                                                                                                |\n| `--opsin-accent-ring`                        | `oklch(0.53 0.155 250)`                                                                                                                                               | The focus ring. Measured at the non-text floor on the page and on a card. Read as --ring.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-accent-glow`                        | `transparent`                                                                                                                                                         | Light thrown by the action, as a shadow colour. Decorative, never a boundary, so it is not measured. Only vibes casts one. Read as --brand-glow.                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n\n### `.dark, .opsin-product.dark` [#dark-opsin-productdark]\n\n| Variable                              | Value                                                                                                            | Controls                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--opsin-chrome-background`           | `oklch(0.145 0.005 250)`                                                                                         | Chrome role background, resolved to the ladder step it names.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |\n| `--opsin-chrome-foreground`           | `oklch(0.967 0.003 250)`                                                                                         | Chrome role foreground, resolved to the ladder step it names.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |\n| `--opsin-chrome-card`                 | `oklch(0.205 0.006 250)`                                                                                         | Chrome role card, resolved to the ladder step it names.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-chrome-card-foreground`      | `oklch(0.967 0.003 250)`                                                                                         | Chrome role cardForeground, resolved to the ladder step it names.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |\n| `--opsin-chrome-muted`                | `oklch(0.269 0.007 250)`                                                                                         | Chrome role muted, resolved to the ladder step it names.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| `--opsin-chrome-muted-foreground`     | `oklch(0.871 0.005 250)`                                                                                         | Chrome role mutedForeground, resolved to the ladder step it names.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |\n| `--opsin-chrome-border`               | `oklch(0.556 0.009 250)`                                                                                         | Chrome role border, resolved to the ladder step it names.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-chrome-input`                | `oklch(0.556 0.009 250)`                                                                                         | Chrome role input, resolved to the ladder step it names.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| `--opsin-chrome-edge`                 | `oklch(1 0 0 / 0.1)`                                                                                             | Chrome role edge, resolved to the ladder step it names.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-chrome-ring`                 | `oklch(0.75 0.13 250)`                                                                                           | Chrome role ring, resolved to the ladder step it names.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-chrome-brand`                | `oklch(0.75 0.13 250)`                                                                                           | Chrome role brand, resolved to the ladder step it names.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| `--opsin-chrome-primary`              | `oklch(0.985 0.002 250)`                                                                                         | Chrome role primary, resolved to the ladder step it names.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |\n| `--opsin-chrome-primary-foreground`   | `oklch(0.145 0.005 250)`                                                                                         | Chrome role primaryForeground, resolved to the ladder step it names.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-category-sleep-surface`      | `oklch(0.208 0.062 275)`                                                                                         | The tinted background a component in this ramp sits on.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-category-sleep-line`         | `oklch(0.806 0.092 275)`                                                                                         | The boundary, icon stroke or chart mark. The lightest value in the ramp that clears the non-text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-category-sleep-ink`          | `oklch(0.884 0.057 275)`                                                                                         | Text and text-sized icons on `surface`. Clears the text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `--opsin-category-sleep-accent`       | `oklch(0.714 0.123 275)`                                                                                         | The identity fill: a bar fill, a dial track, a legend dot. Chosen for recognition, not for contrast. It must be bounded by `line` or labelled in `ink`; it is never the only thing that carries the meaning.                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-category-heart-surface`      | `oklch(0.208 0.075 15)`                                                                                          | The tinted background a component in this ramp sits on.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-category-heart-line`         | `oklch(0.806 0.112 15)`                                                                                          | The boundary, icon stroke or chart mark. The lightest value in the ramp that clears the non-text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-category-heart-ink`          | `oklch(0.884 0.062 15)`                                                                                          | Text and text-sized icons on `surface`. Clears the text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `--opsin-category-heart-accent`       | `oklch(0.714 0.15 15)`                                                                                           | The identity fill: a bar fill, a dial track, a legend dot. Chosen for recognition, not for contrast. It must be bounded by `line` or labelled in `ink`; it is never the only thing that carries the meaning.                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-category-activity-surface`   | `oklch(0.208 0.07 140)`                                                                                          | The tinted background a component in this ramp sits on.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-category-activity-line`      | `oklch(0.806 0.106 140)`                                                                                         | The boundary, icon stroke or chart mark. The lightest value in the ramp that clears the non-text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-category-activity-ink`       | `oklch(0.884 0.067 140)`                                                                                         | Text and text-sized icons on `surface`. Clears the text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `--opsin-category-activity-accent`    | `oklch(0.714 0.141 140)`                                                                                         | The identity fill: a bar fill, a dial track, a legend dot. Chosen for recognition, not for contrast. It must be bounded by `line` or labelled in `ink`; it is never the only thing that carries the meaning.                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-category-nutrition-surface`  | `oklch(0.208 0.049 70)`                                                                                          | The tinted background a component in this ramp sits on.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-category-nutrition-line`     | `oklch(0.806 0.092 70)`                                                                                          | The boundary, icon stroke or chart mark. The lightest value in the ramp that clears the non-text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-category-nutrition-ink`      | `oklch(0.884 0.059 70)`                                                                                          | Text and text-sized icons on `surface`. Clears the text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `--opsin-category-nutrition-accent`   | `oklch(0.714 0.123 70)`                                                                                          | The identity fill: a bar fill, a dial track, a legend dot. Chosen for recognition, not for contrast. It must be bounded by `line` or labelled in `ink`; it is never the only thing that carries the meaning.                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-category-mind-surface`       | `oklch(0.208 0.062 310)`                                                                                         | The tinted background a component in this ramp sits on.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-category-mind-line`          | `oklch(0.806 0.092 310)`                                                                                         | The boundary, icon stroke or chart mark. The lightest value in the ramp that clears the non-text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-category-mind-ink`           | `oklch(0.884 0.059 310)`                                                                                         | Text and text-sized icons on `surface`. Clears the text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `--opsin-category-mind-accent`        | `oklch(0.714 0.123 310)`                                                                                         | The identity fill: a bar fill, a dial track, a legend dot. Chosen for recognition, not for contrast. It must be bounded by `line` or labelled in `ink`; it is never the only thing that carries the meaning.                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-category-labs-surface`       | `oklch(0.208 0.038 210)`                                                                                         | The tinted background a component in this ramp sits on.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-category-labs-line`          | `oklch(0.806 0.073 210)`                                                                                         | The boundary, icon stroke or chart mark. The lightest value in the ramp that clears the non-text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-category-labs-ink`           | `oklch(0.884 0.046 210)`                                                                                         | Text and text-sized icons on `surface`. Clears the text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `--opsin-category-labs-accent`        | `oklch(0.714 0.097 210)`                                                                                         | The identity fill: a bar fill, a dial track, a legend dot. Chosen for recognition, not for contrast. It must be bounded by `line` or labelled in `ink`; it is never the only thing that carries the meaning.                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-status-steady-surface`       | `oklch(0.208 0.041 178)`                                                                                         | The tinted background a component in this ramp sits on.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-status-steady-line`          | `oklch(0.806 0.073 178)`                                                                                         | The boundary, icon stroke or chart mark. The lightest value in the ramp that clears the non-text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-status-steady-ink`           | `oklch(0.884 0.046 178)`                                                                                         | Text and text-sized icons on `surface`. Clears the text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `--opsin-status-steady-accent`        | `oklch(0.714 0.097 178)`                                                                                         | The identity fill: a bar fill, a dial track, a legend dot. Chosen for recognition, not for contrast. It must be bounded by `line` or labelled in `ink`; it is never the only thing that carries the meaning.                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-status-watch-surface`        | `oklch(0.208 0.046 82)`                                                                                          | The tinted background a component in this ramp sits on.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-status-watch-line`           | `oklch(0.806 0.092 82)`                                                                                          | The boundary, icon stroke or chart mark. The lightest value in the ramp that clears the non-text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-status-watch-ink`            | `oklch(0.884 0.059 82)`                                                                                          | Text and text-sized icons on `surface`. Clears the text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `--opsin-status-watch-accent`         | `oklch(0.714 0.123 82)`                                                                                          | The identity fill: a bar fill, a dial track, a legend dot. Chosen for recognition, not for contrast. It must be bounded by `line` or labelled in `ink`; it is never the only thing that carries the meaning.                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-status-attention-surface`    | `oklch(0.208 0.065 45)`                                                                                          | The tinted background a component in this ramp sits on.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-status-attention-line`       | `oklch(0.806 0.099 45)`                                                                                          | The boundary, icon stroke or chart mark. The lightest value in the ramp that clears the non-text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-status-attention-ink`        | `oklch(0.884 0.063 45)`                                                                                          | Text and text-sized icons on `surface`. Clears the text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `--opsin-status-attention-accent`     | `oklch(0.714 0.132 45)`                                                                                          | The identity fill: a bar fill, a dial track, a legend dot. Chosen for recognition, not for contrast. It must be bounded by `line` or labelled in `ink`; it is never the only thing that carries the meaning.                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-status-urgent-surface`       | `oklch(0.208 0.088 27)`                                                                                          | The tinted background a component in this ramp sits on.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-status-urgent-line`          | `oklch(0.806 0.11 27)`                                                                                           | The boundary, icon stroke or chart mark. The lightest value in the ramp that clears the non-text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-status-urgent-ink`           | `oklch(0.884 0.061 27)`                                                                                          | Text and text-sized icons on `surface`. Clears the text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `--opsin-status-urgent-accent`        | `oklch(0.714 0.176 27)`                                                                                          | The identity fill: a bar fill, a dial track, a legend dot. Chosen for recognition, not for contrast. It must be bounded by `line` or labelled in `ink`; it is never the only thing that carries the meaning.                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-status-unknown-surface`      | `oklch(0.208 0.009 250)`                                                                                         | The tinted background a component in this ramp sits on.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-status-unknown-line`         | `oklch(0.806 0.013 250)`                                                                                         | The boundary, icon stroke or chart mark. The lightest value in the ramp that clears the non-text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-status-unknown-ink`          | `oklch(0.884 0.008 250)`                                                                                         | Text and text-sized icons on `surface`. Clears the text floor against `surface`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `--opsin-status-unknown-accent`       | `oklch(0.714 0.018 250)`                                                                                         | The identity fill: a bar fill, a dial track, a legend dot. Chosen for recognition, not for contrast. It must be bounded by `line` or labelled in `ink`; it is never the only thing that carries the meaning.                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-material-canvas-tint`        | `var(--opsin-neutral-950)`                                                                                       | Rung 0 (canvas): the tint over what is behind it. The application background. Nothing is behind it, so nothing shows through it.                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `--opsin-material-canvas-opaque`      | `var(--opsin-neutral-950)`                                                                                       | Rung 0 (canvas): the opaque substitute used under prefers-reduced-transparency and where backdrop-filter is unsupported.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| `--opsin-material-inset-tint`         | `oklch(0.178 0.006 250)`                                                                                         | Rung 0.5 (inset): the tint over what is behind it. The recessed well inside a card: the explanatory note a Callout draws inside the reading it annotates, and the track a RangeBar lays its range along. Its fill sits below the card fill in both themes, so the well reads as carved into the card rather than lifted off it. In light it is neutral-100, one step under the white card, which is where a Callout already sat. In dark it is a value between the page and the card, below the card so the well is a recess and above the page so a Callout used on its own is still visible. |\n| `--opsin-material-inset-opaque`       | `oklch(0.178 0.006 250)`                                                                                         | Rung 0.5 (inset): the opaque substitute used under prefers-reduced-transparency and where backdrop-filter is unsupported.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-material-card-tint`          | `var(--opsin-neutral-900)`                                                                                       | Rung 1 (card): the tint over what is behind it. The default home for a health value. Opaque, edged by a decorative line, and lifted off the page by a soft drop and a line of light along its top. The rung every ResultCard, MetricTile and RangeBar sits on.                                                                                                                                                                                                                                                                                                                                 |\n| `--opsin-material-card-border`        | `var(--opsin-chrome-edge)`                                                                                       | Rung 1 (card): the boundary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-material-card-shadow`        | `inset 0 1px 0 0 oklch(1 0 0 / 0.05), 0 1px 2px 0 oklch(0 0 0 / 0.45), 0 14px 36px -16px oklch(0 0 0 / 0.7)`     | Rung 1 (card): the shadow that separates it from what is behind.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `--opsin-material-card-opaque`        | `var(--opsin-neutral-900)`                                                                                       | Rung 1 (card): the opaque substitute used under prefers-reduced-transparency and where backdrop-filter is unsupported.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-material-raised-tint`        | `var(--opsin-neutral-800)`                                                                                       | Rung 2 (raised): the tint over what is behind it. Menus, popovers, tooltips, a dragged card. Still opaque: the shadow, not translucency, is what says 'above'.                                                                                                                                                                                                                                                                                                                                                                                                                                 |\n| `--opsin-material-raised-border`      | `var(--opsin-chrome-edge)`                                                                                       | Rung 2 (raised): the boundary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |\n| `--opsin-material-raised-shadow`      | `inset 0 1px 0 0 oklch(1 0 0 / 0.06), 0 2px 8px -2px oklch(0 0 0 / 0.55), 0 26px 60px -18px oklch(0 0 0 / 0.85)` | Rung 2 (raised): the shadow that separates it from what is behind.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |\n| `--opsin-material-raised-opaque`      | `var(--opsin-neutral-800)`                                                                                       | Rung 2 (raised): the opaque substitute used under prefers-reduced-transparency and where backdrop-filter is unsupported.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| `--opsin-material-sheet-tint`         | `var(--opsin-neutral-900)`                                                                                       | Rung 3 (sheet): the tint over what is behind it. A bottom sheet or side panel the reader can dismiss by dragging. Its tint is now near opaque, so the panel lands close to the card colour and a white control inside it no longer floats above a greyer surface. What keeps the covered page recognisable is the scrim around the panel rather than the page reading through the panel, because at this opacity very little of the page shows through the tint.                                                                                                                               |\n| `--opsin-material-sheet-tint-alpha`   | `0.9`                                                                                                            | Rung 3 (sheet): how opaque that tint is.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| `--opsin-material-sheet-border`       | `var(--opsin-chrome-edge)`                                                                                       | Rung 3 (sheet): the boundary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |\n| `--opsin-material-sheet-shadow`       | `inset 0 1px 0 0 oklch(1 0 0 / 0.07), 0 4px 12px -4px oklch(0 0 0 / 0.6), 0 48px 120px -24px oklch(0 0 0 / 0.9)` | Rung 3 (sheet): the shadow that separates it from what is behind.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |\n| `--opsin-material-sheet-opaque`       | `var(--opsin-neutral-900)`                                                                                       | Rung 3 (sheet): the opaque substitute used under prefers-reduced-transparency and where backdrop-filter is unsupported.                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-material-overlay-tint`       | `var(--opsin-neutral-900)`                                                                                       | Rung 4 (overlay): the tint over what is behind it. A pinned toolbar, a tab bar and a floating action bar are all chrome that content scrolls beneath.                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-material-overlay-tint-alpha` | `0.7`                                                                                                            | Rung 4 (overlay): how opaque that tint is.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |\n| `--opsin-material-overlay-border`     | `var(--opsin-chrome-edge)`                                                                                       | Rung 4 (overlay): the boundary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |\n| `--opsin-material-overlay-shadow`     | `inset 0 1px 0 0 oklch(1 0 0 / 0.06), 0 1px 2px 0 oklch(0 0 0 / 0.5), 0 14px 36px -14px oklch(0 0 0 / 0.8)`      | Rung 4 (overlay): the shadow that separates it from what is behind.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |\n| `--opsin-material-overlay-opaque`     | `var(--opsin-neutral-900)`                                                                                       | Rung 4 (overlay): the opaque substitute used under prefers-reduced-transparency and where backdrop-filter is unsupported.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-material-scrim-tint`         | `var(--opsin-neutral-1000)`                                                                                      | Rung 5 (scrim): the tint over what is behind it. The dimming layer behind a modal dialog or a consent sheet. Its job is to remove the page from consideration, not to look like glass.                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-material-scrim-tint-alpha`   | `0.6`                                                                                                            | Rung 5 (scrim): how opaque that tint is.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| `--opsin-material-scrim-opaque`       | `oklch(0 0 0 / 0.8)`                                                                                             | Rung 5 (scrim): the opaque substitute used under prefers-reduced-transparency and where backdrop-filter is unsupported.                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| `--opsin-accent-action`               | `oklch(0.985 0.002 250)`                                                                                         | The fill of the one filled action on a surface, Button's primary rung. Read as --primary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-accent-action-foreground`    | `oklch(0.145 0.005 250)`                                                                                         | The label on the action fill. Measured against the fill and both of its states at the body floor. Read as --primary-foreground.                                                                                                                                                                                                                                                                                                                                                                                                                                                                |\n| `--opsin-accent-action-hover`         | `oklch(0.929 0.004 250)`                                                                                         | The action fill under a pointer. It moves away from the label, so the label never loses contrast. Read as --state-primary-hover.                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `--opsin-accent-action-press`         | `oklch(0.871 0.005 250)`                                                                                         | The action fill while pressed or busy. It moves away from the label as well. Read as --state-primary-press.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |\n| `--opsin-accent-action-edge`          | `transparent`                                                                                                    | The action's boundary. Transparent where the fill alone clears the non-text floor against the page; an ink rim where a bright fill does not. Read as --primary-edge.                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-accent-fill`                 | `oklch(0.845 0.079 250)`                                                                                         | The selected state of a selection control: a switch that is on, a ticked checkbox, a chosen radio, the range of a slider, a progress fill, the current tab. Read as --brand.                                                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-accent-fill-foreground`      | `oklch(0.145 0.005 250)`                                                                                         | A glyph or a label on the accent fill: a checkbox tick, a chosen scale value. Measured at the body floor. Read as --brand-foreground.                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-accent-fill-edge`            | `transparent`                                                                                                    | The boundary of an accent fill, for the same reason as actionEdge. Read as --brand-edge.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| `--opsin-accent-ink`                  | `oklch(0.855 0.074 250)`                                                                                         | Accent-coloured text on the page and on a card: a quiet button, an alternative action. Measured at the body floor on both. Read as --brand-ink.                                                                                                                                                                                                                                                                                                                                                                                                                                                |\n| `--opsin-accent-ring`                 | `oklch(0.75 0.13 250)`                                                                                           | The focus ring. Measured at the non-text floor on the page and on a card. Read as --ring.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `--opsin-accent-glow`                 | `transparent`                                                                                                    | Light thrown by the action, as a shadow colour. Decorative, never a boundary, so it is not measured. Only vibes casts one. Read as --brand-glow.                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n\n### `@supports (color-gamut: p3)` [#supports-color-gamut-p3]\n\n| Variable                             | Value                    | Controls                                                                             |\n| ------------------------------------ | ------------------------ | ------------------------------------------------------------------------------------ |\n| `--opsin-category-sleep-50`          | `oklch(0.972 0.015 275)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-sleep-100`         | `oklch(0.941 0.031 275)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-sleep-200`         | `oklch(0.884 0.062 275)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-sleep-300`         | `oklch(0.806 0.107 275)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-sleep-400`         | `oklch(0.714 0.145 275)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-sleep-500`         | `oklch(0.622 0.165 275)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-sleep-600`         | `oklch(0.541 0.16 275)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-sleep-700`         | `oklch(0.452 0.145 275)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-sleep-800`         | `oklch(0.362 0.122 275)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-sleep-900`         | `oklch(0.276 0.096 275)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-sleep-950`         | `oklch(0.208 0.073 275)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-sleep-surface`     | `oklch(0.972 0.015 275)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-sleep-line`        | `oklch(0.541 0.16 275)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-sleep-ink`         | `oklch(0.362 0.122 275)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-sleep-accent`      | `oklch(0.714 0.145 275)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-heart-50`          | `oklch(0.972 0.018 15)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-heart-100`         | `oklch(0.941 0.039 15)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-heart-200`         | `oklch(0.884 0.081 15)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-heart-300`         | `oklch(0.806 0.132 15)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-heart-400`         | `oklch(0.714 0.177 15)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-heart-500`         | `oklch(0.622 0.201 15)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-heart-600`         | `oklch(0.541 0.195 15)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-heart-700`         | `oklch(0.452 0.177 15)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-heart-800`         | `oklch(0.362 0.148 15)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-heart-900`         | `oklch(0.276 0.116 15)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-heart-950`         | `oklch(0.208 0.088 15)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-heart-surface`     | `oklch(0.972 0.018 15)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-heart-line`        | `oklch(0.541 0.195 15)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-heart-ink`         | `oklch(0.362 0.148 15)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-heart-accent`      | `oklch(0.714 0.177 15)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-activity-50`       | `oklch(0.972 0.026 140)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-activity-100`      | `oklch(0.941 0.045 140)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-activity-200`      | `oklch(0.884 0.079 140)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-activity-300`      | `oklch(0.806 0.125 140)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-activity-400`      | `oklch(0.714 0.166 140)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-activity-500`      | `oklch(0.622 0.189 140)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-activity-600`      | `oklch(0.541 0.183 140)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-activity-700`      | `oklch(0.452 0.166 140)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-activity-800`      | `oklch(0.362 0.139 140)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-activity-900`      | `oklch(0.276 0.108 140)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-activity-950`      | `oklch(0.208 0.083 140)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-activity-surface`  | `oklch(0.972 0.026 140)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-activity-line`     | `oklch(0.541 0.183 140)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-activity-ink`      | `oklch(0.362 0.139 140)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-activity-accent`   | `oklch(0.714 0.166 140)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-nutrition-50`      | `oklch(0.972 0.023 70)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-nutrition-100`     | `oklch(0.941 0.04 70)`   | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-nutrition-200`     | `oklch(0.884 0.069 70)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-nutrition-300`     | `oklch(0.806 0.109 70)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-nutrition-400`     | `oklch(0.714 0.145 70)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-nutrition-500`     | `oklch(0.622 0.155 70)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-nutrition-600`     | `oklch(0.541 0.135 70)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-nutrition-700`     | `oklch(0.452 0.113 70)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-nutrition-800`     | `oklch(0.362 0.091 70)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-nutrition-900`     | `oklch(0.276 0.071 70)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-nutrition-950`     | `oklch(0.208 0.056 70)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-nutrition-surface` | `oklch(0.972 0.023 70)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-nutrition-line`    | `oklch(0.541 0.135 70)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-nutrition-ink`     | `oklch(0.362 0.091 70)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-nutrition-accent`  | `oklch(0.714 0.145 70)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-mind-50`           | `oklch(0.972 0.02 310)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-mind-100`          | `oklch(0.941 0.04 310)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-mind-200`          | `oklch(0.884 0.069 310)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-mind-300`          | `oklch(0.806 0.109 310)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-mind-400`          | `oklch(0.714 0.145 310)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-mind-500`          | `oklch(0.622 0.165 310)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-mind-600`          | `oklch(0.541 0.16 310)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-mind-700`          | `oklch(0.452 0.145 310)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-mind-800`          | `oklch(0.362 0.122 310)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-mind-900`          | `oklch(0.276 0.096 310)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-mind-950`          | `oklch(0.208 0.073 310)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-mind-surface`      | `oklch(0.972 0.02 310)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-mind-line`         | `oklch(0.541 0.16 310)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-mind-ink`          | `oklch(0.362 0.122 310)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-mind-accent`       | `oklch(0.714 0.145 310)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-labs-50`           | `oklch(0.972 0.018 210)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-labs-100`          | `oklch(0.941 0.031 210)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-labs-200`          | `oklch(0.884 0.055 210)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-labs-300`          | `oklch(0.806 0.086 210)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-labs-400`          | `oklch(0.714 0.114 210)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-labs-500`          | `oklch(0.622 0.13 210)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-labs-600`          | `oklch(0.541 0.125 210)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-labs-700`          | `oklch(0.452 0.105 210)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-labs-800`          | `oklch(0.362 0.084 210)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-labs-900`          | `oklch(0.276 0.065 210)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-labs-950`          | `oklch(0.208 0.051 210)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-labs-surface`      | `oklch(0.972 0.018 210)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-labs-line`         | `oklch(0.541 0.125 210)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-labs-ink`          | `oklch(0.362 0.084 210)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-category-labs-accent`       | `oklch(0.714 0.114 210)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-steady-50`           | `oklch(0.972 0.018 178)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-steady-100`          | `oklch(0.941 0.031 178)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-steady-200`          | `oklch(0.884 0.055 178)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-steady-300`          | `oklch(0.806 0.086 178)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-steady-400`          | `oklch(0.714 0.114 178)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-steady-500`          | `oklch(0.622 0.13 178)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-steady-600`          | `oklch(0.541 0.126 178)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-steady-700`          | `oklch(0.452 0.114 178)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-steady-800`          | `oklch(0.362 0.091 178)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-steady-900`          | `oklch(0.276 0.071 178)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-steady-950`          | `oklch(0.208 0.055 178)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-steady-surface`      | `oklch(0.972 0.018 178)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-steady-line`         | `oklch(0.541 0.126 178)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-steady-ink`          | `oklch(0.362 0.091 178)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-steady-accent`       | `oklch(0.714 0.114 178)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-watch-50`            | `oklch(0.972 0.023 82)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-watch-100`           | `oklch(0.941 0.04 82)`   | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-watch-200`           | `oklch(0.884 0.069 82)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-watch-300`           | `oklch(0.806 0.109 82)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-watch-400`           | `oklch(0.714 0.145 82)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-watch-500`           | `oklch(0.622 0.148 82)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-watch-600`           | `oklch(0.541 0.129 82)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-watch-700`           | `oklch(0.452 0.108 82)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-watch-800`           | `oklch(0.362 0.087 82)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-watch-900`           | `oklch(0.276 0.068 82)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-watch-950`           | `oklch(0.208 0.054 82)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-watch-surface`       | `oklch(0.972 0.023 82)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-watch-line`          | `oklch(0.541 0.129 82)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-watch-ink`           | `oklch(0.362 0.087 82)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-watch-accent`        | `oklch(0.60 0.14 82)`    | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-attention-50`        | `oklch(0.972 0.019 45)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-attention-100`       | `oklch(0.941 0.041 45)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-attention-200`       | `oklch(0.884 0.074 45)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-attention-300`       | `oklch(0.806 0.117 45)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-attention-400`       | `oklch(0.714 0.156 45)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-attention-500`       | `oklch(0.622 0.177 45)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-attention-600`       | `oklch(0.541 0.172 45)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-attention-700`       | `oklch(0.452 0.148 45)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-attention-800`       | `oklch(0.362 0.119 45)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-attention-900`       | `oklch(0.276 0.093 45)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-attention-950`       | `oklch(0.208 0.074 45)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-attention-surface`   | `oklch(0.972 0.019 45)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-attention-line`      | `oklch(0.541 0.172 45)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-attention-ink`       | `oklch(0.362 0.119 45)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-attention-accent`    | `oklch(0.714 0.156 45)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-urgent-50`           | `oklch(0.972 0.018 27)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-urgent-100`          | `oklch(0.941 0.039 27)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-urgent-200`          | `oklch(0.884 0.079 27)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-urgent-300`          | `oklch(0.806 0.142 27)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-urgent-400`          | `oklch(0.714 0.208 27)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-urgent-500`          | `oklch(0.622 0.236 27)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-urgent-600`          | `oklch(0.541 0.229 27)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-urgent-700`          | `oklch(0.452 0.208 27)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-urgent-800`          | `oklch(0.362 0.168 27)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-urgent-900`          | `oklch(0.276 0.129 27)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-urgent-950`          | `oklch(0.208 0.1 27)`    | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-urgent-surface`      | `oklch(0.972 0.018 27)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-urgent-line`         | `oklch(0.541 0.229 27)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-urgent-ink`          | `oklch(0.362 0.168 27)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-urgent-accent`       | `oklch(0.714 0.208 27)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-unknown-100`         | `oklch(0.941 0.006 250)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-unknown-200`         | `oklch(0.884 0.01 250)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-unknown-300`         | `oklch(0.806 0.016 250)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-unknown-400`         | `oklch(0.714 0.021 250)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-unknown-500`         | `oklch(0.622 0.024 250)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-unknown-600`         | `oklch(0.541 0.023 250)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-unknown-700`         | `oklch(0.452 0.021 250)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-unknown-800`         | `oklch(0.362 0.017 250)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-unknown-900`         | `oklch(0.276 0.014 250)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-unknown-950`         | `oklch(0.208 0.01 250)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-unknown-surface`     | `oklch(0.208 0.01 250)`  | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-unknown-line`        | `oklch(0.541 0.023 250)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-unknown-ink`         | `oklch(0.362 0.017 250)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n| `--opsin-status-unknown-accent`      | `oklch(0.714 0.021 250)` | Chroma escalation only: same hue, same lightness, so measured contrast is unchanged. |\n\n{/* opsinjs:generated:end */}"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/reference/generated/data-attributes",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/reference/generated/data-attributes.md",
      "slug": [
        "reference",
        "generated",
        "data-attributes"
      ],
      "section": "Reference",
      "title": "Data attributes",
      "description": "Every data-* attribute the system emits, the condition that produces it, and the values it can take.",
      "kind": "reference",
      "aliases": [
        "data-attributes",
        "styling hooks",
        "every data attribute"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-09-02",
      "markdown": "Written by `scripts/build-reference.mts`. A data attribute is a styling contract covered by the versioning policy in the [Changelog](../../changelog.mdx): removing one, or changing when it appears, is a breaking change. [Styling](../../styling.mdx) describes the contract.\n\n{/* opsinjs:generated:begin - everything below is replaced by scripts/build-reference.mts */}\n\n<NoDataYet script=\"scripts/build-reference.mts\" />\n\nThis script does not read the component sources for `data-*` attributes yet, so there is no table, which is not the same as no attribute being emitted. Every part carries `data-slot`, and `data-status`, `data-category` and `data-opsinjs-value` appear where they apply, with Base UI's `data-open`, `data-starting-style` and `data-ending-style` inherited. That is the whole component contract, closed at those four, as Styling describes. The squircle is not among them: Card, Callout and Dialog set an inline `corner-shape` property instead. `data-opsinjs-not-implemented` is a documentation-site marker, not a component attribute. Each component page lists its own attributes under Props interface.\n\n{/* opsinjs:generated:end */}"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/reference/generated/keyboard",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/reference/generated/keyboard.md",
      "slug": [
        "reference",
        "generated",
        "keyboard"
      ],
      "section": "Reference",
      "title": "Keyboard",
      "description": "Every keyboard interaction in the system, aggregated from the keyboard table on each component page.",
      "kind": "reference",
      "aliases": [
        "key bindings",
        "keyboard table",
        "shortcuts"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-09-02",
      "markdown": "Aggregated by `scripts/build-reference.mts` from the `<KeyboardTable>` on every component page, so a key that is not documented on its component cannot appear here. Run `pnpm run generate`.\n\n*Component* and *part* say where focus must be, *Key* is written as a keyboard prints it, such as <Kbd>Shift</Kbd> <Kbd>Tab</Kbd>, *Action* is the outcome, and *Notes* carries the exceptions. Browser and operating-system defaults are not listed. The focus contract lives in [Accessibility](../../foundations/accessibility.mdx), and this site's own <Kbd>Ctrl</Kbd> <Kbd>K</Kbd> search shortcut is not part of opsinjs.\n\n{/* opsinjs:generated:begin - everything below is replaced by scripts/build-reference.mts */}\n\n<NoDataYet script=\"scripts/build-reference.mts\" />\n\nThis script does not parse the `<KeyboardTable>` blocks yet, so nothing is aggregated here - not because no component documents its keys. Every component page carries its own table, and that is where the contract is readable today. The global contract every component must meet is in Accessibility under Keyboard and focus.\n\n{/* opsinjs:generated:end */}"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/reference/generated/tokens",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/reference/generated/tokens.md",
      "slug": [
        "reference",
        "generated",
        "tokens"
      ],
      "section": "Reference",
      "title": "Tokens",
      "description": "Every design token opsinjs defines, what it controls, and which parts of the system consume it.",
      "kind": "reference",
      "aliases": [
        "all tokens",
        "token index",
        "complete token table"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-09-02",
      "markdown": "Generated by `scripts/build-tokens.mts` from `tokens/color.json`, `material.json`, `motion.json`, `type.json`, `space.json` and `shape.json`, which also writes `lib/generated/tokens.ts` and `app/tokens.generated.css`. Run `pnpm run generate`; to change a row, edit the JSON source.\n\n*Token* is the name you write, *What it controls* is the one decision it owns, and *Used by* lists the components and foundations that read it, which tells you whether a change is local or system-wide. Primitive tokens are listed for completeness only; components read the semantic and component tiers, as [Theming](../../theming.mdx) explains. The docs chrome's own lyra, shadcn and fumadocs variables are not opsinjs tokens and are not listed.\n\n{/* opsinjs:generated:begin - everything below is replaced by scripts/build-reference.mts */}\n\n## Tokens [#tokens]\n\n### color [#color]\n\n#### neutral [#neutral]\n\n| Token                  | Tier      | What it controls         | Light                    | Dark | Used by      |\n| ---------------------- | --------- | ------------------------ | ------------------------ | ---- | ------------ |\n| `--opsin-neutral-0`    | primitive | Neutral ramp, step 0.    | `oklch(1 0 0)`           | same | no component |\n| `--opsin-neutral-50`   | primitive | Neutral ramp, step 50.   | `oklch(0.985 0.002 250)` | same | no component |\n| `--opsin-neutral-100`  | primitive | Neutral ramp, step 100.  | `oklch(0.967 0.003 250)` | same | no component |\n| `--opsin-neutral-200`  | primitive | Neutral ramp, step 200.  | `oklch(0.929 0.004 250)` | same | no component |\n| `--opsin-neutral-300`  | primitive | Neutral ramp, step 300.  | `oklch(0.871 0.005 250)` | same | no component |\n| `--opsin-neutral-400`  | primitive | Neutral ramp, step 400.  | `oklch(0.708 0.008 250)` | same | no component |\n| `--opsin-neutral-500`  | primitive | Neutral ramp, step 500.  | `oklch(0.556 0.009 250)` | same | no component |\n| `--opsin-neutral-600`  | primitive | Neutral ramp, step 600.  | `oklch(0.439 0.009 250)` | same | no component |\n| `--opsin-neutral-700`  | primitive | Neutral ramp, step 700.  | `oklch(0.371 0.008 250)` | same | no component |\n| `--opsin-neutral-800`  | primitive | Neutral ramp, step 800.  | `oklch(0.269 0.007 250)` | same | no component |\n| `--opsin-neutral-900`  | primitive | Neutral ramp, step 900.  | `oklch(0.205 0.006 250)` | same | no component |\n| `--opsin-neutral-950`  | primitive | Neutral ramp, step 950.  | `oklch(0.145 0.005 250)` | same | no component |\n| `--opsin-neutral-1000` | primitive | Neutral ramp, step 1000. | `oklch(0 0 0)`           | same | no component |\n\n#### chrome [#chrome]\n\n| Token                               | Tier     | What it controls                                                     | Light                          | Dark                     | Used by      |\n| ----------------------------------- | -------- | -------------------------------------------------------------------- | ------------------------------ | ------------------------ | ------------ |\n| `--opsin-chrome-background`         | semantic | Chrome role background, resolved to the ladder step it names.        | `oklch(0.985 0.002 250)`       | `oklch(0.145 0.005 250)` | no component |\n| `--opsin-chrome-foreground`         | semantic | Chrome role foreground, resolved to the ladder step it names.        | `oklch(0.205 0.006 250)`       | `oklch(0.967 0.003 250)` | no component |\n| `--opsin-chrome-card`               | semantic | Chrome role card, resolved to the ladder step it names.              | `oklch(1 0 0)`                 | `oklch(0.205 0.006 250)` | no component |\n| `--opsin-chrome-card-foreground`    | semantic | Chrome role cardForeground, resolved to the ladder step it names.    | `oklch(0.205 0.006 250)`       | `oklch(0.967 0.003 250)` | no component |\n| `--opsin-chrome-muted`              | semantic | Chrome role muted, resolved to the ladder step it names.             | `oklch(0.967 0.003 250)`       | `oklch(0.269 0.007 250)` | no component |\n| `--opsin-chrome-muted-foreground`   | semantic | Chrome role mutedForeground, resolved to the ladder step it names.   | `oklch(0.439 0.009 250)`       | `oklch(0.871 0.005 250)` | no component |\n| `--opsin-chrome-border`             | semantic | Chrome role border, resolved to the ladder step it names.            | `oklch(0.556 0.009 250)`       | `oklch(0.556 0.009 250)` | no component |\n| `--opsin-chrome-input`              | semantic | Chrome role input, resolved to the ladder step it names.             | `oklch(0.556 0.009 250)`       | `oklch(0.556 0.009 250)` | no component |\n| `--opsin-chrome-edge`               | semantic | Chrome role edge, resolved to the ladder step it names.              | `oklch(0.205 0.006 250 / 0.1)` | `oklch(1 0 0 / 0.1)`     | no component |\n| `--opsin-chrome-ring`               | semantic | Chrome role ring, resolved to the ladder step it names.              | `oklch(0.53 0.155 250)`        | `oklch(0.75 0.13 250)`   | no component |\n| `--opsin-chrome-brand`              | semantic | Chrome role brand, resolved to the ladder step it names.             | `oklch(0.53 0.155 250)`        | `oklch(0.75 0.13 250)`   | no component |\n| `--opsin-chrome-primary`            | semantic | Chrome role primary, resolved to the ladder step it names.           | `oklch(0.145 0.005 250)`       | `oklch(0.985 0.002 250)` | no component |\n| `--opsin-chrome-primary-foreground` | semantic | Chrome role primaryForeground, resolved to the ladder step it names. | `oklch(1 0 0)`                 | `oklch(0.145 0.005 250)` | no component |\n\n#### category [#category]\n\n| Token                                | Tier      | What it controls                                                                                                                                                                                             | Light                    | Dark                     | Used by                                         |\n| ------------------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------ | ------------------------ | ----------------------------------------------- |\n| `--opsin-category-sleep-50`          | primitive | Sleep ramp, step 50.                                                                                                                                                                                         | `oklch(0.972 0.013 275)` | same                     | no component                                    |\n| `--opsin-category-sleep-100`         | primitive | Sleep ramp, step 100.                                                                                                                                                                                        | `oklch(0.941 0.028 275)` | same                     | no component                                    |\n| `--opsin-category-sleep-200`         | primitive | Sleep ramp, step 200.                                                                                                                                                                                        | `oklch(0.884 0.057 275)` | same                     | no component                                    |\n| `--opsin-category-sleep-300`         | primitive | Sleep ramp, step 300.                                                                                                                                                                                        | `oklch(0.806 0.092 275)` | same                     | no component                                    |\n| `--opsin-category-sleep-400`         | primitive | Sleep ramp, step 400.                                                                                                                                                                                        | `oklch(0.714 0.123 275)` | same                     | no component                                    |\n| `--opsin-category-sleep-500`         | primitive | Sleep ramp, step 500.                                                                                                                                                                                        | `oklch(0.622 0.14 275)`  | same                     | no component                                    |\n| `--opsin-category-sleep-600`         | primitive | Sleep ramp, step 600.                                                                                                                                                                                        | `oklch(0.541 0.136 275)` | same                     | no component                                    |\n| `--opsin-category-sleep-700`         | primitive | Sleep ramp, step 700.                                                                                                                                                                                        | `oklch(0.452 0.123 275)` | same                     | no component                                    |\n| `--opsin-category-sleep-800`         | primitive | Sleep ramp, step 800.                                                                                                                                                                                        | `oklch(0.362 0.104 275)` | same                     | no component                                    |\n| `--opsin-category-sleep-900`         | primitive | Sleep ramp, step 900.                                                                                                                                                                                        | `oklch(0.276 0.081 275)` | same                     | no component                                    |\n| `--opsin-category-sleep-950`         | primitive | Sleep ramp, step 950.                                                                                                                                                                                        | `oklch(0.208 0.062 275)` | same                     | no component                                    |\n| `--opsin-category-sleep-surface`     | semantic  | The tinted background a component in this ramp sits on.                                                                                                                                                      | `oklch(0.972 0.013 275)` | `oklch(0.208 0.062 275)` | no component                                    |\n| `--opsin-category-sleep-line`        | semantic  | The boundary, icon stroke or chart mark. The lightest value in the ramp that clears the non-text floor against `surface`.                                                                                    | `oklch(0.541 0.136 275)` | `oklch(0.806 0.092 275)` | trend-sparkline                                 |\n| `--opsin-category-sleep-ink`         | semantic  | Text and text-sized icons on `surface`. Clears the text floor against `surface`.                                                                                                                             | `oklch(0.362 0.104 275)` | `oklch(0.884 0.057 275)` | metric-tile, range-bar, result-card, score-dial |\n| `--opsin-category-sleep-accent`      | semantic  | The identity fill: a bar fill, a dial track, a legend dot. Chosen for recognition, not for contrast. It must be bounded by `line` or labelled in `ink`; it is never the only thing that carries the meaning. | `oklch(0.58 0.14 275)`   | `oklch(0.714 0.123 275)` | goal-ring, log-sheet                            |\n| `--opsin-category-heart-50`          | primitive | Heart ramp, step 50.                                                                                                                                                                                         | `oklch(0.972 0.014 15)`  | same                     | no component                                    |\n| `--opsin-category-heart-100`         | primitive | Heart ramp, step 100.                                                                                                                                                                                        | `oklch(0.941 0.03 15)`   | same                     | no component                                    |\n| `--opsin-category-heart-200`         | primitive | Heart ramp, step 200.                                                                                                                                                                                        | `oklch(0.884 0.062 15)`  | same                     | no component                                    |\n| `--opsin-category-heart-300`         | primitive | Heart ramp, step 300.                                                                                                                                                                                        | `oklch(0.806 0.112 15)`  | same                     | no component                                    |\n| `--opsin-category-heart-400`         | primitive | Heart ramp, step 400.                                                                                                                                                                                        | `oklch(0.714 0.15 15)`   | same                     | no component                                    |\n| `--opsin-category-heart-500`         | primitive | Heart ramp, step 500.                                                                                                                                                                                        | `oklch(0.622 0.17 15)`   | same                     | no component                                    |\n| `--opsin-category-heart-600`         | primitive | Heart ramp, step 600.                                                                                                                                                                                        | `oklch(0.541 0.165 15)`  | same                     | no component                                    |\n| `--opsin-category-heart-700`         | primitive | Heart ramp, step 700.                                                                                                                                                                                        | `oklch(0.452 0.15 15)`   | same                     | no component                                    |\n| `--opsin-category-heart-800`         | primitive | Heart ramp, step 800.                                                                                                                                                                                        | `oklch(0.362 0.126 15)`  | same                     | no component                                    |\n| `--opsin-category-heart-900`         | primitive | Heart ramp, step 900.                                                                                                                                                                                        | `oklch(0.276 0.099 15)`  | same                     | no component                                    |\n| `--opsin-category-heart-950`         | primitive | Heart ramp, step 950.                                                                                                                                                                                        | `oklch(0.208 0.075 15)`  | same                     | no component                                    |\n| `--opsin-category-heart-surface`     | semantic  | The tinted background a component in this ramp sits on.                                                                                                                                                      | `oklch(0.972 0.014 15)`  | `oklch(0.208 0.075 15)`  | no component                                    |\n| `--opsin-category-heart-line`        | semantic  | The boundary, icon stroke or chart mark. The lightest value in the ramp that clears the non-text floor against `surface`.                                                                                    | `oklch(0.541 0.165 15)`  | `oklch(0.806 0.112 15)`  | trend-sparkline                                 |\n| `--opsin-category-heart-ink`         | semantic  | Text and text-sized icons on `surface`. Clears the text floor against `surface`.                                                                                                                             | `oklch(0.362 0.126 15)`  | `oklch(0.884 0.062 15)`  | metric-tile, range-bar, result-card, score-dial |\n| `--opsin-category-heart-accent`      | semantic  | The identity fill: a bar fill, a dial track, a legend dot. Chosen for recognition, not for contrast. It must be bounded by `line` or labelled in `ink`; it is never the only thing that carries the meaning. | `oklch(0.62 0.17 15)`    | `oklch(0.714 0.15 15)`   | goal-ring, log-sheet                            |\n| `--opsin-category-activity-50`       | primitive | Activity ramp, step 50.                                                                                                                                                                                      | `oklch(0.972 0.022 140)` | same                     | no component                                    |\n| `--opsin-category-activity-100`      | primitive | Activity ramp, step 100.                                                                                                                                                                                     | `oklch(0.941 0.038 140)` | same                     | no component                                    |\n| `--opsin-category-activity-200`      | primitive | Activity ramp, step 200.                                                                                                                                                                                     | `oklch(0.884 0.067 140)` | same                     | no component                                    |\n| `--opsin-category-activity-300`      | primitive | Activity ramp, step 300.                                                                                                                                                                                     | `oklch(0.806 0.106 140)` | same                     | no component                                    |\n| `--opsin-category-activity-400`      | primitive | Activity ramp, step 400.                                                                                                                                                                                     | `oklch(0.714 0.141 140)` | same                     | no component                                    |\n| `--opsin-category-activity-500`      | primitive | Activity ramp, step 500.                                                                                                                                                                                     | `oklch(0.622 0.16 140)`  | same                     | no component                                    |\n| `--opsin-category-activity-600`      | primitive | Activity ramp, step 600.                                                                                                                                                                                     | `oklch(0.541 0.155 140)` | same                     | no component                                    |\n| `--opsin-category-activity-700`      | primitive | Activity ramp, step 700.                                                                                                                                                                                     | `oklch(0.452 0.141 140)` | same                     | no component                                    |\n| `--opsin-category-activity-800`      | primitive | Activity ramp, step 800.                                                                                                                                                                                     | `oklch(0.362 0.118 140)` | same                     | no component                                    |\n| `--opsin-category-activity-900`      | primitive | Activity ramp, step 900.                                                                                                                                                                                     | `oklch(0.276 0.092 140)` | same                     | no component                                    |\n| `--opsin-category-activity-950`      | primitive | Activity ramp, step 950.                                                                                                                                                                                     | `oklch(0.208 0.07 140)`  | same                     | no component                                    |\n| `--opsin-category-activity-surface`  | semantic  | The tinted background a component in this ramp sits on.                                                                                                                                                      | `oklch(0.972 0.022 140)` | `oklch(0.208 0.07 140)`  | no component                                    |\n| `--opsin-category-activity-line`     | semantic  | The boundary, icon stroke or chart mark. The lightest value in the ramp that clears the non-text floor against `surface`.                                                                                    | `oklch(0.541 0.155 140)` | `oklch(0.806 0.106 140)` | trend-sparkline                                 |\n| `--opsin-category-activity-ink`      | semantic  | Text and text-sized icons on `surface`. Clears the text floor against `surface`.                                                                                                                             | `oklch(0.362 0.118 140)` | `oklch(0.884 0.067 140)` | metric-tile, range-bar, result-card, score-dial |\n| `--opsin-category-activity-accent`   | semantic  | The identity fill: a bar fill, a dial track, a legend dot. Chosen for recognition, not for contrast. It must be bounded by `line` or labelled in `ink`; it is never the only thing that carries the meaning. | `oklch(0.7 0.16 140)`    | `oklch(0.714 0.141 140)` | goal-ring, log-sheet                            |\n| `--opsin-category-nutrition-50`      | primitive | Nutrition ramp, step 50.                                                                                                                                                                                     | `oklch(0.972 0.02 70)`   | same                     | no component                                    |\n| `--opsin-category-nutrition-100`     | primitive | Nutrition ramp, step 100.                                                                                                                                                                                    | `oklch(0.941 0.034 70)`  | same                     | no component                                    |\n| `--opsin-category-nutrition-200`     | primitive | Nutrition ramp, step 200.                                                                                                                                                                                    | `oklch(0.884 0.059 70)`  | same                     | no component                                    |\n| `--opsin-category-nutrition-300`     | primitive | Nutrition ramp, step 300.                                                                                                                                                                                    | `oklch(0.806 0.092 70)`  | same                     | no component                                    |\n| `--opsin-category-nutrition-400`     | primitive | Nutrition ramp, step 400.                                                                                                                                                                                    | `oklch(0.714 0.123 70)`  | same                     | no component                                    |\n| `--opsin-category-nutrition-500`     | primitive | Nutrition ramp, step 500.                                                                                                                                                                                    | `oklch(0.622 0.135 70)`  | same                     | no component                                    |\n| `--opsin-category-nutrition-600`     | primitive | Nutrition ramp, step 600.                                                                                                                                                                                    | `oklch(0.541 0.118 70)`  | same                     | no component                                    |\n| `--opsin-category-nutrition-700`     | primitive | Nutrition ramp, step 700.                                                                                                                                                                                    | `oklch(0.452 0.099 70)`  | same                     | no component                                    |\n| `--opsin-category-nutrition-800`     | primitive | Nutrition ramp, step 800.                                                                                                                                                                                    | `oklch(0.362 0.08 70)`   | same                     | no component                                    |\n| `--opsin-category-nutrition-900`     | primitive | Nutrition ramp, step 900.                                                                                                                                                                                    | `oklch(0.276 0.062 70)`  | same                     | no component                                    |\n| `--opsin-category-nutrition-950`     | primitive | Nutrition ramp, step 950.                                                                                                                                                                                    | `oklch(0.208 0.049 70)`  | same                     | no component                                    |\n| `--opsin-category-nutrition-surface` | semantic  | The tinted background a component in this ramp sits on.                                                                                                                                                      | `oklch(0.972 0.02 70)`   | `oklch(0.208 0.049 70)`  | no component                                    |\n| `--opsin-category-nutrition-line`    | semantic  | The boundary, icon stroke or chart mark. The lightest value in the ramp that clears the non-text floor against `surface`.                                                                                    | `oklch(0.541 0.118 70)`  | `oklch(0.806 0.092 70)`  | trend-sparkline                                 |\n| `--opsin-category-nutrition-ink`     | semantic  | Text and text-sized icons on `surface`. Clears the text floor against `surface`.                                                                                                                             | `oklch(0.362 0.08 70)`   | `oklch(0.884 0.059 70)`  | metric-tile, range-bar, result-card, score-dial |\n| `--opsin-category-nutrition-accent`  | semantic  | The identity fill: a bar fill, a dial track, a legend dot. Chosen for recognition, not for contrast. It must be bounded by `line` or labelled in `ink`; it is never the only thing that carries the meaning. | `oklch(0.75 0.14 70)`    | `oklch(0.714 0.123 70)`  | goal-ring, log-sheet                            |\n| `--opsin-category-mind-50`           | primitive | Mind ramp, step 50.                                                                                                                                                                                          | `oklch(0.972 0.018 310)` | same                     | no component                                    |\n| `--opsin-category-mind-100`          | primitive | Mind ramp, step 100.                                                                                                                                                                                         | `oklch(0.941 0.034 310)` | same                     | no component                                    |\n| `--opsin-category-mind-200`          | primitive | Mind ramp, step 200.                                                                                                                                                                                         | `oklch(0.884 0.059 310)` | same                     | no component                                    |\n| `--opsin-category-mind-300`          | primitive | Mind ramp, step 300.                                                                                                                                                                                         | `oklch(0.806 0.092 310)` | same                     | no component                                    |\n| `--opsin-category-mind-400`          | primitive | Mind ramp, step 400.                                                                                                                                                                                         | `oklch(0.714 0.123 310)` | same                     | no component                                    |\n| `--opsin-category-mind-500`          | primitive | Mind ramp, step 500.                                                                                                                                                                                         | `oklch(0.622 0.14 310)`  | same                     | no component                                    |\n| `--opsin-category-mind-600`          | primitive | Mind ramp, step 600.                                                                                                                                                                                         | `oklch(0.541 0.136 310)` | same                     | no component                                    |\n| `--opsin-category-mind-700`          | primitive | Mind ramp, step 700.                                                                                                                                                                                         | `oklch(0.452 0.123 310)` | same                     | no component                                    |\n| `--opsin-category-mind-800`          | primitive | Mind ramp, step 800.                                                                                                                                                                                         | `oklch(0.362 0.104 310)` | same                     | no component                                    |\n| `--opsin-category-mind-900`          | primitive | Mind ramp, step 900.                                                                                                                                                                                         | `oklch(0.276 0.081 310)` | same                     | no component                                    |\n| `--opsin-category-mind-950`          | primitive | Mind ramp, step 950.                                                                                                                                                                                         | `oklch(0.208 0.062 310)` | same                     | no component                                    |\n| `--opsin-category-mind-surface`      | semantic  | The tinted background a component in this ramp sits on.                                                                                                                                                      | `oklch(0.972 0.018 310)` | `oklch(0.208 0.062 310)` | no component                                    |\n| `--opsin-category-mind-line`         | semantic  | The boundary, icon stroke or chart mark. The lightest value in the ramp that clears the non-text floor against `surface`.                                                                                    | `oklch(0.541 0.136 310)` | `oklch(0.806 0.092 310)` | trend-sparkline                                 |\n| `--opsin-category-mind-ink`          | semantic  | Text and text-sized icons on `surface`. Clears the text floor against `surface`.                                                                                                                             | `oklch(0.362 0.104 310)` | `oklch(0.884 0.059 310)` | metric-tile, range-bar, result-card, score-dial |\n| `--opsin-category-mind-accent`       | semantic  | The identity fill: a bar fill, a dial track, a legend dot. Chosen for recognition, not for contrast. It must be bounded by `line` or labelled in `ink`; it is never the only thing that carries the meaning. | `oklch(0.62 0.14 310)`   | `oklch(0.714 0.123 310)` | goal-ring, log-sheet                            |\n| `--opsin-category-labs-50`           | primitive | Labs ramp, step 50.                                                                                                                                                                                          | `oklch(0.972 0.015 210)` | same                     | no component                                    |\n| `--opsin-category-labs-100`          | primitive | Labs ramp, step 100.                                                                                                                                                                                         | `oklch(0.941 0.026 210)` | same                     | no component                                    |\n| `--opsin-category-labs-200`          | primitive | Labs ramp, step 200.                                                                                                                                                                                         | `oklch(0.884 0.046 210)` | same                     | no component                                    |\n| `--opsin-category-labs-300`          | primitive | Labs ramp, step 300.                                                                                                                                                                                         | `oklch(0.806 0.073 210)` | same                     | no component                                    |\n| `--opsin-category-labs-400`          | primitive | Labs ramp, step 400.                                                                                                                                                                                         | `oklch(0.714 0.097 210)` | same                     | no component                                    |\n| `--opsin-category-labs-500`          | primitive | Labs ramp, step 500.                                                                                                                                                                                         | `oklch(0.622 0.108 210)` | same                     | no component                                    |\n| `--opsin-category-labs-600`          | primitive | Labs ramp, step 600.                                                                                                                                                                                         | `oklch(0.541 0.094 210)` | same                     | no component                                    |\n| `--opsin-category-labs-700`          | primitive | Labs ramp, step 700.                                                                                                                                                                                         | `oklch(0.452 0.079 210)` | same                     | no component                                    |\n| `--opsin-category-labs-800`          | primitive | Labs ramp, step 800.                                                                                                                                                                                         | `oklch(0.362 0.063 210)` | same                     | no component                                    |\n| `--opsin-category-labs-900`          | primitive | Labs ramp, step 900.                                                                                                                                                                                         | `oklch(0.276 0.049 210)` | same                     | no component                                    |\n| `--opsin-category-labs-950`          | primitive | Labs ramp, step 950.                                                                                                                                                                                         | `oklch(0.208 0.038 210)` | same                     | no component                                    |\n| `--opsin-category-labs-surface`      | semantic  | The tinted background a component in this ramp sits on.                                                                                                                                                      | `oklch(0.972 0.015 210)` | `oklch(0.208 0.038 210)` | no component                                    |\n| `--opsin-category-labs-line`         | semantic  | The boundary, icon stroke or chart mark. The lightest value in the ramp that clears the non-text floor against `surface`.                                                                                    | `oklch(0.541 0.094 210)` | `oklch(0.806 0.073 210)` | trend-sparkline                                 |\n| `--opsin-category-labs-ink`          | semantic  | Text and text-sized icons on `surface`. Clears the text floor against `surface`.                                                                                                                             | `oklch(0.362 0.063 210)` | `oklch(0.884 0.046 210)` | metric-tile, range-bar, result-card, score-dial |\n| `--opsin-category-labs-accent`       | semantic  | The identity fill: a bar fill, a dial track, a legend dot. Chosen for recognition, not for contrast. It must be bounded by `line` or labelled in `ink`; it is never the only thing that carries the meaning. | `oklch(0.6 0.11 210)`    | `oklch(0.714 0.097 210)` | goal-ring, log-sheet                            |\n\n#### status [#status]\n\n| Token                                 | Tier      | What it controls                                                                                                                                                                                             | Light                    | Dark                     | Used by                                            |\n| ------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------ | ------------------------ | -------------------------------------------------- |\n| `--opsin-status-steady-50`            | primitive | Steady ramp, step 50.                                                                                                                                                                                        | `oklch(0.972 0.015 178)` | same                     | no component                                       |\n| `--opsin-status-steady-100`           | primitive | Steady ramp, step 100.                                                                                                                                                                                       | `oklch(0.941 0.026 178)` | same                     | no component                                       |\n| `--opsin-status-steady-200`           | primitive | Steady ramp, step 200.                                                                                                                                                                                       | `oklch(0.884 0.046 178)` | same                     | no component                                       |\n| `--opsin-status-steady-300`           | primitive | Steady ramp, step 300.                                                                                                                                                                                       | `oklch(0.806 0.073 178)` | same                     | no component                                       |\n| `--opsin-status-steady-400`           | primitive | Steady ramp, step 400.                                                                                                                                                                                       | `oklch(0.714 0.097 178)` | same                     | no component                                       |\n| `--opsin-status-steady-500`           | primitive | Steady ramp, step 500.                                                                                                                                                                                       | `oklch(0.622 0.11 178)`  | same                     | no component                                       |\n| `--opsin-status-steady-600`           | primitive | Steady ramp, step 600.                                                                                                                                                                                       | `oklch(0.541 0.1 178)`   | same                     | no component                                       |\n| `--opsin-status-steady-700`           | primitive | Steady ramp, step 700.                                                                                                                                                                                       | `oklch(0.452 0.084 178)` | same                     | no component                                       |\n| `--opsin-status-steady-800`           | primitive | Steady ramp, step 800.                                                                                                                                                                                       | `oklch(0.362 0.067 178)` | same                     | no component                                       |\n| `--opsin-status-steady-900`           | primitive | Steady ramp, step 900.                                                                                                                                                                                       | `oklch(0.276 0.052 178)` | same                     | no component                                       |\n| `--opsin-status-steady-950`           | primitive | Steady ramp, step 950.                                                                                                                                                                                       | `oklch(0.208 0.041 178)` | same                     | no component                                       |\n| `--opsin-status-steady-surface`       | semantic  | The tinted background a component in this ramp sits on.                                                                                                                                                      | `oklch(0.972 0.015 178)` | `oklch(0.208 0.041 178)` | alert-banner, status-pill                          |\n| `--opsin-status-steady-line`          | semantic  | The boundary, icon stroke or chart mark. The lightest value in the ramp that clears the non-text floor against `surface`.                                                                                    | `oklch(0.541 0.1 178)`   | `oklch(0.806 0.073 178)` | alert-banner, range-bar, range-legend, status-pill |\n| `--opsin-status-steady-ink`           | semantic  | Text and text-sized icons on `surface`. Clears the text floor against `surface`.                                                                                                                             | `oklch(0.362 0.067 178)` | `oklch(0.884 0.046 178)` | alert-banner, score-dial, status-pill              |\n| `--opsin-status-steady-accent`        | semantic  | The identity fill: a bar fill, a dial track, a legend dot. Chosen for recognition, not for contrast. It must be bounded by `line` or labelled in `ink`; it is never the only thing that carries the meaning. | `oklch(0.62 0.11 178)`   | `oklch(0.714 0.097 178)` | score-dial                                         |\n| `--opsin-status-steady-plate`         | semantic  | Steady plate: the enamel face StatusPill is filled with.                                                                                                                                                     | `oklch(0.5 0.1 167)`     | same                     | status-pill                                        |\n| `--opsin-status-steady-plate-lit`     | semantic  | Steady plate: the band along the top edge of the face, where it turns to the light.                                                                                                                          | `oklch(0.54 0.105 165)`  | same                     | status-pill                                        |\n| `--opsin-status-steady-plate-rim`     | semantic  | Steady plate: the outline of the plate, and the tint of the shadow it casts.                                                                                                                                 | `oklch(0.41 0.08 168)`   | same                     | status-pill                                        |\n| `--opsin-status-steady-plate-word`    | semantic  | Steady plate: the word and the glyph on the plate. Clears the body-text floor on the face and on the lit band.                                                                                               | `oklch(1 0 0)`           | same                     | status-pill                                        |\n| `--opsin-status-watch-50`             | primitive | Watch ramp, step 50.                                                                                                                                                                                         | `oklch(0.972 0.02 82)`   | same                     | no component                                       |\n| `--opsin-status-watch-100`            | primitive | Watch ramp, step 100.                                                                                                                                                                                        | `oklch(0.941 0.034 82)`  | same                     | no component                                       |\n| `--opsin-status-watch-200`            | primitive | Watch ramp, step 200.                                                                                                                                                                                        | `oklch(0.884 0.059 82)`  | same                     | no component                                       |\n| `--opsin-status-watch-300`            | primitive | Watch ramp, step 300.                                                                                                                                                                                        | `oklch(0.806 0.092 82)`  | same                     | no component                                       |\n| `--opsin-status-watch-400`            | primitive | Watch ramp, step 400.                                                                                                                                                                                        | `oklch(0.714 0.123 82)`  | same                     | no component                                       |\n| `--opsin-status-watch-500`            | primitive | Watch ramp, step 500.                                                                                                                                                                                        | `oklch(0.622 0.129 82)`  | same                     | no component                                       |\n| `--opsin-status-watch-600`            | primitive | Watch ramp, step 600.                                                                                                                                                                                        | `oklch(0.541 0.112 82)`  | same                     | no component                                       |\n| `--opsin-status-watch-700`            | primitive | Watch ramp, step 700.                                                                                                                                                                                        | `oklch(0.452 0.094 82)`  | same                     | no component                                       |\n| `--opsin-status-watch-800`            | primitive | Watch ramp, step 800.                                                                                                                                                                                        | `oklch(0.362 0.076 82)`  | same                     | no component                                       |\n| `--opsin-status-watch-900`            | primitive | Watch ramp, step 900.                                                                                                                                                                                        | `oklch(0.276 0.059 82)`  | same                     | no component                                       |\n| `--opsin-status-watch-950`            | primitive | Watch ramp, step 950.                                                                                                                                                                                        | `oklch(0.208 0.046 82)`  | same                     | no component                                       |\n| `--opsin-status-watch-surface`        | semantic  | The tinted background a component in this ramp sits on.                                                                                                                                                      | `oklch(0.972 0.02 82)`   | `oklch(0.208 0.046 82)`  | alert-banner, status-pill                          |\n| `--opsin-status-watch-line`           | semantic  | The boundary, icon stroke or chart mark. The lightest value in the ramp that clears the non-text floor against `surface`.                                                                                    | `oklch(0.541 0.112 82)`  | `oklch(0.806 0.092 82)`  | alert-banner, range-bar, range-legend, status-pill |\n| `--opsin-status-watch-ink`            | semantic  | Text and text-sized icons on `surface`. Clears the text floor against `surface`.                                                                                                                             | `oklch(0.362 0.076 82)`  | `oklch(0.884 0.059 82)`  | alert-banner, score-dial, status-pill              |\n| `--opsin-status-watch-accent`         | semantic  | The identity fill: a bar fill, a dial track, a legend dot. Chosen for recognition, not for contrast. It must be bounded by `line` or labelled in `ink`; it is never the only thing that carries the meaning. | `oklch(0.60 0.123 82)`   | `oklch(0.714 0.123 82)`  | score-dial                                         |\n| `--opsin-status-watch-plate`          | semantic  | Watch plate: the enamel face StatusPill is filled with.                                                                                                                                                      | `oklch(0.855 0.148 83)`  | same                     | status-pill                                        |\n| `--opsin-status-watch-plate-lit`      | semantic  | Watch plate: the band along the top edge of the face, where it turns to the light.                                                                                                                           | `oklch(0.885 0.132 87)`  | same                     | status-pill                                        |\n| `--opsin-status-watch-plate-rim`      | semantic  | Watch plate: the outline of the plate, and the tint of the shadow it casts.                                                                                                                                  | `oklch(0.7 0.12 78)`     | same                     | status-pill                                        |\n| `--opsin-status-watch-plate-word`     | semantic  | Watch plate: the word and the glyph on the plate. Clears the body-text floor on the face and on the lit band.                                                                                                | `oklch(0.21 0.045 68)`   | same                     | status-pill                                        |\n| `--opsin-status-attention-50`         | primitive | Needs attention ramp, step 50.                                                                                                                                                                               | `oklch(0.972 0.015 45)`  | same                     | no component                                       |\n| `--opsin-status-attention-100`        | primitive | Needs attention ramp, step 100.                                                                                                                                                                              | `oklch(0.941 0.032 45)`  | same                     | no component                                       |\n| `--opsin-status-attention-200`        | primitive | Needs attention ramp, step 200.                                                                                                                                                                              | `oklch(0.884 0.063 45)`  | same                     | no component                                       |\n| `--opsin-status-attention-300`        | primitive | Needs attention ramp, step 300.                                                                                                                                                                              | `oklch(0.806 0.099 45)`  | same                     | no component                                       |\n| `--opsin-status-attention-400`        | primitive | Needs attention ramp, step 400.                                                                                                                                                                              | `oklch(0.714 0.132 45)`  | same                     | no component                                       |\n| `--opsin-status-attention-500`        | primitive | Needs attention ramp, step 500.                                                                                                                                                                              | `oklch(0.622 0.15 45)`   | same                     | no component                                       |\n| `--opsin-status-attention-600`        | primitive | Needs attention ramp, step 600.                                                                                                                                                                              | `oklch(0.541 0.145 45)`  | same                     | no component                                       |\n| `--opsin-status-attention-700`        | primitive | Needs attention ramp, step 700.                                                                                                                                                                              | `oklch(0.452 0.13 45)`   | same                     | no component                                       |\n| `--opsin-status-attention-800`        | primitive | Needs attention ramp, step 800.                                                                                                                                                                              | `oklch(0.362 0.105 45)`  | same                     | no component                                       |\n| `--opsin-status-attention-900`        | primitive | Needs attention ramp, step 900.                                                                                                                                                                              | `oklch(0.276 0.082 45)`  | same                     | no component                                       |\n| `--opsin-status-attention-950`        | primitive | Needs attention ramp, step 950.                                                                                                                                                                              | `oklch(0.208 0.065 45)`  | same                     | no component                                       |\n| `--opsin-status-attention-surface`    | semantic  | The tinted background a component in this ramp sits on.                                                                                                                                                      | `oklch(0.972 0.015 45)`  | `oklch(0.208 0.065 45)`  | alert-banner, status-pill                          |\n| `--opsin-status-attention-line`       | semantic  | The boundary, icon stroke or chart mark. The lightest value in the ramp that clears the non-text floor against `surface`.                                                                                    | `oklch(0.541 0.145 45)`  | `oklch(0.806 0.099 45)`  | alert-banner, range-bar, range-legend, status-pill |\n| `--opsin-status-attention-ink`        | semantic  | Text and text-sized icons on `surface`. Clears the text floor against `surface`.                                                                                                                             | `oklch(0.362 0.105 45)`  | `oklch(0.884 0.063 45)`  | alert-banner, score-dial, status-pill              |\n| `--opsin-status-attention-accent`     | semantic  | The identity fill: a bar fill, a dial track, a legend dot. Chosen for recognition, not for contrast. It must be bounded by `line` or labelled in `ink`; it is never the only thing that carries the meaning. | `oklch(0.58 0.15 45)`    | `oklch(0.714 0.132 45)`  | score-dial                                         |\n| `--opsin-status-attention-plate`      | semantic  | Needs attention plate: the enamel face StatusPill is filled with.                                                                                                                                            | `oklch(0.54 0.165 43)`   | same                     | status-pill                                        |\n| `--opsin-status-attention-plate-lit`  | semantic  | Needs attention plate: the band along the top edge of the face, where it turns to the light.                                                                                                                 | `oklch(0.575 0.16 46)`   | same                     | status-pill                                        |\n| `--opsin-status-attention-plate-rim`  | semantic  | Needs attention plate: the outline of the plate, and the tint of the shadow it casts.                                                                                                                        | `oklch(0.44 0.13 40)`    | same                     | status-pill                                        |\n| `--opsin-status-attention-plate-word` | semantic  | Needs attention plate: the word and the glyph on the plate. Clears the body-text floor on the face and on the lit band.                                                                                      | `oklch(1 0 0)`           | same                     | status-pill                                        |\n| `--opsin-status-urgent-50`            | primitive | Urgent ramp, step 50.                                                                                                                                                                                        | `oklch(0.972 0.014 27)`  | same                     | no component                                       |\n| `--opsin-status-urgent-100`           | primitive | Urgent ramp, step 100.                                                                                                                                                                                       | `oklch(0.941 0.03 27)`   | same                     | no component                                       |\n| `--opsin-status-urgent-200`           | primitive | Urgent ramp, step 200.                                                                                                                                                                                       | `oklch(0.884 0.061 27)`  | same                     | no component                                       |\n| `--opsin-status-urgent-300`           | primitive | Urgent ramp, step 300.                                                                                                                                                                                       | `oklch(0.806 0.11 27)`   | same                     | no component                                       |\n| `--opsin-status-urgent-400`           | primitive | Urgent ramp, step 400.                                                                                                                                                                                       | `oklch(0.714 0.176 27)`  | same                     | no component                                       |\n| `--opsin-status-urgent-500`           | primitive | Urgent ramp, step 500.                                                                                                                                                                                       | `oklch(0.622 0.2 27)`    | same                     | no component                                       |\n| `--opsin-status-urgent-600`           | primitive | Urgent ramp, step 600.                                                                                                                                                                                       | `oklch(0.541 0.194 27)`  | same                     | no component                                       |\n| `--opsin-status-urgent-700`           | primitive | Urgent ramp, step 700.                                                                                                                                                                                       | `oklch(0.452 0.176 27)`  | same                     | no component                                       |\n| `--opsin-status-urgent-800`           | primitive | Urgent ramp, step 800.                                                                                                                                                                                       | `oklch(0.362 0.148 27)`  | same                     | no component                                       |\n| `--opsin-status-urgent-900`           | primitive | Urgent ramp, step 900.                                                                                                                                                                                       | `oklch(0.276 0.115 27)`  | same                     | no component                                       |\n| `--opsin-status-urgent-950`           | primitive | Urgent ramp, step 950.                                                                                                                                                                                       | `oklch(0.208 0.088 27)`  | same                     | no component                                       |\n| `--opsin-status-urgent-surface`       | semantic  | The tinted background a component in this ramp sits on.                                                                                                                                                      | `oklch(0.972 0.014 27)`  | `oklch(0.208 0.088 27)`  | alert-banner, status-pill                          |\n| `--opsin-status-urgent-line`          | semantic  | The boundary, icon stroke or chart mark. The lightest value in the ramp that clears the non-text floor against `surface`.                                                                                    | `oklch(0.541 0.194 27)`  | `oklch(0.806 0.11 27)`   | alert-banner, range-bar, range-legend, status-pill |\n| `--opsin-status-urgent-ink`           | semantic  | Text and text-sized icons on `surface`. Clears the text floor against `surface`.                                                                                                                             | `oklch(0.362 0.148 27)`  | `oklch(0.884 0.061 27)`  | alert-banner, score-dial, status-pill              |\n| `--opsin-status-urgent-accent`        | semantic  | The identity fill: a bar fill, a dial track, a legend dot. Chosen for recognition, not for contrast. It must be bounded by `line` or labelled in `ink`; it is never the only thing that carries the meaning. | `oklch(0.52 0.2 27)`     | `oklch(0.714 0.176 27)`  | score-dial                                         |\n| `--opsin-status-urgent-plate`         | semantic  | Urgent plate: the enamel face StatusPill is filled with.                                                                                                                                                     | `oklch(0.5 0.19 25)`     | same                     | status-pill                                        |\n| `--opsin-status-urgent-plate-lit`     | semantic  | Urgent plate: the band along the top edge of the face, where it turns to the light.                                                                                                                          | `oklch(0.54 0.19 26)`    | same                     | status-pill                                        |\n| `--opsin-status-urgent-plate-rim`     | semantic  | Urgent plate: the outline of the plate, and the tint of the shadow it casts.                                                                                                                                 | `oklch(0.4 0.15 24)`     | same                     | status-pill                                        |\n| `--opsin-status-urgent-plate-word`    | semantic  | Urgent plate: the word and the glyph on the plate. Clears the body-text floor on the face and on the lit band.                                                                                               | `oklch(1 0 0)`           | same                     | status-pill                                        |\n| `--opsin-status-unknown-50`           | primitive | Unknown ramp, step 50.                                                                                                                                                                                       | `oklch(0.972 0.003 250)` | same                     | no component                                       |\n| `--opsin-status-unknown-100`          | primitive | Unknown ramp, step 100.                                                                                                                                                                                      | `oklch(0.941 0.005 250)` | same                     | no component                                       |\n| `--opsin-status-unknown-200`          | primitive | Unknown ramp, step 200.                                                                                                                                                                                      | `oklch(0.884 0.008 250)` | same                     | no component                                       |\n| `--opsin-status-unknown-300`          | primitive | Unknown ramp, step 300.                                                                                                                                                                                      | `oklch(0.806 0.013 250)` | same                     | no component                                       |\n| `--opsin-status-unknown-400`          | primitive | Unknown ramp, step 400.                                                                                                                                                                                      | `oklch(0.714 0.018 250)` | same                     | no component                                       |\n| `--opsin-status-unknown-500`          | primitive | Unknown ramp, step 500.                                                                                                                                                                                      | `oklch(0.622 0.02 250)`  | same                     | no component                                       |\n| `--opsin-status-unknown-600`          | primitive | Unknown ramp, step 600.                                                                                                                                                                                      | `oklch(0.541 0.019 250)` | same                     | no component                                       |\n| `--opsin-status-unknown-700`          | primitive | Unknown ramp, step 700.                                                                                                                                                                                      | `oklch(0.452 0.018 250)` | same                     | no component                                       |\n| `--opsin-status-unknown-800`          | primitive | Unknown ramp, step 800.                                                                                                                                                                                      | `oklch(0.362 0.015 250)` | same                     | no component                                       |\n| `--opsin-status-unknown-900`          | primitive | Unknown ramp, step 900.                                                                                                                                                                                      | `oklch(0.276 0.012 250)` | same                     | no component                                       |\n| `--opsin-status-unknown-950`          | primitive | Unknown ramp, step 950.                                                                                                                                                                                      | `oklch(0.208 0.009 250)` | same                     | no component                                       |\n| `--opsin-status-unknown-surface`      | semantic  | The tinted background a component in this ramp sits on.                                                                                                                                                      | `oklch(0.972 0.003 250)` | `oklch(0.208 0.009 250)` | no component                                       |\n| `--opsin-status-unknown-line`         | semantic  | The boundary, icon stroke or chart mark. The lightest value in the ramp that clears the non-text floor against `surface`.                                                                                    | `oklch(0.541 0.019 250)` | `oklch(0.806 0.013 250)` | no component                                       |\n| `--opsin-status-unknown-ink`          | semantic  | Text and text-sized icons on `surface`. Clears the text floor against `surface`.                                                                                                                             | `oklch(0.362 0.015 250)` | `oklch(0.884 0.008 250)` | no component                                       |\n| `--opsin-status-unknown-accent`       | semantic  | The identity fill: a bar fill, a dial track, a legend dot. Chosen for recognition, not for contrast. It must be bounded by `line` or labelled in `ink`; it is never the only thing that carries the meaning. | `oklch(0.72 0.02 250)`   | `oklch(0.714 0.018 250)` | no component                                       |\n\n#### accent [#accent]\n\n| Token                              | Tier     | What it controls                                                                                                                                                             | Light                    | Dark                     | Used by      |\n| ---------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | ------------------------ | ------------ |\n| `--opsin-accent-action`            | semantic | The fill of the one filled action on a surface, Button's primary rung. Read as --primary.                                                                                    | `oklch(0.145 0.005 250)` | `oklch(0.985 0.002 250)` | no component |\n| `--opsin-accent-action-foreground` | semantic | The label on the action fill. Measured against the fill and both of its states at the body floor. Read as --primary-foreground.                                              | `oklch(1 0 0)`           | `oklch(0.145 0.005 250)` | no component |\n| `--opsin-accent-action-hover`      | semantic | The action fill under a pointer. It moves away from the label, so the label never loses contrast. Read as --state-primary-hover.                                             | `oklch(0.269 0.007 250)` | `oklch(0.929 0.004 250)` | no component |\n| `--opsin-accent-action-press`      | semantic | The action fill while pressed or busy. It moves away from the label as well. Read as --state-primary-press.                                                                  | `oklch(0.371 0.008 250)` | `oklch(0.871 0.005 250)` | no component |\n| `--opsin-accent-action-edge`       | semantic | The action's boundary. Transparent where the fill alone clears the non-text floor against the page; an ink rim where a bright fill does not. Read as --primary-edge.         | `transparent`            | `transparent`            | no component |\n| `--opsin-accent-fill`              | semantic | The selected state of a selection control: a switch that is on, a ticked checkbox, a chosen radio, the range of a slider, a progress fill, the current tab. Read as --brand. | `oklch(0.53 0.155 250)`  | `oklch(0.845 0.079 250)` | no component |\n| `--opsin-accent-fill-foreground`   | semantic | A glyph or a label on the accent fill: a checkbox tick, a chosen scale value. Measured at the body floor. Read as --brand-foreground.                                        | `oklch(1 0 0)`           | `oklch(0.145 0.005 250)` | no component |\n| `--opsin-accent-fill-edge`         | semantic | The boundary of an accent fill, for the same reason as actionEdge. Read as --brand-edge.                                                                                     | `transparent`            | `transparent`            | no component |\n| `--opsin-accent-ink`               | semantic | Accent-coloured text on the page and on a card: a quiet button, an alternative action. Measured at the body floor on both. Read as --brand-ink.                              | `oklch(0.5 0.142 250)`   | `oklch(0.855 0.074 250)` | no component |\n| `--opsin-accent-ring`              | semantic | The focus ring. Measured at the non-text floor on the page and on a card. Read as --ring.                                                                                    | `oklch(0.53 0.155 250)`  | `oklch(0.75 0.13 250)`   | no component |\n| `--opsin-accent-glow`              | semantic | Light thrown by the action, as a shadow colour. Decorative, never a boundary, so it is not measured. Only vibes casts one. Read as --brand-glow.                             | `transparent`            | `transparent`            | no component |\n\n### material [#material]\n\n#### material [#material-1]\n\n| Token                                 | Tier     | What it controls                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Light                                                                                                                               | Dark                                                                                                             | Used by                                                                                                                                                                                                                     |\n| ------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--opsin-material-canvas-tint`        | semantic | Rung 0 (canvas): the tint over what is behind it. The application background. Nothing is behind it, so nothing shows through it.                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `var(--opsin-neutral-0)`                                                                                                            | `var(--opsin-neutral-950)`                                                                                       | surface                                                                                                                                                                                                                     |\n| `--opsin-material-canvas-tint-alpha`  | semantic | Rung 0 (canvas): how opaque that tint is.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `1`                                                                                                                                 | same                                                                                                             | surface                                                                                                                                                                                                                     |\n| `--opsin-material-canvas-blur`        | semantic | Rung 0 (canvas): backdrop blur radius.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `0px`                                                                                                                               | same                                                                                                             | surface                                                                                                                                                                                                                     |\n| `--opsin-material-canvas-saturation`  | semantic | Rung 0 (canvas): backdrop saturation multiplier.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `1`                                                                                                                                 | same                                                                                                             | surface                                                                                                                                                                                                                     |\n| `--opsin-material-canvas-border`      | semantic | Rung 0 (canvas): the boundary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `none`                                                                                                                              | same                                                                                                             | surface                                                                                                                                                                                                                     |\n| `--opsin-material-canvas-shadow`      | semantic | Rung 0 (canvas): the shadow that separates it from what is behind.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `none`                                                                                                                              | same                                                                                                             | surface                                                                                                                                                                                                                     |\n| `--opsin-material-canvas-scrim`       | semantic | Rung 0 (canvas): the minimum scrim opacity needed for text on this rung to clear the contrast floor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `0`                                                                                                                                 | same                                                                                                             | surface                                                                                                                                                                                                                     |\n| `--opsin-material-canvas-opaque`      | semantic | Rung 0 (canvas): the opaque substitute used under prefers-reduced-transparency and where backdrop-filter is unsupported.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `var(--opsin-neutral-0)`                                                                                                            | `var(--opsin-neutral-950)`                                                                                       | surface                                                                                                                                                                                                                     |\n| `--opsin-material-inset-tint`         | semantic | Rung 0.5 (inset): the tint over what is behind it. The recessed well inside a card: the explanatory note a Callout draws inside the reading it annotates, and the track a RangeBar lays its range along. Its fill sits below the card fill in both themes, so the well reads as carved into the card rather than lifted off it. In light it is neutral-100, one step under the white card, which is where a Callout already sat. In dark it is a value between the page and the card, below the card so the well is a recess and above the page so a Callout used on its own is still visible. | `var(--opsin-neutral-100)`                                                                                                          | `oklch(0.178 0.006 250)`                                                                                         | callout, range-bar, range-legend, surface                                                                                                                                                                                   |\n| `--opsin-material-inset-tint-alpha`   | semantic | Rung 0.5 (inset): how opaque that tint is.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `1`                                                                                                                                 | same                                                                                                             | surface                                                                                                                                                                                                                     |\n| `--opsin-material-inset-blur`         | semantic | Rung 0.5 (inset): backdrop blur radius.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `0px`                                                                                                                               | same                                                                                                             | surface                                                                                                                                                                                                                     |\n| `--opsin-material-inset-saturation`   | semantic | Rung 0.5 (inset): backdrop saturation multiplier.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `1`                                                                                                                                 | same                                                                                                             | surface                                                                                                                                                                                                                     |\n| `--opsin-material-inset-border`       | semantic | Rung 0.5 (inset): the boundary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `none`                                                                                                                              | same                                                                                                             | surface                                                                                                                                                                                                                     |\n| `--opsin-material-inset-shadow`       | semantic | Rung 0.5 (inset): the shadow that separates it from what is behind.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `none`                                                                                                                              | same                                                                                                             | surface                                                                                                                                                                                                                     |\n| `--opsin-material-inset-scrim`        | semantic | Rung 0.5 (inset): the minimum scrim opacity needed for text on this rung to clear the contrast floor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `0`                                                                                                                                 | same                                                                                                             | surface                                                                                                                                                                                                                     |\n| `--opsin-material-inset-opaque`       | semantic | Rung 0.5 (inset): the opaque substitute used under prefers-reduced-transparency and where backdrop-filter is unsupported.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `var(--opsin-neutral-100)`                                                                                                          | `oklch(0.178 0.006 250)`                                                                                         | surface                                                                                                                                                                                                                     |\n| `--opsin-material-card-tint`          | semantic | Rung 1 (card): the tint over what is behind it. The default home for a health value. Opaque, edged by a decorative line, and lifted off the page by a soft drop and a line of light along its top. The rung every ResultCard, MetricTile and RangeBar sits on.                                                                                                                                                                                                                                                                                                                                 | `var(--opsin-neutral-0)`                                                                                                            | `var(--opsin-neutral-900)`                                                                                       | surface                                                                                                                                                                                                                     |\n| `--opsin-material-card-tint-alpha`    | semantic | Rung 1 (card): how opaque that tint is.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `1`                                                                                                                                 | same                                                                                                             | surface                                                                                                                                                                                                                     |\n| `--opsin-material-card-blur`          | semantic | Rung 1 (card): backdrop blur radius.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `0px`                                                                                                                               | same                                                                                                             | surface                                                                                                                                                                                                                     |\n| `--opsin-material-card-saturation`    | semantic | Rung 1 (card): backdrop saturation multiplier.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `1`                                                                                                                                 | same                                                                                                             | surface                                                                                                                                                                                                                     |\n| `--opsin-material-card-border`        | semantic | Rung 1 (card): the boundary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `var(--opsin-chrome-edge)`                                                                                                          | `var(--opsin-chrome-edge)`                                                                                       | surface                                                                                                                                                                                                                     |\n| `--opsin-material-card-shadow`        | semantic | Rung 1 (card): the shadow that separates it from what is behind.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `inset 0 1px 0 0 oklch(1 0 0 / 0.7), 0 1px 2px 0 oklch(0.205 0.006 250 / 0.05), 0 10px 30px -14px oklch(0.205 0.006 250 / 0.16)`    | `inset 0 1px 0 0 oklch(1 0 0 / 0.05), 0 1px 2px 0 oklch(0 0 0 / 0.45), 0 14px 36px -16px oklch(0 0 0 / 0.7)`     | accordion, body-map, button, care-card, combobox, menu, popover, questionnaire, range-bar, range-legend, result-card, scale-input, scroll-area, segmented-control, select, slider, stepper, surface, switch, toast, tooltip |\n| `--opsin-material-card-scrim`         | semantic | Rung 1 (card): the minimum scrim opacity needed for text on this rung to clear the contrast floor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `0`                                                                                                                                 | same                                                                                                             | surface                                                                                                                                                                                                                     |\n| `--opsin-material-card-opaque`        | semantic | Rung 1 (card): the opaque substitute used under prefers-reduced-transparency and where backdrop-filter is unsupported.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `var(--opsin-neutral-0)`                                                                                                            | `var(--opsin-neutral-900)`                                                                                       | surface                                                                                                                                                                                                                     |\n| `--opsin-material-raised-tint`        | semantic | Rung 2 (raised): the tint over what is behind it. Menus, popovers, tooltips, a dragged card. Still opaque: the shadow, not translucency, is what says 'above'.                                                                                                                                                                                                                                                                                                                                                                                                                                 | `var(--opsin-neutral-0)`                                                                                                            | `var(--opsin-neutral-800)`                                                                                       | surface                                                                                                                                                                                                                     |\n| `--opsin-material-raised-tint-alpha`  | semantic | Rung 2 (raised): how opaque that tint is.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `1`                                                                                                                                 | same                                                                                                             | surface                                                                                                                                                                                                                     |\n| `--opsin-material-raised-blur`        | semantic | Rung 2 (raised): backdrop blur radius.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `0px`                                                                                                                               | same                                                                                                             | surface                                                                                                                                                                                                                     |\n| `--opsin-material-raised-saturation`  | semantic | Rung 2 (raised): backdrop saturation multiplier.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `1`                                                                                                                                 | same                                                                                                             | surface                                                                                                                                                                                                                     |\n| `--opsin-material-raised-border`      | semantic | Rung 2 (raised): the boundary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `var(--opsin-chrome-edge)`                                                                                                          | `var(--opsin-chrome-edge)`                                                                                       | surface                                                                                                                                                                                                                     |\n| `--opsin-material-raised-shadow`      | semantic | Rung 2 (raised): the shadow that separates it from what is behind.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `inset 0 1px 0 0 oklch(1 0 0 / 0.8), 0 2px 8px -2px oklch(0.205 0.006 250 / 0.08), 0 22px 52px -20px oklch(0.205 0.006 250 / 0.28)` | `inset 0 1px 0 0 oklch(1 0 0 / 0.06), 0 2px 8px -2px oklch(0 0 0 / 0.55), 0 26px 60px -18px oklch(0 0 0 / 0.85)` | combobox, menu, popover, select, surface, toast, tooltip                                                                                                                                                                    |\n| `--opsin-material-raised-scrim`       | semantic | Rung 2 (raised): the minimum scrim opacity needed for text on this rung to clear the contrast floor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `0`                                                                                                                                 | same                                                                                                             | surface                                                                                                                                                                                                                     |\n| `--opsin-material-raised-opaque`      | semantic | Rung 2 (raised): the opaque substitute used under prefers-reduced-transparency and where backdrop-filter is unsupported.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `var(--opsin-neutral-0)`                                                                                                            | `var(--opsin-neutral-800)`                                                                                       | surface                                                                                                                                                                                                                     |\n| `--opsin-material-sheet-tint`         | semantic | Rung 3 (sheet): the tint over what is behind it. A bottom sheet or side panel the reader can dismiss by dragging. Its tint is now near opaque, so the panel lands close to the card colour and a white control inside it no longer floats above a greyer surface. What keeps the covered page recognisable is the scrim around the panel rather than the page reading through the panel, because at this opacity very little of the page shows through the tint.                                                                                                                               | `var(--opsin-neutral-0)`                                                                                                            | `var(--opsin-neutral-900)`                                                                                       | surface                                                                                                                                                                                                                     |\n| `--opsin-material-sheet-tint-alpha`   | semantic | Rung 3 (sheet): how opaque that tint is.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `0.93`                                                                                                                              | `0.9`                                                                                                            | surface                                                                                                                                                                                                                     |\n| `--opsin-material-sheet-blur`         | semantic | Rung 3 (sheet): backdrop blur radius.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `20px`                                                                                                                              | same                                                                                                             | surface                                                                                                                                                                                                                     |\n| `--opsin-material-sheet-saturation`   | semantic | Rung 3 (sheet): backdrop saturation multiplier.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `1.6`                                                                                                                               | same                                                                                                             | surface                                                                                                                                                                                                                     |\n| `--opsin-material-sheet-border`       | semantic | Rung 3 (sheet): the boundary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `var(--opsin-chrome-edge)`                                                                                                          | `var(--opsin-chrome-edge)`                                                                                       | surface                                                                                                                                                                                                                     |\n| `--opsin-material-sheet-shadow`       | semantic | Rung 3 (sheet): the shadow that separates it from what is behind.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `inset 0 1px 0 0 oklch(1 0 0 / 0.8), 0 4px 12px -4px oklch(0.205 0.006 250 / 0.1), 0 40px 96px -28px oklch(0.205 0.006 250 / 0.38)` | `inset 0 1px 0 0 oklch(1 0 0 / 0.07), 0 4px 12px -4px oklch(0 0 0 / 0.6), 0 48px 120px -24px oklch(0 0 0 / 0.9)` | sheet, surface                                                                                                                                                                                                              |\n| `--opsin-material-sheet-scrim`        | semantic | Rung 3 (sheet): the minimum scrim opacity needed for text on this rung to clear the contrast floor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `0.93`                                                                                                                              | same                                                                                                             | surface                                                                                                                                                                                                                     |\n| `--opsin-material-sheet-opaque`       | semantic | Rung 3 (sheet): the opaque substitute used under prefers-reduced-transparency and where backdrop-filter is unsupported.                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `var(--opsin-neutral-0)`                                                                                                            | `var(--opsin-neutral-900)`                                                                                       | surface                                                                                                                                                                                                                     |\n| `--opsin-material-overlay-tint`       | semantic | Rung 4 (overlay): the tint over what is behind it. A pinned toolbar, a tab bar and a floating action bar are all chrome that content scrolls beneath.                                                                                                                                                                                                                                                                                                                                                                                                                                          | `var(--opsin-neutral-0)`                                                                                                            | `var(--opsin-neutral-900)`                                                                                       | surface                                                                                                                                                                                                                     |\n| `--opsin-material-overlay-tint-alpha` | semantic | Rung 4 (overlay): how opaque that tint is.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `0.74`                                                                                                                              | `0.7`                                                                                                            | surface                                                                                                                                                                                                                     |\n| `--opsin-material-overlay-blur`       | semantic | Rung 4 (overlay): backdrop blur radius.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `16px`                                                                                                                              | same                                                                                                             | surface                                                                                                                                                                                                                     |\n| `--opsin-material-overlay-saturation` | semantic | Rung 4 (overlay): backdrop saturation multiplier.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `1.8`                                                                                                                               | same                                                                                                             | surface                                                                                                                                                                                                                     |\n| `--opsin-material-overlay-border`     | semantic | Rung 4 (overlay): the boundary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `var(--opsin-chrome-edge)`                                                                                                          | `var(--opsin-chrome-edge)`                                                                                       | surface                                                                                                                                                                                                                     |\n| `--opsin-material-overlay-shadow`     | semantic | Rung 4 (overlay): the shadow that separates it from what is behind.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `inset 0 1px 0 0 oklch(1 0 0 / 0.55), 0 1px 2px 0 oklch(0.205 0.006 250 / 0.05), 0 12px 32px -14px oklch(0.205 0.006 250 / 0.2)`    | `inset 0 1px 0 0 oklch(1 0 0 / 0.06), 0 1px 2px 0 oklch(0 0 0 / 0.5), 0 14px 36px -14px oklch(0 0 0 / 0.8)`      | surface                                                                                                                                                                                                                     |\n| `--opsin-material-overlay-scrim`      | semantic | Rung 4 (overlay): the minimum scrim opacity needed for text on this rung to clear the contrast floor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `0.74`                                                                                                                              | same                                                                                                             | surface                                                                                                                                                                                                                     |\n| `--opsin-material-overlay-opaque`     | semantic | Rung 4 (overlay): the opaque substitute used under prefers-reduced-transparency and where backdrop-filter is unsupported.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `var(--opsin-neutral-0)`                                                                                                            | `var(--opsin-neutral-900)`                                                                                       | surface                                                                                                                                                                                                                     |\n| `--opsin-material-scrim-tint`         | semantic | Rung 5 (scrim): the tint over what is behind it. The dimming layer behind a modal dialog or a consent sheet. Its job is to remove the page from consideration, not to look like glass.                                                                                                                                                                                                                                                                                                                                                                                                         | `var(--opsin-neutral-950)`                                                                                                          | `var(--opsin-neutral-1000)`                                                                                      | surface                                                                                                                                                                                                                     |\n| `--opsin-material-scrim-tint-alpha`   | semantic | Rung 5 (scrim): how opaque that tint is.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `0.44`                                                                                                                              | `0.6`                                                                                                            | surface                                                                                                                                                                                                                     |\n| `--opsin-material-scrim-blur`         | semantic | Rung 5 (scrim): backdrop blur radius.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `2px`                                                                                                                               | same                                                                                                             | surface                                                                                                                                                                                                                     |\n| `--opsin-material-scrim-saturation`   | semantic | Rung 5 (scrim): backdrop saturation multiplier.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `1`                                                                                                                                 | same                                                                                                             | surface                                                                                                                                                                                                                     |\n| `--opsin-material-scrim-border`       | semantic | Rung 5 (scrim): the boundary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `none`                                                                                                                              | same                                                                                                             | surface                                                                                                                                                                                                                     |\n| `--opsin-material-scrim-shadow`       | semantic | Rung 5 (scrim): the shadow that separates it from what is behind.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `none`                                                                                                                              | same                                                                                                             | surface                                                                                                                                                                                                                     |\n| `--opsin-material-scrim-scrim`        | semantic | Rung 5 (scrim): the minimum scrim opacity needed for text on this rung to clear the contrast floor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `0.44`                                                                                                                              | same                                                                                                             | surface                                                                                                                                                                                                                     |\n| `--opsin-material-scrim-opaque`       | semantic | Rung 5 (scrim): the opaque substitute used under prefers-reduced-transparency and where backdrop-filter is unsupported.                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `oklch(0.205 0.006 250 / 0.72)`                                                                                                     | `oklch(0 0 0 / 0.8)`                                                                                             | surface                                                                                                                                                                                                                     |\n\n### motion [#motion]\n\n#### ease [#ease]\n\n| Token                        | Tier     | What it controls                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Light                                                                                                                                                                 | Dark | Used by                                                                                                                                                                                                                                                                                      |\n| ---------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--opsin-ease-spring-snap`   | semantic | Direct manipulation only: a switch the reader just flipped, a box ticked or a radio chosen, a segmented control or a tab indicator gliding to the new choice, a pressed button settling. It overshoots by 1.5%. That is enough to feel physical but not enough to look playful. The 1.5% is the largest overshoot in the system but not the only one: `spring-settle` overshoots by 0.88%. Only `spring-calm` and `spring-sheet` reach their target without passing it. | `linear(0, 0.0715, 0.2271, 0.4053, 0.5722, 0.7119, 0.8198, 0.8978, 0.9505, 0.9836, 1.0025, 1.0118, 1.015, 1.0147, 1.0126, 1.01, 1.0073, 1.0051, 1.0033, 1.0019, 1)`   | same | button, checkbox, dialog, radio-group, segmented-control, sheet, switch, tabs, toast                                                                                                                                                                                                         |\n| `--opsin-ease-spring-settle` | semantic | The workhorse for chrome: popovers, tooltips, menus, selects and comboboxes unfolding from their anchor, chips and toasts appearing and disappearing, and a swiped toast springing back.                                                                                                                                                                                                                                                                                | `linear(0, 0.0742, 0.2328, 0.4113, 0.5758, 0.7116, 0.8157, 0.8905, 0.9412, 0.9736, 0.9928, 1.003, 1.0076, 1.0088, 1.0082, 1.0068, 1.0053, 1.0038, 1.0026, 1.0017, 1)` | same | combobox, menu, popover, select, toast, tooltip                                                                                                                                                                                                                                              |\n| `--opsin-ease-spring-calm`   | semantic | A health value that changes while it is already on screen: a bar re-filling from one reading to the next, a dial travelling between two values the reader has already been shown. Never a first paint and never a first reveal. A value arrives at its final figure, with no count-up, no dial sweep and no line drawing itself in (health/motion-in-health-ui rule 2). Slightly overdamped (zeta just over 1) so it never overshoots and never bounces.                | `linear(0, 0.0829, 0.2457, 0.4157, 0.5642, 0.6832, 0.774, 0.841, 0.8893, 0.9236, 0.9476, 0.9643, 0.9757, 0.9836, 0.9889, 0.9926, 0.995, 0.9967, 0.9978, 0.9985, 1)`   | same | no component                                                                                                                                                                                                                                                                                 |\n| `--opsin-ease-spring-sheet`  | semantic | Large surfaces travelling a long distance: sheets, dialogs, full-screen pushes. Overdamped, because a sheet that bounces at the top of its travel reads as a dropped object.                                                                                                                                                                                                                                                                                            | `linear(0, 0.0881, 0.2576, 0.431, 0.5798, 0.6971, 0.7854, 0.8497, 0.8958, 0.9282, 0.9508, 0.9664, 0.9771, 0.9845, 0.9895, 0.9929, 0.9952, 0.9967, 0.9978, 0.9985, 1)` | same | dialog, sheet                                                                                                                                                                                                                                                                                |\n| `--opsin-ease-standard`      | semantic | Non-spring transitions where a spring would be overkill: colour, opacity, border. Fast out, slow in.                                                                                                                                                                                                                                                                                                                                                                    | `cubic-bezier(0.2, 0, 0, 1)`                                                                                                                                          | same | accordion, body-map, button, card, checkbox, combobox, consent-sheet, dialog, menu, metric-tile, number-field, popover, progress, radio-group, scale-input, scroll-area, segmented-control, select, sheet, skeleton, slider, switch, symptom-picker, tab-bar, tabs, textarea, toast, tooltip |\n| `--opsin-ease-enter`         | semantic | Something arriving from off-screen or from nothing. Decelerating, because an arrival should feel like it is coming to rest.                                                                                                                                                                                                                                                                                                                                             | `cubic-bezier(0.05, 0.7, 0.1, 1)`                                                                                                                                     | same | no component                                                                                                                                                                                                                                                                                 |\n| `--opsin-ease-exit`          | semantic | Something leaving. Accelerating and shorter than its enter, because a reader does not need to watch a dismissal finish.                                                                                                                                                                                                                                                                                                                                                 | `cubic-bezier(0.3, 0, 0.8, 0.15)`                                                                                                                                     | same | checkbox, combobox, dialog, menu, popover, radio-group, select, toast, tooltip                                                                                                                                                                                                               |\n\n#### duration [#duration]\n\n| Token                            | Tier     | What it controls                                                                                                                                                                                                                                                                                                                                                                                                                             | Light    | Dark | Used by                                                                                                                                                                                                                                                               |\n| -------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--opsin-duration-spring-snap`   | semantic | Settle time for the spring-snap spring, measured from its own parameters.                                                                                                                                                                                                                                                                                                                                                                    | `283ms`  | same | button, checkbox, dialog, radio-group, segmented-control, sheet, switch, tabs, toast                                                                                                                                                                                  |\n| `--opsin-duration-spring-settle` | semantic | Settle time for the spring-settle spring, measured from its own parameters.                                                                                                                                                                                                                                                                                                                                                                  | `382ms`  | same | combobox, menu, popover, select, toast, tooltip                                                                                                                                                                                                                       |\n| `--opsin-duration-spring-calm`   | semantic | Settle time for the spring-calm spring, measured from its own parameters.                                                                                                                                                                                                                                                                                                                                                                    | `550ms`  | same | no component                                                                                                                                                                                                                                                          |\n| `--opsin-duration-spring-sheet`  | semantic | Settle time for the spring-sheet spring, measured from its own parameters.                                                                                                                                                                                                                                                                                                                                                                   | `483ms`  | same | dialog, sheet                                                                                                                                                                                                                                                         |\n| `--opsin-duration-instant`       | semantic | State change with no travel: hover tint, focus ring. Also the way down of a press, which `foundations/states` applies on pointer-down and `spring-snap` brings back up.                                                                                                                                                                                                                                                                      | `80ms`   | same | button, card, dialog, metric-tile, sheet, toast                                                                                                                                                                                                                       |\n| `--opsin-duration-fast`          | semantic | Small elements moving a small distance.                                                                                                                                                                                                                                                                                                                                                                                                      | `140ms`  | same | accordion, body-map, card, checkbox, combobox, consent-sheet, menu, metric-tile, number-field, popover, progress, radio-group, scale-input, scroll-area, segmented-control, select, skeleton, slider, switch, symptom-picker, tab-bar, tabs, textarea, toast, tooltip |\n| `--opsin-duration-base`          | semantic | The default for chrome that is not spring-driven.                                                                                                                                                                                                                                                                                                                                                                                            | `220ms`  | same | dialog, sheet                                                                                                                                                                                                                                                         |\n| `--opsin-duration-slow`          | semantic | Layout change: a list reflowing, a card expanding.                                                                                                                                                                                                                                                                                                                                                                                           | `360ms`  | same | no component                                                                                                                                                                                                                                                          |\n| `--opsin-duration-deliberate`    | semantic | The ceiling on a transition a reader is waiting on, such as a first-run reveal or a consent sheet, where the point is that the reader notices. No such transition may exceed it. A looping placeholder period, like the skeleton shimmer, is bounded instead by its iteration count, so a single sweep of it may run longer.                                                                                                                 | `560ms`  | same | no component                                                                                                                                                                                                                                                          |\n| `--opsin-duration-shimmer`       | semantic | One sweep of a loading placeholder's sheen. This is a period, the time for the sheen to make one pass across the bar, and not a travel time. At 1600ms the movement reads as calm rather than as urgency, which the first motion rule requires of anything that is not a value the reader controls. Its consumer pairs it with a finite iteration count so the total motion stays under the five seconds at which WCAG 2.2 SC 2.2.2 engages. | `1600ms` | same | skeleton                                                                                                                                                                                                                                                              |\n\n### type [#type]\n\n#### font [#font]\n\n| Token                  | Tier     | What it controls          | Light                                                                                    | Dark | Used by            |\n| ---------------------- | -------- | ------------------------- | ---------------------------------------------------------------------------------------- | ---- | ------------------ |\n| `--opsin-font-sans`    | semantic | The sans family stack.    | `system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif`      | same | no component       |\n| `--opsin-font-mono`    | semantic | The mono family stack.    | `ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, 'Liberation Mono', monospace` | same | no component       |\n| `--opsin-font-numeric` | semantic | The numeric family stack. | `system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif`                               | same | result-card, value |\n\n#### text [#text]\n\n| Token                                        | Tier     | What it controls                                                                                                                                                | Light       | Dark | Used by                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |\n| -------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `--opsin-text-large-title-size`              | semantic | The largest step in the scale, reserved for a surface whose entire subject is one number or one word. No component in the system sets a value at this step yet. | `2.125rem`  | same | no component                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-text-large-title-leading`           | semantic | Line height for largeTitle, unitless so it scales with the size.                                                                                                | `1.118`     | same | no component                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-text-large-title-tracking`          | semantic | Letter spacing for largeTitle.                                                                                                                                  | `-0.032em`  | same | no component                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-text-large-title-weight`            | semantic | Font weight for largeTitle.                                                                                                                                     | `800`       | same | no component                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-text-title1-size`                   | semantic | A screen title, and the hero treatment a value's number takes at size display.                                                                                  | `1.75rem`   | same | goal-ring, result-card, value                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-text-title1-leading`                | semantic | Line height for title1, unitless so it scales with the size.                                                                                                    | `1.143`     | same | goal-ring, result-card, value                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-text-title1-tracking`               | semantic | Letter spacing for title1.                                                                                                                                      | `-0.026em`  | same | goal-ring, result-card, value                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-text-title1-weight`                 | semantic | Font weight for title1.                                                                                                                                         | `800`       | same | goal-ring, result-card, value                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-text-title2-size`                   | semantic | Section title; the floor for a primary health value inside a card.                                                                                              | `1.375rem`  | same | no component                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-text-title2-leading`                | semantic | Line height for title2, unitless so it scales with the size.                                                                                                    | `1.227`     | same | no component                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-text-title2-tracking`               | semantic | Letter spacing for title2.                                                                                                                                      | `-0.018em`  | same | no component                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-text-title2-weight`                 | semantic | Font weight for title2.                                                                                                                                         | `700`       | same | no component                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-text-title3-size`                   | semantic | A Dialog or Sheet title, and the unit beside a value's number at size display.                                                                                  | `1.25rem`   | same | dialog, goal-ring, questionnaire, reading-input, sheet, value                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-text-title3-leading`                | semantic | Line height for title3, unitless so it scales with the size.                                                                                                    | `1.25`      | same | dialog, goal-ring, questionnaire, reading-input, sheet, value                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-text-title3-tracking`               | semantic | Letter spacing for title3.                                                                                                                                      | `-0.014em`  | same | dialog, goal-ring, questionnaire, reading-input, sheet, value                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-text-title3-weight`                 | semantic | Font weight for title3.                                                                                                                                         | `700`       | same | dialog, goal-ring, questionnaire, reading-input, sheet, value                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-text-headline-size`                 | semantic | An emphasised line of body text, such as a status sentence or a question in a form.                                                                             | `1.0625rem` | same | accordion, alert-banner, avatar, button, callout, card, care-card, empty-state, field, log-sheet, menu, popover, range-bar, reading-input, result-card, scale-input, segmented-control, status-pill, surface, tabs, textarea, timeline-entry, toast, trend-sparkline, value                                                                                                                                                                                                                            |\n| `--opsin-text-headline-leading`              | semantic | Line height for headline, unitless so it scales with the size.                                                                                                  | `1.412`     | same | accordion, alert-banner, avatar, button, callout, card, care-card, empty-state, field, log-sheet, menu, popover, range-bar, reading-input, result-card, scale-input, segmented-control, status-pill, surface, tabs, textarea, timeline-entry, toast, trend-sparkline, value                                                                                                                                                                                                                            |\n| `--opsin-text-headline-tracking`             | semantic | Letter spacing for headline.                                                                                                                                    | `-0.006em`  | same | accordion, alert-banner, avatar, button, callout, card, care-card, empty-state, field, log-sheet, menu, popover, range-bar, reading-input, result-card, scale-input, segmented-control, status-pill, surface, tabs, textarea, timeline-entry, toast, trend-sparkline, value                                                                                                                                                                                                                            |\n| `--opsin-text-headline-weight`               | semantic | Font weight for headline.                                                                                                                                       | `600`       | same | accordion, alert-banner, avatar, button, callout, card, care-card, empty-state, field, log-sheet, menu, popover, range-bar, reading-input, result-card, scale-input, segmented-control, status-pill, surface, tabs, textarea, timeline-entry, toast, trend-sparkline, value                                                                                                                                                                                                                            |\n| `--opsin-text-body-size`                     | semantic | Everything a reader reads as prose. The anchor of the scale.                                                                                                    | `1.0625rem` | same | accordion, alert-banner, badge, callout, card, care-card, checkbox, combobox, consent-sheet, dialog, disclaimer-note, divider, dose-tracker, empty-state, field, goal-ring, link, menu, number-field, popover, questionnaire, radio-group, range-bar, range-legend, reading-input, relative-time, result-card, score-dial, scroll-area, select, sheet, surface, switch, symptom-picker, table, tabs, term, textarea, timeline-entry, toast, tooltip, trend-sparkline, value, visually-hidden           |\n| `--opsin-text-body-leading`                  | semantic | Line height for body, unitless so it scales with the size.                                                                                                      | `1.412`     | same | accordion, alert-banner, badge, callout, card, care-card, checkbox, combobox, consent-sheet, dialog, disclaimer-note, divider, dose-tracker, empty-state, field, goal-ring, link, menu, number-field, popover, questionnaire, radio-group, range-bar, range-legend, reading-input, relative-time, result-card, score-dial, scroll-area, select, sheet, skeleton, surface, switch, symptom-picker, table, tabs, term, textarea, timeline-entry, toast, tooltip, trend-sparkline, value, visually-hidden |\n| `--opsin-text-body-tracking`                 | semantic | Letter spacing for body.                                                                                                                                        | `-0.003em`  | same | accordion, alert-banner, badge, callout, card, care-card, checkbox, combobox, consent-sheet, dialog, disclaimer-note, divider, dose-tracker, empty-state, field, goal-ring, link, menu, number-field, popover, questionnaire, radio-group, range-bar, range-legend, reading-input, relative-time, result-card, score-dial, scroll-area, select, sheet, surface, switch, symptom-picker, table, tabs, term, textarea, timeline-entry, toast, tooltip, trend-sparkline, value, visually-hidden           |\n| `--opsin-text-body-weight`                   | semantic | Font weight for body.                                                                                                                                           | `400`       | same | accordion, alert-banner, badge, callout, card, care-card, checkbox, combobox, consent-sheet, dialog, disclaimer-note, divider, dose-tracker, empty-state, field, goal-ring, link, menu, number-field, popover, questionnaire, radio-group, range-bar, range-legend, reading-input, relative-time, result-card, score-dial, scroll-area, select, sheet, surface, switch, symptom-picker, table, tabs, term, textarea, timeline-entry, toast, tooltip, trend-sparkline, value, visually-hidden           |\n| `--opsin-text-callout-size`                  | semantic | Secondary prose inside a card or a callout.                                                                                                                     | `1rem`      | same | dialog, sheet, toast                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-text-callout-leading`               | semantic | Line height for callout, unitless so it scales with the size.                                                                                                   | `1.375`     | same | dialog, sheet, toast                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-text-callout-tracking`              | semantic | Letter spacing for callout.                                                                                                                                     | `-0.002em`  | same | dialog, sheet, toast                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-text-callout-weight`                | semantic | Font weight for callout.                                                                                                                                        | `400`       | same | dialog, sheet, toast                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-text-subheadline-size`              | semantic | A supporting line under a title.                                                                                                                                | `0.9375rem` | same | care-card, empty-state, goal-ring, metric-tile, progress, radio-group, score-dial, segmented-control, slider, spinner, status-pill, stepper, table                                                                                                                                                                                                                                                                                                                                                     |\n| `--opsin-text-subheadline-leading`           | semantic | Line height for subheadline, unitless so it scales with the size.                                                                                               | `1.333`     | same | care-card, empty-state, goal-ring, metric-tile, progress, radio-group, score-dial, segmented-control, slider, spinner, status-pill, stepper, table                                                                                                                                                                                                                                                                                                                                                     |\n| `--opsin-text-subheadline-tracking`          | semantic | Letter spacing for subheadline.                                                                                                                                 | `-0.001em`  | same | care-card, empty-state, goal-ring, metric-tile, progress, radio-group, score-dial, segmented-control, slider, spinner, status-pill, stepper, table                                                                                                                                                                                                                                                                                                                                                     |\n| `--opsin-text-subheadline-weight`            | semantic | Font weight for subheadline.                                                                                                                                    | `400`       | same | care-card, empty-state, goal-ring, metric-tile, progress, radio-group, score-dial, segmented-control, slider, spinner, status-pill, stepper, table                                                                                                                                                                                                                                                                                                                                                     |\n| `--opsin-text-subheadline-emphasis-size`     | semantic | The emphasised twin of subheadline, for a compact control's label, where the control must read as narrower and never as quieter.                                | `0.9375rem` | same | avatar, button                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-text-subheadline-emphasis-leading`  | semantic | Line height for subheadlineEmphasis, unitless so it scales with the size.                                                                                       | `1.333`     | same | avatar, button                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-text-subheadline-emphasis-tracking` | semantic | Letter spacing for subheadlineEmphasis.                                                                                                                         | `-0.001em`  | same | avatar, button                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-text-subheadline-emphasis-weight`   | semantic | Font weight for subheadlineEmphasis.                                                                                                                            | `600`       | same | avatar, button                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-text-footnote-size`                 | semantic | Provenance: who measured this, when, with what.                                                                                                                 | `0.8125rem` | same | body-map, card, checkbox, combobox, consent-sheet, dialog, disclaimer-note, divider, dose-tracker, goal-ring, log-sheet, menu, metric-tile, questionnaire, radio-group, range-bar, range-legend, result-card, scale-input, score-dial, sheet, source-citation, status-pill, stepper, switch, symptom-picker, table, timeline-entry, toast, tooltip, trend-sparkline                                                                                                                                    |\n| `--opsin-text-footnote-leading`              | semantic | Line height for footnote, unitless so it scales with the size.                                                                                                  | `1.385`     | same | body-map, card, checkbox, combobox, consent-sheet, dialog, disclaimer-note, divider, dose-tracker, goal-ring, log-sheet, menu, metric-tile, questionnaire, radio-group, range-bar, range-legend, result-card, scale-input, score-dial, sheet, source-citation, status-pill, stepper, switch, symptom-picker, table, timeline-entry, toast, tooltip, trend-sparkline                                                                                                                                    |\n| `--opsin-text-footnote-tracking`             | semantic | Letter spacing for footnote.                                                                                                                                    | `0em`       | same | body-map, card, checkbox, combobox, consent-sheet, dialog, disclaimer-note, divider, dose-tracker, goal-ring, log-sheet, menu, metric-tile, questionnaire, radio-group, range-bar, range-legend, result-card, scale-input, score-dial, sheet, source-citation, status-pill, stepper, switch, symptom-picker, table, timeline-entry, toast, tooltip, trend-sparkline                                                                                                                                    |\n| `--opsin-text-footnote-weight`               | semantic | Font weight for footnote.                                                                                                                                       | `400`       | same | body-map, card, checkbox, combobox, consent-sheet, dialog, disclaimer-note, divider, dose-tracker, goal-ring, log-sheet, menu, metric-tile, questionnaire, radio-group, range-bar, range-legend, result-card, scale-input, score-dial, sheet, source-citation, status-pill, stepper, switch, symptom-picker, table, timeline-entry, toast, tooltip, trend-sparkline                                                                                                                                    |\n| `--opsin-text-caption1-size`                 | semantic | Axis labels, legend text, and legal text.                                                                                                                       | `0.75rem`   | same | avatar, badge, consent-sheet, dose-tracker, range-bar, skeleton, tab-bar, visually-hidden                                                                                                                                                                                                                                                                                                                                                                                                              |\n| `--opsin-text-caption1-leading`              | semantic | Line height for caption1, unitless so it scales with the size.                                                                                                  | `1.333`     | same | avatar, badge, consent-sheet, dose-tracker, range-bar, skeleton, tab-bar, visually-hidden                                                                                                                                                                                                                                                                                                                                                                                                              |\n| `--opsin-text-caption1-tracking`             | semantic | Letter spacing for caption1.                                                                                                                                    | `0.002em`   | same | avatar, badge, consent-sheet, dose-tracker, range-bar, skeleton, tab-bar, visually-hidden                                                                                                                                                                                                                                                                                                                                                                                                              |\n| `--opsin-text-caption1-weight`               | semantic | Font weight for caption1.                                                                                                                                       | `400`       | same | avatar, badge, consent-sheet, dose-tracker, range-bar, skeleton, tab-bar, visually-hidden                                                                                                                                                                                                                                                                                                                                                                                                              |\n| `--opsin-text-caption2-size`                 | semantic | The smallest text the system permits, and only for text that repeats a label already present elsewhere. Never the only place a fact appears.                    | `0.6875rem` | same | no component                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-text-caption2-leading`              | semantic | Line height for caption2, unitless so it scales with the size.                                                                                                  | `1.273`     | same | no component                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-text-caption2-tracking`             | semantic | Letter spacing for caption2.                                                                                                                                    | `0.01em`    | same | no component                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-text-caption2-weight`               | semantic | Font weight for caption2.                                                                                                                                       | `600`       | same | no component                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n\n#### numerals [#numerals]\n\n| Token              | Tier     | What it controls                                                                                    | Light          | Dark | Used by      |\n| ------------------ | -------- | --------------------------------------------------------------------------------------------------- | -------------- | ---- | ------------ |\n| `--opsin-numerals` | semantic | Every component that renders a number sets this, so a changing value does not shift its own layout. | `tabular-nums` | same | no component |\n\n### space [#space]\n\n#### space [#space-1]\n\n| Token               | Tier      | What it controls                                                                                                                                              | Light       | Dark | Used by                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |\n| ------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--opsin-space-0`   | primitive | 0px.                                                                                                                                                          | `0rem`      | same | no component                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |\n| `--opsin-space-1`   | primitive | Gap between an icon and its label.                                                                                                                            | `0.25rem`   | same | badge, button, callout, care-card, checkbox, combobox, dialog, dose-tracker, empty-state, field, goal-ring, log-sheet, menu, questionnaire, radio-group, range-bar, result-card, scale-input, scroll-area, segmented-control, select, sheet, slider, source-citation, stepper, surface, symptom-picker, tab-bar, tabs, timeline-entry, toast, tooltip, trend-sparkline                                                                                                                                                    |\n| `--opsin-space-2`   | primitive | Gap between tightly related lines. For the separation between two interactive targets see targets.separation, which is the same number and carries its scope. | `0.5rem`    | same | alert-banner, avatar, badge, body-map, button, callout, combobox, consent-sheet, dialog, disclaimer-note, dose-tracker, empty-state, field, icon-button, log-sheet, menu, metric-tile, number-field, popover, progress, questionnaire, radio-group, range-bar, reading-input, relative-time, scale-input, score-dial, scroll-area, segmented-control, select, sheet, skeleton, slider, spinner, surface, symptom-picker, tab-bar, table, tabs, textarea, timeline-entry, toast, tooltip, trend-sparkline, visually-hidden |\n| `--opsin-space-3`   | primitive | Inner padding of a compact control.                                                                                                                           | `0.75rem`   | same | accordion, alert-banner, button, card, checkbox, combobox, consent-sheet, dialog, disclaimer-note, divider, empty-state, field, log-sheet, menu, metric-tile, progress, radio-group, range-legend, reading-input, result-card, scroll-area, segmented-control, select, sheet, slider, status-pill, stepper, surface, symptom-picker, table, tabs, textarea, timeline-entry, toast, tooltip, value                                                                                                                         |\n| `--opsin-space-4`   | primitive | The default gap between elements inside a card.                                                                                                               | `1rem`      | same | accordion, alert-banner, avatar, badge, button, callout, care-card, consent-sheet, dialog, divider, empty-state, field, goal-ring, link, log-sheet, menu, popover, range-bar, result-card, scale-input, score-dial, segmented-control, sheet, surface, switch, tabs, timeline-entry, toast                                                                                                                                                                                                                                |\n| `--opsin-space-5`   | primitive | Card inner padding on a phone.                                                                                                                                | `1.25rem`   | same | avatar, button, consent-sheet, dialog, menu, questionnaire, sheet, slider, switch, symptom-picker                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| `--opsin-space-6`   | primitive | Card inner padding on a wide screen; gap between cards.                                                                                                       | `1.5rem`    | same | avatar, card, dialog, disclaimer-note, empty-state, field, log-sheet, skeleton, stepper, switch, tab-bar, toast, trend-sparkline                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-space-8`   | primitive | Gap between sections within a screen.                                                                                                                         | `2rem`      | same | avatar, body-map, disclaimer-note, popover, range-bar, reading-input, sheet, stepper, tab-bar                                                                                                                                                                                                                                                                                                                                                                                                                             |\n| `--opsin-space-10`  | primitive | Space above a section heading.                                                                                                                                | `2.5rem`    | same | avatar, sheet, skeleton, switch                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| `--opsin-space-12`  | primitive | Gap between major regions of a screen.                                                                                                                        | `3rem`      | same | avatar, trend-sparkline                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |\n| `--opsin-space-16`  | primitive | Top of a screen below the safe area; the space a consent sheet leaves above its first question.                                                               | `4rem`      | same | dialog, skeleton                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-space-20`  | primitive | Empty-state vertical rhythm.                                                                                                                                  | `5rem`      | same | no component                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |\n| `--opsin-space-24`  | primitive | The largest step. Beyond this, use a layout, not a gap.                                                                                                       | `6rem`      | same | no component                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |\n| `--opsin-space-px`  | primitive | Hairline borders only.                                                                                                                                        | `0.0625rem` | same | body-map, trend-sparkline                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |\n| `--opsin-space-0-5` | primitive | Optical nudges. Not a layout step.                                                                                                                            | `0.125rem`  | same | badge, dose-tracker, radio-group, range-legend, result-card, scroll-area, segmented-control, stepper, switch, tab-bar, tabs, term, trend-sparkline                                                                                                                                                                                                                                                                                                                                                                        |\n\n#### target [#target]\n\n| Token                        | Tier     | What it controls                                                                                                                                                                                                                                                                                                   | Light     | Dark | Used by                                                                                                                                                                                                                                                                                                                                         |\n| ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--opsin-target-minimum`     | semantic | The opsinjs floor for any interactive control, applied to the hit area rather than to the visible box.                                                                                                                                                                                                             | `2.75rem` | same | accordion, body-map, button, card, checkbox, combobox, consent-sheet, dialog, disclaimer-note, field, icon-button, menu, metric-tile, number-field, popover, questionnaire, radio-group, reading-input, scale-input, segmented-control, select, sheet, slider, source-citation, switch, symptom-picker, tab-bar, tabs, textarea, toast, tooltip |\n| `--opsin-target-comfortable` | semantic | The default for a primary action in the product theme.                                                                                                                                                                                                                                                             | `3rem`    | same | dialog                                                                                                                                                                                                                                                                                                                                          |\n| `--opsin-target-generous`    | semantic | A single primary action on a consent, escalation or emergency surface, where a mis-tap has a real cost.                                                                                                                                                                                                            | `3.5rem`  | same | no component                                                                                                                                                                                                                                                                                                                                    |\n| `--opsin-target-separation`  | semantic | The minimum gap between two adjacent targets whose visible boxes are smaller than 44px. It is a floor for undersized targets only. Two targets that both meet the 44px minimum are outside its scope, and separating those is governed by the differing cost of a mis-tap between them rather than by a fixed gap. | `0.5rem`  | same | alert-banner, card, care-card, consent-sheet, result-card                                                                                                                                                                                                                                                                                       |\n\n#### gutter [#gutter]\n\n| Token                   | Tier     | What it controls                                 | Light  | Dark | Used by      |\n| ----------------------- | -------- | ------------------------------------------------ | ------ | ---- | ------------ |\n| `--opsin-gutter-phone`  | semantic | The screen gutter in the phone responsive mode.  | `16px` | same | no component |\n| `--opsin-gutter-tablet` | semantic | The screen gutter in the tablet responsive mode. | `24px` | same | no component |\n| `--opsin-gutter-wide`   | semantic | The screen gutter in the wide responsive mode.   | `32px` | same | no component |\n\n#### measure [#measure]\n\n| Token                         | Tier     | What it controls                                                                                        | Light  | Dark | Used by                                                                |\n| ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------- | ------ | ---- | ---------------------------------------------------------------------- |\n| `--opsin-measure-tight`       | semantic | A caption or a legend.                                                                                  | `45ch` | same | dialog, empty-state, goal-ring, popover, tooltip                       |\n| `--opsin-measure-comfortable` | semantic | The maximum line length for prose anywhere in the product, including a disclaimer nobody wants to read. | `66ch` | same | disclaimer-note, result-card, score-dial, sheet, source-citation, term |\n| `--opsin-measure-wide`        | semantic | Code and machine output only.                                                                           | `80ch` | same | no component                                                           |\n\n#### graphic [#graphic]\n\n| Token                  | Tier     | What it controls                                                                                                                                                                                       | Light   | Dark | Used by               |\n| ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | ---- | --------------------- |\n| `--opsin-graphic-dial` | semantic | The maximum width of the ScoreDial arc. This is 16em against the product body of 1.0625rem, which is 17rem and lands on the 4px grid at 68 steps, and it yields to w-full when the column is narrower. | `17rem` | same | goal-ring, score-dial |\n\n#### safe [#safe]\n\n| Token                 | Tier     | What it controls                                                                                   | Light                              | Dark | Used by       |\n| --------------------- | -------- | -------------------------------------------------------------------------------------------------- | ---------------------------------- | ---- | ------------- |\n| `--opsin-safe-top`    | semantic | The top safe-area inset, for installed web apps where browser chrome does not protect the edge.    | `env(safe-area-inset-top, 0px)`    | same | no component  |\n| `--opsin-safe-right`  | semantic | The right safe-area inset, for installed web apps where browser chrome does not protect the edge.  | `env(safe-area-inset-right, 0px)`  | same | sheet         |\n| `--opsin-safe-bottom` | semantic | The bottom safe-area inset, for installed web apps where browser chrome does not protect the edge. | `env(safe-area-inset-bottom, 0px)` | same | dialog, sheet |\n| `--opsin-safe-left`   | semantic | The left safe-area inset, for installed web apps where browser chrome does not protect the edge.   | `env(safe-area-inset-left, 0px)`   | same | sheet         |\n\n### shape [#shape]\n\n#### radius [#radius]\n\n| Token                               | Tier     | What it controls                                                                                             | Light                                                             | Dark | Used by                                                                                                                                                                                                                                                                                          |\n| ----------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `--opsin-radius-base`               | semantic | The one radius the whole ladder is derived from.                                                             | `1.25rem`                                                         | same | accordion, callout, card, care-card, combobox, empty-state, field, menu, metric-tile, popover, questionnaire, radio-group, range-bar, reading-input, result-card, scale-input, scroll-area, select, skeleton, symptom-picker, tab-bar, textarea, timeline-entry, toast, tooltip, trend-sparkline |\n| `--opsin-radius-none`               | semantic | Full-bleed media and anything that meets a screen edge.                                                      | `0rem`                                                            | same | no component                                                                                                                                                                                                                                                                                     |\n| `--opsin-radius-xs`                 | semantic | The floor for a nested corner. Tags inside a chip, a swatch inside a legend.                                 | `0.3125rem`                                                       | same | popover, surface, symptom-picker, term, tooltip                                                                                                                                                                                                                                                  |\n| `--opsin-radius-sm`                 | semantic | Inputs, small controls and a well inside a card.                                                             | `0.625rem`                                                        | same | card, checkbox, combobox, consent-sheet, dialog, divider, log-sheet, menu, number-field, progress, reading-input, scroll-area, select, sheet, skeleton, slider, switch, tab-bar, tabs, toast, visually-hidden                                                                                    |\n| `--opsin-radius-md`                 | semantic | The default for a bounded surface: a card, a tile, a callout, a list row.                                    | `1.25rem`                                                         | same | accordion, callout, card, combobox, empty-state, field, menu, metric-tile, popover, questionnaire, radio-group, result-card, scale-input, scroll-area, select, skeleton, symptom-picker, tab-bar, textarea, toast, tooltip                                                                       |\n| `--opsin-radius-lg`                 | semantic | A card nearly the width of a phone screen, and a banner.                                                     | `1.875rem`                                                        | same | alert-banner, card, disclaimer-note, result-card, surface, toast                                                                                                                                                                                                                                 |\n| `--opsin-radius-xl`                 | semantic | Sheets and dialogs. Applied to the leading edge only when the surface meets a screen edge on the other side. | `2.5rem`                                                          | same | alert-banner, dialog, sheet                                                                                                                                                                                                                                                                      |\n| `--opsin-radius-inner-card`         | semantic | A box inside a card at the comfortable density (card padding p-5).                                           | `max(calc(1.25rem - 5 * var(--spacing)), var(--opsin-radius-xs))` | same | no component                                                                                                                                                                                                                                                                                     |\n| `--opsin-radius-inner-card-compact` | semantic | A box inside a card at the compact density (card padding p-4).                                               | `max(calc(1.25rem - 4 * var(--spacing)), var(--opsin-radius-xs))` | same | no component                                                                                                                                                                                                                                                                                     |\n\n#### corner-shape [#corner-shape]\n\n| Token                  | Tier     | What it controls                                                               | Light             | Dark | Used by                                                                                |\n| ---------------------- | -------- | ------------------------------------------------------------------------------ | ----------------- | ---- | -------------------------------------------------------------------------------------- |\n| `--opsin-corner-shape` | semantic | The squircle curvature. Degrades to `round` where corner-shape is unsupported. | `superellipse(2)` | same | accordion, alert-banner, callout, card, dialog, field, metric-tile, result-card, sheet |\n\n#### border [#border]\n\n| Token                         | Tier     | What it controls                                                                                                                                                                          | Light | Dark | Used by                                                                                                                                                                                                                                                                        |\n| ----------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `--opsin-border-hairline`     | semantic | Every boundary in the system by default.                                                                                                                                                  | `1px` | same | button, surface                                                                                                                                                                                                                                                                |\n| `--opsin-border-emphasis`     | semantic | The boundary of a surface carrying `attention` or `urgent`, where the boundary is one of the three non-colour carriers of the status.                                                     | `2px` | same | disclaimer-note, field, surface                                                                                                                                                                                                                                                |\n| `--opsin-border-focus`        | semantic | The focus ring. Always 2px with a 2px offset, always in a colour measured against both the surface and the page behind it, and never removed. See /docs/accessibility/keyboard-and-focus. | `2px` | same | accordion, body-map, button, card, checkbox, combobox, consent-sheet, link, menu, number-field, popover, questionnaire, radio-group, scale-input, scroll-area, segmented-control, select, slider, switch, symptom-picker, tab-bar, table, tabs, term, textarea, toast, tooltip |\n| `--opsin-border-focus-offset` | semantic | Offset for the focus boundary.                                                                                                                                                            | `2px` | same | accordion, body-map, button, card, checkbox, combobox, consent-sheet, link, menu, number-field, popover, questionnaire, radio-group, scale-input, scroll-area, segmented-control, select, slider, switch, symptom-picker, tab-bar, table, tabs, term, textarea, toast, tooltip |\n\n{/* opsinjs:generated:end */}"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/reference/generated/types",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/reference/generated/types.md",
      "slug": [
        "reference",
        "generated",
        "types"
      ],
      "section": "Reference",
      "title": "Types",
      "description": "Every TypeScript symbol this documentation site's own lib/ exports, with a page of its own for each type and interface.",
      "kind": "reference",
      "aliases": [
        "exported types",
        "TypeScript API",
        "ClinicalStatus",
        "HealthCategory"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-09-02",
      "markdown": "Generated by `scripts/build-reference.mts` from the `export` declarations under `lib/`, read textually so the page builds before anything compiles. Run `pnpm run generate`; to improve a row, improve the symbol's doc comment.\n\nThese are the site's own symbols. `lib/opsinjs.ts` is copied into a consumer's project with every component, and the clinical vocabulary there is the part that matters: `ClinicalStatus` is the union of the four status levels and `HealthCategory` the union of the categories, so mixing the two axes is a compile error rather than a review finding ([Two colour axes](../../health/two-colour-axes.mdx)). Nothing here installs from npm. Component props are on each component page. Generated modules under `lib/generated/` and names starting with an underscore are excluded.\n\n{/* opsinjs:generated:begin - everything below is replaced by scripts/build-reference.mts */}\n\n## Exported symbols [#exported-symbols]\n\n| Symbol                                                | Kind      | Declared in             | Summary                                                                                                                                                                                                                                                                                                                   |\n| ----------------------------------------------------- | --------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `absoluteUrl`                                         | function  | `lib/routes.ts`         | Turn a root-relative path into a full URL on the canonical origin.                                                                                                                                                                                                                                                        |\n| `agentRoutes`                                         | const     | `lib/routes.ts`         | -                                                                                                                                                                                                                                                                                                                         |\n| `aliasesFor`                                          | function  | `lib/catalogue.ts`      | The exact array a page's `aliases` frontmatter must contain.                                                                                                                                                                                                                                                              |\n| `aliasIndex`                                          | function  | `lib/catalogue.ts`      | alias → the id or page it resolves to. Lower-cased, because a reader typing \"Blood Pressure\" and a reader typing \"blood pressure\" want the same page.                                                                                                                                                                     |\n| [`AliasProblem`](#aliasproblem)                       | interface | `lib/catalogue.ts`      | One search synonym that cannot be used, either because two components claim it or because it collides with a component id.                                                                                                                                                                                                |\n| `apca`                                                | const     | `lib/color/apca.ts`     | The short name, for callers that just want the number: `apca(\"#333\", \"#fff\")`. Identical to `apcaContrast`.                                                                                                                                                                                                               |\n| `APCA_FLOOR`                                          | const     | `lib/color/apca.ts`     | The published opsinjs APCA floor. These are the system's own commitments, chosen a little above the bare minimum because the audience is reading a number that matters to them on a phone, outdoors, often over 60.                                                                                                       |\n| `apcaContrast`                                        | function  | `lib/color/apca.ts`     | Lc for text on a background. Positive means dark-on-light, negative means light-on-dark, and the two arguments are not interchangeable.                                                                                                                                                                                   |\n| `apcaContrastOklch`                                   | function  | `lib/color/apca.ts`     | The same, taking OKLCH. Both colours are clamped into sRGB first, because that is what a screen shows.                                                                                                                                                                                                                    |\n| `apcaVerdict`                                         | function  | `lib/color/apca.ts`     | -                                                                                                                                                                                                                                                                                                                         |\n| [`ApcaVerdict`](#apcaverdict)                         | interface | `lib/color/apca.ts`     | The result of one APCA measurement, with the signed Lc, its polarity, the floor for that use, and how far above or below the floor it landed.                                                                                                                                                                             |\n| `apiRoutes`                                           | const     | `lib/routes.ts`         | -                                                                                                                                                                                                                                                                                                                         |\n| `apiSymbolPath`                                       | function  | `lib/routes.ts`         | A type's section on the generated Types page. `\\<ApiLink\\>` resolves here.                                                                                                                                                                                                                                                |\n| `axisConflict`                                        | function  | `lib/status.ts`         | THE NEVER-MIX RULE, as a function.                                                                                                                                                                                                                                                                                        |\n| [`AxisConflict`](#axisconflict)                       | interface | `lib/status.ts`         | A refusal. It is what the system answers when a measurement category and a clinical status are asked to share one surface.                                                                                                                                                                                                |\n| `BANNED_WORDS`                                        | const     | `lib/opsinjs.ts`        | Words a component's copy must not use, with the replacement and the reason. Generated from `tokens/glossary.json`.                                                                                                                                                                                                        |\n| `baseOptions`                                         | function  | `lib/layout.shared.tsx` | THERE IS NO TOP NAVIGATION, AND THAT IS THE POINT.                                                                                                                                                                                                                                                                        |\n| `baseStyleQuery`                                      | function  | `lib/routes.ts`         | The `?base=&style=` query a docs page uses for the same switch. Returns an empty string at the defaults so the canonical URL stays clean.                                                                                                                                                                                 |\n| `builtComponentCount`                                 | function  | `lib/registry.ts`       | How many distinct components have a real renderable behind them.                                                                                                                                                                                                                                                          |\n| `byNamespace`                                         | function  | `lib/tokens.ts`         | -                                                                                                                                                                                                                                                                                                                         |\n| `byTier`                                              | function  | `lib/tokens.ts`         | -                                                                                                                                                                                                                                                                                                                         |\n| [`CatalogueIndexRow`](#catalogueindexrow)             | interface | `lib/catalogue.ts`      | One component as the light registry index publishes it, flattened to the fields a decision to install actually turns on.                                                                                                                                                                                                  |\n| `CATEGORY_GATED_SECTIONS`                             | const     | `lib/status.ts`         | Sections whose presence depends on the component's category. Clinical meaning is required on a `health-*` component and forbidden elsewhere, because a component outside the health categories asserts nothing clinical.                                                                                                  |\n| `CHROMA_ENVELOPE`                                     | const     | `lib/color/derive.ts`   | Chroma as a fraction of the seed's, per step. Mirrors `chromaEnvelope` in tokens/color.json.                                                                                                                                                                                                                              |\n| `CHROMA_STEP`                                         | const     | `lib/preset.ts`         | The quantisation of chroma: 0.005 per step, so 63 steps reach 0.315.                                                                                                                                                                                                                                                      |\n| `clampToGamut`                                        | function  | `lib/color/oklch.ts`    | Bring a colour into gamut by reducing chroma only.                                                                                                                                                                                                                                                                        |\n| `CLINICAL_STATUS_META`                                | const     | `lib/status.ts`         | -                                                                                                                                                                                                                                                                                                                         |\n| `CLINICAL_STATUSES`                                   | const     | `lib/status.ts`         | -                                                                                                                                                                                                                                                                                                                         |\n| [`ClinicalStatus`](#clinicalstatus)                   | type      | `lib/status.ts`         | What a reading means and what, if anything, to do about it.                                                                                                                                                                                                                                                               |\n| [`ClinicalStatusMeta`](#clinicalstatusmeta)           | interface | `lib/status.ts`         | Everything a clinical status carries besides its colour. The word, the example sentence, who may assign it, its icon and its place in the order.                                                                                                                                                                          |\n| [`ClinicalStatusOrUnknown`](#clinicalstatusorunknown) | type      | `lib/status.ts`         | The four clinical statuses plus `unknown`. Unknown is the absence of an assertion rather than a fifth level of urgency.                                                                                                                                                                                                   |\n| `cn`                                                  | function  | `lib/utils.ts`          | Join and de-duplicate class names, resolving Tailwind conflicts last-wins.                                                                                                                                                                                                                                                |\n| `COLLAPSE_THRESHOLD`                                  | const     | `lib/color/cvd.ts`      | The minimum Lc at which two swatches shown side by side are still telling two different colours apart.                                                                                                                                                                                                                    |\n| [`ColorInput`](#colorinput)                           | type      | `lib/color/apca.ts`     | Anything the contrast functions accept: an sRGB triple, an OKLCH object, or a CSS colour string (`#0b6bcb`, `oklch(0.62 0.17 15)`, `rgb(11 107 203)`).                                                                                                                                                                    |\n| `COMPONENT_OPTIONAL_SECTIONS`                         | const     | `lib/status.ts`         | Sections a component page may leave out. None: every section in the outline has something true to say on every component, and the one conditional section, Clinical meaning, is gated by category below rather than optional.                                                                                             |\n| `COMPONENT_SECTIONS_BY_STATUS`                        | const     | `lib/status.ts`         | The outline by release phase. A `planned` page has nothing to install or show, so it carries the specification instead: what it is for, what it means clinically, the proposed API and the accessibility contract. No page is `planned` today; the outline stays so that adding one is not a redesign.                    |\n| `componentPath`                                       | function  | `lib/routes.ts`         | A component specification page, by catalogue id.                                                                                                                                                                                                                                                                          |\n| `componentRequiredSections`                           | function  | `lib/status.ts`         | The sections a component page must carry: its outline minus the optional ones.                                                                                                                                                                                                                                            |\n| `componentSections`                                   | function  | `lib/status.ts`         | The outline for one component page, with the category gate applied.                                                                                                                                                                                                                                                       |\n| `compositeOver`                                       | function  | `lib/color/oklch.ts`    | Composite a translucent `foreground` at `alpha` over an opaque `backdrop`, source-over, and return the opaque colour a reader actually sees.                                                                                                                                                                              |\n| `CONTRAST_USE_LABELS`                                 | const     | `lib/color/apca.ts`     | -                                                                                                                                                                                                                                                                                                                         |\n| [`ContrastCheck`](#contrastcheck)                     | interface | `lib/color/derive.ts`   | One measured pair from a derived theme, carrying both the APCA Lc and the WCAG ratio, the use that fixes the floor, and whether it passed.                                                                                                                                                                                |\n| `contrastRatio`                                       | function  | `lib/color/wcag.ts`     | The contrast ratio, from 1 (identical) to 21 (black on white).                                                                                                                                                                                                                                                            |\n| `contrastRatioOklch`                                  | function  | `lib/color/wcag.ts`     | -                                                                                                                                                                                                                                                                                                                         |\n| [`ContrastUse`](#contrastuse)                         | type      | `lib/color/apca.ts`     | What a pair is being used for. Determines which floor applies.                                                                                                                                                                                                                                                            |\n| `convertUnit`                                         | function  | `lib/opsinjs.ts`        | One value in another unit, or `undefined` when this system does not own the factor.                                                                                                                                                                                                                                       |\n| `CORNER_SHAPE_VALUES`                                 | const     | `lib/preset.ts`         | -                                                                                                                                                                                                                                                                                                                         |\n| `CVD_LABELS`                                          | const     | `lib/color/cvd.ts`      | -                                                                                                                                                                                                                                                                                                                         |\n| `CVD_TYPES`                                           | const     | `lib/color/cvd.ts`      | -                                                                                                                                                                                                                                                                                                                         |\n| [`CvdCollision`](#cvdcollision)                       | interface | `lib/color/cvd.ts`      | Two colours that stop being distinguishable under one kind of colour vision deficiency, and the Lc left between them once simulated.                                                                                                                                                                                      |\n| [`CvdType`](#cvdtype)                                 | type      | `lib/color/cvd.ts`      | The three dichromacies, plus the achromatic check every specimen must also survive.                                                                                                                                                                                                                                       |\n| [`DataState`](#datastate)                             | type      | `lib/opsinjs.ts`        | The state a data surface is in, named once so the surfaces converge on one vocabulary, though no component accepts it yet.                                                                                                                                                                                                |\n| [`DecodeError`](#decodeerror)                         | type      | `lib/preset.ts`         | Why a preset code could not be read. The five reasons are kept distinct so that the sentence shown to a person can be a specific one.                                                                                                                                                                                     |\n| `decodePreset`                                        | function  | `lib/preset.ts`         | Decode a preset code.                                                                                                                                                                                                                                                                                                     |\n| [`DecodeResult`](#decoderesult)                       | interface | `lib/preset.ts`         | The outcome of reading a preset code. Either the preset and its version, or an error and a sentence a person can act on.                                                                                                                                                                                                  |\n| `decodeTransfer`                                      | function  | `lib/color/oklch.ts`    | sRGB gamma-encoded channel → light-linear. Also used for Display-P3, which shares sRGB's transfer curve.                                                                                                                                                                                                                  |\n| `DEFAULT_BASE`                                        | const     | `lib/registry.ts`       | -                                                                                                                                                                                                                                                                                                                         |\n| `DEFAULT_BASE`                                        | const     | `lib/routes.ts`         | -                                                                                                                                                                                                                                                                                                                         |\n| `DEFAULT_PRESET`                                      | const     | `lib/preset.ts`         | -                                                                                                                                                                                                                                                                                                                         |\n| `DEFAULT_STYLE`                                       | const     | `lib/registry.ts`       | -                                                                                                                                                                                                                                                                                                                         |\n| `DEFAULT_STYLE`                                       | const     | `lib/routes.ts`         | -                                                                                                                                                                                                                                                                                                                         |\n| `DENSITY_VALUES`                                      | const     | `lib/preset.ts`         | -                                                                                                                                                                                                                                                                                                                         |\n| `deprecatedTokens`                                    | function  | `lib/tokens.ts`         | -                                                                                                                                                                                                                                                                                                                         |\n| [`DerivedTheme`](#derivedtheme)                       | interface | `lib/color/derive.ts`   | Everything derivation produces from one brand colour. Both ramps, every role in light and dark, the contrast checks, the warnings, and whether it is sound.                                                                                                                                                               |\n| [`DeriveOptions`](#deriveoptions)                     | interface | `lib/color/derive.ts`   | The knobs on theme derivation. Every one of them has a default, so a brand colour on its own is already a complete input.                                                                                                                                                                                                 |\n| `deriveRamp`                                          | function  | `lib/color/derive.ts`   | Build one ramp from a seed, clamping to sRGB and recording the P3 enhancement.                                                                                                                                                                                                                                            |\n| `deriveTheme`                                         | function  | `lib/color/derive.ts`   | Derive a complete, contrast-validated theme from one brand colour.                                                                                                                                                                                                                                                        |\n| [`DeriveWarning`](#derivewarning)                     | interface | `lib/color/derive.ts`   | One thing the derivation has to say about a theme, as a level, a stable code and a message.                                                                                                                                                                                                                               |\n| [`Detent`](#detent)                                   | type      | `lib/opsinjs.ts`        | How far a sheet is open.                                                                                                                                                                                                                                                                                                  |\n| `displayP3ToOklch`                                    | function  | `lib/color/oklch.ts`    | Gamma-encoded Display-P3, 0 to 1 per channel → OKLCH.                                                                                                                                                                                                                                                                     |\n| `DOCS_BASE`                                           | const     | `lib/routes.ts`         | The docs base segment. Everything else derives from it.                                                                                                                                                                                                                                                                   |\n| `docsMarkdownPath`                                    | function  | `lib/routes.ts`         | The same page as processed markdown: `/docs/components/range-bar.md`.                                                                                                                                                                                                                                                     |\n| [`DocsNav`](#docsnav)                                 | interface | `lib/docs-nav.ts`       | -                                                                                                                                                                                                                                                                                                                         |\n| `docsPath`                                            | function  | `lib/routes.ts`         | The URL of a docs page from its slug segments. `docsPath()` is the docs index. This is the function a locale segment would be inserted into.                                                                                                                                                                              |\n| `doctrinePath`                                        | function  | `lib/routes.ts`         | A doctrine page reference as written in frontmatter, such as `two-colour-axes`, or `foundations/colour/contrast-and-apca` when it is not in Health.                                                                                                                                                                       |\n| `editUrl`                                             | function  | `lib/routes.ts`         | \"Edit this page\" on GitHub, from a source file path relative to the content root.                                                                                                                                                                                                                                         |\n| `encodePreset`                                        | function  | `lib/preset.ts`         | Encode a theme as a preset code.                                                                                                                                                                                                                                                                                          |\n| `encodeTransfer`                                      | function  | `lib/color/oklch.ts`    | Light-linear channel → gamma-encoded.                                                                                                                                                                                                                                                                                     |\n| `EXAMPLE_SOURCE`                                      | const     | `lib/opsinjs.ts`        | The only citation an opsinjs example, demo or preview may carry.                                                                                                                                                                                                                                                          |\n| `explainUnresolved`                                   | function  | `lib/registry.ts`       | Explain an empty lookup.                                                                                                                                                                                                                                                                                                  |\n| `findAliasProblems`                                   | function  | `lib/catalogue.ts`      | The uniqueness check, as a function rather than as a comment.                                                                                                                                                                                                                                                             |\n| `findByAlias`                                         | function  | `lib/catalogue.ts`      | -                                                                                                                                                                                                                                                                                                                         |\n| `findCollisions`                                      | function  | `lib/color/cvd.ts`      | Check that a set of named colours stays mutually distinguishable under every simulation. This is the function that turns \"status must survive grayscale\" from doctrine into a build step.                                                                                                                                 |\n| `findUnit`                                            | function  | `lib/opsinjs.ts`        | The unit a symbol names, or `undefined` when this system has never heard of it.                                                                                                                                                                                                                                           |\n| `fit`                                                 | function  | `lib/color/derive.ts`   | Fit an arbitrary colour into the shipped gamut without moving its hue or lightness.                                                                                                                                                                                                                                       |\n| `FLOOR_VALUES`                                        | const     | `lib/preset.ts`         | Which APCA floor the theme is validated against. `standard` is the published one.                                                                                                                                                                                                                                         |\n| `FORMAT_VERSION`                                      | const     | `lib/preset.ts`         | Bump this, and add a decode branch, whenever a field changes shape.                                                                                                                                                                                                                                                       |\n| `formatDisplayP3`                                     | function  | `lib/color/oklch.ts`    | `color(display-p3 0.9 0.2 0.3)`. Channels are clamped, because this is an output format.                                                                                                                                                                                                                                  |\n| `formatHex`                                           | function  | `lib/color/oklch.ts`    | `#rrggbb`, clamped into sRGB.                                                                                                                                                                                                                                                                                             |\n| `formatOklch`                                         | function  | `lib/color/oklch.ts`    | `oklch(0.622 0.17 15)`, or with an alpha, `oklch(0.622 0.17 15 / 0.5)`.                                                                                                                                                                                                                                                   |\n| `formatRatio`                                         | function  | `lib/color/wcag.ts`     | Ratios are conventionally quoted to one decimal place and rounded DOWN, so a published figure is never better than the measurement.                                                                                                                                                                                       |\n| `formatToken`                                         | function  | `lib/tokens.ts`         | Render a token in one of the copyable formats.                                                                                                                                                                                                                                                                            |\n| `foundationsPath`                                     | function  | `lib/routes.ts`         | -                                                                                                                                                                                                                                                                                                                         |\n| [`Gamut`](#gamut)                                     | type      | `lib/color/oklch.ts`    | The colour spaces this module can express a colour in.                                                                                                                                                                                                                                                                    |\n| `GAMUT_EPSILON`                                       | const     | `lib/color/oklch.ts`    | The tolerance a channel may exceed 0 or 1 by and still count as in gamut. Half a unit at 8-bit precision: a value that rounds to a representable channel is in gamut for every purpose this system has.                                                                                                                   |\n| `GAMUT_VALUES`                                        | const     | `lib/preset.ts`         | -                                                                                                                                                                                                                                                                                                                         |\n| [`GeneratedBannedWord`](#generatedbannedword)         | interface | `lib/opsinjs.ts`        | One banned word: the word a component's copy must not use, what to write in its place, and why the word is barred.                                                                                                                                                                                                        |\n| `getAllPages`                                         | function  | `lib/source.ts`         | Every page in the corpus. The input to the sitemap, llms.txt and the shards.                                                                                                                                                                                                                                              |\n| `getByCategory`                                       | function  | `lib/catalogue.ts`      | -                                                                                                                                                                                                                                                                                                                         |\n| `getByStatus`                                         | function  | `lib/catalogue.ts`      | -                                                                                                                                                                                                                                                                                                                         |\n| `getCatalogue`                                        | function  | `lib/catalogue.ts`      | Every row.                                                                                                                                                                                                                                                                                                                |\n| `getDocsNav`                                          | function  | `lib/docs-nav.ts`       | -                                                                                                                                                                                                                                                                                                                         |\n| `getEntry`                                            | function  | `lib/catalogue.ts`      | -                                                                                                                                                                                                                                                                                                                         |\n| `getPage`                                             | function  | `lib/source.ts`         | One page by its slug segments, or undefined.                                                                                                                                                                                                                                                                              |\n| `getPagesInSection`                                   | function  | `lib/source.ts`         | Pages under one top-level section, in tree order.                                                                                                                                                                                                                                                                         |\n| `getPageTree`                                         | function  | `lib/source.ts`         | The page tree the docs layout renders.                                                                                                                                                                                                                                                                                    |\n| `getRegistryEntry`                                    | function  | `lib/registry.ts`       | Resolve one entry, or null.                                                                                                                                                                                                                                                                                               |\n| `getShipped`                                          | function  | `lib/catalogue.ts`      | Every catalogue row. Not a claim about code. Read `implemented` in `/r/index.json`, or `toIndexRow`'s `isBuilt` argument, for that.                                                                                                                                                                                       |\n| `getToken`                                            | function  | `lib/tokens.ts`         | -                                                                                                                                                                                                                                                                                                                         |\n| `getTokens`                                           | function  | `lib/tokens.ts`         | -                                                                                                                                                                                                                                                                                                                         |\n| `grouped`                                             | function  | `lib/tokens.ts`         | Tokens grouped for a table: namespace → group → tokens, in emit order.                                                                                                                                                                                                                                                    |\n| `groupedByCategory`                                   | function  | `lib/catalogue.ts`      | Every category that has at least one row, in the declared order, with its rows.                                                                                                                                                                                                                                           |\n| `hasComponentPage`                                    | function  | `lib/catalogue.ts`      | True when `/docs/components/\\<id\\>` resolves to a page.                                                                                                                                                                                                                                                                   |\n| `HEALTH_CATEGORIES`                                   | const     | `lib/status.ts`         | -                                                                                                                                                                                                                                                                                                                         |\n| `HEALTH_CATEGORY_LABELS`                              | const     | `lib/status.ts`         | -                                                                                                                                                                                                                                                                                                                         |\n| [`HealthCategory`](#healthcategory)                   | type      | `lib/status.ts`         | What a reading is ABOUT. Identity, never verdict.                                                                                                                                                                                                                                                                         |\n| `healthPath`                                          | function  | `lib/routes.ts`         | A health doctrine page, by the page id that `governedBy` and `implements` use.                                                                                                                                                                                                                                            |\n| `inGamut`                                             | function  | `lib/color/oklch.ts`    | -                                                                                                                                                                                                                                                                                                                         |\n| `isBuilt`                                             | function  | `lib/registry.ts`       | True only when a base component for this name is on disk, which a catalogue row alone is not. A specified-but-unbuilt id answers false, and so does a built id asked for at a base that does not carry it.                                                                                                                |\n| `isClinicalStatus`                                    | function  | `lib/status.ts`         | -                                                                                                                                                                                                                                                                                                                         |\n| `isDevelopment`                                       | function  | `lib/opsinjs.ts`        | True in development, and false wherever that cannot be established.                                                                                                                                                                                                                                                       |\n| `isHealthCategory`                                    | function  | `lib/catalogue.ts`      | True for the four `health-*` categories, which carry the extra clinical obligations.                                                                                                                                                                                                                                      |\n| `isHealthCategory`                                    | function  | `lib/status.ts`         | -                                                                                                                                                                                                                                                                                                                         |\n| `isKind`                                              | function  | `lib/status.ts`         | -                                                                                                                                                                                                                                                                                                                         |\n| `isKnownId`                                           | function  | `lib/catalogue.ts`      | Does this id exist at all, under any status?                                                                                                                                                                                                                                                                              |\n| `isNotImplemented`                                    | function  | `lib/status.ts`         | True when a page at this status must carry a not-implemented marker.                                                                                                                                                                                                                                                      |\n| `isResolvable`                                        | function  | `lib/registry.ts`       | True when the id exists in the catalogue, whatever its status. Used to decide 404 from \"no\".                                                                                                                                                                                                                              |\n| `isStatus`                                            | function  | `lib/status.ts`         | -                                                                                                                                                                                                                                                                                                                         |\n| `issueUrl`                                            | function  | `lib/routes.ts`         | A prefilled docs issue. Used by `\\<Feedback\\>` when the feedback endpoint is unavailable.                                                                                                                                                                                                                                 |\n| `joinPath`                                            | function  | `lib/routes.ts`         | Join path segments into a root-relative path, dropping empties and stray slashes.                                                                                                                                                                                                                                         |\n| [`Kind`](#kind)                                       | type      | `lib/status.ts`         | A page's kind, one per sidebar section. Only `component` fixes the page's headings; every other kind names its own, as a page on blueprintjs.com does.                                                                                                                                                                    |\n| `KINDS`                                               | const     | `lib/status.ts`         | -                                                                                                                                                                                                                                                                                                                         |\n| `LEGACY_ROOT_SEGMENTS`                                | const     | `lib/redirects.ts`      | The first path segment of every documentation URL the site served from the root, between 2026-09-20 and 2026-10-12, when `DOCS_BASE` was empty. `proxy.ts` sends a path that starts with one of these to the same path under `/docs` (ADR 0027), so a bookmark such as `/components/button` still lands.                  |\n| `LIGHTNESS_STEP`                                      | const     | `lib/preset.ts`         | The quantisation of lightness: 1% per step.                                                                                                                                                                                                                                                                               |\n| `linearP3ToLinearSrgb`                                | function  | `lib/color/oklch.ts`    | Light-linear Display-P3 → light-linear sRGB, through XYZ (D65).                                                                                                                                                                                                                                                           |\n| `linearSrgbToLinearP3`                                | function  | `lib/color/oklch.ts`    | Light-linear sRGB → light-linear Display-P3, through XYZ (D65).                                                                                                                                                                                                                                                           |\n| `linearSrgbToOklab`                                   | function  | `lib/color/oklch.ts`    | Light-linear sRGB → OKLab. Ottosson's forward matrices.                                                                                                                                                                                                                                                                   |\n| `linearToSrgb`                                        | function  | `lib/color/oklch.ts`    | -                                                                                                                                                                                                                                                                                                                         |\n| `listBases`                                           | function  | `lib/registry.ts`       | -                                                                                                                                                                                                                                                                                                                         |\n| `listByKind`                                          | function  | `lib/registry.ts`       | Every entry of a kind, for the examples gallery and the screens index.                                                                                                                                                                                                                                                    |\n| `listStyles`                                          | function  | `lib/registry.ts`       | -                                                                                                                                                                                                                                                                                                                         |\n| [`MaterialRung`](#materialrung)                       | type      | `lib/opsinjs.ts`        | A rung of the material ladder, meaning how a surface sits above what is behind it.                                                                                                                                                                                                                                        |\n| `maxChroma`                                           | function  | `lib/color/oklch.ts`    | The largest chroma that is still inside `gamut` at this lightness and hue.                                                                                                                                                                                                                                                |\n| `minimumFontSize`                                     | function  | `lib/color/apca.ts`     | The smallest font size, in px, at which this Lc is usable at the given weight, from a coarse reading of the APCA font-size guidance rather than from the full lookup table.                                                                                                                                               |\n| `mixOklch`                                            | function  | `lib/color/oklch.ts`    | Mix two OKLCH colours. Hue takes the shorter way round the circle, which is what CSS `color-mix` does and what anyone reading the result expects.                                                                                                                                                                         |\n| `MODE_VALUES`                                         | const     | `lib/preset.ts`         | The colour mode a theme opens in. `system` follows the reader's own setting.                                                                                                                                                                                                                                              |\n| [`NavGroup`](#navgroup)                               | interface | `lib/docs-nav.ts`       | -                                                                                                                                                                                                                                                                                                                         |\n| [`NavHeading`](#navheading)                           | interface | `lib/docs-nav.ts`       | -                                                                                                                                                                                                                                                                                                                         |\n| [`NavLink`](#navlink)                                 | interface | `lib/docs-nav.ts`       | -                                                                                                                                                                                                                                                                                                                         |\n| [`NavSection`](#navsection)                           | interface | `lib/docs-nav.ts`       | -                                                                                                                                                                                                                                                                                                                         |\n| `NEUTRAL_CHROMA_VALUES`                               | const     | `lib/preset.ts`         | Chroma of the neutral ramp. Index 0 is a dead grey; the default is index 2.                                                                                                                                                                                                                                               |\n| `ogUrl`                                               | function  | `lib/routes.ts`         | The OG image service. One endpoint for the whole site. There is no per-route opengraph-image.                                                                                                                                                                                                                             |\n| [`Oklab`](#oklab)                                     | interface | `lib/color/oklch.ts`    | A colour in OKLab.                                                                                                                                                                                                                                                                                                        |\n| `oklabToLinearSrgb`                                   | function  | `lib/color/oklch.ts`    | OKLab → light-linear sRGB. Ottosson's inverse matrices.                                                                                                                                                                                                                                                                   |\n| `oklabToOklch`                                        | function  | `lib/color/oklch.ts`    | -                                                                                                                                                                                                                                                                                                                         |\n| [`Oklch`](#oklch)                                     | interface | `lib/color/oklch.ts`    | A colour in OKLCH. `l` 0 to 1, `c` unbounded, `h` in degrees.                                                                                                                                                                                                                                                             |\n| `oklchToDisplayP3`                                    | function  | `lib/color/oklch.ts`    | OKLCH → gamma-encoded Display-P3, 0 to 1 per channel. Not clamped.                                                                                                                                                                                                                                                        |\n| `oklchToOklab`                                        | function  | `lib/color/oklch.ts`    | -                                                                                                                                                                                                                                                                                                                         |\n| `oklchToRgb255`                                       | function  | `lib/color/oklch.ts`    | OKLCH → 0 to 255 sRGB integers, clamped. The input for both contrast models.                                                                                                                                                                                                                                              |\n| `oklchToSrgb`                                         | function  | `lib/color/oklch.ts`    | OKLCH → gamma-encoded sRGB, 0 to 1 per channel. Not clamped.                                                                                                                                                                                                                                                              |\n| `OPSIN_ERRORS`                                        | const     | `lib/opsinjs.ts`        | The table `warnOnce()` reads. Generated from `tokens/errors.json`.                                                                                                                                                                                                                                                        |\n| [`OpsinError`](#opsinerror)                           | interface | `lib/opsinjs.ts`        | One warning code: what it is called, how severe it is, and the page that prevents it.                                                                                                                                                                                                                                     |\n| [`OpsinErrorCode`](#opsinerrorcode)                   | type      | `lib/opsinjs.ts`        | Every warning code opsinjs can emit.                                                                                                                                                                                                                                                                                      |\n| [`OpsinErrorParams`](#opsinerrorparams)               | type      | `lib/opsinjs.ts`        | The values a message template asks for, keyed by placeholder name.                                                                                                                                                                                                                                                        |\n| [`OpsinErrorSeverity`](#opsinerrorseverity)           | type      | `lib/opsinjs.ts`        | How severe a warning is.                                                                                                                                                                                                                                                                                                  |\n| `ORPHAN_ALLOWLIST`                                    | const     | `lib/routes.ts`         | Routes that exist but are not reachable from the top nav or the sidebar, and are allowed not to be.                                                                                                                                                                                                                       |\n| `OUTLINE_IS_EXACT`                                    | const     | `lib/status.ts`         | No kind other than `component` has an exact outline.                                                                                                                                                                                                                                                                      |\n| `P3_CHROMA_GAIN`                                      | const     | `lib/color/derive.ts`   | How much more chroma Display-P3 is allowed to spend than sRGB at the same step.                                                                                                                                                                                                                                           |\n| `parseColor`                                          | function  | `lib/color/oklch.ts`    | Parse the colour syntaxes a person is likely to paste into the theme playground: `oklch(...)` with or without percentages, `#rrggbb`, and `rgb(r g b)` or `rgb(r, g, b)`. Anything else returns null rather than guessing. A theme derived from a misparsed brand colour is worse than a refusal to derive one.           |\n| `parseHex`                                            | function  | `lib/color/oklch.ts`    | `#rgb`, `#rrggbb` or `#rrggbbaa` → sRGB 0 to 1. Returns null on anything else.                                                                                                                                                                                                                                            |\n| `passesApca`                                          | function  | `lib/color/apca.ts`     | -                                                                                                                                                                                                                                                                                                                         |\n| [`Preset`](#preset)                                   | interface | `lib/preset.ts`         | A theme as a person describes it. What `encodePreset` takes and `decodePreset` returns.                                                                                                                                                                                                                                   |\n| `PRESET_PREFIX`                                       | const     | `lib/preset.ts`         | -                                                                                                                                                                                                                                                                                                                         |\n| `presetBrandColor`                                    | function  | `lib/preset.ts`         | The brand colour a preset describes, as an `oklch()` string the colour engine can parse.                                                                                                                                                                                                                                  |\n| `RADIUS_VALUES`                                       | const     | `lib/preset.ts`         | `--opsin-radius-base` in px. Index 3 (14px) is the product default.                                                                                                                                                                                                                                                       |\n| [`Ramp`](#ramp)                                       | type      | `lib/color/derive.ts`   | One complete lightness ramp, as a value per step. The chromatic ramp and the neutral ramp of a derived theme are both this shape.                                                                                                                                                                                         |\n| `RAMP_LIGHTNESS`                                      | const     | `lib/color/derive.ts`   | -                                                                                                                                                                                                                                                                                                                         |\n| `RAMP_STEPS`                                          | const     | `lib/color/derive.ts`   | The ramp steps, and the lightness of each. Mirrors `ladder` in tokens/color.json.                                                                                                                                                                                                                                         |\n| [`RampStep`](#rampstep)                               | type      | `lib/color/derive.ts`   | One rung of the lightness ladder, from 50 at the lightest to 950 at the darkest. The rungs are fixed, so two themes are comparable step by step.                                                                                                                                                                          |\n| [`RampStepValue`](#rampstepvalue)                     | interface | `lib/color/derive.ts`   | One rung of a ramp, as the sRGB value that ships, the wide-gamut value where P3 has headroom, and whether sRGB had to clamp the chroma away.                                                                                                                                                                              |\n| `referencePath`                                       | function  | `lib/routes.ts`         | -                                                                                                                                                                                                                                                                                                                         |\n| [`ReferenceRange`](#referencerange)                   | interface | `lib/opsinjs.ts`        | The interval a reading is being compared against, and who says so.                                                                                                                                                                                                                                                        |\n| `REFUSED_CONVERSIONS`                                 | const     | `lib/opsinjs.ts`        | Conversions this system refuses to publish, and why. Generated from `tokens/units.json`.                                                                                                                                                                                                                                  |\n| [`RefusedConversion`](#refusedconversion)             | interface | `lib/opsinjs.ts`        | A pair people expect to be arithmetic and is not, with the reason.                                                                                                                                                                                                                                                        |\n| `registryInstallUrl`                                  | function  | `lib/routes.ts`         | What a consumer types to install an item. Rendered by `\\<ComponentInstall\\>`.                                                                                                                                                                                                                                             |\n| [`RegistryLookup`](#registrylookup)                   | type      | `lib/registry.ts`       | Both call shapes are supported on purpose.                                                                                                                                                                                                                                                                                |\n| `registryMeta`                                        | function  | `lib/registry.ts`       | Provenance for the registry surfaces: when it was generated and from what. `generatedAt: null` means the placeholder is still in place and `pnpm run generate` has not run. The registry pages say that out loud rather than rendering an empty table.                                                                    |\n| [`RegistryQuery`](#registryquery)                     | interface | `lib/registry.ts`       | A request for one registry item, by id and optionally by base, style and kind. Anything left out falls back to the default.                                                                                                                                                                                               |\n| `registryRoutes`                                      | const     | `lib/routes.ts`         | -                                                                                                                                                                                                                                                                                                                         |\n| `relativeLuminance`                                   | function  | `lib/color/wcag.ts`     | WCAG 2.2 relative luminance, 0 for black and 1 for white.                                                                                                                                                                                                                                                                 |\n| `RETIRED_PAGES`                                       | const     | `lib/redirects.ts`      | Every documentation URL that stopped being a page when the site took the clawscale shape (ADR 0026), and the page that absorbed it. `proxy.ts` answers each with a permanent redirect, and the `.md` twin of each with a redirect to the twin of its target, so no bookmark, search result or agent cache lands on a 404. |\n| `REVIEW_FLOOR_NOTICE`                                 | const     | `lib/status.ts`         | THE REVIEW FLOOR, AS ONE STRING.                                                                                                                                                                                                                                                                                          |\n| [`Rgb`](#rgb)                                         | interface | `lib/color/oklch.ts`    | Red, green and blue, each 0 to 1, in whichever space the function says.                                                                                                                                                                                                                                                   |\n| [`Rgb255`](#rgb255)                                   | type      | `lib/color/apca.ts`     | A colour as 0 to 255 sRGB integers, which is what APCA is defined over.                                                                                                                                                                                                                                                   |\n| [`RoleName`](#rolename)                               | type      | `lib/color/derive.ts`   | The roles a derived theme guarantees. Components consume these and never a step.                                                                                                                                                                                                                                          |\n| [`RolePair`](#rolepair)                               | interface | `lib/color/derive.ts`   | One semantic role in both colour modes. Roles are derived as a pair, because a role that exists only in light mode is a role that breaks in dark.                                                                                                                                                                         |\n| [`RoleValue`](#rolevalue)                             | interface | `lib/color/derive.ts`   | What a semantic role resolves to in one colour mode. The ramp step it came from, the OKLCH value, and the CSS it is written as.                                                                                                                                                                                           |\n| `routes`                                              | const     | `lib/routes.ts`         | -                                                                                                                                                                                                                                                                                                                         |\n| `screenLuminance`                                     | function  | `lib/color/apca.ts`     | Screen luminance Y for an sRGB triple, using APCA's own simple-exponent transfer rather than the piecewise sRGB curve. This is deliberate and is one of the places APCA and WCAG genuinely differ: APCA models the display, not the encoding.                                                                             |\n| `searchCatalogue`                                     | function  | `lib/catalogue.ts`      | The filter behind `\\<StatusMatrix\\>`: matches an id, a name, the description or any alias. Substring matching, because the reader typing \"range\" wants both RangeBar and the reference-range guidance and has no reason to know which word the system chose.                                                              |\n| `searchTokens`                                        | function  | `lib/tokens.ts`         | Substring match over name, description and value. The `/tokens` browser's filter.                                                                                                                                                                                                                                         |\n| `SECTION_OUTLINES`                                    | const     | `lib/status.ts`         | The H2s a page must have, by `kind`, for every kind but `component`.                                                                                                                                                                                                                                                      |\n| `SHIPPED_PRESETS`                                     | const     | `lib/preset.ts`         | The shipped presets. Names, not codes, are what the documentation refers to; the code is what a reader copies. `build-tokens.mts` materialises each into `/r/themes/\\<code\\>.json`.                                                                                                                                       |\n| [`Showcase`](#showcase)                               | interface | `lib/showcases.ts`      | The screens on `/showcase`: whole screens assembled only from opsinjs components, each one rendered from a file under `registry/screens/`.                                                                                                                                                                                |\n| `showcases`                                           | const     | `lib/showcases.ts`      | The showcase grid, in the order it renders.                                                                                                                                                                                                                                                                               |\n| `simulate`                                            | function  | `lib/color/cvd.ts`      | Simulate a dichromacy. `severity` 0 returns the input unchanged and 1 returns full dichromacy; values between interpolate in linear light.                                                                                                                                                                                |\n| `simulateOklch`                                       | function  | `lib/color/cvd.ts`      | -                                                                                                                                                                                                                                                                                                                         |\n| `simulateRgb255`                                      | function  | `lib/color/cvd.ts`      | -                                                                                                                                                                                                                                                                                                                         |\n| `site`                                                | const     | `lib/routes.ts`         | -                                                                                                                                                                                                                                                                                                                         |\n| `source`                                              | const     | `lib/source.ts`         | -                                                                                                                                                                                                                                                                                                                         |\n| `spokenUnit`                                          | function  | `lib/opsinjs.ts`        | How a screen reader should say this unit for this count.                                                                                                                                                                                                                                                                  |\n| `srgbToLinear`                                        | function  | `lib/color/oklch.ts`    | -                                                                                                                                                                                                                                                                                                                         |\n| `srgbToOklch`                                         | function  | `lib/color/oklch.ts`    | Gamma-encoded sRGB, 0 to 1 per channel → OKLCH.                                                                                                                                                                                                                                                                           |\n| [`Status`](#status)                                   | type      | `lib/status.ts`         | The release phase of a component page or a catalogue entry.                                                                                                                                                                                                                                                               |\n| `STATUS_META`                                         | const     | `lib/status.ts`         | -                                                                                                                                                                                                                                                                                                                         |\n| `STATUS_ORDER`                                        | const     | `lib/status.ts`         | Statuses in display order.                                                                                                                                                                                                                                                                                                |\n| `statusCounts`                                        | function  | `lib/catalogue.ts`      | Counts per status, in display order. The input to `\\<SectionProgress\\>`.                                                                                                                                                                                                                                                  |\n| `STATUSES`                                            | const     | `lib/status.ts`         | A RELEASE PHASE IS NEVER PAINTED, AND THERE IS NOW NOTHING HERE TO PAINT IT WITH.                                                                                                                                                                                                                                         |\n| [`StatusMeta`](#statusmeta)                           | interface | `lib/status.ts`         | What a release phase shows on a badge. A label and one sentence a reader can act on, which is also the chip's title and its accessible name.                                                                                                                                                                              |\n| `textOf`                                              | function  | `lib/docs-nav.ts`       | Plain text of a page-tree name or a heading title, which may be markup.                                                                                                                                                                                                                                                   |\n| `themeToCssVariables`                                 | function  | `lib/color/derive.ts`   | Every custom property a derived theme emits, ready for a stylesheet or a copy button.                                                                                                                                                                                                                                     |\n| `toGrayscale`                                         | function  | `lib/color/cvd.ts`      | Grayscale by relative luminance rather than by an average of the channels.                                                                                                                                                                                                                                                |\n| `toIndexRow`                                          | function  | `lib/catalogue.ts`      | One row of `/r/index.json` and of the generated catalogue reference page.                                                                                                                                                                                                                                                 |\n| `TOKEN_FORMAT_LABELS`                                 | const     | `lib/tokens.ts`         | -                                                                                                                                                                                                                                                                                                                         |\n| `TOKEN_NAMESPACE_LABELS`                              | const     | `lib/tokens.ts`         | -                                                                                                                                                                                                                                                                                                                         |\n| `TOKEN_NAMESPACES`                                    | const     | `lib/tokens.ts`         | -                                                                                                                                                                                                                                                                                                                         |\n| `TOKEN_TIER_DESCRIPTIONS`                             | const     | `lib/tokens.ts`         | -                                                                                                                                                                                                                                                                                                                         |\n| `TOKEN_TIER_LABELS`                                   | const     | `lib/tokens.ts`         | -                                                                                                                                                                                                                                                                                                                         |\n| [`TokenFormat`](#tokenformat)                         | type      | `lib/tokens.ts`         | The formats the `/tokens` and `/colors` browsers can copy a value in.                                                                                                                                                                                                                                                     |\n| `tokenMeta`                                           | function  | `lib/tokens.ts`         | -                                                                                                                                                                                                                                                                                                                         |\n| `tokensAreGenerated`                                  | function  | `lib/tokens.ts`         | Whether the generated layer has actually been produced.                                                                                                                                                                                                                                                                   |\n| `tokensUsedBy`                                        | function  | `lib/tokens.ts`         | Every token one component consumes. The query behind section 17 of a component page, and the reason `usedBy` is populated at generation time rather than inferred at render time.                                                                                                                                         |\n| `toRgb255`                                            | function  | `lib/color/oklch.ts`    | 0 to 1 sRGB → 0 to 255 integers, clamped.                                                                                                                                                                                                                                                                                 |\n| `toRgb255Input`                                       | function  | `lib/color/apca.ts`     | Coerce any accepted colour form to an sRGB triple.                                                                                                                                                                                                                                                                        |\n| [`TrendPoint`](#trendpoint)                           | interface | `lib/opsinjs.ts`        | One reading in a series, for the components that draw change over time.                                                                                                                                                                                                                                                   |\n| [`Unit`](#unit)                                       | interface | `lib/opsinjs.ts`        | One unit: what it is called, what a reader sees, and how it is SPOKEN.                                                                                                                                                                                                                                                    |\n| `UNIT_CONVERSIONS`                                    | const     | `lib/opsinjs.ts`        | Every convertible ordered pair, composed by the generator. Never authored by hand.                                                                                                                                                                                                                                        |\n| `unitConversion`                                      | function  | `lib/opsinjs.ts`        | The authored conversion between two symbols, or `undefined` when there is none.                                                                                                                                                                                                                                           |\n| [`UnitConversion`](#unitconversion)                   | interface | `lib/opsinjs.ts`        | An exact conversion between two units of the same kind.                                                                                                                                                                                                                                                                   |\n| `UNITS`                                               | const     | `lib/opsinjs.ts`        | Every unit this system can speak, sorted by id. Generated from `tokens/units.json`.                                                                                                                                                                                                                                       |\n| `UNITS_BY_SYMBOL`                                     | const     | `lib/opsinjs.ts`        | The lookup `findUnit()` reads, derived from `UNITS` rather than emitted twice.                                                                                                                                                                                                                                            |\n| `unknownImplementsIds`                                | function  | `lib/catalogue.ts`      | Validate a doctrine page's `implements` list. Every entry must be a real catalogue id. This is the check that would have caught `implements: [alert-banner, care-card, toast]` before `toast` was on the roster.                                                                                                          |\n| [`UnknownStatus`](#unknownstatus)                     | type      | `lib/status.ts`         | The absence of an assertion, which covers a reading never taken, a stale reading, or a reading whose reference range the product does not own.                                                                                                                                                                            |\n| [`UnresolvedReason`](#unresolvedreason)               | interface | `lib/registry.ts`       | Why a lookup came back empty. The input to `\\<NotBuiltYet\\>`.                                                                                                                                                                                                                                                             |\n| [`ViewKind`](#viewkind)                               | type      | `lib/routes.ts`         | What a `/view` route can render.                                                                                                                                                                                                                                                                                          |\n| [`ViewParams`](#viewparams)                           | interface | `lib/routes.ts`         | Everything a chrome-less preview URL can carry. Name and kind become path segments, and the rest become query parameters applied before first paint.                                                                                                                                                                      |\n| `viewPath`                                            | function  | `lib/routes.ts`         | `/view/base/base-lyra/component/range-bar?mode=dark&text=200`.                                                                                                                                                                                                                                                            |\n| [`WarningLevel`](#warninglevel)                       | type      | `lib/color/derive.ts`   | How serious a derivation warning is. An `error` makes the theme unsound and stops it shipping, while a `warning` and a `note` are advisory.                                                                                                                                                                               |\n| `warnOnce`                                            | function  | `lib/opsinjs.ts`        | Report a defect in development, once, and never do anything else.                                                                                                                                                                                                                                                         |\n| `wcag`                                                | const     | `lib/color/wcag.ts`     | The short name, matching `apca()`. Identical to `contrastRatio`.                                                                                                                                                                                                                                                          |\n| `WCAG_FLOOR`                                          | const     | `lib/color/wcag.ts`     | The three WCAG 2.2 thresholds this system checks against.                                                                                                                                                                                                                                                                 |\n| [`WcagUse`](#wcaguse)                                 | type      | `lib/color/wcag.ts`     | Which WCAG 2.2 contrast threshold applies. Body text, large text and non- text content each have a different floor.                                                                                                                                                                                                       |\n| `wcagVerdict`                                         | function  | `lib/color/wcag.ts`     | -                                                                                                                                                                                                                                                                                                                         |\n| [`WcagVerdict`](#wcagverdict)                         | interface | `lib/color/wcag.ts`     | The result of one WCAG 2.2 contrast measurement, with the ratio, the floor for that use, and the success criterion it is measured against.                                                                                                                                                                                |\n\n## Declarations [#declarations]\n\n### AliasProblem [#aliasproblem]\n\nOne search synonym that cannot be used, either because two components claim it or because it collides with a component id.\n\nA interface in `lib/catalogue.ts`.\n\n```ts\nexport interface AliasProblem {\n  alias: string\n  reason: \"duplicate\" | \"collides-with-id\"\n  owners: string[]\n}\n```\n\n**Members**\n\n| Member   | Type                                | Required | What it is |\n| -------- | ----------------------------------- | -------- | ---------- |\n| `alias`  | `string`                            | Yes      | -          |\n| `reason` | `\"duplicate\" \\| \"collides-with-id\"` | Yes      | -          |\n| `owners` | `string[]`                          | Yes      | -          |\n\n**Used by** `findAliasProblems`.\n\n### ApcaVerdict [#apcaverdict]\n\nThe result of one APCA measurement, with the signed Lc, its polarity, the floor for that use, and how far above or below the floor it landed.\n\nA interface in `lib/color/apca.ts`.\n\n```ts\nexport interface ApcaVerdict {\n  lc: number\n  magnitude: number\n  polarity: \"dark-on-light\" | \"light-on-dark\" | \"indistinguishable\"\n  use: ContrastUse\n  floor: number\n  passes: boolean\n  headroom: number\n}\n```\n\n**Members**\n\n| Member      | Type                                                        | Required | What it is |\n| ----------- | ----------------------------------------------------------- | -------- | ---------- |\n| `lc`        | `number`                                                    | Yes      | -          |\n| `magnitude` | `number`                                                    | Yes      | -          |\n| `polarity`  | `\"dark-on-light\" \\| \"light-on-dark\" \\| \"indistinguishable\"` | Yes      | -          |\n| `use`       | `ContrastUse`                                               | Yes      | -          |\n| `floor`     | `number`                                                    | Yes      | -          |\n| `passes`    | `boolean`                                                   | Yes      | -          |\n| `headroom`  | `number`                                                    | Yes      | -          |\n\n### AxisConflict [#axisconflict]\n\nA refusal. It is what the system answers when a measurement category and a clinical status are asked to share one surface.\n\nA interface in `lib/status.ts`.\n\n```ts\nexport interface AxisConflict {\n  code: \"OPSIN-0001\"\n  category: HealthCategory\n  status: ClinicalStatus\n  message: string\n  docs: string\n}\n```\n\n**Members**\n\n| Member     | Type             | Required | What it is |\n| ---------- | ---------------- | -------- | ---------- |\n| `code`     | `\"OPSIN-0001\"`   | Yes      | -          |\n| `category` | `HealthCategory` | Yes      | -          |\n| `status`   | `ClinicalStatus` | Yes      | -          |\n| `message`  | `string`         | Yes      | -          |\n| `docs`     | `string`         | Yes      | -          |\n\n**Used by** `axisConflict`.\n\n### CatalogueIndexRow [#catalogueindexrow]\n\nOne component as the light registry index publishes it, flattened to the fields a decision to install actually turns on.\n\nA interface in `lib/catalogue.ts`.\n\n```ts\nexport interface CatalogueIndexRow {\n  name: string\n  title: string\n  description: string\n  type: \"registry:ui\"\n  category: CatalogueCategory\n  status: Status\n  since: string\n  aliases: string[]\n  implemented: boolean\n  docs: string | null\n  dependencies?: string[]\n  registryDependencies?: string[]\n}\n```\n\n**Members**\n\n| Member                 | Type                | Required | What it is |\n| ---------------------- | ------------------- | -------- | ---------- |\n| `name`                 | `string`            | Yes      | -          |\n| `title`                | `string`            | Yes      | -          |\n| `description`          | `string`            | Yes      | -          |\n| `type`                 | `\"registry:ui\"`     | Yes      | -          |\n| `category`             | `CatalogueCategory` | Yes      | -          |\n| `status`               | `Status`            | Yes      | -          |\n| `since`                | `string`            | Yes      | -          |\n| `aliases`              | `string[]`          | Yes      | -          |\n| `implemented`          | `boolean`           | Yes      | -          |\n| `docs`                 | `string \\| null`    | Yes      | -          |\n| `dependencies`         | `string[]`          | No       | -          |\n| `registryDependencies` | `string[]`          | No       | -          |\n\n### ClinicalStatus [#clinicalstatus]\n\nWhat a reading means and what, if anything, to do about it.\n\nFour levels, ordered. This is the ONLY status vocabulary in the system: the documentation chrome's callouts, the product's status pills and the dev warnings all use these four words, so a developer reading a Callout in these docs is reading the same vocabulary they will ship.\n\nA level is assigned by the consuming product from a reference range or a threshold that the product owns. opsinjs never assigns one, because opsinjs does not know the reader.\n\nA type in `lib/status.ts`.\n\n```ts\nexport type ClinicalStatus = (typeof CLINICAL_STATUSES)[number]\n```\n\n**Used by** `axisConflict`, [`AxisConflict`](#axisconflict), [`ClinicalStatusOrUnknown`](#clinicalstatusorunknown), `isClinicalStatus`, [`TrendPoint`](#trendpoint).\n\n### ClinicalStatusMeta [#clinicalstatusmeta]\n\nEverything a clinical status carries besides its colour. The word, the example sentence, who may assign it, its icon and its place in the order.\n\nA interface in `lib/status.ts`.\n\n```ts\nexport interface ClinicalStatusMeta {\n  word: string\n  sentence: string\n  assignedBy: string\n  icon: string\n  level: number\n}\n```\n\n**Members**\n\n| Member       | Type     | Required | What it is |\n| ------------ | -------- | -------- | ---------- |\n| `word`       | `string` | Yes      | -          |\n| `sentence`   | `string` | Yes      | -          |\n| `assignedBy` | `string` | Yes      | -          |\n| `icon`       | `string` | Yes      | -          |\n| `level`      | `number` | Yes      | -          |\n\n### ClinicalStatusOrUnknown [#clinicalstatusorunknown]\n\nThe four clinical statuses plus `unknown`. Unknown is the absence of an assertion rather than a fifth level of urgency.\n\nA type in `lib/status.ts`.\n\n```ts\nexport type ClinicalStatusOrUnknown = ClinicalStatus | UnknownStatus\n```\n\n### ColorInput [#colorinput]\n\nAnything the contrast functions accept: an sRGB triple, an OKLCH object, or a CSS colour string (`#0b6bcb`, `oklch(0.62 0.17 15)`, `rgb(11 107 203)`).\n\nThe string form is here because the two callers that matter most are a route handler receiving JSON and a playground receiving a paste, and neither has a triple to hand. A string that cannot be parsed yields NaN rather than an exception or a silent black: NaN propagates visibly into the response and into any comparison, which is the behaviour you want from a number nobody managed to measure.\n\nA type in `lib/color/apca.ts`.\n\n```ts\nexport type ColorInput = Rgb255 | Oklch | string\n```\n\n**Used by** `apcaContrast`, `contrastRatio`, `relativeLuminance`, `screenLuminance`, `toRgb255Input`.\n\n### ContrastCheck [#contrastcheck]\n\nOne measured pair from a derived theme, carrying both the APCA Lc and the WCAG ratio, the use that fixes the floor, and whether it passed.\n\nA interface in `lib/color/derive.ts`.\n\n```ts\nexport interface ContrastCheck {\n  pair: string\n  use: ContrastUse\n  apcaLc: number\n  wcagRatio: number\n  passes: boolean\n  advisory?: boolean\n}\n```\n\n**Members**\n\n| Member      | Type          | Required | What it is |\n| ----------- | ------------- | -------- | ---------- |\n| `pair`      | `string`      | Yes      | -          |\n| `use`       | `ContrastUse` | Yes      | -          |\n| `apcaLc`    | `number`      | Yes      | -          |\n| `wcagRatio` | `number`      | Yes      | -          |\n| `passes`    | `boolean`     | Yes      | -          |\n| `advisory`  | `boolean`     | No       | -          |\n\n**Used by** [`DerivedTheme`](#derivedtheme).\n\n### ContrastUse [#contrastuse]\n\nWhat a pair is being used for. Determines which floor applies.\n\nA type in `lib/color/apca.ts`.\n\n```ts\nexport type ContrastUse = \"body\" | \"large\" | \"nonText\"\n```\n\n**Used by** `APCA_FLOOR`, [`ApcaVerdict`](#apcaverdict), `CONTRAST_USE_LABELS`, [`ContrastCheck`](#contrastcheck), `passesApca`.\n\n### CvdCollision [#cvdcollision]\n\nTwo colours that stop being distinguishable under one kind of colour vision deficiency, and the Lc left between them once simulated.\n\nA interface in `lib/color/cvd.ts`.\n\n```ts\nexport interface CvdCollision {\n  type: CvdType\n  a: string\n  b: string\n  lc: number\n}\n```\n\n**Members**\n\n| Member | Type      | Required | What it is |\n| ------ | --------- | -------- | ---------- |\n| `type` | `CvdType` | Yes      | -          |\n| `a`    | `string`  | Yes      | -          |\n| `b`    | `string`  | Yes      | -          |\n| `lc`   | `number`  | Yes      | -          |\n\n### CvdType [#cvdtype]\n\nThe three dichromacies, plus the achromatic check every specimen must also survive.\n\nA type in `lib/color/cvd.ts`.\n\n```ts\nexport type CvdType = \"protanopia\" | \"deuteranopia\" | \"tritanopia\" | \"grayscale\"\n```\n\n**Used by** `CVD_LABELS`, `CVD_TYPES`, [`CvdCollision`](#cvdcollision), `simulate`.\n\n### DataState [#datastate]\n\nThe state a data surface is in, named once so the surfaces converge on one vocabulary, though no component accepts it yet.\n\nThese are the five states the Data states foundation names, which are loading, error, empty, partial and stale, plus the resolved case where the value is real, current and simply rendered. The members are listed with the five doctrine states first and resolved last; the order a surface actually moves through them is the resolution order the foundation's flow diagram fixes, which is error first, then loading, empty, partial, stale and finally resolved.\n\nNo component accepts this type yet. It exists so that when the data surfaces do converge on a single state input they converge on one set of names rather than six, and because lib/opsinjs.ts is the substrate `shadcn add` copies into a consumer's project, a type declared here already travels with every installed component and costs nothing at runtime. Turning this alias into a running state machine, with a prop, a guard and a default, is a larger change this name does not stand in for.\n\nA type in `lib/opsinjs.ts`.\n\n```ts\nexport type DataState =\n  | \"loading\"\n  | \"error\"\n  | \"empty\"\n  | \"partial\"\n  | \"stale\"\n  | \"resolved\"\n```\n\n### DecodeError [#decodeerror]\n\nWhy a preset code could not be read. The five reasons are kept distinct so that the sentence shown to a person can be a specific one.\n\nA type in `lib/preset.ts`.\n\n```ts\nexport type DecodeError =\n  | \"missing-prefix\"\n  | \"wrong-length\"\n  | \"unknown-version\"\n  | \"bad-characters\"\n  | \"bad-checksum\"\n```\n\n**Used by** [`DecodeResult`](#decoderesult).\n\n### DecodeResult [#decoderesult]\n\nThe outcome of reading a preset code. Either the preset and its version, or an error and a sentence a person can act on.\n\nA interface in `lib/preset.ts`.\n\n```ts\nexport interface DecodeResult {\n  preset: Preset | null\n  version: number | null\n  error: DecodeError | null\n  message: string | null\n}\n```\n\n**Members**\n\n| Member    | Type                  | Required | What it is |\n| --------- | --------------------- | -------- | ---------- |\n| `preset`  | `Preset \\| null`      | Yes      | -          |\n| `version` | `number \\| null`      | Yes      | -          |\n| `error`   | `DecodeError \\| null` | Yes      | -          |\n| `message` | `string \\| null`      | Yes      | -          |\n\n**Used by** `decodePreset`.\n\n### DerivedTheme [#derivedtheme]\n\nEverything derivation produces from one brand colour. Both ramps, every role in light and dark, the contrast checks, the warnings, and whether it is sound.\n\nA interface in `lib/color/derive.ts`.\n\n```ts\nexport interface DerivedTheme {\n  brand: Oklch\n  seed: Oklch\n  brandRamp: Ramp\n  neutralRamp: Ramp\n  roles: Record<RoleName, RolePair>\n  checks: ContrastCheck[]\n  warnings: DeriveWarning[]\n  sound: boolean\n}\n```\n\n**Members**\n\n| Member        | Type                         | Required | What it is |\n| ------------- | ---------------------------- | -------- | ---------- |\n| `brand`       | `Oklch`                      | Yes      | -          |\n| `seed`        | `Oklch`                      | Yes      | -          |\n| `brandRamp`   | `Ramp`                       | Yes      | -          |\n| `neutralRamp` | `Ramp`                       | Yes      | -          |\n| `roles`       | `Record<RoleName, RolePair>` | Yes      | -          |\n| `checks`      | `ContrastCheck[]`            | Yes      | -          |\n| `warnings`    | `DeriveWarning[]`            | Yes      | -          |\n| `sound`       | `boolean`                    | Yes      | -          |\n\n### DeriveOptions [#deriveoptions]\n\nThe knobs on theme derivation. Every one of them has a default, so a brand colour on its own is already a complete input.\n\nA interface in `lib/color/derive.ts`.\n\n```ts\nexport interface DeriveOptions {\n  neutralChroma?: number\n  gamut?: Gamut\n  maxSeedChroma?: number\n}\n```\n\n**Members**\n\n| Member          | Type     | Required | What it is |\n| --------------- | -------- | -------- | ---------- |\n| `neutralChroma` | `number` | No       | -          |\n| `gamut`         | `Gamut`  | No       | -          |\n| `maxSeedChroma` | `number` | No       | -          |\n\n### DeriveWarning [#derivewarning]\n\nOne thing the derivation has to say about a theme, as a level, a stable code and a message.\n\nA interface in `lib/color/derive.ts`.\n\n```ts\nexport interface DeriveWarning {\n  level: WarningLevel\n  code: string\n  message: string\n}\n```\n\n**Members**\n\n| Member    | Type           | Required | What it is |\n| --------- | -------------- | -------- | ---------- |\n| `level`   | `WarningLevel` | Yes      | -          |\n| `code`    | `string`       | Yes      | -          |\n| `message` | `string`       | Yes      | -          |\n\n**Used by** [`DerivedTheme`](#derivedtheme).\n\n### Detent [#detent]\n\nHow far a sheet is open.\n\nThree stops rather than a continuous height, because a sheet a reader can leave at an arbitrary position is a sheet that will be left half over the value it is explaining. `content` is as tall as what is inside it, `half` is the resting stop that keeps the screen behind it readable, and `full` is the whole surface.\n\nA type in `lib/opsinjs.ts`.\n\n```ts\nexport type Detent = \"content\" | \"half\" | \"full\"\n```\n\n### DocsNav [#docsnav]\n\nThis symbol has no doc comment yet.\n\nA interface in `lib/docs-nav.ts`.\n\n```ts\nexport interface DocsNav {\n  sections: NavSection[]\n  headings: Record<string, NavHeading[]>\n}\n```\n\n**Members**\n\n| Member     | Type                           | Required | What it is |\n| ---------- | ------------------------------ | -------- | ---------- |\n| `sections` | `NavSection[]`                 | Yes      | -          |\n| `headings` | `Record<string, NavHeading[]>` | Yes      | -          |\n\n**Used by** `getDocsNav`.\n\n### Gamut [#gamut]\n\nThe colour spaces this module can express a colour in.\n\nA type in `lib/color/oklch.ts`.\n\n```ts\nexport type Gamut = \"srgb\" | \"display-p3\"\n```\n\n**Used by** `clampToGamut`, [`DeriveOptions`](#deriveoptions), `deriveRamp`, `fit`.\n\n### GeneratedBannedWord [#generatedbannedword]\n\nOne banned word: the word a component's copy must not use, what to write in its place, and why the word is barred.\n\nThe shape lives here, in the shipped substrate, rather than in lib/generated, because a component that reads this list has to compile inside a consumer's project. build-registry ships exactly two library files, this one and lib/status.ts, so a list a component imports can live in one of those two and nowhere else, and lib/generated is a documentation-site artefact that never leaves this repository.\n\nThe rows themselves are generated rather than typed by hand. The space below is reserved and not yet filled. Once scripts/build-tokens.mts emits its banned-word region, the rows will arrive there from tokens/glossary.json, the single source for the banned list and the plain-language glossary alike, and `node scripts/build-tokens.mts --check` will then hold the generated copy and that source in step, failing the build the moment one drifts. Only the shape is stated here, so the generated region can carry data alone.\n\nA interface in `lib/opsinjs.ts`.\n\n```ts\nexport interface GeneratedBannedWord {\n  word: string\n  instead: string\n  reason: string\n}\n```\n\n**Members**\n\n| Member    | Type     | Required | What it is |\n| --------- | -------- | -------- | ---------- |\n| `word`    | `string` | Yes      | -          |\n| `instead` | `string` | Yes      | -          |\n| `reason`  | `string` | Yes      | -          |\n\n**Used by** `BANNED_WORDS`.\n\n### HealthCategory [#healthcategory]\n\nWhat a reading is ABOUT. Identity, never verdict.\n\nA heart-red card does not mean something is wrong with a heart reading; it means the reading concerns the heart. This is the axis products most often misuse, because red already means something else everywhere else on the web.\n\nA type in `lib/status.ts`.\n\n```ts\nexport type HealthCategory = (typeof HEALTH_CATEGORIES)[number]\n```\n\n**Used by** `axisConflict`, [`AxisConflict`](#axisconflict), `HEALTH_CATEGORY_LABELS`, `isHealthCategory`.\n\n### Kind [#kind]\n\nA page's kind, one per sidebar section. Only `component` fixes the page's headings; every other kind names its own, as a page on blueprintjs.com does.\n\nA type in `lib/status.ts`.\n\n```ts\nexport type Kind = (typeof KINDS)[number]\n```\n\n**Used by** `isKind`, `OUTLINE_IS_EXACT`, `SECTION_OUTLINES`.\n\n### MaterialRung [#materialrung]\n\nA rung of the material ladder, meaning how a surface sits above what is behind it.\n\nThese six names are the token names: every rung resolves a matching set of `--opsin-material-<rung>-*` custom properties for blur, tint, shadow and border. Where a specification page names a different set, the tokens win, because the tokens are what actually renders.\n\nA type in `lib/opsinjs.ts`.\n\n```ts\nexport type MaterialRung =\n  | \"canvas\"\n  | \"card\"\n  | \"raised\"\n  | \"sheet\"\n  | \"overlay\"\n  | \"scrim\"\n```\n\n### NavGroup [#navgroup]\n\nThis symbol has no doc comment yet.\n\nA interface in `lib/docs-nav.ts`.\n\n```ts\nexport interface NavGroup {\n  title?: string\n  links: NavLink[]\n}\n```\n\n**Members**\n\n| Member  | Type        | Required | What it is |\n| ------- | ----------- | -------- | ---------- |\n| `title` | `string`    | No       | -          |\n| `links` | `NavLink[]` | Yes      | -          |\n\n**Used by** [`NavSection`](#navsection).\n\n### NavHeading [#navheading]\n\nThis symbol has no doc comment yet.\n\nA interface in `lib/docs-nav.ts`.\n\n```ts\nexport interface NavHeading {\n  depth: 2 | 3\n  id: string\n  text: string\n}\n```\n\n**Members**\n\n| Member  | Type     | Required | What it is |\n| ------- | -------- | -------- | ---------- |\n| `depth` | `2 \\| 3` | Yes      | -          |\n| `id`    | `string` | Yes      | -          |\n| `text`  | `string` | Yes      | -          |\n\n**Used by** [`DocsNav`](#docsnav), `getDocsNav`.\n\n### NavLink [#navlink]\n\nThis symbol has no doc comment yet.\n\nA interface in `lib/docs-nav.ts`.\n\n```ts\nexport interface NavLink {\n  title: string\n  url: string\n}\n```\n\n**Members**\n\n| Member  | Type     | Required | What it is |\n| ------- | -------- | -------- | ---------- |\n| `title` | `string` | Yes      | -          |\n| `url`   | `string` | Yes      | -          |\n\n**Used by** [`NavGroup`](#navgroup).\n\n### NavSection [#navsection]\n\nThis symbol has no doc comment yet.\n\nA interface in `lib/docs-nav.ts`.\n\n```ts\nexport interface NavSection {\n  id: string\n  title: string\n  url: string\n  meta?: string\n  groups: NavGroup[]\n}\n```\n\n**Members**\n\n| Member   | Type         | Required | What it is |\n| -------- | ------------ | -------- | ---------- |\n| `id`     | `string`     | Yes      | -          |\n| `title`  | `string`     | Yes      | -          |\n| `url`    | `string`     | Yes      | -          |\n| `meta`   | `string`     | No       | -          |\n| `groups` | `NavGroup[]` | Yes      | -          |\n\n**Used by** [`DocsNav`](#docsnav), `getDocsNav`.\n\n### Oklab [#oklab]\n\nA colour in OKLab.\n\nA interface in `lib/color/oklch.ts`.\n\n```ts\nexport interface Oklab {\n  l: number\n  a: number\n  b: number\n  alpha?: number\n}\n```\n\n**Members**\n\n| Member  | Type     | Required | What it is |\n| ------- | -------- | -------- | ---------- |\n| `l`     | `number` | Yes      | -          |\n| `a`     | `number` | Yes      | -          |\n| `b`     | `number` | Yes      | -          |\n| `alpha` | `number` | No       | -          |\n\n**Used by** `linearSrgbToOklab`, `oklabToLinearSrgb`, `oklabToOklch`, `oklchToOklab`.\n\n### Oklch [#oklch]\n\nA colour in OKLCH. `l` 0 to 1, `c` unbounded, `h` in degrees.\n\nA interface in `lib/color/oklch.ts`.\n\n```ts\nexport interface Oklch {\n  l: number\n  c: number\n  h: number\n  alpha?: number\n}\n```\n\n**Members**\n\n| Member  | Type     | Required | What it is |\n| ------- | -------- | -------- | ---------- |\n| `l`     | `number` | Yes      | -          |\n| `c`     | `number` | Yes      | -          |\n| `h`     | `number` | Yes      | -          |\n| `alpha` | `number` | No       | -          |\n\n**Used by** `apcaContrastOklch`, `clampToGamut`, [`ColorInput`](#colorinput), `contrastRatioOklch`, [`DerivedTheme`](#derivedtheme), `deriveRamp`, `displayP3ToOklch`, `fit`, `formatDisplayP3`, `formatHex`, `formatOklch`, `mixOklch`, `oklabToOklch`, `oklchToDisplayP3`, `oklchToOklab`, `oklchToRgb255`, `oklchToSrgb`, `parseColor`, [`RampStepValue`](#rampstepvalue), [`RoleValue`](#rolevalue), `srgbToOklch`.\n\n### OpsinError [#opsinerror]\n\nOne warning code: what it is called, how severe it is, and the page that prevents it.\n\nA interface in `lib/opsinjs.ts`.\n\n```ts\nexport interface OpsinError {\n  code: OpsinErrorCode\n  severity: OpsinErrorSeverity\n  title: string\n  message: string\n  docs: string\n  params: string[]\n}\n```\n\n**Members**\n\n| Member     | Type                 | Required | What it is |\n| ---------- | -------------------- | -------- | ---------- |\n| `code`     | `OpsinErrorCode`     | Yes      | -          |\n| `severity` | `OpsinErrorSeverity` | Yes      | -          |\n| `title`    | `string`             | Yes      | -          |\n| `message`  | `string`             | Yes      | -          |\n| `docs`     | `string`             | Yes      | -          |\n| `params`   | `string[]`           | Yes      | -          |\n\n**Used by** `OPSIN_ERRORS`.\n\n### OpsinErrorCode [#opsinerrorcode]\n\nEvery warning code opsinjs can emit.\n\nFlat, allocated in sequence, and permanent: a code is never reused, never renumbered and never removed. The union is what makes `warnOnce(\"OPSIN-0004\")` a compile error when the code does not exist, which is the difference between a stable code and a string somebody typed.\n\nA type in `lib/opsinjs.ts`.\n\n```ts\nexport type OpsinErrorCode =\n  | \"OPSIN-0001\"\n  | \"OPSIN-0002\"\n  | \"OPSIN-0003\"\n  | \"OPSIN-0004\"\n  | \"OPSIN-0005\"\n  | \"OPSIN-0006\"\n  | \"OPSIN-0007\"\n  | \"OPSIN-0008\"\n  | \"OPSIN-0009\"\n  | \"OPSIN-0010\"\n  | \"OPSIN-0011\"\n  | \"OPSIN-0012\"\n  | \"OPSIN-0013\"\n  | \"OPSIN-0014\"\n  | \"OPSIN-0015\"\n  | \"OPSIN-0016\"\n  | \"OPSIN-0017\"\n  | \"OPSIN-0018\"\n  | \"OPSIN-0019\"\n  | \"OPSIN-0020\"\n  | \"OPSIN-0021\"\n```\n\n**Used by** `OPSIN_ERRORS`, [`OpsinError`](#opsinerror), `warnOnce`.\n\n### OpsinErrorParams [#opsinerrorparams]\n\nThe values a message template asks for, keyed by placeholder name.\n\nValues are stringified as they are: a number arrives as a number so the message does not have to decide how to format it, and no value is ever rounded, unit-converted or localised on its way into a warning. A warning that reformats what it was given is a warning that can disagree with the screen it is complaining about.\n\nA type in `lib/opsinjs.ts`.\n\n```ts\nexport type OpsinErrorParams = Record<string, string | number>\n```\n\n**Used by** `warnOnce`.\n\n### OpsinErrorSeverity [#opsinerrorseverity]\n\nHow severe a warning is.\n\nThe three classes are declared in `tokens/errors.json`'s `policy.severity` block, which also carries the sentence that says what each one means:\n\n* safety - A defect that can mislead a reader about their own health. Treat as a bug, not as a lint warning.\n* correctness - The component will render something, but not what the author meant.\n* hygiene - Works today, will not survive an upgrade.\n\nA type in `lib/opsinjs.ts`.\n\n```ts\nexport type OpsinErrorSeverity = \"safety\" | \"correctness\" | \"hygiene\"\n```\n\n**Used by** [`OpsinError`](#opsinerror).\n\n### Preset [#preset]\n\nA theme as a person describes it. What `encodePreset` takes and `decodePreset` returns.\n\nA interface in `lib/preset.ts`.\n\n```ts\nexport interface Preset {\n  hue: number\n  chroma: number\n  lightness: number\n  neutralChroma: number\n  radius: number\n  density: (typeof DENSITY_VALUES)[number]\n  gamut: (typeof GAMUT_VALUES)[number]\n  floor: (typeof FLOOR_VALUES)[number]\n  cornerShape: (typeof CORNER_SHAPE_VALUES)[number]\n  mode: (typeof MODE_VALUES)[number]\n}\n```\n\n**Members**\n\n| Member          | Type                                   | Required | What it is |\n| --------------- | -------------------------------------- | -------- | ---------- |\n| `hue`           | `number`                               | Yes      | -          |\n| `chroma`        | `number`                               | Yes      | -          |\n| `lightness`     | `number`                               | Yes      | -          |\n| `neutralChroma` | `number`                               | Yes      | -          |\n| `radius`        | `number`                               | Yes      | -          |\n| `density`       | `(typeof DENSITY_VALUES)[number]`      | Yes      | -          |\n| `gamut`         | `(typeof GAMUT_VALUES)[number]`        | Yes      | -          |\n| `floor`         | `(typeof FLOOR_VALUES)[number]`        | Yes      | -          |\n| `cornerShape`   | `(typeof CORNER_SHAPE_VALUES)[number]` | Yes      | -          |\n| `mode`          | `(typeof MODE_VALUES)[number]`         | Yes      | -          |\n\n**Used by** [`DecodeResult`](#decoderesult), `DEFAULT_PRESET`, `presetBrandColor`, `SHIPPED_PRESETS`.\n\n### Ramp [#ramp]\n\nOne complete lightness ramp, as a value per step. The chromatic ramp and the neutral ramp of a derived theme are both this shape.\n\nA type in `lib/color/derive.ts`.\n\n```ts\nexport type Ramp = Record<RampStep, RampStepValue>\n```\n\n**Used by** [`DerivedTheme`](#derivedtheme), `deriveRamp`.\n\n### RampStep [#rampstep]\n\nOne rung of the lightness ladder, from 50 at the lightest to 950 at the darkest. The rungs are fixed, so two themes are comparable step by step.\n\nA type in `lib/color/derive.ts`.\n\n```ts\nexport type RampStep = (typeof RAMP_STEPS)[number]\n```\n\n**Used by** `CHROMA_ENVELOPE`, [`Ramp`](#ramp), `RAMP_LIGHTNESS`, [`RampStepValue`](#rampstepvalue).\n\n### RampStepValue [#rampstepvalue]\n\nOne rung of a ramp, as the sRGB value that ships, the wide-gamut value where P3 has headroom, and whether sRGB had to clamp the chroma away.\n\nA interface in `lib/color/derive.ts`.\n\n```ts\nexport interface RampStepValue {\n  step: RampStep\n  srgb: Oklch\n  p3?: Oklch\n  clamped: boolean\n  css: { srgb: string; p3?: string }\n}\n```\n\n**Members**\n\n| Member    | Type                            | Required | What it is |\n| --------- | ------------------------------- | -------- | ---------- |\n| `step`    | `RampStep`                      | Yes      | -          |\n| `srgb`    | `Oklch`                         | Yes      | -          |\n| `p3`      | `Oklch`                         | No       | -          |\n| `clamped` | `boolean`                       | Yes      | -          |\n| `css`     | `{ srgb: string; p3?: string }` | Yes      | -          |\n\n**Used by** [`Ramp`](#ramp).\n\n### ReferenceRange [#referencerange]\n\nThe interval a reading is being compared against, and who says so.\n\nBoth bounds are optional because a one-sided range is a real range: some measurements have a floor and no ceiling, and rendering a bound the product did not supply would invent a threshold. An omitted bound renders as an open end, never as zero and never as an assumed limit.\n\n`source` is required, and it is required because opsinjs does not own a single clinical number. A range arriving with no attribution is the consuming product asking this system to vouch for a threshold it has never seen, which is the one thing it must not do; a component handed a range with no `source` reports OPSIN-0004 rather than drawing it.\n\nA interface in `lib/opsinjs.ts`.\n\n```ts\nexport interface ReferenceRange {\n  low?: number\n  high?: number\n  source: string\n  asOf?: string\n}\n```\n\n**Members**\n\n| Member   | Type     | Required | What it is |\n| -------- | -------- | -------- | ---------- |\n| `low`    | `number` | No       | -          |\n| `high`   | `number` | No       | -          |\n| `source` | `string` | Yes      | -          |\n| `asOf`   | `string` | No       | -          |\n\n### RefusedConversion [#refusedconversion]\n\nA pair people expect to be arithmetic and is not, with the reason.\n\nThis list is the load-bearing half of the unit table. An omitted conversion has to render as an explicit \"we do not have this\", never as a substituted default, and a component that wants to explain WHY reads its reason here.\n\nA interface in `lib/opsinjs.ts`.\n\n```ts\nexport interface RefusedConversion {\n  between: [string, string]\n  reason: string\n  docs: string\n}\n```\n\n**Members**\n\n| Member    | Type               | Required | What it is |\n| --------- | ------------------ | -------- | ---------- |\n| `between` | `[string, string]` | Yes      | -          |\n| `reason`  | `string`           | Yes      | -          |\n| `docs`    | `string`           | Yes      | -          |\n\n**Used by** `REFUSED_CONVERSIONS`.\n\n### RegistryLookup [#registrylookup]\n\nBoth call shapes are supported on purpose.\n\n`getRegistryEntry(\"range-bar\", base, style)` is what the preview surface and the machine routes call, and it reads naturally at a call site that already has three variables. The object form exists for the one caller that needs to pass a `kind`, and because a fourth positional argument is where a signature stops being readable.\n\nA type in `lib/registry.ts`.\n\n```ts\nexport type RegistryLookup = string | RegistryQuery\n```\n\n### RegistryQuery [#registryquery]\n\nA request for one registry item, by id and optionally by base, style and kind. Anything left out falls back to the default.\n\nA interface in `lib/registry.ts`.\n\n```ts\nexport interface RegistryQuery {\n  name: string\n  base?: string\n  style?: string\n  kind?: RegistryKind\n}\n```\n\n**Members**\n\n| Member  | Type           | Required | What it is |\n| ------- | -------------- | -------- | ---------- |\n| `name`  | `string`       | Yes      | -          |\n| `base`  | `string`       | No       | -          |\n| `style` | `string`       | No       | -          |\n| `kind`  | `RegistryKind` | No       | -          |\n\n**Used by** [`RegistryLookup`](#registrylookup).\n\n### Rgb [#rgb]\n\nRed, green and blue, each 0 to 1, in whichever space the function says.\n\nA interface in `lib/color/oklch.ts`.\n\n```ts\nexport interface Rgb {\n  r: number\n  g: number\n  b: number\n  alpha?: number\n}\n```\n\n**Members**\n\n| Member  | Type     | Required | What it is |\n| ------- | -------- | -------- | ---------- |\n| `r`     | `number` | Yes      | -          |\n| `g`     | `number` | Yes      | -          |\n| `b`     | `number` | Yes      | -          |\n| `alpha` | `number` | No       | -          |\n\n**Used by** `displayP3ToOklch`, `linearP3ToLinearSrgb`, `linearSrgbToLinearP3`, `linearSrgbToOklab`, `linearToSrgb`, `oklabToLinearSrgb`, `oklchToDisplayP3`, `oklchToSrgb`, `parseHex`, `simulate`, `srgbToLinear`, `srgbToOklch`, `toGrayscale`, `toRgb255`.\n\n### Rgb255 [#rgb255]\n\nA colour as 0 to 255 sRGB integers, which is what APCA is defined over.\n\nA type in `lib/color/apca.ts`.\n\n```ts\nexport type Rgb255 = [number, number, number]\n```\n\n**Used by** [`ColorInput`](#colorinput), `toRgb255Input`.\n\n### RoleName [#rolename]\n\nThe roles a derived theme guarantees. Components consume these and never a step.\n\nA type in `lib/color/derive.ts`.\n\n```ts\nexport type RoleName =\n  | \"canvas\"\n  | \"surface\"\n  | \"ink\"\n  | \"muted-ink\"\n  | \"line\"\n  | \"control-line\"\n  | \"primary\"\n  | \"on-primary\"\n  | \"focus\"\n```\n\n**Used by** [`DerivedTheme`](#derivedtheme).\n\n### RolePair [#rolepair]\n\nOne semantic role in both colour modes. Roles are derived as a pair, because a role that exists only in light mode is a role that breaks in dark.\n\nA interface in `lib/color/derive.ts`.\n\n```ts\nexport interface RolePair {\n  light: RoleValue\n  dark: RoleValue\n}\n```\n\n**Members**\n\n| Member  | Type        | Required | What it is |\n| ------- | ----------- | -------- | ---------- |\n| `light` | `RoleValue` | Yes      | -          |\n| `dark`  | `RoleValue` | Yes      | -          |\n\n**Used by** [`DerivedTheme`](#derivedtheme).\n\n### RoleValue [#rolevalue]\n\nWhat a semantic role resolves to in one colour mode. The ramp step it came from, the OKLCH value, and the CSS it is written as.\n\nA interface in `lib/color/derive.ts`.\n\n```ts\nexport interface RoleValue {\n  source: string\n  value: Oklch\n  css: string\n}\n```\n\n**Members**\n\n| Member   | Type     | Required | What it is |\n| -------- | -------- | -------- | ---------- |\n| `source` | `string` | Yes      | -          |\n| `value`  | `Oklch`  | Yes      | -          |\n| `css`    | `string` | Yes      | -          |\n\n**Used by** [`RolePair`](#rolepair).\n\n### Showcase [#showcase]\n\nThe screens on `/showcase`: whole screens assembled only from opsinjs components, each one rendered from a file under `registry/screens/`.\n\nEvery entry here is opsinjs's own work. An entry from another team would have to clear the four tests printed on the showcase, and none has, so this list holds no product somebody else shipped. Add one only when a screen file exists and renders at its `/view` route. The entry's card links to `/showcase/<slug>`, which shows the screen on its own.\n\nA interface in `lib/showcases.ts`.\n\n```ts\nexport interface Showcase {\n  slug: \"diabetes-medicines-app\" | \"patient-record-portal\" | \"results-screen\"\n  title: string\n  description: string\n  domain: string\n  components: number\n  highlights: string[]\n}\n```\n\n**Members**\n\n| Member        | Type                                                                      | Required | What it is |\n| ------------- | ------------------------------------------------------------------------- | -------- | ---------- |\n| `slug`        | `\"diabetes-medicines-app\" \\| \"patient-record-portal\" \\| \"results-screen\"` | Yes      | -          |\n| `title`       | `string`                                                                  | Yes      | -          |\n| `description` | `string`                                                                  | Yes      | -          |\n| `domain`      | `string`                                                                  | Yes      | -          |\n| `components`  | `number`                                                                  | Yes      | -          |\n| `highlights`  | `string[]`                                                                | Yes      | -          |\n\n**Used by** `showcases`.\n\n### Status [#status]\n\nThe release phase of a component page or a catalogue entry.\n\nA type in `lib/status.ts`.\n\n```ts\nexport type Status = (typeof STATUSES)[number]\n```\n\n**Used by** [`CatalogueIndexRow`](#catalogueindexrow), `COMPONENT_SECTIONS_BY_STATUS`, `componentSections`, `getByStatus`, `isNotImplemented`, `isStatus`, `OPSIN_ERRORS`, `STATUS_META`, `STATUS_ORDER`, [`UnresolvedReason`](#unresolvedreason).\n\n### StatusMeta [#statusmeta]\n\nWhat a release phase shows on a badge. A label and one sentence a reader can act on, which is also the chip's title and its accessible name.\n\nA interface in `lib/status.ts`.\n\n```ts\nexport interface StatusMeta {\n  label: string\n  summary: string\n}\n```\n\n**Members**\n\n| Member    | Type     | Required | What it is |\n| --------- | -------- | -------- | ---------- |\n| `label`   | `string` | Yes      | -          |\n| `summary` | `string` | Yes      | -          |\n\n**Used by** `STATUS_META`.\n\n### TokenFormat [#tokenformat]\n\nThe formats the `/tokens` and `/colors` browsers can copy a value in.\n\nA type in `lib/tokens.ts`.\n\n```ts\nexport type TokenFormat = \"oklch\" | \"display-p3\" | \"hex\" | \"var\" | \"class\"\n```\n\n**Used by** `TOKEN_FORMAT_LABELS`.\n\n### TrendPoint [#trendpoint]\n\nOne reading in a series, for the components that draw change over time.\n\n`value` is `number | null` rather than `number` because a gap in a series is information: a day with no reading is not a day with a reading of zero, and charting it as zero invents a measurement. A `null` point is drawn as a break in the line and described in words by the chart's text twin.\n\n`status` is optional and is an input, never a derivation. opsinjs does not compare a point to a range and decide what it means, because it does not know the reader; a point carries a verdict only when the consuming product attached one.\n\nA interface in `lib/opsinjs.ts`.\n\n```ts\nexport interface TrendPoint {\n  at: string\n  value: number | null\n  status?: ClinicalStatus\n}\n```\n\n**Members**\n\n| Member   | Type             | Required | What it is |\n| -------- | ---------------- | -------- | ---------- |\n| `at`     | `string`         | Yes      | -          |\n| `value`  | `number \\| null` | Yes      | -          |\n| `status` | `ClinicalStatus` | No       | -          |\n\n### Unit [#unit]\n\nOne unit: what it is called, what a reader sees, and how it is SPOKEN.\n\nThe spoken form is the whole reason this table exists. A screen reader handed `mmHg` improvises a pronunciation, and \"one twenty over eighty em em aitch gee\" is a failure rather than a quirk.\n\nThere is no reference range here, no threshold, no plausibility bound and no default precision. A unit table says what a number is measured in; it never says what a number should be. Decimal places belong to the MEASUREMENT and travel with it from the product - health/numbers-units-precision, rule 2.\n\n`joined` is typography, not a claim about a reading: it records that a symbol sits against the number with no space, as everyday English writes 98% and 36.8°C. Which symbols take it is settled by content/docs/content/grammar-and-mechanics.mdx, not by this table.\n\nA interface in `lib/opsinjs.ts`.\n\n```ts\nexport interface Unit {\n  id: string\n  symbol: string\n  spoken: string\n  plural: string\n  measures: string\n  joined?: true\n}\n```\n\n**Members**\n\n| Member     | Type     | Required | What it is |\n| ---------- | -------- | -------- | ---------- |\n| `id`       | `string` | Yes      | -          |\n| `symbol`   | `string` | Yes      | -          |\n| `spoken`   | `string` | Yes      | -          |\n| `plural`   | `string` | Yes      | -          |\n| `measures` | `string` | Yes      | -          |\n| `joined`   | `true`   | No       | -          |\n\n**Used by** `findUnit`, `UNITS`, `UNITS_BY_SYMBOL`.\n\n### UnitConversion [#unitconversion]\n\nAn exact conversion between two units of the same kind.\n\nApplied as `to = from * numerator / denominator + offsetNumerator / offsetDenominator`. Every field is an integer, and that is deliberate: these are definitions rather than measurements, and a definition stored as a rounded decimal is an approximation wearing a definition's provenance.\n\n`basis` names the definition each factor comes from. A conversion with no basis does not belong in this system: opsinjs does not own a clinical number, and the ones it does carry are the ones that are true by definition rather than by measurement.\n\nA interface in `lib/opsinjs.ts`.\n\n```ts\nexport interface UnitConversion {\n  from: string\n  to: string\n  numerator: number\n  denominator: number\n  offsetNumerator: number\n  offsetDenominator: number\n  basis: string[]\n}\n```\n\n**Members**\n\n| Member              | Type       | Required | What it is |\n| ------------------- | ---------- | -------- | ---------- |\n| `from`              | `string`   | Yes      | -          |\n| `to`                | `string`   | Yes      | -          |\n| `numerator`         | `number`   | Yes      | -          |\n| `denominator`       | `number`   | Yes      | -          |\n| `offsetNumerator`   | `number`   | Yes      | -          |\n| `offsetDenominator` | `number`   | Yes      | -          |\n| `basis`             | `string[]` | Yes      | -          |\n\n**Used by** `UNIT_CONVERSIONS`, `unitConversion`.\n\n### UnknownStatus [#unknownstatus]\n\nThe absence of an assertion, which covers a reading never taken, a stale reading, or a reading whose reference range the product does not own.\n\nDeliberately NOT a fifth clinical status: rendering \"we do not know\" as a status would claim a verdict the system does not have, and colouring it anywhere near `watch` would let a reader read it as \"probably fine\".\n\nA type in `lib/status.ts`.\n\n```ts\nexport type UnknownStatus = \"unknown\"\n```\n\n**Used by** [`ClinicalStatusOrUnknown`](#clinicalstatusorunknown).\n\n### UnresolvedReason [#unresolvedreason]\n\nWhy a lookup came back empty. The input to `<NotBuiltYet>`.\n\nA interface in `lib/registry.ts`.\n\n```ts\nexport interface UnresolvedReason {\n  name: string\n  reason: \"not-built\" | \"unknown\"\n  status: Status | null\n  message: string\n}\n```\n\n**Members**\n\n| Member    | Type                       | Required | What it is |\n| --------- | -------------------------- | -------- | ---------- |\n| `name`    | `string`                   | Yes      | -          |\n| `reason`  | `\"not-built\" \\| \"unknown\"` | Yes      | -          |\n| `status`  | `Status \\| null`           | Yes      | -          |\n| `message` | `string`                   | Yes      | -          |\n\n**Used by** `explainUnresolved`.\n\n### ViewKind [#viewkind]\n\nWhat a `/view` route can render.\n\nA type in `lib/routes.ts`.\n\n```ts\nexport type ViewKind = \"component\" | \"example\" | \"screen\"\n```\n\n**Used by** [`ViewParams`](#viewparams).\n\n### ViewParams [#viewparams]\n\nEverything a chrome-less preview URL can carry. Name and kind become path segments, and the rest become query parameters applied before first paint.\n\nA interface in `lib/routes.ts`.\n\n```ts\nexport interface ViewParams {\n  name: string\n  kind?: ViewKind\n  base?: string\n  style?: string\n  mode?: \"light\" | \"dark\"\n  density?: \"comfortable\" | \"compact\"\n  text?: 100 | 125 | 150 | 200\n  theme?: string\n  accentTheme?: string\n  accent?: string\n}\n```\n\n**Members**\n\n| Member        | Type                         | Required | What it is |\n| ------------- | ---------------------------- | -------- | ---------- |\n| `name`        | `string`                     | Yes      | -          |\n| `kind`        | `ViewKind`                   | No       | -          |\n| `base`        | `string`                     | No       | -          |\n| `style`       | `string`                     | No       | -          |\n| `mode`        | `\"light\" \\| \"dark\"`          | No       | -          |\n| `density`     | `\"comfortable\" \\| \"compact\"` | No       | -          |\n| `text`        | `100 \\| 125 \\| 150 \\| 200`   | No       | -          |\n| `theme`       | `string`                     | No       | -          |\n| `accentTheme` | `string`                     | No       | -          |\n| `accent`      | `string`                     | No       | -          |\n\n**Used by** `viewPath`.\n\n### WarningLevel [#warninglevel]\n\nHow serious a derivation warning is. An `error` makes the theme unsound and stops it shipping, while a `warning` and a `note` are advisory.\n\nA type in `lib/color/derive.ts`.\n\n```ts\nexport type WarningLevel = \"error\" | \"warning\" | \"note\"\n```\n\n**Used by** [`DeriveWarning`](#derivewarning).\n\n### WcagUse [#wcaguse]\n\nWhich WCAG 2.2 contrast threshold applies. Body text, large text and non- text content each have a different floor.\n\nA type in `lib/color/wcag.ts`.\n\n```ts\nexport type WcagUse = \"body\" | \"large\" | \"nonText\"\n```\n\n**Used by** [`WcagVerdict`](#wcagverdict).\n\n### WcagVerdict [#wcagverdict]\n\nThe result of one WCAG 2.2 contrast measurement, with the ratio, the floor for that use, and the success criterion it is measured against.\n\nA interface in `lib/color/wcag.ts`.\n\n```ts\nexport interface WcagVerdict {\n  ratio: number\n  use: WcagUse\n  floor: number\n  passesAA: boolean\n  passesAAA: boolean\n  criterion: string\n}\n```\n\n**Members**\n\n| Member      | Type      | Required | What it is |\n| ----------- | --------- | -------- | ---------- |\n| `ratio`     | `number`  | Yes      | -          |\n| `use`       | `WcagUse` | Yes      | -          |\n| `floor`     | `number`  | Yes      | -          |\n| `passesAA`  | `boolean` | Yes      | -          |\n| `passesAAA` | `boolean` | Yes      | -          |\n| `criterion` | `string`  | Yes      | -          |\n\n{/* opsinjs:generated:end */}"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/reference/glossary",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/reference/glossary.md",
      "slug": [
        "reference",
        "glossary"
      ],
      "section": "Reference",
      "title": "Glossary",
      "description": "The words opsinjs uses about itself, from axis and rung to tier and twin, each with the page that defines it.",
      "kind": "reference",
      "aliases": [
        "system glossary",
        "rung",
        "base vs style",
        "system vocabulary"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "This is the vocabulary of the system, not of health. For HbA1c or systolic, use the [Plain English A to Z](./plain-english.mdx), which is written for the people using your app. Where a word has two meanings, both are listed. The one that catches people out is status.\n\nThis page is written by hand. A definition here may summarise the page it links but never contradicts it.\n\n| Term                  | What it means                                                                                                                                                                                                                                    | See                                              |\n| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ |\n| **alias**             | A search synonym in a page's frontmatter. Aliases are indexed, emitted into `llms.txt` and `/r/index.json`, and unique across the docs.                                                                                                          | [Agents and LLMs](../agents.mdx)                 |\n| **axis**              | One of the two independent colour dimensions. The status axis carries clinical urgency and the category axis carries subject identity. They never combine on one element.                                                                        | [Two colour axes](../health/two-colour-axes.mdx) |\n| **base**              | The React code that implements a component's behaviour. `base` is the only one. Its URL segment means a second base would be additive rather than a migration.                                                                                   | [Registry](../registry.mdx)                      |\n| **catalogue**         | The single list of every component id, with its category, release phase and aliases. `registry/catalogue.ts` is its only definition.                                                                                                             | [Components](../components/index.mdx)            |\n| **category**          | The subject a value belongs to, which is the identity axis. A category colour says what a number is about, never how worried to be.                                                                                                              | [Two colour axes](../health/two-colour-axes.mdx) |\n| **chrome**            | The documentation site's own interface: sidebar, header and search. It shares the product's visual language at desk density and sets Inter, while the product keeps the platform face.                                                           | [Reading the docs](../reading-the-docs.mdx)      |\n| **doctrine**          | A rule page that constrains components rather than describing one. A Health page lists the components it governs in `implements`.                                                                                                                | [Health](../health/index.mdx)                    |\n| **foundation**        | A cross-cutting layer every component draws on, from colour to writing. Six have tokens of their own: colour, typography, space, shape, motion and materials.                                                                                    | [Foundations](../foundations/index.mdx)          |\n| **generated marker**  | The comment pair `opsinjs:generated:begin` and `opsinjs:generated:end`. A script writes everything between them and erases it on the next run. The error table uses `opsinjs:errors:begin` and `opsinjs:errors:end`.                             | [Reference](./index.mdx)                         |\n| **ladder**            | The material rungs from canvas to scrim, an ordered set where position carries meaning rather than size.                                                                                                                                         | [Materials](../foundations/materials.mdx)        |\n| **namespace**         | The `@opsinjs` prefix a consumer registers in `components.json` so that `npx shadcn add @opsinjs/result-card` resolves here.                                                                                                                     | [Registry](../registry.mdx)                      |\n| **pattern**           | A multi-screen sequence a health product keeps rebuilding, such as result disclosure or daily logging.                                                                                                                                           | [Patterns](../patterns/index.mdx)                |\n| **preset**            | A complete theme expressed as values rather than code. The values are the token overrides that turn the system a particular colour.                                                                                                              | [Theming](../theming.mdx)                        |\n| **preset code**       | The short opaque string, `opsinjs-*`, that encodes a preset for a URL or a CLI flag. It is decodable, versioned and not a secret.                                                                                                                | [Theming](../theming.mdx)                        |\n| **product theme**     | The theme components render under: squircle corners, `system-ui` and generous spacing. Every `/view` route and component preview uses it. The docs chrome does not.                                                                              | [Reading the docs](../reading-the-docs.mdx)      |\n| **ramp**              | A perceptually even series of steps generated from one colour in OKLCH, clamped for gamut and checked for contrast. Each axis colour has one.                                                                                                    | [Colour](../foundations/colour.mdx)              |\n| **registry item**     | The JSON for one distributable unit in the shadcn registry schema: its files, dependencies and target paths. Served from `/r`.                                                                                                                   | [Registry](../registry.mdx)                      |\n| **role**              | A semantic colour slot filled by a ramp step. The four roles are surface, line, ink and accent. Components read roles, never ramp steps.                                                                                                         | [Colour](../foundations/colour.mdx)              |\n| **rung**              | One step of the material ladder, identified by its position in the stacking order rather than by a blur radius.                                                                                                                                  | [Materials](../foundations/materials.mdx)        |\n| **scale**             | An ordered set of sizes named by intent rather than by t-shirt size. The scales are type, space and radius.                                                                                                                                      | [Theming](../theming.mdx)                        |\n| **screen**            | A whole-screen specimen: several components under one layout, showing what the parts do together.                                                                                                                                                | [Patterns](../patterns/index.mdx)                |\n| **status (clinical)** | One of the four ordinal levels describing a value against what is expected for a person: steady, watch, attention and urgent. The product assigns it, and opsinjs only renders it. `unknown` means there is no reading. It is not a fifth level. | [Two colour axes](../health/two-colour-axes.mdx) |\n| **status (release)**  | The phase a component page declares: planned, shipped or deprecated. Only a component page carries one. Shipped means the source installs and renders. It never means reviewed.                                                                  | [Reading the docs](../reading-the-docs.mdx)      |\n| **style**             | A visual variant applied as CSS only, never as behaviour. `base-lyra` is the default, and styles are addressable in `/view` and `/r` URLs.                                                                                                       | [Registry](../registry.mdx)                      |\n| **tier**              | The level a token sits at: primitive (a raw value), semantic (a role) or component (a part). Components read the semantic and component tiers only.                                                                                              | [Theming](../theming.mdx)                        |\n| **twin**              | The `.md` version of a documentation page, served by appending `.md` to its URL. It is processed Markdown, not raw MDX.                                                                                                                          | [Agents and LLMs](../agents.mdx)                 |"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/reference/plain-english",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/reference/plain-english.md",
      "slug": [
        "reference",
        "plain-english"
      ],
      "section": "Reference",
      "title": "Plain English A to Z",
      "description": "The clinical words a reader meets, the plain words to use instead, and how Term shows them in your product.",
      "kind": "reference",
      "aliases": [
        "clinical vocabulary",
        "plain words",
        "clinical terms",
        "a to z",
        "glossary data"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "markdown": "Each entry maps a clinical term to the plain wording a writer uses instead. Every definition is written from scratch for opsinjs. Nothing is copied from the NHS A to Z, any other Crown-copyright source, a dictionary or a manufacturer's leaflet.\n\n## Choosing a plain word [#choosing-a-plain-word]\n\nA replacement passes four tests, in order:\n\n1. **Would someone say it out loud?** \"Raised\" passes. \"Elevated\" does not.\n2. **Does it lose anything the reader needs?** \"Water pill\" is plainer than \"diuretic\" and wrong, because the reader will not recognise it on the box. When plainness costs accuracy, use both words.\n3. **Will they meet the clinical term elsewhere?** If it is on their prescription, letter, portal or monitor, give the clinical term and the explanation once, then the plain form.\n4. **Is it the same word every time?** One clinical term maps to one plain replacement across the product.\n\n| Write                                                                              | Not                                                           |\n| ---------------------------------------------------------------------------------- | ------------------------------------------------------------- |\n| Your blood pressure was 148 over 92. Your GP might call the top number \"systolic\". | Your systolic BP was 148 mmHg and your diastolic was 92 mmHg. |\n| Long-term (lasting months or years)                                                | Chronic                                                       |\n| A steroid inhaler (sometimes called a \"preventer\")                                 | An inhaler                                                    |\n\nSome plain words make things worse.\n\n| Avoid                             | Use instead                                        |\n| --------------------------------- | -------------------------------------------------- |\n| water pill, for a diuretic        | the medicine's name, and what it does              |\n| sugar, for glucose in a result    | blood sugar once, then the measure's name          |\n| good cholesterol, bad cholesterol | the named fraction, and what a higher figure means |\n| passed away                       | died                                               |\n\n## Term in your product [#term-in-your-product]\n\n[Term](../components/term.mdx) shows a clinical word with its everyday meaning attached. It ships with an empty glossary. Your product passes its own entries to `TermGlossaryProvider` once, and each `<Term id>` looks one up. An id with no entry renders unmarked and warns in development.\n\n```tsx\nimport { Term, TermGlossaryProvider } from \"@/components/ui/term\"\n\n<TermGlossaryProvider glossary={GLOSSARY}>\n  <p>\n    An <Term id=\"acute\" /> problem started suddenly.\n  </p>\n</TermGlossaryProvider>\n```\n\nEach entry's `showBoth` says when the clinical term appears.\n\n| `showBoth`   | Behaviour                                                                                               |\n| ------------ | ------------------------------------------------------------------------------------------------------- |\n| `always`     | Both forms every time, so a reader can match the screen to their paperwork                              |\n| `first-use`  | Both forms the first time on a screen, then the plain wording alone. Express it with Term's `once` prop |\n| `plain-only` | The clinical term never reaches the reader. The entry tells authors what to write instead               |\n\nA definition says what a word is, in one sentence. It is never what to do, what the word means for this reader, or a reassurance. Review your glossary as clinical content, not as microcopy.\n\nTerm shows the clinical word with the plain wording attached, which is the reverse of `policy.rule` in `tokens/glossary.json`. That conflict is still open.\n\n## The A to Z [#the-a-to-z]\n\nThe list is authored in `tokens/glossary.json`, which also holds a `banned` list of words such as normal, elevated and don't worry, each with a replacement. Treat a change to a `plain` wording as a breaking change to copy, and record it in the [changelog](../changelog.mdx).\n\n<Glossary />"
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/contribute",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/contribute.md",
      "slug": [
        "contribute"
      ],
      "section": "Contribute",
      "title": "Contribute with Claude Code",
      "description": "A plain-language guide for clinicians and health scientists who want to improve opsinjs by asking Claude Code to make the change.",
      "kind": "guide",
      "aliases": [
        "contributing",
        "how to contribute",
        "first contribution",
        "non-developer guide"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-10-08",
      "markdown": "You do not need to be a software engineer. You describe the change in plain words, Claude Code makes it, and you check the result before anybody else sees it.\n\n## Who this is for [#who-this-is-for]\n\n1. You work in health: a doctor, a nurse, a pharmacist, a researcher or a student.\n2. You know a little React, or none at all.\n3. You have an idea, such as a calmer colour, larger text, or a component health apps keep needing.\n\n## What you need [#what-you-need]\n\n1. A free GitHub account.\n2. A Claude plan that includes Claude Code: Pro, Max, Team, Enterprise or a Console account. The free plan does not include it.\n3. A Mac, Windows or Linux computer, and about an hour for the first set-up.\n\n## How a change gets in [#how-a-change-gets-in]\n\n1. **Issue.** You describe the idea on GitHub, and a maintainer agrees the approach before anybody writes code.\n2. **Set up.** You copy the project to your computer. You do this once.\n3. **Plan.** You tell Claude Code what you want, and it writes a plan before it changes anything.\n4. **Change.** Claude Code makes the change on its own branch.\n5. **Check.** You look at the result in your browser, and Claude Code runs the project's checks.\n6. **Pull request.** Claude Code sends the change to GitHub for review.\n7. **Review.** A maintainer reads it, may ask for changes, and merges it.\n8. **Live.** The site updates a few minutes after the merge.\n\n## Read next [#read-next]\n\n| Page                                   | Read it                                                               |\n| -------------------------------------- | --------------------------------------------------------------------- |\n| [Set up once](./set-up.mdx)            | Before your first change                                              |\n| [Make a change](./make-a-change.mdx)   | For every change. It has the prompts to use                           |\n| [Three examples](./examples.mdx)       | To see a colour, a text size and a new component done start to finish |\n| [What not to do](./what-not-to-do.mdx) | Before your first change, and whenever you are unsure                 |\n\nThe rules every contributor follows are in [CONTRIBUTING.md](https://github.com/prashantonomy/opsinjs/blob/main/CONTRIBUTING.md)."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/contribute/examples",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/contribute/examples.md",
      "slug": [
        "contribute",
        "examples"
      ],
      "section": "Contribute",
      "title": "Three examples",
      "description": "A colour change, a text size change and a new component, each taken from the idea to a pull request with the prompts that do it.",
      "kind": "guide",
      "aliases": [
        "contribution examples",
        "example prompts",
        "worked examples"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-10-08",
      "markdown": "Each example follows [Make a change](./make-a-change.mdx). Replace issue #42 with your own issue number.\n\n## 1. \"This colour would look better\" [#1-this-colour-would-look-better]\n\nYou think the Sleep colour is too intense for a bedtime screen and want it calmer.\n\nWhat to know first:\n\n1. Colours are tokens. Each category colour, such as Sleep, Heart or Activity, is one seed in `apps/www/tokens/color.json` plus eleven shades worked out from it by a rule written in the same file.\n2. A category colour says what a reading is about. A status colour says how urgent it is. They must never look alike, so a category stays clear of the status hues, and red means urgent only. See [Two colour axes](../health/two-colour-axes.mdx).\n3. A token change reaches every app that uses opsinjs, so it starts with a proposal.\n\nThe steps:\n\n1. Open a proposal called \"Token change: a calmer Sleep colour\", with a screenshot and your reason.\n\n2. When it is agreed, ask for a plan:\n\n   ```text title=\"Prompt\"\n   For issue #42 I want the Sleep category colour calmer, meaning less\n   saturated. Do not change anything yet. Show me its seed and its eleven\n   shades in apps/www/tokens/color.json, explain the rule that turns the\n   seed into the shades, list the components and pages that use it, and\n   tell me how a change would affect contrast in light and dark mode.\n   ```\n\n3. Make the change:\n\n   ```text title=\"Prompt\"\n   Lower the chroma of the Sleep seed as agreed in issue #42, and recompute\n   all eleven Sleep shades with the ladder rule in color.json. Change\n   nothing else. Then run the generate and contrast scripts in apps/www,\n   and show me the Sleep contrast figures before and after. If any pair\n   falls below its floor, stop and tell me.\n   ```\n\n4. Look at the [colour browser](/colors) and a component page with a Sleep example, in light and dark mode. Make sure the new colour cannot be mistaken for a status colour.\n\n5. Run the checks and open the pull request with screenshots from before and after.\n\n## 2. \"This text should be a little bigger\" [#2-this-text-should-be-a-little-bigger]\n\nThe numbers at each end of a RangeBar are hard for older patients to read.\n\nWhat to know first:\n\n1. Text sizes are named steps in `apps/www/tokens/type.json`, from `largeTitle` down to `caption2`. A component picks a step and never sets a pixel size. The accessibility check fails if it does.\n2. Those end labels use `caption1`, the step for axis labels and legend text.\n3. There are two ways to make them bigger. Give the RangeBar labels a larger step, which changes one component. Or make `caption1` itself bigger, which changes every component that uses it and needs a proposal first.\n\nThe steps:\n\n1. Ask for a plan:\n\n   ```text title=\"Prompt\"\n   For issue #42: the numbers at each end of a RangeBar are hard to read\n   for older patients. Do not change anything yet. Tell me which text step\n   they use, which other components use the same step, and the two ways to\n   make them bigger, with what each one would change.\n   ```\n\n2. Choose the smaller change, unless the issue agreed the larger one:\n\n   ```text title=\"Prompt\"\n   Use the next larger text step for the end labels in the RangeBar\n   component only. Do not touch tokens/type.json. Keep each label on one\n   line, and update the RangeBar docs page if it names the step.\n   ```\n\n3. Check the RangeBar page at 100% and 200% text size, and in a window as narrow as a phone. The labels must stay readable and must never overlap or be cut off.\n\n4. Run the checks and open the pull request with screenshots at both text sizes.\n\n## 3. \"Health apps keep needing this, so make it a component\" [#3-health-apps-keep-needing-this-so-make-it-a-component]\n\nMany apps show a patient's next appointment, and you want a reusable card for it.\n\nWhat to know first:\n\n1. A new component is the biggest kind of change. Its proposal is agreed before anybody writes code.\n2. Something close may already exist. Check the [component list](../components/index.mdx) first, because two existing components together may already do the job.\n3. A component shows information. It never decides anything clinical, such as whether a missed appointment is urgent.\n\nThe steps:\n\n1. Check what exists:\n\n   ```text title=\"Prompt\"\n   I want a reusable card for a patient's next appointment: the date, the\n   time, the place and who it is with. Before writing any code, check\n   apps/www/registry/catalogue.ts and the component pages. Does a component\n   already do this, or could two existing ones be combined? Answer in plain\n   English.\n   ```\n\n2. If nothing fits, draft the proposal:\n\n   ```text title=\"Prompt\"\n   Draft a proposal for an appointment card, following\n   .github/ISSUE_TEMPLATE/proposal.yml. Say what it shows, what it must\n   never assert about somebody's health, and what happens when it is wrong,\n   for example when an appointment moves or is cancelled. Do not write any\n   code.\n   ```\n\n3. Post the proposal on GitHub and wait until a maintainer agrees it.\n\n4. Build it as agreed:\n\n   ```text title=\"Prompt\"\n   Build the appointment-card component as agreed in issue #42. Follow\n   AGENTS.md, copy the shape of apps/www/content/docs/components/button.mdx\n   for its page, and use made-up example data only. Then run the checks and\n   show me the preview.\n   ```\n\n5. Check the preview in light and dark mode, at phone width and at 200% text size, then open the pull request."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/contribute/make-a-change",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/contribute/make-a-change.md",
      "slug": [
        "contribute",
        "make-a-change"
      ],
      "section": "Contribute",
      "title": "Make a change",
      "description": "The steps for every change, from an idea to a merged pull request, with the prompt to give Claude Code at each step.",
      "kind": "guide",
      "aliases": [
        "contribution workflow",
        "plan mode",
        "open a pull request"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-10-08",
      "markdown": "Follow these steps for every change. Claude Code does the typing. You make the decisions and check the result.\n\n## The steps [#the-steps]\n\n1. **Start with an issue.** A typo or a broken link needs none. A colour, a text size or a new component needs a [proposal](https://github.com/prashantonomy/opsinjs/issues/new?template=proposal.yml) first, and you wait until a maintainer agrees the approach. Write the clinical reason in your own words, because that is the part only you can supply.\n\n2. **Start fresh.** In your `opsinjs` folder, run `claude`. Between two unrelated tasks, type `/clear`.\n\n3. **Get the latest code and a branch.**\n\n   ```text title=\"Prompt\"\n   Update my fork's main branch from prashantonomy/opsinjs, then create a\n   new branch for issue #42.\n   ```\n\n4. **Ask for a plan first.** Press Shift+Tab until the status bar shows plan mode. Claude then reads and plans without changing anything.\n\n   ```text title=\"Prompt\"\n   For issue #42 I want to <describe your change>. Do not change anything\n   yet. Find the files involved, explain in plain English what you would\n   change and why, and tell me what could go wrong.\n   ```\n\n5. **Read the plan.** Ask about anything you do not understand, and correct anything that is wrong, before you approve it.\n\n6. **Let Claude make the change.** It asks before it edits a file or runs a command. If you are not sure what a command does, ask before you approve it.\n\n7. **Look at the result.** With `pnpm dev` running, open the page in your browser. Check light and dark mode, a window as narrow as a phone, and 200% text size with the switches on each preview.\n\n8. **Run the checks.**\n\n   ```text title=\"Prompt\"\n   Run pnpm typecheck, pnpm lint and pnpm check. If anything fails, explain\n   it in plain English and fix the cause. Never change a check to make it\n   pass.\n   ```\n\n9. **Open the pull request.**\n\n   ```text title=\"Prompt\"\n   Commit this with a Conventional Commits message, push the branch to my\n   fork, and open a pull request against prashantonomy/opsinjs. Fill in the\n   pull request template and write \"Closes #42\" in it.\n   ```\n\n10. **Answer the review.** Paste each review comment into Claude, ask it to make the change, check the result again, and ask it to push to the same branch. The pull request updates by itself.\n\n11. **Undo when you need to.** Press Esc twice, or type `/rewind`, to go back to an earlier point. Git keeps everything you committed.\n\n## Best practices [#best-practices]\n\n1. **One idea per pull request.** Two small pull requests are reviewed faster than one large one.\n2. **Be specific.** Name the page, the component, what you see and what you want. \"The numbers at the ends of the range bar are hard to read at arm's length\" beats \"make the text bigger\".\n3. **Plan before every change.** A wrong plan costs a minute. A wrong change costs an afternoon.\n4. **Make Claude show its work.** Ask for the checks, a screenshot, or the values before and after.\n5. **Ask why.** If Claude cannot explain a change in plain English, do not submit it.\n6. **Start again when stuck.** If you have corrected Claude twice on the same thing, type `/clear` and ask again with a more specific prompt.\n7. **Keep the issue up to date.** Write down what you decided and why, so the reviewer does not have to guess.\n\nBefore your first change, read [What not to do](./what-not-to-do.mdx)."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/contribute/set-up",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/contribute/set-up.md",
      "slug": [
        "contribute",
        "set-up"
      ],
      "section": "Contribute",
      "title": "Set up once",
      "description": "Install the tools, copy opsinjs to your computer and start Claude Code. You do this once, and it takes about an hour.",
      "kind": "guide",
      "aliases": [
        "contributor setup",
        "install claude code",
        "fork and clone"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-10-08",
      "markdown": "Do these steps in order. Open the Terminal app on a Mac, or PowerShell on Windows, type each command and press Enter. Once Claude Code is installed, you can paste any error into it and ask what went wrong.\n\n## 1. Accounts [#1-accounts]\n\n1. Create a free account at [github.com](https://github.com/signup).\n2. Check that your Claude plan includes Claude Code: Pro, Max, Team, Enterprise or a Console account.\n\n## 2. Tools [#2-tools]\n\n1. **Git** keeps track of every change. On a Mac, run `xcode-select --install`. On Windows, install [Git for Windows](https://git-scm.com/download/win).\n2. **Node.js 24** runs the site. Install it from [nodejs.org](https://nodejs.org), then check it with `node --version`.\n3. **GitHub CLI** lets Claude Code work with GitHub. Install it from [cli.github.com](https://cli.github.com), then run `gh auth login` and accept the suggested answers.\n4. **Claude Code** makes the changes. On a Mac or Linux:\n\n   ```bash\n   curl -fsSL https://claude.ai/install.sh | bash\n   ```\n\n   On Windows, in PowerShell:\n\n   ```powershell\n   irm https://claude.ai/install.ps1 | iex\n   ```\n\n   Check it with `claude --version`. New to the terminal? Anthropic's [terminal guide](https://code.claude.com/docs/en/terminal-guide) starts from the beginning.\n\n## 3. Your copy of opsinjs [#3-your-copy-of-opsinjs]\n\n1. Make your own copy on GitHub, called a fork, and download it:\n\n   ```bash\n   gh repo fork prashantonomy/opsinjs --clone\n   cd opsinjs\n   ```\n\n2. Install the project's packages. If you are asked to download pnpm, type `Y`. If `corepack` is not found, run `npm install --global corepack@latest` first. On Windows, run `corepack enable` in PowerShell opened as administrator.\n\n   ```bash\n   corepack enable\n   pnpm install\n   ```\n\n3. Start the docs site:\n\n   ```bash\n   pnpm dev\n   ```\n\n4. Open `http://localhost:4000` in your browser. You should see these docs. Leave this window open while you work, and press Ctrl+C in it when you want to stop the site.\n\n## 4. Claude Code [#4-claude-code]\n\n1. Open a second terminal window, go to the same folder with `cd opsinjs`, and run `claude`. Sign in the first time.\n\n2. Check that it has read the project's rules:\n\n   ```text title=\"Prompt\"\n   Read CLAUDE.md and AGENTS.md. In five short sentences of plain English,\n   tell me what this project is and the rules you must follow when you\n   change it.\n   ```\n\n3. If the answer mentions tokens, the two colour axes and never inventing evidence, you are ready.\n\nPrefer a window to a terminal? The [VS Code extension](https://code.claude.com/docs/en/vs-code) runs the same Claude Code in a panel. Next, read [Make a change](./make-a-change.mdx)."
    },
    {
      "url": "https://opsinjs.pensievelabs.org/docs/contribute/what-not-to-do",
      "markdownUrl": "https://opsinjs.pensievelabs.org/docs/contribute/what-not-to-do.md",
      "slug": [
        "contribute",
        "what-not-to-do"
      ],
      "section": "Contribute",
      "title": "What not to do",
      "description": "The mistakes that matter most in a design system for health apps, each with what to do instead. Read it before your first change.",
      "kind": "guide",
      "aliases": [
        "contributor mistakes",
        "contribution rules",
        "do and do not"
      ],
      "implements": [],
      "governedBy": [],
      "usedIn": [],
      "reviewed": "2026-10-08",
      "markdown": "Patients read what opsinjs draws, so some mistakes here can mislead a person about their own health. These rules are not optional, and each one says what to do instead.\n\n## Patient safety [#patient-safety]\n\n1. **Do not let a component judge a reading.** No component decides whether a number is high, low or dangerous, and no screen gives medical advice. Show the value, and leave its meaning to the product that uses opsinjs. See [Health](../health/index.mdx).\n2. **Do not mix the two colour axes.** A category colour says what a reading is about, and a status colour says how urgent it is. They never share one element, and red means urgent only. Give each element one axis. See [Two colour axes](../health/two-colour-axes.mdx).\n3. **Do not show a status by colour alone.** Every status needs its word, and an icon where there is room. Use the StatusPill component, or the status word the system supplies.\n4. **Do not soften clinical wording.** \"Nothing to worry about\" is a clinical claim, not friendlier copy. Use the wording in [Writing](../foundations/writing.mdx).\n5. **Do not invent evidence.** No made-up study, statistic, guideline or reference, from you or from Claude. Check every reference Claude suggests, and label an opinion as an opinion.\n6. **Do not claim a review that has not happened.** Never write \"clinically validated\", \"meets WCAG\" or \"safe for patients\". Say what was checked, and who checked it.\n\n## Data and security [#data-and-security]\n\n7. **Do not put real patient data anywhere.** Not in code, an example, a screenshot, an issue or a prompt. Use made-up names and values.\n8. **Do not share a secret.** Never paste a password, an API key or a token into Claude, an issue or a commit. If one slips out, cancel it at once with the service that issued it.\n9. **Do not copy protected text.** Cite NHS and other Crown copyright text, and write your own words rather than pasting it.\n10. **Do not approve a command you do not understand.** Ask Claude \"what does this command do?\" first. Never start Claude Code with `--dangerously-skip-permissions`, which turns every safety prompt off.\n\n## Code and process [#code-and-process]\n\n11. **Do not type raw values.** No hex colour such as `#3b82f6` and no pixel size such as `14px` in a component. Use a token, or change the token through a proposal.\n12. **Do not change a check to make it pass.** If `pnpm check` fails, fix what it found. A check that is edited or switched off hides the problem from everybody after you.\n13. **Do not edit a generated file.** Change its source and regenerate. AGENTS.md section 7 lists which files are generated.\n14. **Do not start a big change without an agreed issue.** A colour, a text size or a new component starts with a proposal.\n15. **Do not bundle ideas.** Put one idea in each pull request.\n16. **Do not submit what you have not looked at.** Open the change in your browser in light and dark mode, at phone width and at 200% text size.\n17. **Do not push to `main`.** Work on a branch in your fork and open a pull request.\n18. **Do not use em dashes or en dashes.** The build fails on U+2014 and U+2013. Ask Claude to rewrite the sentence instead."
    }
  ]
}
