Start here

Overview

This site is large, and most of it is doctrine rather than code. That is deliberate, and it stayed true after the code arrived: every catalogue row is implemented and installable, and the tokens, the rules and the accessibility contract are still the part with the longest useful life. This page is the map.

60 shipped

Five minutes gets you three things: whether opsinjs fits your product, what it will and will not do for you, and where the rule you need actually lives. If you only have two minutes, read Is opsinjs right for this project? and stop there.

Read this in the order that matches your job

You are deciding whether to adopt it. Is opsinjs right for this project? → Safety, scope and limitations → The two colour axes. Twenty minutes, and the second page is the one that will decide it for anything clinical-adjacent.

You are an engineer about to build a screen. Quick start → Choose a component → the component page → its governedBy doctrine pages. The decision table is the fastest route from "I have a number and a range" to the right component.

You are a designer. For designers is the role-shaped entry point: what is fixed by the system, what you are expected to decide, and which foundations pages are the ones you will actually reference.

You are writing the copy. Content and language → Plain-English A to Z → Numbers, units and precision. In a health product the words are not decoration around the component; they are most of what the component does.

You are an agent, or you are configuring one. Rules for agents → Raw markdown API. Append .md to any docs URL for processed markdown. The three rules that matter most: never invent a threshold, never mix the colour axes, and never generate an implementation from a page whose status says there is none.

Understand the shape before you go looking

Four page kinds cover almost everything on this site, and knowing which one you are on tells you what you can expect from it:

• Doctrine. Health has the rules about what an interface may assert about a person's body. Real and complete today.
• Foundations. Foundations says what a token means: colour, material, motion, type, space, shape. Real today, and the layer every implemented component reads from.
• Components. Components lists every catalogued id, and every one of them is implemented and installable. Each carries a written specification and shipped code, which the page shows side by side. Every component page names its intent, when not to use it, its clinical contract, its API, and the accessibility bar it must clear.
• Recipes and screens. Recipes covers task-first assemblies: components plus tokens plus copy rules, in one scroll. The five Screens specimens are specifications; none has been built.

Two more you will need eventually: Handbook and Theming tell you how to change things, and Reference is the generated list of everything.

Know what pre-release means here

There is code, and there is no host serving it. opsinjs.pensievelabs.org is the intended host and does not resolve yet, so the commands on the installation pages work only against a registry you point @opsinjs at yourself; and there is no npm package, which is a permanent answer rather than a gap. Distribution is registry copy-in, decided in ADR 0002. Every installation page says so at the top.

Everything built is still pre-release. Every opsinjs component has been audited against WCAG 2.2 AA by its own authors, in a static source pass and a rendered pass, and the findings were fixed in the same change. That is an author-run audit, not an independent review, and no component has had a clinical review, which is still pending. The record is ADR 0025. shipped means the source installs and that the author audit ran, and it does not mean an independent accessibility review or a clinical review has happened. Nothing here is for a production health surface until a clinician signs it. The API of a shipped component may change in any release, and every change carries a changelog entry.

The useful consequence is that both layers are reviewable now, while they are still cheap to change. If an API looks wrong to you, that is the most valuable thing you can tell us, and Community is where to say it.

Verify it worked

You are oriented if you can do three things:

1. Name the rule that stops you colouring a "Sleep" tile amber because sleep was poor. It is the never-mix rule in The two colour axes.
2. Say where a threshold comes from. It comes from your product's clinical owner, never from opsinjs and never from a component default.
3. Find a component's governing doctrine without searching. It is listed in the page header under governedBy, and the doctrine page lists the component back.

Troubleshooting

The sidebar is long and you cannot find a topic. Use search (⌘ K). Every page carries aliases, which are the words a reader would actually type, including clinical vocabulary like a1c, spo2 and resting heart rate. Searching for the measurement therefore usually lands you on the component that displays it.

You found two pages that seem to cover the same thing. One of them is canonical and says so. Plain-language vocabulary is canonical in Plain-English A to Z; numeric formatting is canonical in Numbers, units and precision. The other page links to it rather than restating it, and a build check enforces that.

A link took you to a page that shows no code. Read its status. shipped means there is code and an install command. planned means a specification and no implementation, which is a definite answer rather than a missing page. See Reading these docs.

Next

• Quick start is the end-to-end path for a single result card, using three components that are implemented.
• Reading these docs covers page contracts, status badges, and how to read a token or contrast table without being misled.
• Health is the doctrine layer, and the part of opsinjs that is worth reading even if you never install it.