State of the system
Dated and blunt about what exists today, what is safe to build on, what will break, and who is behind it.
Read this before you depend on anything here
As of the date at the foot of this page, opsinjs is a documentation site, a set
of design tokens, and sixty React components you can install as registry
source. Every catalogue row is implemented and installable. No component
ships as an npm package and none is meant to. Distribution is registry copy-in, decided in
ADR 0002. Every opsinjs
component has been audited against WCAG 2.2 AA by its own authors, in a static
source pass and a rendered pass, with the findings fixed in the same change.
That audit is author-run, so it is not an independent review, and no component
has had a clinical review. shipped means the source installs, and it does not
mean an independent review or a clinical review has happened. Nothing here is
for a production health surface until a clinician signs it. The record is
ADR 0025.
That paragraph is the first thing on this page because almost every other page on
this site is written as though the whole system were finished. A component page
describes an anatomy, an API and an accessibility bar in the present tense,
because a specification written in the conditional is unreadable. The marker that
tells you which you are reading is the status in a component page's
frontmatter. Every component is shipped, which means the code exists and the
API may change in any release. No other kind of page carries the field at all.
This page is where the plain version of that lives.
What exists today
| Surface | State | Safe to build on? |
|---|---|---|
| Doctrine covering Health, Accessibility, Content and language | Written, self-reviewed, no external clinical review | Yes, as guidance. Cite it with the reviewed date on the page |
| Foundations covering colour, materials, motion, type, space and shape | Written against real tokens | Yes, as guidance |
Design tokens (tokens/*.json) | Authored: two colour axes, six material rungs, spring easings, type, space and shape scales | Yes, as values. Names may change before 1.0 |
| Generated tables and measured contrast | Produced by scripts from those tokens; empty wherever the source is empty | Yes, for the presets described. Not for a theme you derived |
| Component pages (60) | Written as specifications; for all sixty they now also describe shipped code | Yes to design against, and to review an implementation against |
| React components | 60, all shipped, under registry/bases/base/, so every catalogue id resolves to built code | Yes to prototype and evaluate, knowing a shipped API may move in any release, that its WCAG 2.2 AA audit was author-run rather than independently reviewed, and that clinical review is still pending. No for a production health surface |
@opsinjs/* npm packages | None published | No |
Registry endpoints under /r | Serve the catalogue, and the full source of all sixty implemented items | Yes. The item shape follows the upstream shadcn specification and moves with it |
| CLI | Does not exist and is not planned first, because npx shadcn already does the job | Not applicable |
| Accessibility conformance | Audited against WCAG 2.2 AA by the authors; no independent audit has taken place | No, not until an independent review and a clinical sign-off. See Accessibility statement |
What is safe to build on, in order
1. The guidance. The clinical, content and accessibility doctrine is the part of this project with the fewest dependencies on anything shipping. It is licensed CC BY 4.0 precisely so that a team can quote it in a design-history file or a hazard log; see Licence and attribution. Where a page states an opinion rather than a cited finding, it says so in its frontmatter and in the text.
2. The token values. The numbers and colours in tokens/*.json are real,
generated into CSS, and measured for contrast. Copying a value into your own
system today is a reasonable thing to do. Copying a name is a smaller bet:
names are covered by semver only after 1.0, and this project is at 0.x.
3. The URL contract. Every page has a .md twin, /llms.txt and its shards
exist, and /r/index.json describes the catalogue. Those addresses are meant to
be depended on by programs, and changing one is treated as a breaking change to
the documentation. See Agents and automation.
4. The component pages. A component page tells you what the component
asserts, what it must never be read as, its anatomy and API, and the
accessibility bar it has to clear. All sixty pages describe code you can install
and read, and the page is the right place
to check an implementation against. Read status rather than inferring how far a
component has settled: shipped means the API may change in any release, and its
WCAG 2.2 AA audit was author-run rather than independently reviewed, with clinical
review still pending. It
is in the frontmatter, in the .md twin and in /r/index.json, so a program
never has to guess.
What will break
- Token names before 1.0. Values are stable in intent; identifiers are not.
- The category members. The status axis is closed at four levels and will not grow. The category axis is expected to change as real products bring real subjects. See Category palettes.
- The per-symbol API pages. Everything under Reference → API is a seed until a package ships.
- Registry item shape, where the upstream shadcn registry specification moves. We follow it rather than fork it; that is ADR 0002.
What is not measured, and therefore not claimed
No independent accessibility audit. The WCAG 2.2 AA audit on record was run by the components' own authors, not an outside reviewer, and no component has had a clinical review. No cross-browser test matrix running in CI. No performance budget enforced against a real bundle, because there is no bundle. No usability research with patients. The research citations on health pages are other people's published work, read and cited, not studies this project ran. Where a page needs a number that nobody has measured, it renders an honest empty state naming the script that will fill it, rather than an estimate.
Who maintains it
The opsinjs maintainers, in the open, with no company behind the project and no support contract. Assume a small team until Community says otherwise. Decisions are recorded before implementation as decision records.
How to tell if this page is stale
Compare the review date at the foot of this page with the newest entry in the
changelog. If the changelog is newer, trust the
changelog. This page is rewritten as part of every release and is reviewed
every three months; check-freshness.mts reports it as expired if that lapses,
and an expired state-of-the-system is treated as a release blocker rather than a
documentation chore.
Last read through against the system on 2026-09-20. Due for review every 3 months; expiry is reported by pnpm run check:freshness.