---
title: "Start here"
description: "A five-minute map of this site, and the shortest useful path through it for your role."
url: "https://opsinjs.pensievelabs.org/start"
source: "https://opsinjs.pensievelabs.org/start.md"
section: "Start here"
kind: "guide"
reviewed: "2026-09-20"
reviewer: "content"
aliases: ["start here", "five minute map", "where do I begin"]
---
> Elements written as `` below are opsinjs documentation
> components. Their attributes are the content: the values they render are
> generated from `tokens/*.json` and `registry/catalogue.ts` and are
> published separately at https://opsinjs.pensievelabs.org/r/index.json and under the Reference
> section.
> Nothing is missing from this page. The data simply does not live in
> the prose.
## Overview [#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.
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?](./is-opsinjs-right.mdx) and stop there.
## Read this in the order that matches your job [#read-this-in-the-order-that-matches-your-job]
**You are deciding whether to adopt it.**
[Is opsinjs right for this project?](./is-opsinjs-right.mdx) →
[Safety, scope and limitations](./safety-scope-and-limitations.mdx) →
[The two colour axes](../health/two-colour-axes.mdx). 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](./quick-start.mdx) →
[Choose a component](../recipes/choose-a-component.mdx) → 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](./for-designers.mdx) 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](../content/index.mdx) →
[Plain-English A to Z](../content/plain-english-a-z.mdx) →
[Numbers, units and precision](../health/numbers-units-precision.mdx). 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](../agents/rules-for-agents.mdx) →
[Raw markdown API](../agents/raw-markdown-api.mdx). 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 [#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](../health/index.mdx) has the rules about what an
interface may assert about a person's body. Real and complete today.
* **Foundations.** [Foundations](../foundations/index.mdx) says what a token
*means*: colour, material, motion, type, space, shape. Real today, and the
layer every implemented component reads from.
* **Components.** [Components](../components/index.mdx) 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](../recipes/index.mdx) covers task-first
assemblies: components plus tokens plus copy rules, in one scroll. The five
[Screens](../screens/index.mdx) specimens are specifications; none has been
built.
Two more you will need eventually: [Handbook](../handbook/index.mdx) and
[Theming](../theming/index.mdx) tell you how to *change* things, and
[Reference](../reference/index.mdx) is the generated list of everything.
## Know what pre-release means here [#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](../project/decisions/0002-shadcn-registry-distribution.mdx). 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](../project/decisions/0025-the-audit-is-author-run.mdx). `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](../project/community.mdx) is where to say
it.
## Verify it worked [#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](../health/two-colour-axes.mdx).
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 [#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](../content/plain-english-a-z.mdx); numeric formatting is
canonical in
[Numbers, units and precision](../health/numbers-units-precision.mdx). 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](./reading-these-docs.mdx#for-agents).
## Next [#next]
* [Quick start](./quick-start.mdx) is the end-to-end path for a single result
card, using three components that are implemented.
* [Reading these docs](./reading-these-docs.mdx) covers page contracts, status
badges, and how to read a token or contrast table without being misled.
* [Health](../health/index.mdx) is the doctrine layer, and the part of opsinjs
that is worth reading even if you never install it.