---
title: "Reference"
description: "Written by a script from the same source the build uses, covering every token, data attribute, CSS variable, key, exported type and defined term."
url: "https://opsinjs.pensievelabs.org/reference"
source: "https://opsinjs.pensievelabs.org/reference.md"
section: "Reference"
kind: "reference"
reviewed: "2026-09-02"
reviewer: "engineering"
aliases: ["generated reference", "what is generated"]
---
> 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.
Three pillars describe the same tokens from three directions, and the split is
deliberate:
> **Foundations = what a token means. Handbook and Theming = how you change it.
> Reference = the generated list of every one.**
If you are reading to understand a decision, you are in the wrong pillar. This
one exists so that a question with a finite answer can be answered by looking
rather than by reading. *How many status levels are there, what does
`data-stale` mean, which variable controls the ladder's third rung* are
questions of exactly that kind.
## How this is generated [#how-this-is-generated]
Nothing on the eight pages below is typed by a person. Each is written by
`scripts/build-reference.mts` from a source that the application itself consumes,
so a row cannot describe a token the build does not ship. `pnpm run check` runs
`pnpm run generate` and then diffs the working tree; a page that has drifted from
its source fails CI rather than quietly lying.
### What is generated, and from what [#what-is-generated-and-from-what]
| Page | Source of truth | Produced by | Refreshed |
| --------------- | -------------------------------------------------- | ----------------------------------------------------- | ----------------------------- |
| Tokens | `tokens/*.json` | `build-tokens.mts` → `lib/generated/tokens.ts` | every build |
| Data attributes | component sources and their registry items | `build-registry.mts` | every build |
| CSS variables | `tokens/*.json` → `app/tokens.generated.css` | `build-tokens.mts` | every build |
| Keyboard | the `` block on each component page | `build-reference.mts` | every build |
| Types | the published `.d.ts` of the `@opsinjs` packages | `build-reference.mts` (fumadocs-typescript) | every build |
| Contrast | `tokens/color.json`, `tokens/material.json` | `check-contrast.mts` → `lib/generated/contrast.json` | nightly, and before a release |
| Glossary | `tokens/glossary.json` | `build-reference.mts` | every build |
| Catalogue | `registry/catalogue.ts` | `build-registry.mts` → `lib/generated/catalogue.json` | every build |
| API, per symbol | the published `.d.ts` of the `@opsinjs` packages | `build-reference.mts` | every build |
### The page contract [#the-page-contract]
Every generated page has the same shape. Above the marker comment
`opsinjs:generated:begin` sits a short hand-written block that names the source
and the script. You are reading it now. Everything below it is replaced
wholesale. Editing below the marker is not a mistake the tooling tolerates: the
next `pnpm run generate` erases it, and `check:generated` fails the pull request
that contained it.
To change a row, change the source. There is no exception to this, and the
absence of an exception is the point: a table that can be hand-edited is a table
you cannot trust when it matters.
### Two pages here are hand-written, on purpose [#two-pages-here-are-hand-written-on-purpose]
[System glossary](./system-glossary.mdx) defines the words this project uses about
itself: rung, axis, role, base, style, preset. There is no machine-readable
source for a project's own vocabulary, and inventing one to satisfy a rule would
be worse than writing twenty definitions carefully. [The API index](./api/index.mdx)
is likewise hand-written; only the per-symbol pages beneath it are generated.
### Empty tables are honest, not broken [#empty-tables-are-honest-not-broken]
Two of the eight lists are empty: [Data attributes](./generated/data-attributes.mdx)
and [Keyboard](./generated/keyboard.mdx). They say so with a ``
block naming the script that will fill them. The reason is a gap in the
aggregator rather than an empty system: the implemented components do emit data
attributes and every component page carries its own ``, but
`build-reference.mts` does not yet read the component sources for the first or
parse those blocks for the second. Each page states that on itself, because
"empty because nothing exists" and "empty because nobody wrote the extractor" are
different problems and only one of them gets fixed by somebody reading this. What
an empty table never means is that the page failed to load, and it is never
padded with a plausible example row. A fake row in a reference table is
indistinguishable from a real one, which is the exact failure this pillar exists
to prevent.
### Where these lists also appear [#where-these-lists-also-appear]
Everything here is duplicated into machine surfaces on purpose: `/llms.txt` and
its shards, the `.md` twin of every page, and `/r/index.json`. Prefer those if
you are a program. If you are a person and the list is long, the search box
(Ctrl K) indexes generated pages exactly like written ones.
That is the whole reason these are committed MDX rather than a runtime API.