---
title: "State of the system"
description: "Dated and blunt about what exists today, what is safe to build on, what will break, and who is behind it."
url: "https://opsinjs.pensievelabs.org/project/state-of-the-system"
source: "https://opsinjs.pensievelabs.org/project/state-of-the-system.md"
section: "Project"
kind: "project"
reviewed: "2026-09-20"
reviewer: "engineering"
aliases: ["what exists", "is it ready", "production ready", "current state"]
---
> 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.
## Read this before you depend on anything here [#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](./decisions/0002-shadcn-registry-distribution.mdx). 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](./decisions/0025-the-audit-is-author-run.mdx).**
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 [#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](../accessibility/accessibility-statement.mdx) |
## What is safe to build on, in order [#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](./licence-and-attribution.mdx). 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](../agents/index.mdx).
**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 [#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](../theming/category-palettes.mdx).
* **The per-symbol API pages.** Everything under
[Reference → API](../reference/api/index.mdx) 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](./decisions/0002-shadcn-registry-distribution.mdx).
## What is not measured, and therefore not claimed [#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 [#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](./community.mdx) says
otherwise. Decisions are recorded before implementation as
[decision records](./decisions/index.mdx).
## How to tell if this page is stale [#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](./changelog/index.mdx). **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.