Skip to content
opsinjs
Edit this page

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

SymbolKindDeclared inSummary
absoluteUrlfunctionlib/routes.tsTurn a root-relative path into a full URL on the canonical origin.
agentRoutesconstlib/routes.ts-
aliasesForfunctionlib/catalogue.tsThe exact array a page's aliases frontmatter must contain.
aliasIndexfunctionlib/catalogue.tsalias → 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.
AliasProbleminterfacelib/catalogue.tsOne search synonym that cannot be used, either because two components claim it or because it collides with a component id.
apcaconstlib/color/apca.tsThe short name, for callers that just want the number: apca("#333", "#fff"). Identical to apcaContrast.
APCA_FLOORconstlib/color/apca.tsThe 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.
apcaContrastfunctionlib/color/apca.tsLc for text on a background. Positive means dark-on-light, negative means light-on-dark, and the two arguments are not interchangeable.
apcaContrastOklchfunctionlib/color/apca.tsThe same, taking OKLCH. Both colours are clamped into sRGB first, because that is what a screen shows.
apcaVerdictfunctionlib/color/apca.ts-
ApcaVerdictinterfacelib/color/apca.tsThe 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.
apiRoutesconstlib/routes.ts-
apiSymbolPathfunctionlib/routes.tsA type's section on the generated Types page. \<ApiLink\> resolves here.
axisConflictfunctionlib/status.tsTHE NEVER-MIX RULE, as a function.
AxisConflictinterfacelib/status.tsA refusal. It is what the system answers when a measurement category and a clinical status are asked to share one surface.
BANNED_WORDSconstlib/opsinjs.tsWords a component's copy must not use, with the replacement and the reason. Generated from tokens/glossary.json.
baseOptionsfunctionlib/layout.shared.tsxTHERE IS NO TOP NAVIGATION, AND THAT IS THE POINT.
baseStyleQueryfunctionlib/routes.tsThe ?base=&style= query a docs page uses for the same switch. Returns an empty string at the defaults so the canonical URL stays clean.
builtComponentCountfunctionlib/registry.tsHow many distinct components have a real renderable behind them.
byNamespacefunctionlib/tokens.ts-
byTierfunctionlib/tokens.ts-
CatalogueIndexRowinterfacelib/catalogue.tsOne component as the light registry index publishes it, flattened to the fields a decision to install actually turns on.
CATEGORY_GATED_SECTIONSconstlib/status.tsSections 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_ENVELOPEconstlib/color/derive.tsChroma as a fraction of the seed's, per step. Mirrors chromaEnvelope in tokens/color.json.
CHROMA_STEPconstlib/preset.tsThe quantisation of chroma: 0.005 per step, so 63 steps reach 0.315.
clampToGamutfunctionlib/color/oklch.tsBring a colour into gamut by reducing chroma only.
CLINICAL_STATUS_METAconstlib/status.ts-
CLINICAL_STATUSESconstlib/status.ts-
ClinicalStatustypelib/status.tsWhat a reading means and what, if anything, to do about it.
ClinicalStatusMetainterfacelib/status.tsEverything a clinical status carries besides its colour. The word, the example sentence, who may assign it, its icon and its place in the order.
ClinicalStatusOrUnknowntypelib/status.tsThe four clinical statuses plus unknown. Unknown is the absence of an assertion rather than a fifth level of urgency.
cnfunctionlib/utils.tsJoin and de-duplicate class names, resolving Tailwind conflicts last-wins.
COLLAPSE_THRESHOLDconstlib/color/cvd.tsThe minimum Lc at which two swatches shown side by side are still telling two different colours apart.
ColorInputtypelib/color/apca.tsAnything 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_SECTIONSconstlib/status.tsSections 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_STATUSconstlib/status.tsThe 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.
componentPathfunctionlib/routes.tsA component specification page, by catalogue id.
componentRequiredSectionsfunctionlib/status.tsThe sections a component page must carry: its outline minus the optional ones.
componentSectionsfunctionlib/status.tsThe outline for one component page, with the category gate applied.
compositeOverfunctionlib/color/oklch.tsComposite a translucent foreground at alpha over an opaque backdrop, source-over, and return the opaque colour a reader actually sees.
CONTRAST_USE_LABELSconstlib/color/apca.ts-
ContrastCheckinterfacelib/color/derive.tsOne 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.
contrastRatiofunctionlib/color/wcag.tsThe contrast ratio, from 1 (identical) to 21 (black on white).
contrastRatioOklchfunctionlib/color/wcag.ts-
ContrastUsetypelib/color/apca.tsWhat a pair is being used for. Determines which floor applies.
convertUnitfunctionlib/opsinjs.tsOne value in another unit, or undefined when this system does not own the factor.
CORNER_SHAPE_VALUESconstlib/preset.ts-
CVD_LABELSconstlib/color/cvd.ts-
CVD_TYPESconstlib/color/cvd.ts-
CvdCollisioninterfacelib/color/cvd.tsTwo colours that stop being distinguishable under one kind of colour vision deficiency, and the Lc left between them once simulated.
CvdTypetypelib/color/cvd.tsThe three dichromacies, plus the achromatic check every specimen must also survive.
DataStatetypelib/opsinjs.tsThe state a data surface is in, named once so the surfaces converge on one vocabulary, though no component accepts it yet.
DecodeErrortypelib/preset.tsWhy 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.
decodePresetfunctionlib/preset.tsDecode a preset code.
DecodeResultinterfacelib/preset.tsThe outcome of reading a preset code. Either the preset and its version, or an error and a sentence a person can act on.
decodeTransferfunctionlib/color/oklch.tssRGB gamma-encoded channel → light-linear. Also used for Display-P3, which shares sRGB's transfer curve.
DEFAULT_BASEconstlib/registry.ts-
DEFAULT_BASEconstlib/routes.ts-
DEFAULT_PRESETconstlib/preset.ts-
DEFAULT_STYLEconstlib/registry.ts-
DEFAULT_STYLEconstlib/routes.ts-
DENSITY_VALUESconstlib/preset.ts-
deprecatedTokensfunctionlib/tokens.ts-
DerivedThemeinterfacelib/color/derive.tsEverything derivation produces from one brand colour. Both ramps, every role in light and dark, the contrast checks, the warnings, and whether it is sound.
DeriveOptionsinterfacelib/color/derive.tsThe knobs on theme derivation. Every one of them has a default, so a brand colour on its own is already a complete input.
deriveRampfunctionlib/color/derive.tsBuild one ramp from a seed, clamping to sRGB and recording the P3 enhancement.
deriveThemefunctionlib/color/derive.tsDerive a complete, contrast-validated theme from one brand colour.
DeriveWarninginterfacelib/color/derive.tsOne thing the derivation has to say about a theme, as a level, a stable code and a message.
Detenttypelib/opsinjs.tsHow far a sheet is open.
displayP3ToOklchfunctionlib/color/oklch.tsGamma-encoded Display-P3, 0 to 1 per channel → OKLCH.
DOCS_BASEconstlib/routes.tsThe docs base segment. Everything else derives from it.
docsMarkdownPathfunctionlib/routes.tsThe same page as processed markdown: /docs/components/range-bar.md.
DocsNavinterfacelib/docs-nav.ts-
docsPathfunctionlib/routes.tsThe 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.
doctrinePathfunctionlib/routes.tsA doctrine page reference as written in frontmatter, such as two-colour-axes, or foundations/colour/contrast-and-apca when it is not in Health.
editUrlfunctionlib/routes.ts"Edit this page" on GitHub, from a source file path relative to the content root.
encodePresetfunctionlib/preset.tsEncode a theme as a preset code.
encodeTransferfunctionlib/color/oklch.tsLight-linear channel → gamma-encoded.
EXAMPLE_SOURCEconstlib/opsinjs.tsThe only citation an opsinjs example, demo or preview may carry.
explainUnresolvedfunctionlib/registry.tsExplain an empty lookup.
findAliasProblemsfunctionlib/catalogue.tsThe uniqueness check, as a function rather than as a comment.
findByAliasfunctionlib/catalogue.ts-
findCollisionsfunctionlib/color/cvd.tsCheck 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.
findUnitfunctionlib/opsinjs.tsThe unit a symbol names, or undefined when this system has never heard of it.
fitfunctionlib/color/derive.tsFit an arbitrary colour into the shipped gamut without moving its hue or lightness.
FLOOR_VALUESconstlib/preset.tsWhich APCA floor the theme is validated against. standard is the published one.
FORMAT_VERSIONconstlib/preset.tsBump this, and add a decode branch, whenever a field changes shape.
formatDisplayP3functionlib/color/oklch.tscolor(display-p3 0.9 0.2 0.3). Channels are clamped, because this is an output format.
formatHexfunctionlib/color/oklch.ts#rrggbb, clamped into sRGB.
formatOklchfunctionlib/color/oklch.tsoklch(0.622 0.17 15), or with an alpha, oklch(0.622 0.17 15 / 0.5).
formatRatiofunctionlib/color/wcag.tsRatios are conventionally quoted to one decimal place and rounded DOWN, so a published figure is never better than the measurement.
formatTokenfunctionlib/tokens.tsRender a token in one of the copyable formats.
foundationsPathfunctionlib/routes.ts-
Gamuttypelib/color/oklch.tsThe colour spaces this module can express a colour in.
GAMUT_EPSILONconstlib/color/oklch.tsThe 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_VALUESconstlib/preset.ts-
GeneratedBannedWordinterfacelib/opsinjs.tsOne banned word: the word a component's copy must not use, what to write in its place, and why the word is barred.
getAllPagesfunctionlib/source.tsEvery page in the corpus. The input to the sitemap, llms.txt and the shards.
getByCategoryfunctionlib/catalogue.ts-
getByStatusfunctionlib/catalogue.ts-
getCataloguefunctionlib/catalogue.tsEvery row.
getDocsNavfunctionlib/docs-nav.ts-
getEntryfunctionlib/catalogue.ts-
getPagefunctionlib/source.tsOne page by its slug segments, or undefined.
getPagesInSectionfunctionlib/source.tsPages under one top-level section, in tree order.
getPageTreefunctionlib/source.tsThe page tree the docs layout renders.
getRegistryEntryfunctionlib/registry.tsResolve one entry, or null.
getShippedfunctionlib/catalogue.tsEvery catalogue row. Not a claim about code. Read implemented in /r/index.json, or toIndexRow's isBuilt argument, for that.
getTokenfunctionlib/tokens.ts-
getTokensfunctionlib/tokens.ts-
groupedfunctionlib/tokens.tsTokens grouped for a table: namespace → group → tokens, in emit order.
groupedByCategoryfunctionlib/catalogue.tsEvery category that has at least one row, in the declared order, with its rows.
hasComponentPagefunctionlib/catalogue.tsTrue when /docs/components/\<id\> resolves to a page.
HEALTH_CATEGORIESconstlib/status.ts-
HEALTH_CATEGORY_LABELSconstlib/status.ts-
HealthCategorytypelib/status.tsWhat a reading is ABOUT. Identity, never verdict.
healthPathfunctionlib/routes.tsA health doctrine page, by the page id that governedBy and implements use.
inGamutfunctionlib/color/oklch.ts-
isBuiltfunctionlib/registry.tsTrue 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.
isClinicalStatusfunctionlib/status.ts-
isDevelopmentfunctionlib/opsinjs.tsTrue in development, and false wherever that cannot be established.
isHealthCategoryfunctionlib/catalogue.tsTrue for the four health-* categories, which carry the extra clinical obligations.
isHealthCategoryfunctionlib/status.ts-
isKindfunctionlib/status.ts-
isKnownIdfunctionlib/catalogue.tsDoes this id exist at all, under any status?
isNotImplementedfunctionlib/status.tsTrue when a page at this status must carry a not-implemented marker.
isResolvablefunctionlib/registry.tsTrue when the id exists in the catalogue, whatever its status. Used to decide 404 from "no".
isStatusfunctionlib/status.ts-
issueUrlfunctionlib/routes.tsA prefilled docs issue. Used by \<Feedback\> when the feedback endpoint is unavailable.
joinPathfunctionlib/routes.tsJoin path segments into a root-relative path, dropping empties and stray slashes.
Kindtypelib/status.tsA 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.
KINDSconstlib/status.ts-
LEGACY_ROOT_SEGMENTSconstlib/redirects.tsThe 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_STEPconstlib/preset.tsThe quantisation of lightness: 1% per step.
linearP3ToLinearSrgbfunctionlib/color/oklch.tsLight-linear Display-P3 → light-linear sRGB, through XYZ (D65).
linearSrgbToLinearP3functionlib/color/oklch.tsLight-linear sRGB → light-linear Display-P3, through XYZ (D65).
linearSrgbToOklabfunctionlib/color/oklch.tsLight-linear sRGB → OKLab. Ottosson's forward matrices.
linearToSrgbfunctionlib/color/oklch.ts-
listBasesfunctionlib/registry.ts-
listByKindfunctionlib/registry.tsEvery entry of a kind, for the examples gallery and the screens index.
listStylesfunctionlib/registry.ts-
MaterialRungtypelib/opsinjs.tsA rung of the material ladder, meaning how a surface sits above what is behind it.
maxChromafunctionlib/color/oklch.tsThe largest chroma that is still inside gamut at this lightness and hue.
minimumFontSizefunctionlib/color/apca.tsThe 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.
mixOklchfunctionlib/color/oklch.tsMix 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_VALUESconstlib/preset.tsThe colour mode a theme opens in. system follows the reader's own setting.
NavGroupinterfacelib/docs-nav.ts-
NavHeadinginterfacelib/docs-nav.ts-
NavLinkinterfacelib/docs-nav.ts-
NavSectioninterfacelib/docs-nav.ts-
NEUTRAL_CHROMA_VALUESconstlib/preset.tsChroma of the neutral ramp. Index 0 is a dead grey; the default is index 2.
ogUrlfunctionlib/routes.tsThe OG image service. One endpoint for the whole site. There is no per-route opengraph-image.
Oklabinterfacelib/color/oklch.tsA colour in OKLab.
oklabToLinearSrgbfunctionlib/color/oklch.tsOKLab → light-linear sRGB. Ottosson's inverse matrices.
oklabToOklchfunctionlib/color/oklch.ts-
Oklchinterfacelib/color/oklch.tsA colour in OKLCH. l 0 to 1, c unbounded, h in degrees.
oklchToDisplayP3functionlib/color/oklch.tsOKLCH → gamma-encoded Display-P3, 0 to 1 per channel. Not clamped.
oklchToOklabfunctionlib/color/oklch.ts-
oklchToRgb255functionlib/color/oklch.tsOKLCH → 0 to 255 sRGB integers, clamped. The input for both contrast models.
oklchToSrgbfunctionlib/color/oklch.tsOKLCH → gamma-encoded sRGB, 0 to 1 per channel. Not clamped.
OPSIN_ERRORSconstlib/opsinjs.tsThe table warnOnce() reads. Generated from tokens/errors.json.
OpsinErrorinterfacelib/opsinjs.tsOne warning code: what it is called, how severe it is, and the page that prevents it.
OpsinErrorCodetypelib/opsinjs.tsEvery warning code opsinjs can emit.
OpsinErrorParamstypelib/opsinjs.tsThe values a message template asks for, keyed by placeholder name.
OpsinErrorSeveritytypelib/opsinjs.tsHow severe a warning is.
ORPHAN_ALLOWLISTconstlib/routes.tsRoutes that exist but are not reachable from the top nav or the sidebar, and are allowed not to be.
OUTLINE_IS_EXACTconstlib/status.tsNo kind other than component has an exact outline.
P3_CHROMA_GAINconstlib/color/derive.tsHow much more chroma Display-P3 is allowed to spend than sRGB at the same step.
parseColorfunctionlib/color/oklch.tsParse 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.
parseHexfunctionlib/color/oklch.ts#rgb, #rrggbb or #rrggbbaa → sRGB 0 to 1. Returns null on anything else.
passesApcafunctionlib/color/apca.ts-
Presetinterfacelib/preset.tsA theme as a person describes it. What encodePreset takes and decodePreset returns.
PRESET_PREFIXconstlib/preset.ts-
presetBrandColorfunctionlib/preset.tsThe brand colour a preset describes, as an oklch() string the colour engine can parse.
RADIUS_VALUESconstlib/preset.ts--opsin-radius-base in px. Index 3 (14px) is the product default.
Ramptypelib/color/derive.tsOne complete lightness ramp, as a value per step. The chromatic ramp and the neutral ramp of a derived theme are both this shape.
RAMP_LIGHTNESSconstlib/color/derive.ts-
RAMP_STEPSconstlib/color/derive.tsThe ramp steps, and the lightness of each. Mirrors ladder in tokens/color.json.
RampSteptypelib/color/derive.tsOne 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.
RampStepValueinterfacelib/color/derive.tsOne 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.
referencePathfunctionlib/routes.ts-
ReferenceRangeinterfacelib/opsinjs.tsThe interval a reading is being compared against, and who says so.
REFUSED_CONVERSIONSconstlib/opsinjs.tsConversions this system refuses to publish, and why. Generated from tokens/units.json.
RefusedConversioninterfacelib/opsinjs.tsA pair people expect to be arithmetic and is not, with the reason.
registryInstallUrlfunctionlib/routes.tsWhat a consumer types to install an item. Rendered by \<ComponentInstall\>.
RegistryLookuptypelib/registry.tsBoth call shapes are supported on purpose.
registryMetafunctionlib/registry.tsProvenance 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.
RegistryQueryinterfacelib/registry.tsA request for one registry item, by id and optionally by base, style and kind. Anything left out falls back to the default.
registryRoutesconstlib/routes.ts-
relativeLuminancefunctionlib/color/wcag.tsWCAG 2.2 relative luminance, 0 for black and 1 for white.
RETIRED_PAGESconstlib/redirects.tsEvery 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_NOTICEconstlib/status.tsTHE REVIEW FLOOR, AS ONE STRING.
Rgbinterfacelib/color/oklch.tsRed, green and blue, each 0 to 1, in whichever space the function says.
Rgb255typelib/color/apca.tsA colour as 0 to 255 sRGB integers, which is what APCA is defined over.
RoleNametypelib/color/derive.tsThe roles a derived theme guarantees. Components consume these and never a step.
RolePairinterfacelib/color/derive.tsOne 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.
RoleValueinterfacelib/color/derive.tsWhat 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.
routesconstlib/routes.ts-
screenLuminancefunctionlib/color/apca.tsScreen 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.
searchCataloguefunctionlib/catalogue.tsThe 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.
searchTokensfunctionlib/tokens.tsSubstring match over name, description and value. The /tokens browser's filter.
SECTION_OUTLINESconstlib/status.tsThe H2s a page must have, by kind, for every kind but component.
SHIPPED_PRESETSconstlib/preset.tsThe 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.
Showcaseinterfacelib/showcases.tsThe screens on /showcase: whole screens assembled only from opsinjs components, each one rendered from a file under registry/screens/.
showcasesconstlib/showcases.tsThe showcase grid, in the order it renders.
simulatefunctionlib/color/cvd.tsSimulate a dichromacy. severity 0 returns the input unchanged and 1 returns full dichromacy; values between interpolate in linear light.
simulateOklchfunctionlib/color/cvd.ts-
simulateRgb255functionlib/color/cvd.ts-
siteconstlib/routes.ts-
sourceconstlib/source.ts-
spokenUnitfunctionlib/opsinjs.tsHow a screen reader should say this unit for this count.
srgbToLinearfunctionlib/color/oklch.ts-
srgbToOklchfunctionlib/color/oklch.tsGamma-encoded sRGB, 0 to 1 per channel → OKLCH.
Statustypelib/status.tsThe release phase of a component page or a catalogue entry.
STATUS_METAconstlib/status.ts-
STATUS_ORDERconstlib/status.tsStatuses in display order.
statusCountsfunctionlib/catalogue.tsCounts per status, in display order. The input to \<SectionProgress\>.
STATUSESconstlib/status.tsA RELEASE PHASE IS NEVER PAINTED, AND THERE IS NOW NOTHING HERE TO PAINT IT WITH.
StatusMetainterfacelib/status.tsWhat 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.
textOffunctionlib/docs-nav.tsPlain text of a page-tree name or a heading title, which may be markup.
themeToCssVariablesfunctionlib/color/derive.tsEvery custom property a derived theme emits, ready for a stylesheet or a copy button.
toGrayscalefunctionlib/color/cvd.tsGrayscale by relative luminance rather than by an average of the channels.
toIndexRowfunctionlib/catalogue.tsOne row of /r/index.json and of the generated catalogue reference page.
TOKEN_FORMAT_LABELSconstlib/tokens.ts-
TOKEN_NAMESPACE_LABELSconstlib/tokens.ts-
TOKEN_NAMESPACESconstlib/tokens.ts-
TOKEN_TIER_DESCRIPTIONSconstlib/tokens.ts-
TOKEN_TIER_LABELSconstlib/tokens.ts-
TokenFormattypelib/tokens.tsThe formats the /tokens and /colors browsers can copy a value in.
tokenMetafunctionlib/tokens.ts-
tokensAreGeneratedfunctionlib/tokens.tsWhether the generated layer has actually been produced.
tokensUsedByfunctionlib/tokens.tsEvery 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.
toRgb255functionlib/color/oklch.ts0 to 1 sRGB → 0 to 255 integers, clamped.
toRgb255Inputfunctionlib/color/apca.tsCoerce any accepted colour form to an sRGB triple.
TrendPointinterfacelib/opsinjs.tsOne reading in a series, for the components that draw change over time.
Unitinterfacelib/opsinjs.tsOne unit: what it is called, what a reader sees, and how it is SPOKEN.
UNIT_CONVERSIONSconstlib/opsinjs.tsEvery convertible ordered pair, composed by the generator. Never authored by hand.
unitConversionfunctionlib/opsinjs.tsThe authored conversion between two symbols, or undefined when there is none.
UnitConversioninterfacelib/opsinjs.tsAn exact conversion between two units of the same kind.
UNITSconstlib/opsinjs.tsEvery unit this system can speak, sorted by id. Generated from tokens/units.json.
UNITS_BY_SYMBOLconstlib/opsinjs.tsThe lookup findUnit() reads, derived from UNITS rather than emitted twice.
unknownImplementsIdsfunctionlib/catalogue.tsValidate 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.
UnknownStatustypelib/status.tsThe absence of an assertion, which covers a reading never taken, a stale reading, or a reading whose reference range the product does not own.
UnresolvedReasoninterfacelib/registry.tsWhy a lookup came back empty. The input to \<NotBuiltYet\>.
ViewKindtypelib/routes.tsWhat a /view route can render.
ViewParamsinterfacelib/routes.tsEverything a chrome-less preview URL can carry. Name and kind become path segments, and the rest become query parameters applied before first paint.
viewPathfunctionlib/routes.ts/view/base/base-lyra/component/range-bar?mode=dark&text=200.
WarningLeveltypelib/color/derive.tsHow serious a derivation warning is. An error makes the theme unsound and stops it shipping, while a warning and a note are advisory.
warnOncefunctionlib/opsinjs.tsReport a defect in development, once, and never do anything else.
wcagconstlib/color/wcag.tsThe short name, matching apca(). Identical to contrastRatio.
WCAG_FLOORconstlib/color/wcag.tsThe three WCAG 2.2 thresholds this system checks against.
WcagUsetypelib/color/wcag.tsWhich WCAG 2.2 contrast threshold applies. Body text, large text and non- text content each have a different floor.
wcagVerdictfunctionlib/color/wcag.ts-
WcagVerdictinterfacelib/color/wcag.tsThe 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

MemberTypeRequiredWhat it is
aliasstringYes-
reason"duplicate" | "collides-with-id"Yes-
ownersstring[]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

MemberTypeRequiredWhat it is
lcnumberYes-
magnitudenumberYes-
polarity"dark-on-light" | "light-on-dark" | "indistinguishable"Yes-
useContrastUseYes-
floornumberYes-
passesbooleanYes-
headroomnumberYes-

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

MemberTypeRequiredWhat it is
code"OPSIN-0001"Yes-
categoryHealthCategoryYes-
statusClinicalStatusYes-
messagestringYes-
docsstringYes-

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

MemberTypeRequiredWhat it is
namestringYes-
titlestringYes-
descriptionstringYes-
type"registry:ui"Yes-
categoryCatalogueCategoryYes-
statusStatusYes-
sincestringYes-
aliasesstring[]Yes-
implementedbooleanYes-
docsstring | nullYes-
dependenciesstring[]No-
registryDependenciesstring[]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

MemberTypeRequiredWhat it is
wordstringYes-
sentencestringYes-
assignedBystringYes-
iconstringYes-
levelnumberYes-

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 | UnknownStatus

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.

export type ColorInput = Rgb255 | Oklch | string

Used 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

MemberTypeRequiredWhat it is
pairstringYes-
useContrastUseYes-
apcaLcnumberYes-
wcagRationumberYes-
passesbooleanYes-
advisorybooleanNo-

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

MemberTypeRequiredWhat it is
typeCvdTypeYes-
astringYes-
bstringYes-
lcnumberYes-

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

MemberTypeRequiredWhat it is
presetPreset | nullYes-
versionnumber | nullYes-
errorDecodeError | nullYes-
messagestring | nullYes-

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

MemberTypeRequiredWhat it is
brandOklchYes-
seedOklchYes-
brandRampRampYes-
neutralRampRampYes-
rolesRecord<RoleName, RolePair>Yes-
checksContrastCheck[]Yes-
warningsDeriveWarning[]Yes-
soundbooleanYes-

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

MemberTypeRequiredWhat it is
neutralChromanumberNo-
gamutGamutNo-
maxSeedChromanumberNo-

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

MemberTypeRequiredWhat it is
levelWarningLevelYes-
codestringYes-
messagestringYes-

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

MemberTypeRequiredWhat it is
sectionsNavSection[]Yes-
headingsRecord<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

MemberTypeRequiredWhat it is
wordstringYes-
insteadstringYes-
reasonstringYes-

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"

This symbol has no doc comment yet.

A interface in lib/docs-nav.ts.

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

Members

MemberTypeRequiredWhat it is
titlestringNo-
linksNavLink[]Yes-

Used by NavSection.

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

MemberTypeRequiredWhat it is
depth2 | 3Yes-
idstringYes-
textstringYes-

Used by DocsNav, getDocsNav.

This symbol has no doc comment yet.

A interface in lib/docs-nav.ts.

export interface NavLink {
  title: string
  url: string
}

Members

MemberTypeRequiredWhat it is
titlestringYes-
urlstringYes-

Used by NavGroup.

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

MemberTypeRequiredWhat it is
idstringYes-
titlestringYes-
urlstringYes-
metastringNo-
groupsNavGroup[]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

MemberTypeRequiredWhat it is
lnumberYes-
anumberYes-
bnumberYes-
alphanumberNo-

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

MemberTypeRequiredWhat it is
lnumberYes-
cnumberYes-
hnumberYes-
alphanumberNo-

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

MemberTypeRequiredWhat it is
codeOpsinErrorCodeYes-
severityOpsinErrorSeverityYes-
titlestringYes-
messagestringYes-
docsstringYes-
paramsstring[]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

MemberTypeRequiredWhat it is
huenumberYes-
chromanumberYes-
lightnessnumberYes-
neutralChromanumberYes-
radiusnumberYes-
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

MemberTypeRequiredWhat it is
stepRampStepYes-
srgbOklchYes-
p3OklchNo-
clampedbooleanYes-
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

MemberTypeRequiredWhat it is
lownumberNo-
highnumberNo-
sourcestringYes-
asOfstringNo-

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

MemberTypeRequiredWhat it is
between[string, string]Yes-
reasonstringYes-
docsstringYes-

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

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

Members

MemberTypeRequiredWhat it is
namestringYes-
basestringNo-
stylestringNo-
kindRegistryKindNo-

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

MemberTypeRequiredWhat it is
rnumberYes-
gnumberYes-
bnumberYes-
alphanumberNo-

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

MemberTypeRequiredWhat it is
lightRoleValueYes-
darkRoleValueYes-

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

MemberTypeRequiredWhat it is
sourcestringYes-
valueOklchYes-
cssstringYes-

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

MemberTypeRequiredWhat it is
slug"diabetes-medicines-app" | "patient-record-portal" | "results-screen"Yes-
titlestringYes-
descriptionstringYes-
domainstringYes-
componentsnumberYes-
highlightsstring[]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

MemberTypeRequiredWhat it is
labelstringYes-
summarystringYes-

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

MemberTypeRequiredWhat it is
atstringYes-
valuenumber | nullYes-
statusClinicalStatusNo-

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

MemberTypeRequiredWhat it is
idstringYes-
symbolstringYes-
spokenstringYes-
pluralstringYes-
measuresstringYes-
joinedtrueNo-

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

MemberTypeRequiredWhat it is
fromstringYes-
tostringYes-
numeratornumberYes-
denominatornumberYes-
offsetNumeratornumberYes-
offsetDenominatornumberYes-
basisstring[]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

MemberTypeRequiredWhat it is
namestringYes-
reason"not-built" | "unknown"Yes-
statusStatus | nullYes-
messagestringYes-

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

MemberTypeRequiredWhat it is
namestringYes-
kindViewKindNo-
basestringNo-
stylestringNo-
mode"light" | "dark"No-
density"comfortable" | "compact"No-
text100 | 125 | 150 | 200No-
themestringNo-
accentThemestringNo-
accentstringNo-

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

MemberTypeRequiredWhat it is
rationumberYes-
useWcagUseYes-
floornumberYes-
passesAAbooleanYes-
passesAAAbooleanYes-
criterionstringYes-