A catalogue of UX specs — reusable, technology-agnostic definitions of UI patterns, written to be a shared source of truth for humans and AI agents. They span the full experience: from the smallest interface element up to complete pages and flows.
A spec describes what a pattern is, when to use it, how it is composed, how it behaves, and how it stays accessible — without prescribing a framework, styling approach, or a single visual design.
That makes each spec portable across projects, contexts, and tech stacks while keeping the meaning of the pattern consistent everywhere. A spec is a specification of intent and structure, not an implementation — each project maps specs onto its own tokens, framework, and visual language.
Design systems and component libraries get re-invented on every project and every stack. The visual skin and the framework change, but the underlying pattern — what a Button is, what a Navbar must do, what a Dashboard is for — does not. Prescriptive captures those stable patterns once, so they can be:
- Reused across projects and stacks (React, Vue, SwiftUI, design tools, …).
- Referenced by AI agents as a source of truth when generating UI.
- Composed from small units into components and full pages.
- Enforced — the specs carry machine-readable contracts that tooling checks.
- Versioned so changes are explicit and traceable.
Specs are organized into five layers, from the smallest unit to the complete experience — one directory per layer, one Markdown file per spec.
| Layer | Directory | What it is | Examples |
|---|---|---|---|
| Element | specs/elements/ |
An indivisible UI unit with a single responsibility. | button, input, badge, avatar, checkbox, spinner |
| Component | specs/components/ |
A self-contained pattern composed of elements. | navbar, card, form, dialog, data-table, tabs |
| Block | specs/blocks/ |
A page-level section composed toward one purpose. | hero, feature-grid, pricing-table, faq, cta-section |
| Page | specs/pages/ |
A full-screen spec composing components and blocks toward one goal. | landing-page, dashboard, sign-in, pricing, settings |
| Flow | specs/flows/ |
A multi-step journey across pages toward an outcome. | authentication, onboarding, checkout |
The layer of a spec is declared in its metadata (layer:) and reflected by
the directory it lives in. Alongside the layers, two cross-cutting catalogues
capture shared concerns once:
traits/— reusable interaction contracts (dismissible,focus-trap,anchored,roving-focus,typeahead) that many specs reference instead of re-describing them.responsive/— the vocabulary of reflow patterns (stack,collapse-to-menu,to-sheet,reflow-to-cards, …) that specs bind to.
Every spec follows the same document pattern so it's predictable for readers
and machines. It has a YAML frontmatter block (schema:
schema/spec.schema.json) and a fixed set of body
sections (template: templates/SPEC_TEMPLATE.md).
Beyond the human prose, an implementable spec carries machine-readable contracts that the build validates:
## API— a JSON contract naming theprops(with types, enum values, defaults),slots,events,a11y(role, keyboard, announcements),states, the design-tokentokensit consumes, and aresponsiveblock (container,minTarget, and areflowlist bound to breakpoints).## Composition— a JSON block wiring each part to aslotwith thepropspassed, so the composition graph is explicit.traits:frontmatter — the shared behaviors the spec exhibits.
These are what let an agent (or a component library) implement a spec to a contract rather than improvising prop names, states, and accessibility.
The repository is an npm-workspaces monorepo. The framework itself (the specs,
tokens, traits, responsive vocabulary, schema, templates) is the root package;
derived, consumable artifacts live under packages/:
| Package | What it is |
|---|---|
prescriptive (root) |
The spec catalogue + design tokens — the source of truth every package below is generated from. |
@prescriptive/tokens |
The design tokens as ready-to-use artifacts: CSS custom properties, a Tailwind v4 preset, [data-theme]/[data-mode] overlays, and a typed JS export. |
@prescriptive/xote |
Accessible Xote/ReScript components implementing the specs. Their prop types are generated from each spec's ## API, so the compiler enforces they can't drift. Styled via @prescriptive/tokens. |
skill/ |
An Agent Skill — the specs, traits, tokens, and responsive vocabulary compiled into a reference an AI coding agent loads to implement UI to the contracts. |
Each package is generated from the framework source, so nothing downstream can drift from the specs. See each package's README for usage.
The framework uses Semantic Versioning at two levels,
tracked in package.json and CHANGELOG.md.
- Collection version — MAJOR for a breaking change to the document pattern or schema (or removing a spec); MINOR for a new spec or compatible schema/template addition; PATCH for clarifications and fixes.
- Per-spec version — each spec carries its own
versionunder the same rules, scoped to that one document. Thestatusfield tracks lifecycle:draft,stable,deprecated.
Because the specs are structured, the build checks them (npm run checks in
website/, run in CI). Drift fails the build:
- conformance — every mapped component implements its contract's props/enums.
- conformance:traits — every trait claim is backed by the required keys.
- conformance:composition — every composition
refresolves and everyslotis declared. - conformance:tokens — every token role a contract references exists.
- conformance:responsive — every spec declares
responsive, with a known pattern and a real breakpoint.
prescriptive/ # root workspace = the `prescriptive` spec + tokens source
├── specs/ # the catalogue, one file per spec
│ ├── elements/ components/ blocks/ pages/ flows/
├── traits/ # shared interaction contracts
├── responsive/ # reflow-pattern vocabulary (patterns.json)
├── tokens/ # design tokens (W3C DTCG) + themes.json
├── schema/ # JSON Schemas (spec, api, trait)
├── templates/ # SPEC_TEMPLATE.md — the document pattern to copy
├── skill/ # the distributable Agent Skill
├── packages/
│ ├── tokens/ # @prescriptive/tokens (CSS vars, Tailwind preset, JS)
│ └── xote/ # @prescriptive/xote (Xote/ReScript components)
├── website/ # interactive catalogue (Vite + ReScript + Xote)
├── INDEX.md # generated registry of every spec
└── CHANGELOG.md
See INDEX.md for the full, current list of specs.
Specs describe structure and behavior and avoid pixels and hues on purpose.
The concrete values — color, type, spacing, radius, elevation, motion,
breakpoints — live in tokens/ in the standard
W3C Design Tokens (DTCG) format,
with ready-made themes in themes.json. Consume them as
CSS variables, a Tailwind preset, or a JS object via
@prescriptive/tokens. See tokens/README.md.
An interactive catalogue lives in website/: it lists every spec,
renders a live example of each (composed from @prescriptive/xote), shows the API
contract and responsive behavior, and lets you retheme the whole site live from
the design tokens. Built with Vite, ReScript, Xote, and
Tailwind CSS. See website/README.md to run it.
See CONTRIBUTING.md. In short: copy the template, fill in
the metadata and every section (including the ## API contract for
implementable specs), keep the id/filename/layer in sync, and bump the
versions and changelog.
MIT.