---
title: "Types"
description: "Every TypeScript symbol this documentation site's own lib/ exports, with a page of its own for each type and interface."
url: "https://opsinjs.pensievelabs.org/docs/reference/generated/types"
source: "https://opsinjs.pensievelabs.org/docs/reference/generated/types.md"
section: "Reference"
kind: "reference"
reviewed: "2026-09-02"
reviewer: "engineering"
aliases: ["exported types", "TypeScript API", "ClinicalStatus", "HealthCategory"]
---

> Elements written as `<PascalCase … />` below are opsinjs documentation
> components. Their attributes are the content: the values they render are
> generated from `tokens/*.json` and `registry/catalogue.ts` and are
> published separately at https://opsinjs.pensievelabs.org/r/index.json and under the Reference
> section.
> Nothing is missing from this page. The data simply does not live in
> the prose.

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.

These 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.

{/* opsinjs:generated:begin - everything below is replaced by scripts/build-reference.mts */}

## Exported symbols [#exported-symbols]

| Symbol                                                | Kind      | Declared in             | Summary                                                                                                                                                                                                                                                                                                                   |
| ----------------------------------------------------- | --------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `absoluteUrl`                                         | function  | `lib/routes.ts`         | Turn a root-relative path into a full URL on the canonical origin.                                                                                                                                                                                                                                                        |
| `agentRoutes`                                         | const     | `lib/routes.ts`         | -                                                                                                                                                                                                                                                                                                                         |
| `aliasesFor`                                          | function  | `lib/catalogue.ts`      | The exact array a page's `aliases` frontmatter must contain.                                                                                                                                                                                                                                                              |
| `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.                                                                                                                                                                     |
| [`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.                                                                                                                                                                                                |
| `apca`                                                | const     | `lib/color/apca.ts`     | The short name, for callers that just want the number: `apca("#333", "#fff")`. Identical to `apcaContrast`.                                                                                                                                                                                                               |
| `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.                                                                                                       |
| `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.                                                                                                                                                                                   |
| `apcaContrastOklch`                                   | function  | `lib/color/apca.ts`     | The same, taking OKLCH. Both colours are clamped into sRGB first, because that is what a screen shows.                                                                                                                                                                                                                    |
| `apcaVerdict`                                         | function  | `lib/color/apca.ts`     | -                                                                                                                                                                                                                                                                                                                         |
| [`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.                                                                                                                                                                             |
| `apiRoutes`                                           | const     | `lib/routes.ts`         | -                                                                                                                                                                                                                                                                                                                         |
| `apiSymbolPath`                                       | function  | `lib/routes.ts`         | A type's section on the generated Types page. `\<ApiLink\>` resolves here.                                                                                                                                                                                                                                                |
| `axisConflict`                                        | function  | `lib/status.ts`         | THE NEVER-MIX RULE, as a function.                                                                                                                                                                                                                                                                                        |
| [`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.                                                                                                                                                                                                |
| `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`.                                                                                                                                                                                                        |
| `baseOptions`                                         | function  | `lib/layout.shared.tsx` | THERE IS NO TOP NAVIGATION, AND THAT IS THE POINT.                                                                                                                                                                                                                                                                        |
| `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.                                                                                                                                                                                 |
| `builtComponentCount`                                 | function  | `lib/registry.ts`       | How many distinct components have a real renderable behind them.                                                                                                                                                                                                                                                          |
| `byNamespace`                                         | function  | `lib/tokens.ts`         | -                                                                                                                                                                                                                                                                                                                         |
| `byTier`                                              | function  | `lib/tokens.ts`         | -                                                                                                                                                                                                                                                                                                                         |
| [`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.                                                                                                                                                                                                  |
| `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.                                                                                                  |
| `CHROMA_ENVELOPE`                                     | const     | `lib/color/derive.ts`   | Chroma as a fraction of the seed's, per step. Mirrors `chromaEnvelope` in tokens/color.json.                                                                                                                                                                                                                              |
| `CHROMA_STEP`                                         | const     | `lib/preset.ts`         | The quantisation of chroma: 0.005 per step, so 63 steps reach 0.315.                                                                                                                                                                                                                                                      |
| `clampToGamut`                                        | function  | `lib/color/oklch.ts`    | Bring a colour into gamut by reducing chroma only.                                                                                                                                                                                                                                                                        |
| `CLINICAL_STATUS_META`                                | const     | `lib/status.ts`         | -                                                                                                                                                                                                                                                                                                                         |
| `CLINICAL_STATUSES`                                   | const     | `lib/status.ts`         | -                                                                                                                                                                                                                                                                                                                         |
| [`ClinicalStatus`](#clinicalstatus)                   | type      | `lib/status.ts`         | What a reading means and what, if anything, to do about it.                                                                                                                                                                                                                                                               |
| [`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.                                                                                                                                                                          |
| [`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.                                                                                                                                                                                                   |
| `cn`                                                  | function  | `lib/utils.ts`          | Join and de-duplicate class names, resolving Tailwind conflicts last-wins.                                                                                                                                                                                                                                                |
| `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.                                                                                                                                                                                                                    |
| [`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)`).                                                                                                                                                                    |
| `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.                                                                                             |
| `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.                    |
| `componentPath`                                       | function  | `lib/routes.ts`         | A component specification page, by catalogue id.                                                                                                                                                                                                                                                                          |
| `componentRequiredSections`                           | function  | `lib/status.ts`         | The sections a component page must carry: its outline minus the optional ones.                                                                                                                                                                                                                                            |
| `componentSections`                                   | function  | `lib/status.ts`         | The outline for one component page, with the category gate applied.                                                                                                                                                                                                                                                       |
| `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.                                                                                                                                                                              |
| `CONTRAST_USE_LABELS`                                 | const     | `lib/color/apca.ts`     | -                                                                                                                                                                                                                                                                                                                         |
| [`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.                                                                                                                                                                                |
| `contrastRatio`                                       | function  | `lib/color/wcag.ts`     | The contrast ratio, from 1 (identical) to 21 (black on white).                                                                                                                                                                                                                                                            |
| `contrastRatioOklch`                                  | function  | `lib/color/wcag.ts`     | -                                                                                                                                                                                                                                                                                                                         |
| [`ContrastUse`](#contrastuse)                         | type      | `lib/color/apca.ts`     | What a pair is being used for. Determines which floor applies.                                                                                                                                                                                                                                                            |
| `convertUnit`                                         | function  | `lib/opsinjs.ts`        | One value in another unit, or `undefined` when this system does not own the factor.                                                                                                                                                                                                                                       |
| `CORNER_SHAPE_VALUES`                                 | const     | `lib/preset.ts`         | -                                                                                                                                                                                                                                                                                                                         |
| `CVD_LABELS`                                          | const     | `lib/color/cvd.ts`      | -                                                                                                                                                                                                                                                                                                                         |
| `CVD_TYPES`                                           | const     | `lib/color/cvd.ts`      | -                                                                                                                                                                                                                                                                                                                         |
| [`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.                                                                                                                                                                                      |
| [`CvdType`](#cvdtype)                                 | type      | `lib/color/cvd.ts`      | The three dichromacies, plus the achromatic check every specimen must also survive.                                                                                                                                                                                                                                       |
| [`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.                                                                                                                                                                                                |
| [`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.                                                                                                                                                                                     |
| `decodePreset`                                        | function  | `lib/preset.ts`         | Decode a preset code.                                                                                                                                                                                                                                                                                                     |
| [`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.                                                                                                                                                                                                  |
| `decodeTransfer`                                      | function  | `lib/color/oklch.ts`    | sRGB gamma-encoded channel → light-linear. Also used for Display-P3, which shares sRGB's transfer curve.                                                                                                                                                                                                                  |
| `DEFAULT_BASE`                                        | const     | `lib/registry.ts`       | -                                                                                                                                                                                                                                                                                                                         |
| `DEFAULT_BASE`                                        | const     | `lib/routes.ts`         | -                                                                                                                                                                                                                                                                                                                         |
| `DEFAULT_PRESET`                                      | const     | `lib/preset.ts`         | -                                                                                                                                                                                                                                                                                                                         |
| `DEFAULT_STYLE`                                       | const     | `lib/registry.ts`       | -                                                                                                                                                                                                                                                                                                                         |
| `DEFAULT_STYLE`                                       | const     | `lib/routes.ts`         | -                                                                                                                                                                                                                                                                                                                         |
| `DENSITY_VALUES`                                      | const     | `lib/preset.ts`         | -                                                                                                                                                                                                                                                                                                                         |
| `deprecatedTokens`                                    | function  | `lib/tokens.ts`         | -                                                                                                                                                                                                                                                                                                                         |
| [`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.                                                                                                                                                               |
| [`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.                                                                                                                                                                                                 |
| `deriveRamp`                                          | function  | `lib/color/derive.ts`   | Build one ramp from a seed, clamping to sRGB and recording the P3 enhancement.                                                                                                                                                                                                                                            |
| `deriveTheme`                                         | function  | `lib/color/derive.ts`   | Derive a complete, contrast-validated theme from one brand colour.                                                                                                                                                                                                                                                        |
| [`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.                                                                                                                                                                                                                               |
| [`Detent`](#detent)                                   | type      | `lib/opsinjs.ts`        | How far a sheet is open.                                                                                                                                                                                                                                                                                                  |
| `displayP3ToOklch`                                    | function  | `lib/color/oklch.ts`    | Gamma-encoded Display-P3, 0 to 1 per channel → OKLCH.                                                                                                                                                                                                                                                                     |
| `DOCS_BASE`                                           | const     | `lib/routes.ts`         | The docs base segment. Everything else derives from it.                                                                                                                                                                                                                                                                   |
| `docsMarkdownPath`                                    | function  | `lib/routes.ts`         | The same page as processed markdown: `/docs/components/range-bar.md`.                                                                                                                                                                                                                                                     |
| [`DocsNav`](#docsnav)                                 | interface | `lib/docs-nav.ts`       | -                                                                                                                                                                                                                                                                                                                         |
| `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.                                                                                                                                                                              |
| `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.                                                                                                                                                                       |
| `editUrl`                                             | function  | `lib/routes.ts`         | "Edit this page" on GitHub, from a source file path relative to the content root.                                                                                                                                                                                                                                         |
| `encodePreset`                                        | function  | `lib/preset.ts`         | Encode a theme as a preset code.                                                                                                                                                                                                                                                                                          |
| `encodeTransfer`                                      | function  | `lib/color/oklch.ts`    | Light-linear channel → gamma-encoded.                                                                                                                                                                                                                                                                                     |
| `EXAMPLE_SOURCE`                                      | const     | `lib/opsinjs.ts`        | The only citation an opsinjs example, demo or preview may carry.                                                                                                                                                                                                                                                          |
| `explainUnresolved`                                   | function  | `lib/registry.ts`       | Explain an empty lookup.                                                                                                                                                                                                                                                                                                  |
| `findAliasProblems`                                   | function  | `lib/catalogue.ts`      | The uniqueness check, as a function rather than as a comment.                                                                                                                                                                                                                                                             |
| `findByAlias`                                         | function  | `lib/catalogue.ts`      | -                                                                                                                                                                                                                                                                                                                         |
| `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.                                                                                                                                 |
| `findUnit`                                            | function  | `lib/opsinjs.ts`        | The unit a symbol names, or `undefined` when this system has never heard of it.                                                                                                                                                                                                                                           |
| `fit`                                                 | function  | `lib/color/derive.ts`   | Fit an arbitrary colour into the shipped gamut without moving its hue or lightness.                                                                                                                                                                                                                                       |
| `FLOOR_VALUES`                                        | const     | `lib/preset.ts`         | Which APCA floor the theme is validated against. `standard` is the published one.                                                                                                                                                                                                                                         |
| `FORMAT_VERSION`                                      | const     | `lib/preset.ts`         | Bump this, and add a decode branch, whenever a field changes shape.                                                                                                                                                                                                                                                       |
| `formatDisplayP3`                                     | function  | `lib/color/oklch.ts`    | `color(display-p3 0.9 0.2 0.3)`. Channels are clamped, because this is an output format.                                                                                                                                                                                                                                  |
| `formatHex`                                           | function  | `lib/color/oklch.ts`    | `#rrggbb`, clamped into sRGB.                                                                                                                                                                                                                                                                                             |
| `formatOklch`                                         | function  | `lib/color/oklch.ts`    | `oklch(0.622 0.17 15)`, or with an alpha, `oklch(0.622 0.17 15 / 0.5)`.                                                                                                                                                                                                                                                   |
| `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.                                                                                                                                                                                       |
| `formatToken`                                         | function  | `lib/tokens.ts`         | Render a token in one of the copyable formats.                                                                                                                                                                                                                                                                            |
| `foundationsPath`                                     | function  | `lib/routes.ts`         | -                                                                                                                                                                                                                                                                                                                         |
| [`Gamut`](#gamut)                                     | type      | `lib/color/oklch.ts`    | The colour spaces this module can express a colour in.                                                                                                                                                                                                                                                                    |
| `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.                                                                                                                   |
| `GAMUT_VALUES`                                        | const     | `lib/preset.ts`         | -                                                                                                                                                                                                                                                                                                                         |
| [`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.                                                                                                                                                                                                        |
| `getAllPages`                                         | function  | `lib/source.ts`         | Every page in the corpus. The input to the sitemap, llms.txt and the shards.                                                                                                                                                                                                                                              |
| `getByCategory`                                       | function  | `lib/catalogue.ts`      | -                                                                                                                                                                                                                                                                                                                         |
| `getByStatus`                                         | function  | `lib/catalogue.ts`      | -                                                                                                                                                                                                                                                                                                                         |
| `getCatalogue`                                        | function  | `lib/catalogue.ts`      | Every row.                                                                                                                                                                                                                                                                                                                |
| `getDocsNav`                                          | function  | `lib/docs-nav.ts`       | -                                                                                                                                                                                                                                                                                                                         |
| `getEntry`                                            | function  | `lib/catalogue.ts`      | -                                                                                                                                                                                                                                                                                                                         |
| `getPage`                                             | function  | `lib/source.ts`         | One page by its slug segments, or undefined.                                                                                                                                                                                                                                                                              |
| `getPagesInSection`                                   | function  | `lib/source.ts`         | Pages under one top-level section, in tree order.                                                                                                                                                                                                                                                                         |
| `getPageTree`                                         | function  | `lib/source.ts`         | The page tree the docs layout renders.                                                                                                                                                                                                                                                                                    |
| `getRegistryEntry`                                    | function  | `lib/registry.ts`       | Resolve one entry, or null.                                                                                                                                                                                                                                                                                               |
| `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.                                                                                                                                                                                       |
| `getToken`                                            | function  | `lib/tokens.ts`         | -                                                                                                                                                                                                                                                                                                                         |
| `getTokens`                                           | function  | `lib/tokens.ts`         | -                                                                                                                                                                                                                                                                                                                         |
| `grouped`                                             | function  | `lib/tokens.ts`         | Tokens grouped for a table: namespace → group → tokens, in emit order.                                                                                                                                                                                                                                                    |
| `groupedByCategory`                                   | function  | `lib/catalogue.ts`      | Every category that has at least one row, in the declared order, with its rows.                                                                                                                                                                                                                                           |
| `hasComponentPage`                                    | function  | `lib/catalogue.ts`      | True when `/docs/components/\<id\>` resolves to a page.                                                                                                                                                                                                                                                                   |
| `HEALTH_CATEGORIES`                                   | const     | `lib/status.ts`         | -                                                                                                                                                                                                                                                                                                                         |
| `HEALTH_CATEGORY_LABELS`                              | const     | `lib/status.ts`         | -                                                                                                                                                                                                                                                                                                                         |
| [`HealthCategory`](#healthcategory)                   | type      | `lib/status.ts`         | What a reading is ABOUT. Identity, never verdict.                                                                                                                                                                                                                                                                         |
| `healthPath`                                          | function  | `lib/routes.ts`         | A health doctrine page, by the page id that `governedBy` and `implements` use.                                                                                                                                                                                                                                            |
| `inGamut`                                             | function  | `lib/color/oklch.ts`    | -                                                                                                                                                                                                                                                                                                                         |
| `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.                                                                                                                |
| `isClinicalStatus`                                    | function  | `lib/status.ts`         | -                                                                                                                                                                                                                                                                                                                         |
| `isDevelopment`                                       | function  | `lib/opsinjs.ts`        | True in development, and false wherever that cannot be established.                                                                                                                                                                                                                                                       |
| `isHealthCategory`                                    | function  | `lib/catalogue.ts`      | True for the four `health-*` categories, which carry the extra clinical obligations.                                                                                                                                                                                                                                      |
| `isHealthCategory`                                    | function  | `lib/status.ts`         | -                                                                                                                                                                                                                                                                                                                         |
| `isKind`                                              | function  | `lib/status.ts`         | -                                                                                                                                                                                                                                                                                                                         |
| `isKnownId`                                           | function  | `lib/catalogue.ts`      | Does this id exist at all, under any status?                                                                                                                                                                                                                                                                              |
| `isNotImplemented`                                    | function  | `lib/status.ts`         | True when a page at this status must carry a not-implemented marker.                                                                                                                                                                                                                                                      |
| `isResolvable`                                        | function  | `lib/registry.ts`       | True when the id exists in the catalogue, whatever its status. Used to decide 404 from "no".                                                                                                                                                                                                                              |
| `isStatus`                                            | function  | `lib/status.ts`         | -                                                                                                                                                                                                                                                                                                                         |
| `issueUrl`                                            | function  | `lib/routes.ts`         | A prefilled docs issue. Used by `\<Feedback\>` when the feedback endpoint is unavailable.                                                                                                                                                                                                                                 |
| `joinPath`                                            | function  | `lib/routes.ts`         | Join path segments into a root-relative path, dropping empties and stray slashes.                                                                                                                                                                                                                                         |
| [`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.                                                                                                                                                                    |
| `KINDS`                                               | const     | `lib/status.ts`         | -                                                                                                                                                                                                                                                                                                                         |
| `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.                  |
| `LIGHTNESS_STEP`                                      | const     | `lib/preset.ts`         | The quantisation of lightness: 1% per step.                                                                                                                                                                                                                                                                               |
| `linearP3ToLinearSrgb`                                | function  | `lib/color/oklch.ts`    | Light-linear Display-P3 → light-linear sRGB, through XYZ (D65).                                                                                                                                                                                                                                                           |
| `linearSrgbToLinearP3`                                | function  | `lib/color/oklch.ts`    | Light-linear sRGB → light-linear Display-P3, through XYZ (D65).                                                                                                                                                                                                                                                           |
| `linearSrgbToOklab`                                   | function  | `lib/color/oklch.ts`    | Light-linear sRGB → OKLab. Ottosson's forward matrices.                                                                                                                                                                                                                                                                   |
| `linearToSrgb`                                        | function  | `lib/color/oklch.ts`    | -                                                                                                                                                                                                                                                                                                                         |
| `listBases`                                           | function  | `lib/registry.ts`       | -                                                                                                                                                                                                                                                                                                                         |
| `listByKind`                                          | function  | `lib/registry.ts`       | Every entry of a kind, for the examples gallery and the screens index.                                                                                                                                                                                                                                                    |
| `listStyles`                                          | function  | `lib/registry.ts`       | -                                                                                                                                                                                                                                                                                                                         |
| [`MaterialRung`](#materialrung)                       | type      | `lib/opsinjs.ts`        | A rung of the material ladder, meaning how a surface sits above what is behind it.                                                                                                                                                                                                                                        |
| `maxChroma`                                           | function  | `lib/color/oklch.ts`    | The largest chroma that is still inside `gamut` at this lightness and hue.                                                                                                                                                                                                                                                |
| `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.                                                                                                                                               |
| `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.                                                                                                                                                                         |
| `MODE_VALUES`                                         | const     | `lib/preset.ts`         | The colour mode a theme opens in. `system` follows the reader's own setting.                                                                                                                                                                                                                                              |
| [`NavGroup`](#navgroup)                               | interface | `lib/docs-nav.ts`       | -                                                                                                                                                                                                                                                                                                                         |
| [`NavHeading`](#navheading)                           | interface | `lib/docs-nav.ts`       | -                                                                                                                                                                                                                                                                                                                         |
| [`NavLink`](#navlink)                                 | interface | `lib/docs-nav.ts`       | -                                                                                                                                                                                                                                                                                                                         |
| [`NavSection`](#navsection)                           | interface | `lib/docs-nav.ts`       | -                                                                                                                                                                                                                                                                                                                         |
| `NEUTRAL_CHROMA_VALUES`                               | const     | `lib/preset.ts`         | Chroma of the neutral ramp. Index 0 is a dead grey; the default is index 2.                                                                                                                                                                                                                                               |
| `ogUrl`                                               | function  | `lib/routes.ts`         | The OG image service. One endpoint for the whole site. There is no per-route opengraph-image.                                                                                                                                                                                                                             |
| [`Oklab`](#oklab)                                     | interface | `lib/color/oklch.ts`    | A colour in OKLab.                                                                                                                                                                                                                                                                                                        |
| `oklabToLinearSrgb`                                   | function  | `lib/color/oklch.ts`    | OKLab → light-linear sRGB. Ottosson's inverse matrices.                                                                                                                                                                                                                                                                   |
| `oklabToOklch`                                        | function  | `lib/color/oklch.ts`    | -                                                                                                                                                                                                                                                                                                                         |
| [`Oklch`](#oklch)                                     | interface | `lib/color/oklch.ts`    | A colour in OKLCH. `l` 0 to 1, `c` unbounded, `h` in degrees.                                                                                                                                                                                                                                                             |
| `oklchToDisplayP3`                                    | function  | `lib/color/oklch.ts`    | OKLCH → gamma-encoded Display-P3, 0 to 1 per channel. Not clamped.                                                                                                                                                                                                                                                        |
| `oklchToOklab`                                        | function  | `lib/color/oklch.ts`    | -                                                                                                                                                                                                                                                                                                                         |
| `oklchToRgb255`                                       | function  | `lib/color/oklch.ts`    | OKLCH → 0 to 255 sRGB integers, clamped. The input for both contrast models.                                                                                                                                                                                                                                              |
| `oklchToSrgb`                                         | function  | `lib/color/oklch.ts`    | OKLCH → gamma-encoded sRGB, 0 to 1 per channel. Not clamped.                                                                                                                                                                                                                                                              |
| `OPSIN_ERRORS`                                        | const     | `lib/opsinjs.ts`        | The table `warnOnce()` reads. Generated from `tokens/errors.json`.                                                                                                                                                                                                                                                        |
| [`OpsinError`](#opsinerror)                           | interface | `lib/opsinjs.ts`        | One warning code: what it is called, how severe it is, and the page that prevents it.                                                                                                                                                                                                                                     |
| [`OpsinErrorCode`](#opsinerrorcode)                   | type      | `lib/opsinjs.ts`        | Every warning code opsinjs can emit.                                                                                                                                                                                                                                                                                      |
| [`OpsinErrorParams`](#opsinerrorparams)               | type      | `lib/opsinjs.ts`        | The values a message template asks for, keyed by placeholder name.                                                                                                                                                                                                                                                        |
| [`OpsinErrorSeverity`](#opsinerrorseverity)           | type      | `lib/opsinjs.ts`        | How severe a warning is.                                                                                                                                                                                                                                                                                                  |
| `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.                                                                                                                                                                                                                       |
| `OUTLINE_IS_EXACT`                                    | const     | `lib/status.ts`         | No kind other than `component` has an exact outline.                                                                                                                                                                                                                                                                      |
| `P3_CHROMA_GAIN`                                      | const     | `lib/color/derive.ts`   | How much more chroma Display-P3 is allowed to spend than sRGB at the same step.                                                                                                                                                                                                                                           |
| `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.           |
| `parseHex`                                            | function  | `lib/color/oklch.ts`    | `#rgb`, `#rrggbb` or `#rrggbbaa` → sRGB 0 to 1. Returns null on anything else.                                                                                                                                                                                                                                            |
| `passesApca`                                          | function  | `lib/color/apca.ts`     | -                                                                                                                                                                                                                                                                                                                         |
| [`Preset`](#preset)                                   | interface | `lib/preset.ts`         | A theme as a person describes it. What `encodePreset` takes and `decodePreset` returns.                                                                                                                                                                                                                                   |
| `PRESET_PREFIX`                                       | const     | `lib/preset.ts`         | -                                                                                                                                                                                                                                                                                                                         |
| `presetBrandColor`                                    | function  | `lib/preset.ts`         | The brand colour a preset describes, as an `oklch()` string the colour engine can parse.                                                                                                                                                                                                                                  |
| `RADIUS_VALUES`                                       | const     | `lib/preset.ts`         | `--opsin-radius-base` in px. Index 3 (14px) is the product default.                                                                                                                                                                                                                                                       |
| [`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.                                                                                                                                                                                         |
| `RAMP_LIGHTNESS`                                      | const     | `lib/color/derive.ts`   | -                                                                                                                                                                                                                                                                                                                         |
| `RAMP_STEPS`                                          | const     | `lib/color/derive.ts`   | The ramp steps, and the lightness of each. Mirrors `ladder` in tokens/color.json.                                                                                                                                                                                                                                         |
| [`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.                                                                                                                                                                          |
| [`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.                                                                                                                                                                              |
| `referencePath`                                       | function  | `lib/routes.ts`         | -                                                                                                                                                                                                                                                                                                                         |
| [`ReferenceRange`](#referencerange)                   | interface | `lib/opsinjs.ts`        | The interval a reading is being compared against, and who says so.                                                                                                                                                                                                                                                        |
| `REFUSED_CONVERSIONS`                                 | const     | `lib/opsinjs.ts`        | Conversions this system refuses to publish, and why. Generated from `tokens/units.json`.                                                                                                                                                                                                                                  |
| [`RefusedConversion`](#refusedconversion)             | interface | `lib/opsinjs.ts`        | A pair people expect to be arithmetic and is not, with the reason.                                                                                                                                                                                                                                                        |
| `registryInstallUrl`                                  | function  | `lib/routes.ts`         | What a consumer types to install an item. Rendered by `\<ComponentInstall\>`.                                                                                                                                                                                                                                             |
| [`RegistryLookup`](#registrylookup)                   | type      | `lib/registry.ts`       | Both call shapes are supported on purpose.                                                                                                                                                                                                                                                                                |
| `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.                                                                    |
| [`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.                                                                                                                                                                                               |
| `registryRoutes`                                      | const     | `lib/routes.ts`         | -                                                                                                                                                                                                                                                                                                                         |
| `relativeLuminance`                                   | function  | `lib/color/wcag.ts`     | WCAG 2.2 relative luminance, 0 for black and 1 for white.                                                                                                                                                                                                                                                                 |
| `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. |
| `REVIEW_FLOOR_NOTICE`                                 | const     | `lib/status.ts`         | THE REVIEW FLOOR, AS ONE STRING.                                                                                                                                                                                                                                                                                          |
| [`Rgb`](#rgb)                                         | interface | `lib/color/oklch.ts`    | Red, green and blue, each 0 to 1, in whichever space the function says.                                                                                                                                                                                                                                                   |
| [`Rgb255`](#rgb255)                                   | type      | `lib/color/apca.ts`     | A colour as 0 to 255 sRGB integers, which is what APCA is defined over.                                                                                                                                                                                                                                                   |
| [`RoleName`](#rolename)                               | type      | `lib/color/derive.ts`   | The roles a derived theme guarantees. Components consume these and never a step.                                                                                                                                                                                                                                          |
| [`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.                                                                                                                                                                         |
| [`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.                                                                                                                                                                                           |
| `routes`                                              | const     | `lib/routes.ts`         | -                                                                                                                                                                                                                                                                                                                         |
| `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.                                                                             |
| `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.                                                              |
| `searchTokens`                                        | function  | `lib/tokens.ts`         | Substring match over name, description and value. The `/tokens` browser's filter.                                                                                                                                                                                                                                         |
| `SECTION_OUTLINES`                                    | const     | `lib/status.ts`         | The H2s a page must have, by `kind`, for every kind but `component`.                                                                                                                                                                                                                                                      |
| `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`.                                                                                                                                       |
| [`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/`.                                                                                                                                                                                |
| `showcases`                                           | const     | `lib/showcases.ts`      | The showcase grid, in the order it renders.                                                                                                                                                                                                                                                                               |
| `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.                                                                                                                                                                                |
| `simulateOklch`                                       | function  | `lib/color/cvd.ts`      | -                                                                                                                                                                                                                                                                                                                         |
| `simulateRgb255`                                      | function  | `lib/color/cvd.ts`      | -                                                                                                                                                                                                                                                                                                                         |
| `site`                                                | const     | `lib/routes.ts`         | -                                                                                                                                                                                                                                                                                                                         |
| `source`                                              | const     | `lib/source.ts`         | -                                                                                                                                                                                                                                                                                                                         |
| `spokenUnit`                                          | function  | `lib/opsinjs.ts`        | How a screen reader should say this unit for this count.                                                                                                                                                                                                                                                                  |
| `srgbToLinear`                                        | function  | `lib/color/oklch.ts`    | -                                                                                                                                                                                                                                                                                                                         |
| `srgbToOklch`                                         | function  | `lib/color/oklch.ts`    | Gamma-encoded sRGB, 0 to 1 per channel → OKLCH.                                                                                                                                                                                                                                                                           |
| [`Status`](#status)                                   | type      | `lib/status.ts`         | The release phase of a component page or a catalogue entry.                                                                                                                                                                                                                                                               |
| `STATUS_META`                                         | const     | `lib/status.ts`         | -                                                                                                                                                                                                                                                                                                                         |
| `STATUS_ORDER`                                        | const     | `lib/status.ts`         | Statuses in display order.                                                                                                                                                                                                                                                                                                |
| `statusCounts`                                        | function  | `lib/catalogue.ts`      | Counts per status, in display order. The input to `\<SectionProgress\>`.                                                                                                                                                                                                                                                  |
| `STATUSES`                                            | const     | `lib/status.ts`         | A RELEASE PHASE IS NEVER PAINTED, AND THERE IS NOW NOTHING HERE TO PAINT IT WITH.                                                                                                                                                                                                                                         |
| [`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.                                                                                                                                                                              |
| `textOf`                                              | function  | `lib/docs-nav.ts`       | Plain text of a page-tree name or a heading title, which may be markup.                                                                                                                                                                                                                                                   |
| `themeToCssVariables`                                 | function  | `lib/color/derive.ts`   | Every custom property a derived theme emits, ready for a stylesheet or a copy button.                                                                                                                                                                                                                                     |
| `toGrayscale`                                         | function  | `lib/color/cvd.ts`      | Grayscale by relative luminance rather than by an average of the channels.                                                                                                                                                                                                                                                |
| `toIndexRow`                                          | function  | `lib/catalogue.ts`      | One row of `/r/index.json` and of the generated catalogue reference page.                                                                                                                                                                                                                                                 |
| `TOKEN_FORMAT_LABELS`                                 | const     | `lib/tokens.ts`         | -                                                                                                                                                                                                                                                                                                                         |
| `TOKEN_NAMESPACE_LABELS`                              | const     | `lib/tokens.ts`         | -                                                                                                                                                                                                                                                                                                                         |
| `TOKEN_NAMESPACES`                                    | const     | `lib/tokens.ts`         | -                                                                                                                                                                                                                                                                                                                         |
| `TOKEN_TIER_DESCRIPTIONS`                             | const     | `lib/tokens.ts`         | -                                                                                                                                                                                                                                                                                                                         |
| `TOKEN_TIER_LABELS`                                   | const     | `lib/tokens.ts`         | -                                                                                                                                                                                                                                                                                                                         |
| [`TokenFormat`](#tokenformat)                         | type      | `lib/tokens.ts`         | The formats the `/tokens` and `/colors` browsers can copy a value in.                                                                                                                                                                                                                                                     |
| `tokenMeta`                                           | function  | `lib/tokens.ts`         | -                                                                                                                                                                                                                                                                                                                         |
| `tokensAreGenerated`                                  | function  | `lib/tokens.ts`         | Whether the generated layer has actually been produced.                                                                                                                                                                                                                                                                   |
| `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.                                                                                                                                         |
| `toRgb255`                                            | function  | `lib/color/oklch.ts`    | 0 to 1 sRGB → 0 to 255 integers, clamped.                                                                                                                                                                                                                                                                                 |
| `toRgb255Input`                                       | function  | `lib/color/apca.ts`     | Coerce any accepted colour form to an sRGB triple.                                                                                                                                                                                                                                                                        |
| [`TrendPoint`](#trendpoint)                           | interface | `lib/opsinjs.ts`        | One reading in a series, for the components that draw change over time.                                                                                                                                                                                                                                                   |
| [`Unit`](#unit)                                       | interface | `lib/opsinjs.ts`        | One unit: what it is called, what a reader sees, and how it is SPOKEN.                                                                                                                                                                                                                                                    |
| `UNIT_CONVERSIONS`                                    | const     | `lib/opsinjs.ts`        | Every convertible ordered pair, composed by the generator. Never authored by hand.                                                                                                                                                                                                                                        |
| `unitConversion`                                      | function  | `lib/opsinjs.ts`        | The authored conversion between two symbols, or `undefined` when there is none.                                                                                                                                                                                                                                           |
| [`UnitConversion`](#unitconversion)                   | interface | `lib/opsinjs.ts`        | An exact conversion between two units of the same kind.                                                                                                                                                                                                                                                                   |
| `UNITS`                                               | const     | `lib/opsinjs.ts`        | Every unit this system can speak, sorted by id. Generated from `tokens/units.json`.                                                                                                                                                                                                                                       |
| `UNITS_BY_SYMBOL`                                     | const     | `lib/opsinjs.ts`        | The lookup `findUnit()` reads, derived from `UNITS` rather than emitted twice.                                                                                                                                                                                                                                            |
| `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.                                                                                                          |
| [`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.                                                                                                                                                                            |
| [`UnresolvedReason`](#unresolvedreason)               | interface | `lib/registry.ts`       | Why a lookup came back empty. The input to `\<NotBuiltYet\>`.                                                                                                                                                                                                                                                             |
| [`ViewKind`](#viewkind)                               | type      | `lib/routes.ts`         | What a `/view` route can render.                                                                                                                                                                                                                                                                                          |
| [`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.                                                                                                                                                                      |
| `viewPath`                                            | function  | `lib/routes.ts`         | `/view/base/base-lyra/component/range-bar?mode=dark&text=200`.                                                                                                                                                                                                                                                            |
| [`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.                                                                                                                                                                               |
| `warnOnce`                                            | function  | `lib/opsinjs.ts`        | Report a defect in development, once, and never do anything else.                                                                                                                                                                                                                                                         |
| `wcag`                                                | const     | `lib/color/wcag.ts`     | The short name, matching `apca()`. Identical to `contrastRatio`.                                                                                                                                                                                                                                                          |
| `WCAG_FLOOR`                                          | const     | `lib/color/wcag.ts`     | The three WCAG 2.2 thresholds this system checks against.                                                                                                                                                                                                                                                                 |
| [`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.                                                                                                                                                                                                       |
| `wcagVerdict`                                         | function  | `lib/color/wcag.ts`     | -                                                                                                                                                                                                                                                                                                                         |
| [`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.                                                                                                                                                                                |

## Declarations [#declarations]

### AliasProblem [#aliasproblem]

One search synonym that cannot be used, either because two components claim it or because it collides with a component id.

A interface in `lib/catalogue.ts`.

```ts
export interface AliasProblem {
  alias: string
  reason: "duplicate" | "collides-with-id"
  owners: string[]
}
```

**Members**

| Member   | Type                                | Required | What it is |
| -------- | ----------------------------------- | -------- | ---------- |
| `alias`  | `string`                            | Yes      | -          |
| `reason` | `"duplicate" \| "collides-with-id"` | Yes      | -          |
| `owners` | `string[]`                          | Yes      | -          |

**Used by** `findAliasProblems`.

### ApcaVerdict [#apcaverdict]

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.

A interface in `lib/color/apca.ts`.

```ts
export interface ApcaVerdict {
  lc: number
  magnitude: number
  polarity: "dark-on-light" | "light-on-dark" | "indistinguishable"
  use: ContrastUse
  floor: number
  passes: boolean
  headroom: number
}
```

**Members**

| Member      | Type                                                        | Required | What it is |
| ----------- | ----------------------------------------------------------- | -------- | ---------- |
| `lc`        | `number`                                                    | Yes      | -          |
| `magnitude` | `number`                                                    | Yes      | -          |
| `polarity`  | `"dark-on-light" \| "light-on-dark" \| "indistinguishable"` | Yes      | -          |
| `use`       | `ContrastUse`                                               | Yes      | -          |
| `floor`     | `number`                                                    | Yes      | -          |
| `passes`    | `boolean`                                                   | Yes      | -          |
| `headroom`  | `number`                                                    | Yes      | -          |

### AxisConflict [#axisconflict]

A refusal. It is what the system answers when a measurement category and a clinical status are asked to share one surface.

A interface in `lib/status.ts`.

```ts
export interface AxisConflict {
  code: "OPSIN-0001"
  category: HealthCategory
  status: ClinicalStatus
  message: string
  docs: string
}
```

**Members**

| Member     | Type             | Required | What it is |
| ---------- | ---------------- | -------- | ---------- |
| `code`     | `"OPSIN-0001"`   | Yes      | -          |
| `category` | `HealthCategory` | Yes      | -          |
| `status`   | `ClinicalStatus` | Yes      | -          |
| `message`  | `string`         | Yes      | -          |
| `docs`     | `string`         | Yes      | -          |

**Used by** `axisConflict`.

### CatalogueIndexRow [#catalogueindexrow]

One component as the light registry index publishes it, flattened to the fields a decision to install actually turns on.

A interface in `lib/catalogue.ts`.

```ts
export interface CatalogueIndexRow {
  name: string
  title: string
  description: string
  type: "registry:ui"
  category: CatalogueCategory
  status: Status
  since: string
  aliases: string[]
  implemented: boolean
  docs: string | null
  dependencies?: string[]
  registryDependencies?: string[]
}
```

**Members**

| Member                 | Type                | Required | What it is |
| ---------------------- | ------------------- | -------- | ---------- |
| `name`                 | `string`            | Yes      | -          |
| `title`                | `string`            | Yes      | -          |
| `description`          | `string`            | Yes      | -          |
| `type`                 | `"registry:ui"`     | Yes      | -          |
| `category`             | `CatalogueCategory` | Yes      | -          |
| `status`               | `Status`            | Yes      | -          |
| `since`                | `string`            | Yes      | -          |
| `aliases`              | `string[]`          | Yes      | -          |
| `implemented`          | `boolean`           | Yes      | -          |
| `docs`                 | `string \| null`    | Yes      | -          |
| `dependencies`         | `string[]`          | No       | -          |
| `registryDependencies` | `string[]`          | No       | -          |

### ClinicalStatus [#clinicalstatus]

What a reading means and what, if anything, to do about it.

Four 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.

A 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.

A type in `lib/status.ts`.

```ts
export type ClinicalStatus = (typeof CLINICAL_STATUSES)[number]
```

**Used by** `axisConflict`, [`AxisConflict`](#axisconflict), [`ClinicalStatusOrUnknown`](#clinicalstatusorunknown), `isClinicalStatus`, [`TrendPoint`](#trendpoint).

### ClinicalStatusMeta [#clinicalstatusmeta]

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.

A interface in `lib/status.ts`.

```ts
export interface ClinicalStatusMeta {
  word: string
  sentence: string
  assignedBy: string
  icon: string
  level: number
}
```

**Members**

| Member       | Type     | Required | What it is |
| ------------ | -------- | -------- | ---------- |
| `word`       | `string` | Yes      | -          |
| `sentence`   | `string` | Yes      | -          |
| `assignedBy` | `string` | Yes      | -          |
| `icon`       | `string` | Yes      | -          |
| `level`      | `number` | Yes      | -          |

### ClinicalStatusOrUnknown [#clinicalstatusorunknown]

The four clinical statuses plus `unknown`. Unknown is the absence of an assertion rather than a fifth level of urgency.

A type in `lib/status.ts`.

```ts
export type ClinicalStatusOrUnknown = ClinicalStatus | UnknownStatus
```

### ColorInput [#colorinput]

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)`).

The 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.

A type in `lib/color/apca.ts`.

```ts
export type ColorInput = Rgb255 | Oklch | string
```

**Used by** `apcaContrast`, `contrastRatio`, `relativeLuminance`, `screenLuminance`, `toRgb255Input`.

### ContrastCheck [#contrastcheck]

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.

A interface in `lib/color/derive.ts`.

```ts
export interface ContrastCheck {
  pair: string
  use: ContrastUse
  apcaLc: number
  wcagRatio: number
  passes: boolean
  advisory?: boolean
}
```

**Members**

| Member      | Type          | Required | What it is |
| ----------- | ------------- | -------- | ---------- |
| `pair`      | `string`      | Yes      | -          |
| `use`       | `ContrastUse` | Yes      | -          |
| `apcaLc`    | `number`      | Yes      | -          |
| `wcagRatio` | `number`      | Yes      | -          |
| `passes`    | `boolean`     | Yes      | -          |
| `advisory`  | `boolean`     | No       | -          |

**Used by** [`DerivedTheme`](#derivedtheme).

### ContrastUse [#contrastuse]

What a pair is being used for. Determines which floor applies.

A type in `lib/color/apca.ts`.

```ts
export type ContrastUse = "body" | "large" | "nonText"
```

**Used by** `APCA_FLOOR`, [`ApcaVerdict`](#apcaverdict), `CONTRAST_USE_LABELS`, [`ContrastCheck`](#contrastcheck), `passesApca`.

### CvdCollision [#cvdcollision]

Two colours that stop being distinguishable under one kind of colour vision deficiency, and the Lc left between them once simulated.

A interface in `lib/color/cvd.ts`.

```ts
export interface CvdCollision {
  type: CvdType
  a: string
  b: string
  lc: number
}
```

**Members**

| Member | Type      | Required | What it is |
| ------ | --------- | -------- | ---------- |
| `type` | `CvdType` | Yes      | -          |
| `a`    | `string`  | Yes      | -          |
| `b`    | `string`  | Yes      | -          |
| `lc`   | `number`  | Yes      | -          |

### CvdType [#cvdtype]

The three dichromacies, plus the achromatic check every specimen must also survive.

A type in `lib/color/cvd.ts`.

```ts
export type CvdType = "protanopia" | "deuteranopia" | "tritanopia" | "grayscale"
```

**Used by** `CVD_LABELS`, `CVD_TYPES`, [`CvdCollision`](#cvdcollision), `simulate`.

### DataState [#datastate]

The state a data surface is in, named once so the surfaces converge on one vocabulary, though no component accepts it yet.

These 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.

No 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.

A type in `lib/opsinjs.ts`.

```ts
export type DataState =
  | "loading"
  | "error"
  | "empty"
  | "partial"
  | "stale"
  | "resolved"
```

### DecodeError [#decodeerror]

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.

A type in `lib/preset.ts`.

```ts
export type DecodeError =
  | "missing-prefix"
  | "wrong-length"
  | "unknown-version"
  | "bad-characters"
  | "bad-checksum"
```

**Used by** [`DecodeResult`](#decoderesult).

### DecodeResult [#decoderesult]

The outcome of reading a preset code. Either the preset and its version, or an error and a sentence a person can act on.

A interface in `lib/preset.ts`.

```ts
export interface DecodeResult {
  preset: Preset | null
  version: number | null
  error: DecodeError | null
  message: string | null
}
```

**Members**

| Member    | Type                  | Required | What it is |
| --------- | --------------------- | -------- | ---------- |
| `preset`  | `Preset \| null`      | Yes      | -          |
| `version` | `number \| null`      | Yes      | -          |
| `error`   | `DecodeError \| null` | Yes      | -          |
| `message` | `string \| null`      | Yes      | -          |

**Used by** `decodePreset`.

### DerivedTheme [#derivedtheme]

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.

A interface in `lib/color/derive.ts`.

```ts
export interface DerivedTheme {
  brand: Oklch
  seed: Oklch
  brandRamp: Ramp
  neutralRamp: Ramp
  roles: Record<RoleName, RolePair>
  checks: ContrastCheck[]
  warnings: DeriveWarning[]
  sound: boolean
}
```

**Members**

| Member        | Type                         | Required | What it is |
| ------------- | ---------------------------- | -------- | ---------- |
| `brand`       | `Oklch`                      | Yes      | -          |
| `seed`        | `Oklch`                      | Yes      | -          |
| `brandRamp`   | `Ramp`                       | Yes      | -          |
| `neutralRamp` | `Ramp`                       | Yes      | -          |
| `roles`       | `Record<RoleName, RolePair>` | Yes      | -          |
| `checks`      | `ContrastCheck[]`            | Yes      | -          |
| `warnings`    | `DeriveWarning[]`            | Yes      | -          |
| `sound`       | `boolean`                    | Yes      | -          |

### DeriveOptions [#deriveoptions]

The knobs on theme derivation. Every one of them has a default, so a brand colour on its own is already a complete input.

A interface in `lib/color/derive.ts`.

```ts
export interface DeriveOptions {
  neutralChroma?: number
  gamut?: Gamut
  maxSeedChroma?: number
}
```

**Members**

| Member          | Type     | Required | What it is |
| --------------- | -------- | -------- | ---------- |
| `neutralChroma` | `number` | No       | -          |
| `gamut`         | `Gamut`  | No       | -          |
| `maxSeedChroma` | `number` | No       | -          |

### DeriveWarning [#derivewarning]

One thing the derivation has to say about a theme, as a level, a stable code and a message.

A interface in `lib/color/derive.ts`.

```ts
export interface DeriveWarning {
  level: WarningLevel
  code: string
  message: string
}
```

**Members**

| Member    | Type           | Required | What it is |
| --------- | -------------- | -------- | ---------- |
| `level`   | `WarningLevel` | Yes      | -          |
| `code`    | `string`       | Yes      | -          |
| `message` | `string`       | Yes      | -          |

**Used by** [`DerivedTheme`](#derivedtheme).

### Detent [#detent]

How far a sheet is open.

Three 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.

A type in `lib/opsinjs.ts`.

```ts
export type Detent = "content" | "half" | "full"
```

### DocsNav [#docsnav]

This symbol has no doc comment yet.

A interface in `lib/docs-nav.ts`.

```ts
export interface DocsNav {
  sections: NavSection[]
  headings: Record<string, NavHeading[]>
}
```

**Members**

| Member     | Type                           | Required | What it is |
| ---------- | ------------------------------ | -------- | ---------- |
| `sections` | `NavSection[]`                 | Yes      | -          |
| `headings` | `Record<string, NavHeading[]>` | Yes      | -          |

**Used by** `getDocsNav`.

### Gamut [#gamut]

The colour spaces this module can express a colour in.

A type in `lib/color/oklch.ts`.

```ts
export type Gamut = "srgb" | "display-p3"
```

**Used by** `clampToGamut`, [`DeriveOptions`](#deriveoptions), `deriveRamp`, `fit`.

### GeneratedBannedWord [#generatedbannedword]

One banned word: the word a component's copy must not use, what to write in its place, and why the word is barred.

The 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.

The 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.

A interface in `lib/opsinjs.ts`.

```ts
export interface GeneratedBannedWord {
  word: string
  instead: string
  reason: string
}
```

**Members**

| Member    | Type     | Required | What it is |
| --------- | -------- | -------- | ---------- |
| `word`    | `string` | Yes      | -          |
| `instead` | `string` | Yes      | -          |
| `reason`  | `string` | Yes      | -          |

**Used by** `BANNED_WORDS`.

### HealthCategory [#healthcategory]

What a reading is ABOUT. Identity, never verdict.

A 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.

A type in `lib/status.ts`.

```ts
export type HealthCategory = (typeof HEALTH_CATEGORIES)[number]
```

**Used by** `axisConflict`, [`AxisConflict`](#axisconflict), `HEALTH_CATEGORY_LABELS`, `isHealthCategory`.

### Kind [#kind]

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.

A type in `lib/status.ts`.

```ts
export type Kind = (typeof KINDS)[number]
```

**Used by** `isKind`, `OUTLINE_IS_EXACT`, `SECTION_OUTLINES`.

### MaterialRung [#materialrung]

A rung of the material ladder, meaning how a surface sits above what is behind it.

These 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.

A type in `lib/opsinjs.ts`.

```ts
export type MaterialRung =
  | "canvas"
  | "card"
  | "raised"
  | "sheet"
  | "overlay"
  | "scrim"
```

### NavGroup [#navgroup]

This symbol has no doc comment yet.

A interface in `lib/docs-nav.ts`.

```ts
export interface NavGroup {
  title?: string
  links: NavLink[]
}
```

**Members**

| Member  | Type        | Required | What it is |
| ------- | ----------- | -------- | ---------- |
| `title` | `string`    | No       | -          |
| `links` | `NavLink[]` | Yes      | -          |

**Used by** [`NavSection`](#navsection).

### NavHeading [#navheading]

This symbol has no doc comment yet.

A interface in `lib/docs-nav.ts`.

```ts
export interface NavHeading {
  depth: 2 | 3
  id: string
  text: string
}
```

**Members**

| Member  | Type     | Required | What it is |
| ------- | -------- | -------- | ---------- |
| `depth` | `2 \| 3` | Yes      | -          |
| `id`    | `string` | Yes      | -          |
| `text`  | `string` | Yes      | -          |

**Used by** [`DocsNav`](#docsnav), `getDocsNav`.

### NavLink [#navlink]

This symbol has no doc comment yet.

A interface in `lib/docs-nav.ts`.

```ts
export interface NavLink {
  title: string
  url: string
}
```

**Members**

| Member  | Type     | Required | What it is |
| ------- | -------- | -------- | ---------- |
| `title` | `string` | Yes      | -          |
| `url`   | `string` | Yes      | -          |

**Used by** [`NavGroup`](#navgroup).

### NavSection [#navsection]

This symbol has no doc comment yet.

A interface in `lib/docs-nav.ts`.

```ts
export interface NavSection {
  id: string
  title: string
  url: string
  meta?: string
  groups: NavGroup[]
}
```

**Members**

| Member   | Type         | Required | What it is |
| -------- | ------------ | -------- | ---------- |
| `id`     | `string`     | Yes      | -          |
| `title`  | `string`     | Yes      | -          |
| `url`    | `string`     | Yes      | -          |
| `meta`   | `string`     | No       | -          |
| `groups` | `NavGroup[]` | Yes      | -          |

**Used by** [`DocsNav`](#docsnav), `getDocsNav`.

### Oklab [#oklab]

A colour in OKLab.

A interface in `lib/color/oklch.ts`.

```ts
export interface Oklab {
  l: number
  a: number
  b: number
  alpha?: number
}
```

**Members**

| Member  | Type     | Required | What it is |
| ------- | -------- | -------- | ---------- |
| `l`     | `number` | Yes      | -          |
| `a`     | `number` | Yes      | -          |
| `b`     | `number` | Yes      | -          |
| `alpha` | `number` | No       | -          |

**Used by** `linearSrgbToOklab`, `oklabToLinearSrgb`, `oklabToOklch`, `oklchToOklab`.

### Oklch [#oklch]

A colour in OKLCH. `l` 0 to 1, `c` unbounded, `h` in degrees.

A interface in `lib/color/oklch.ts`.

```ts
export interface Oklch {
  l: number
  c: number
  h: number
  alpha?: number
}
```

**Members**

| Member  | Type     | Required | What it is |
| ------- | -------- | -------- | ---------- |
| `l`     | `number` | Yes      | -          |
| `c`     | `number` | Yes      | -          |
| `h`     | `number` | Yes      | -          |
| `alpha` | `number` | No       | -          |

**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`.

### OpsinError [#opsinerror]

One warning code: what it is called, how severe it is, and the page that prevents it.

A interface in `lib/opsinjs.ts`.

```ts
export interface OpsinError {
  code: OpsinErrorCode
  severity: OpsinErrorSeverity
  title: string
  message: string
  docs: string
  params: string[]
}
```

**Members**

| Member     | Type                 | Required | What it is |
| ---------- | -------------------- | -------- | ---------- |
| `code`     | `OpsinErrorCode`     | Yes      | -          |
| `severity` | `OpsinErrorSeverity` | Yes      | -          |
| `title`    | `string`             | Yes      | -          |
| `message`  | `string`             | Yes      | -          |
| `docs`     | `string`             | Yes      | -          |
| `params`   | `string[]`           | Yes      | -          |

**Used by** `OPSIN_ERRORS`.

### OpsinErrorCode [#opsinerrorcode]

Every warning code opsinjs can emit.

Flat, 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.

A type in `lib/opsinjs.ts`.

```ts
export type OpsinErrorCode =
  | "OPSIN-0001"
  | "OPSIN-0002"
  | "OPSIN-0003"
  | "OPSIN-0004"
  | "OPSIN-0005"
  | "OPSIN-0006"
  | "OPSIN-0007"
  | "OPSIN-0008"
  | "OPSIN-0009"
  | "OPSIN-0010"
  | "OPSIN-0011"
  | "OPSIN-0012"
  | "OPSIN-0013"
  | "OPSIN-0014"
  | "OPSIN-0015"
  | "OPSIN-0016"
  | "OPSIN-0017"
  | "OPSIN-0018"
  | "OPSIN-0019"
  | "OPSIN-0020"
  | "OPSIN-0021"
```

**Used by** `OPSIN_ERRORS`, [`OpsinError`](#opsinerror), `warnOnce`.

### OpsinErrorParams [#opsinerrorparams]

The values a message template asks for, keyed by placeholder name.

Values 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.

A type in `lib/opsinjs.ts`.

```ts
export type OpsinErrorParams = Record<string, string | number>
```

**Used by** `warnOnce`.

### OpsinErrorSeverity [#opsinerrorseverity]

How severe a warning is.

The three classes are declared in `tokens/errors.json`'s `policy.severity` block, which also carries the sentence that says what each one means:

* safety - A defect that can mislead a reader about their own health. Treat as a bug, not as a lint warning.
* correctness - The component will render something, but not what the author meant.
* hygiene - Works today, will not survive an upgrade.

A type in `lib/opsinjs.ts`.

```ts
export type OpsinErrorSeverity = "safety" | "correctness" | "hygiene"
```

**Used by** [`OpsinError`](#opsinerror).

### Preset [#preset]

A theme as a person describes it. What `encodePreset` takes and `decodePreset` returns.

A interface in `lib/preset.ts`.

```ts
export interface Preset {
  hue: number
  chroma: number
  lightness: number
  neutralChroma: number
  radius: number
  density: (typeof DENSITY_VALUES)[number]
  gamut: (typeof GAMUT_VALUES)[number]
  floor: (typeof FLOOR_VALUES)[number]
  cornerShape: (typeof CORNER_SHAPE_VALUES)[number]
  mode: (typeof MODE_VALUES)[number]
}
```

**Members**

| Member          | Type                                   | Required | What it is |
| --------------- | -------------------------------------- | -------- | ---------- |
| `hue`           | `number`                               | Yes      | -          |
| `chroma`        | `number`                               | Yes      | -          |
| `lightness`     | `number`                               | Yes      | -          |
| `neutralChroma` | `number`                               | Yes      | -          |
| `radius`        | `number`                               | Yes      | -          |
| `density`       | `(typeof DENSITY_VALUES)[number]`      | Yes      | -          |
| `gamut`         | `(typeof GAMUT_VALUES)[number]`        | Yes      | -          |
| `floor`         | `(typeof FLOOR_VALUES)[number]`        | Yes      | -          |
| `cornerShape`   | `(typeof CORNER_SHAPE_VALUES)[number]` | Yes      | -          |
| `mode`          | `(typeof MODE_VALUES)[number]`         | Yes      | -          |

**Used by** [`DecodeResult`](#decoderesult), `DEFAULT_PRESET`, `presetBrandColor`, `SHIPPED_PRESETS`.

### Ramp [#ramp]

One complete lightness ramp, as a value per step. The chromatic ramp and the neutral ramp of a derived theme are both this shape.

A type in `lib/color/derive.ts`.

```ts
export type Ramp = Record<RampStep, RampStepValue>
```

**Used by** [`DerivedTheme`](#derivedtheme), `deriveRamp`.

### RampStep [#rampstep]

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.

A type in `lib/color/derive.ts`.

```ts
export type RampStep = (typeof RAMP_STEPS)[number]
```

**Used by** `CHROMA_ENVELOPE`, [`Ramp`](#ramp), `RAMP_LIGHTNESS`, [`RampStepValue`](#rampstepvalue).

### RampStepValue [#rampstepvalue]

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.

A interface in `lib/color/derive.ts`.

```ts
export interface RampStepValue {
  step: RampStep
  srgb: Oklch
  p3?: Oklch
  clamped: boolean
  css: { srgb: string; p3?: string }
}
```

**Members**

| Member    | Type                            | Required | What it is |
| --------- | ------------------------------- | -------- | ---------- |
| `step`    | `RampStep`                      | Yes      | -          |
| `srgb`    | `Oklch`                         | Yes      | -          |
| `p3`      | `Oklch`                         | No       | -          |
| `clamped` | `boolean`                       | Yes      | -          |
| `css`     | `{ srgb: string; p3?: string }` | Yes      | -          |

**Used by** [`Ramp`](#ramp).

### ReferenceRange [#referencerange]

The interval a reading is being compared against, and who says so.

Both 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.

`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.

A interface in `lib/opsinjs.ts`.

```ts
export interface ReferenceRange {
  low?: number
  high?: number
  source: string
  asOf?: string
}
```

**Members**

| Member   | Type     | Required | What it is |
| -------- | -------- | -------- | ---------- |
| `low`    | `number` | No       | -          |
| `high`   | `number` | No       | -          |
| `source` | `string` | Yes      | -          |
| `asOf`   | `string` | No       | -          |

### RefusedConversion [#refusedconversion]

A pair people expect to be arithmetic and is not, with the reason.

This 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.

A interface in `lib/opsinjs.ts`.

```ts
export interface RefusedConversion {
  between: [string, string]
  reason: string
  docs: string
}
```

**Members**

| Member    | Type               | Required | What it is |
| --------- | ------------------ | -------- | ---------- |
| `between` | `[string, string]` | Yes      | -          |
| `reason`  | `string`           | Yes      | -          |
| `docs`    | `string`           | Yes      | -          |

**Used by** `REFUSED_CONVERSIONS`.

### RegistryLookup [#registrylookup]

Both call shapes are supported on purpose.

`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.

A type in `lib/registry.ts`.

```ts
export type RegistryLookup = string | RegistryQuery
```

### RegistryQuery [#registryquery]

A request for one registry item, by id and optionally by base, style and kind. Anything left out falls back to the default.

A interface in `lib/registry.ts`.

```ts
export interface RegistryQuery {
  name: string
  base?: string
  style?: string
  kind?: RegistryKind
}
```

**Members**

| Member  | Type           | Required | What it is |
| ------- | -------------- | -------- | ---------- |
| `name`  | `string`       | Yes      | -          |
| `base`  | `string`       | No       | -          |
| `style` | `string`       | No       | -          |
| `kind`  | `RegistryKind` | No       | -          |

**Used by** [`RegistryLookup`](#registrylookup).

### Rgb [#rgb]

Red, green and blue, each 0 to 1, in whichever space the function says.

A interface in `lib/color/oklch.ts`.

```ts
export interface Rgb {
  r: number
  g: number
  b: number
  alpha?: number
}
```

**Members**

| Member  | Type     | Required | What it is |
| ------- | -------- | -------- | ---------- |
| `r`     | `number` | Yes      | -          |
| `g`     | `number` | Yes      | -          |
| `b`     | `number` | Yes      | -          |
| `alpha` | `number` | No       | -          |

**Used by** `displayP3ToOklch`, `linearP3ToLinearSrgb`, `linearSrgbToLinearP3`, `linearSrgbToOklab`, `linearToSrgb`, `oklabToLinearSrgb`, `oklchToDisplayP3`, `oklchToSrgb`, `parseHex`, `simulate`, `srgbToLinear`, `srgbToOklch`, `toGrayscale`, `toRgb255`.

### Rgb255 [#rgb255]

A colour as 0 to 255 sRGB integers, which is what APCA is defined over.

A type in `lib/color/apca.ts`.

```ts
export type Rgb255 = [number, number, number]
```

**Used by** [`ColorInput`](#colorinput), `toRgb255Input`.

### RoleName [#rolename]

The roles a derived theme guarantees. Components consume these and never a step.

A type in `lib/color/derive.ts`.

```ts
export type RoleName =
  | "canvas"
  | "surface"
  | "ink"
  | "muted-ink"
  | "line"
  | "control-line"
  | "primary"
  | "on-primary"
  | "focus"
```

**Used by** [`DerivedTheme`](#derivedtheme).

### RolePair [#rolepair]

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.

A interface in `lib/color/derive.ts`.

```ts
export interface RolePair {
  light: RoleValue
  dark: RoleValue
}
```

**Members**

| Member  | Type        | Required | What it is |
| ------- | ----------- | -------- | ---------- |
| `light` | `RoleValue` | Yes      | -          |
| `dark`  | `RoleValue` | Yes      | -          |

**Used by** [`DerivedTheme`](#derivedtheme).

### RoleValue [#rolevalue]

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.

A interface in `lib/color/derive.ts`.

```ts
export interface RoleValue {
  source: string
  value: Oklch
  css: string
}
```

**Members**

| Member   | Type     | Required | What it is |
| -------- | -------- | -------- | ---------- |
| `source` | `string` | Yes      | -          |
| `value`  | `Oklch`  | Yes      | -          |
| `css`    | `string` | Yes      | -          |

**Used by** [`RolePair`](#rolepair).

### Showcase [#showcase]

The screens on `/showcase`: whole screens assembled only from opsinjs components, each one rendered from a file under `registry/screens/`.

Every 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.

A interface in `lib/showcases.ts`.

```ts
export interface Showcase {
  slug: "diabetes-medicines-app" | "patient-record-portal" | "results-screen"
  title: string
  description: string
  domain: string
  components: number
  highlights: string[]
}
```

**Members**

| Member        | Type                                                                      | Required | What it is |
| ------------- | ------------------------------------------------------------------------- | -------- | ---------- |
| `slug`        | `"diabetes-medicines-app" \| "patient-record-portal" \| "results-screen"` | Yes      | -          |
| `title`       | `string`                                                                  | Yes      | -          |
| `description` | `string`                                                                  | Yes      | -          |
| `domain`      | `string`                                                                  | Yes      | -          |
| `components`  | `number`                                                                  | Yes      | -          |
| `highlights`  | `string[]`                                                                | Yes      | -          |

**Used by** `showcases`.

### Status [#status]

The release phase of a component page or a catalogue entry.

A type in `lib/status.ts`.

```ts
export type Status = (typeof STATUSES)[number]
```

**Used by** [`CatalogueIndexRow`](#catalogueindexrow), `COMPONENT_SECTIONS_BY_STATUS`, `componentSections`, `getByStatus`, `isNotImplemented`, `isStatus`, `OPSIN_ERRORS`, `STATUS_META`, `STATUS_ORDER`, [`UnresolvedReason`](#unresolvedreason).

### StatusMeta [#statusmeta]

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.

A interface in `lib/status.ts`.

```ts
export interface StatusMeta {
  label: string
  summary: string
}
```

**Members**

| Member    | Type     | Required | What it is |
| --------- | -------- | -------- | ---------- |
| `label`   | `string` | Yes      | -          |
| `summary` | `string` | Yes      | -          |

**Used by** `STATUS_META`.

### TokenFormat [#tokenformat]

The formats the `/tokens` and `/colors` browsers can copy a value in.

A type in `lib/tokens.ts`.

```ts
export type TokenFormat = "oklch" | "display-p3" | "hex" | "var" | "class"
```

**Used by** `TOKEN_FORMAT_LABELS`.

### TrendPoint [#trendpoint]

One reading in a series, for the components that draw change over time.

`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.

`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.

A interface in `lib/opsinjs.ts`.

```ts
export interface TrendPoint {
  at: string
  value: number | null
  status?: ClinicalStatus
}
```

**Members**

| Member   | Type             | Required | What it is |
| -------- | ---------------- | -------- | ---------- |
| `at`     | `string`         | Yes      | -          |
| `value`  | `number \| null` | Yes      | -          |
| `status` | `ClinicalStatus` | No       | -          |

### Unit [#unit]

One unit: what it is called, what a reader sees, and how it is SPOKEN.

The 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.

There 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.

`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.

A interface in `lib/opsinjs.ts`.

```ts
export interface Unit {
  id: string
  symbol: string
  spoken: string
  plural: string
  measures: string
  joined?: true
}
```

**Members**

| Member     | Type     | Required | What it is |
| ---------- | -------- | -------- | ---------- |
| `id`       | `string` | Yes      | -          |
| `symbol`   | `string` | Yes      | -          |
| `spoken`   | `string` | Yes      | -          |
| `plural`   | `string` | Yes      | -          |
| `measures` | `string` | Yes      | -          |
| `joined`   | `true`   | No       | -          |

**Used by** `findUnit`, `UNITS`, `UNITS_BY_SYMBOL`.

### UnitConversion [#unitconversion]

An exact conversion between two units of the same kind.

Applied 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.

`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.

A interface in `lib/opsinjs.ts`.

```ts
export interface UnitConversion {
  from: string
  to: string
  numerator: number
  denominator: number
  offsetNumerator: number
  offsetDenominator: number
  basis: string[]
}
```

**Members**

| Member              | Type       | Required | What it is |
| ------------------- | ---------- | -------- | ---------- |
| `from`              | `string`   | Yes      | -          |
| `to`                | `string`   | Yes      | -          |
| `numerator`         | `number`   | Yes      | -          |
| `denominator`       | `number`   | Yes      | -          |
| `offsetNumerator`   | `number`   | Yes      | -          |
| `offsetDenominator` | `number`   | Yes      | -          |
| `basis`             | `string[]` | Yes      | -          |

**Used by** `UNIT_CONVERSIONS`, `unitConversion`.

### UnknownStatus [#unknownstatus]

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.

Deliberately 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".

A type in `lib/status.ts`.

```ts
export type UnknownStatus = "unknown"
```

**Used by** [`ClinicalStatusOrUnknown`](#clinicalstatusorunknown).

### UnresolvedReason [#unresolvedreason]

Why a lookup came back empty. The input to `<NotBuiltYet>`.

A interface in `lib/registry.ts`.

```ts
export interface UnresolvedReason {
  name: string
  reason: "not-built" | "unknown"
  status: Status | null
  message: string
}
```

**Members**

| Member    | Type                       | Required | What it is |
| --------- | -------------------------- | -------- | ---------- |
| `name`    | `string`                   | Yes      | -          |
| `reason`  | `"not-built" \| "unknown"` | Yes      | -          |
| `status`  | `Status \| null`           | Yes      | -          |
| `message` | `string`                   | Yes      | -          |

**Used by** `explainUnresolved`.

### ViewKind [#viewkind]

What a `/view` route can render.

A type in `lib/routes.ts`.

```ts
export type ViewKind = "component" | "example" | "screen"
```

**Used by** [`ViewParams`](#viewparams).

### ViewParams [#viewparams]

Everything a chrome-less preview URL can carry. Name and kind become path segments, and the rest become query parameters applied before first paint.

A interface in `lib/routes.ts`.

```ts
export interface ViewParams {
  name: string
  kind?: ViewKind
  base?: string
  style?: string
  mode?: "light" | "dark"
  density?: "comfortable" | "compact"
  text?: 100 | 125 | 150 | 200
  theme?: string
  accentTheme?: string
  accent?: string
}
```

**Members**

| Member        | Type                         | Required | What it is |
| ------------- | ---------------------------- | -------- | ---------- |
| `name`        | `string`                     | Yes      | -          |
| `kind`        | `ViewKind`                   | No       | -          |
| `base`        | `string`                     | No       | -          |
| `style`       | `string`                     | No       | -          |
| `mode`        | `"light" \| "dark"`          | No       | -          |
| `density`     | `"comfortable" \| "compact"` | No       | -          |
| `text`        | `100 \| 125 \| 150 \| 200`   | No       | -          |
| `theme`       | `string`                     | No       | -          |
| `accentTheme` | `string`                     | No       | -          |
| `accent`      | `string`                     | No       | -          |

**Used by** `viewPath`.

### WarningLevel [#warninglevel]

How serious a derivation warning is. An `error` makes the theme unsound and stops it shipping, while a `warning` and a `note` are advisory.

A type in `lib/color/derive.ts`.

```ts
export type WarningLevel = "error" | "warning" | "note"
```

**Used by** [`DeriveWarning`](#derivewarning).

### WcagUse [#wcaguse]

Which WCAG 2.2 contrast threshold applies. Body text, large text and non- text content each have a different floor.

A type in `lib/color/wcag.ts`.

```ts
export type WcagUse = "body" | "large" | "nonText"
```

**Used by** [`WcagVerdict`](#wcagverdict).

### WcagVerdict [#wcagverdict]

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.

A interface in `lib/color/wcag.ts`.

```ts
export interface WcagVerdict {
  ratio: number
  use: WcagUse
  floor: number
  passesAA: boolean
  passesAAA: boolean
  criterion: string
}
```

**Members**

| Member      | Type      | Required | What it is |
| ----------- | --------- | -------- | ---------- |
| `ratio`     | `number`  | Yes      | -          |
| `use`       | `WcagUse` | Yes      | -          |
| `floor`     | `number`  | Yes      | -          |
| `passesAA`  | `boolean` | Yes      | -          |
| `passesAAA` | `boolean` | Yes      | -          |
| `criterion` | `string`  | Yes      | -          |

{/* opsinjs:generated:end */}
