Reference
Types
Every TypeScript symbol this documentation site's own lib/ exports, with a page of its own for each type and interface.
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). 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.
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 | 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 | 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 | 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 | 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 | type | lib/status.ts | What a reading means and what, if anything, to do about it. |
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 | 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 | 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 | 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 | 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 | 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 | type | lib/color/cvd.ts | The three dichromacies, plus the achromatic check every specimen must also survive. |
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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | interface | lib/docs-nav.ts | - |
NavHeading | interface | lib/docs-nav.ts | - |
NavLink | interface | lib/docs-nav.ts | - |
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 | 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 | 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 | interface | lib/opsinjs.ts | One warning code: what it is called, how severe it is, and the page that prevents it. |
OpsinErrorCode | type | lib/opsinjs.ts | Every warning code opsinjs can emit. |
OpsinErrorParams | type | lib/opsinjs.ts | The values a message template asks for, keyed by placeholder name. |
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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | interface | lib/color/oklch.ts | Red, green and blue, each 0 to 1, in whichever space the function says. |
Rgb255 | type | lib/color/apca.ts | A colour as 0 to 255 sRGB integers, which is what APCA is defined over. |
RoleName | type | lib/color/derive.ts | The roles a derived theme guarantees. Components consume these and never a step. |
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 | 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 | 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 | 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 | 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 | 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 | interface | lib/opsinjs.ts | One reading in a series, for the components that draw change over time. |
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 | 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 | 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 | interface | lib/registry.ts | Why a lookup came back empty. The input to \<NotBuiltYet\>. |
ViewKind | type | lib/routes.ts | What a /view route can render. |
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 | 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 | 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 | 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
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.
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
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.
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
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.
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
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.
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
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.
export type ClinicalStatus = (typeof CLINICAL_STATUSES)[number]Used by axisConflict, AxisConflict, ClinicalStatusOrUnknown, isClinicalStatus, TrendPoint.
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.
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
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.
export type ClinicalStatusOrUnknown = ClinicalStatus | UnknownStatusColorInput
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.
export type ColorInput = Rgb255 | Oklch | stringUsed by apcaContrast, contrastRatio, relativeLuminance, screenLuminance, toRgb255Input.
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.
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.
ContrastUse
What a pair is being used for. Determines which floor applies.
A type in lib/color/apca.ts.
export type ContrastUse = "body" | "large" | "nonText"Used by APCA_FLOOR, ApcaVerdict, CONTRAST_USE_LABELS, ContrastCheck, passesApca.
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.
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
The three dichromacies, plus the achromatic check every specimen must also survive.
A type in lib/color/cvd.ts.
export type CvdType = "protanopia" | "deuteranopia" | "tritanopia" | "grayscale"Used by CVD_LABELS, CVD_TYPES, CvdCollision, simulate.
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.
export type DataState =
| "loading"
| "error"
| "empty"
| "partial"
| "stale"
| "resolved"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.
export type DecodeError =
| "missing-prefix"
| "wrong-length"
| "unknown-version"
| "bad-characters"
| "bad-checksum"Used by 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.
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
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.
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
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.
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
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.
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.
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.
export type Detent = "content" | "half" | "full"DocsNav
This symbol has no doc comment yet.
A interface in lib/docs-nav.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
The colour spaces this module can express a colour in.
A type in lib/color/oklch.ts.
export type Gamut = "srgb" | "display-p3"Used by clampToGamut, DeriveOptions, deriveRamp, fit.
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.
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
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.
export type HealthCategory = (typeof HEALTH_CATEGORIES)[number]Used by axisConflict, AxisConflict, HEALTH_CATEGORY_LABELS, isHealthCategory.
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.
export type Kind = (typeof KINDS)[number]Used by isKind, OUTLINE_IS_EXACT, SECTION_OUTLINES.
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.
export type MaterialRung =
| "canvas"
| "card"
| "raised"
| "sheet"
| "overlay"
| "scrim"NavGroup
This symbol has no doc comment yet.
A interface in lib/docs-nav.ts.
export interface NavGroup {
title?: string
links: NavLink[]
}Members
| Member | Type | Required | What it is |
|---|---|---|---|
title | string | No | - |
links | NavLink[] | Yes | - |
Used by NavSection.
NavHeading
This symbol has no doc comment yet.
A interface in lib/docs-nav.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, getDocsNav.
NavLink
This symbol has no doc comment yet.
A interface in lib/docs-nav.ts.
export interface NavLink {
title: string
url: string
}Members
| Member | Type | Required | What it is |
|---|---|---|---|
title | string | Yes | - |
url | string | Yes | - |
Used by NavGroup.
NavSection
This symbol has no doc comment yet.
A interface in lib/docs-nav.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, getDocsNav.
Oklab
A colour in OKLab.
A interface in lib/color/oklch.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
A colour in OKLCH. l 0 to 1, c unbounded, h in degrees.
A interface in lib/color/oklch.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, contrastRatioOklch, DerivedTheme, deriveRamp, displayP3ToOklch, fit, formatDisplayP3, formatHex, formatOklch, mixOklch, oklabToOklch, oklchToDisplayP3, oklchToOklab, oklchToRgb255, oklchToSrgb, parseColor, RampStepValue, RoleValue, srgbToOklch.
OpsinError
One warning code: what it is called, how severe it is, and the page that prevents it.
A interface in lib/opsinjs.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
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.
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, warnOnce.
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.
export type OpsinErrorParams = Record<string, string | number>Used by warnOnce.
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.
export type OpsinErrorSeverity = "safety" | "correctness" | "hygiene"Used by OpsinError.
Preset
A theme as a person describes it. What encodePreset takes and decodePreset returns.
A interface in lib/preset.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, DEFAULT_PRESET, presetBrandColor, SHIPPED_PRESETS.
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.
export type Ramp = Record<RampStep, RampStepValue>Used by DerivedTheme, deriveRamp.
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.
export type RampStep = (typeof RAMP_STEPS)[number]Used by CHROMA_ENVELOPE, Ramp, RAMP_LIGHTNESS, 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.
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.
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.
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
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.
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
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.
export type RegistryLookup = string | RegistryQueryRegistryQuery
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.
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.
Rgb
Red, green and blue, each 0 to 1, in whichever space the function says.
A interface in lib/color/oklch.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
A colour as 0 to 255 sRGB integers, which is what APCA is defined over.
A type in lib/color/apca.ts.
export type Rgb255 = [number, number, number]Used by ColorInput, toRgb255Input.
RoleName
The roles a derived theme guarantees. Components consume these and never a step.
A type in lib/color/derive.ts.
export type RoleName =
| "canvas"
| "surface"
| "ink"
| "muted-ink"
| "line"
| "control-line"
| "primary"
| "on-primary"
| "focus"Used by DerivedTheme.
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.
export interface RolePair {
light: RoleValue
dark: RoleValue
}Members
| Member | Type | Required | What it is |
|---|---|---|---|
light | RoleValue | Yes | - |
dark | RoleValue | Yes | - |
Used by DerivedTheme.
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.
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.
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.
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
The release phase of a component page or a catalogue entry.
A type in lib/status.ts.
export type Status = (typeof STATUSES)[number]Used by CatalogueIndexRow, COMPONENT_SECTIONS_BY_STATUS, componentSections, getByStatus, isNotImplemented, isStatus, OPSIN_ERRORS, STATUS_META, STATUS_ORDER, UnresolvedReason.
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.
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
The formats the /tokens and /colors browsers can copy a value in.
A type in lib/tokens.ts.
export type TokenFormat = "oklch" | "display-p3" | "hex" | "var" | "class"Used by TOKEN_FORMAT_LABELS.
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.
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
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.
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
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.
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
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.
export type UnknownStatus = "unknown"Used by ClinicalStatusOrUnknown.
UnresolvedReason
Why a lookup came back empty. The input to <NotBuiltYet>.
A interface in lib/registry.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
What a /view route can render.
A type in lib/routes.ts.
export type ViewKind = "component" | "example" | "screen"Used by 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.
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
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.
export type WarningLevel = "error" | "warning" | "note"Used by DeriveWarning.
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.
export type WcagUse = "body" | "large" | "nonText"Used by 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.
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 | - |