blueprints/CONTEXT.md

Context — ubiquitous language

The shared vocabulary for blueprints. These terms should appear verbatim in conversation, code, file names, and commits. This file is a glossary only — no implementation details (those live in DESIGN.md).

Blueprint

A named contract for a recurring UI pattern, taken from the blueprint-ontology repo — declarative, categorical, abstract (a concept in Jackson's sense). It defines what must be true of the pattern: its signature, state machine, behaviors, invariants, functions, critical-performance thresholds, and failure modes. Examples: List, Grid, Table, Async.

Blueprints come in two roles (from the ontology):

• Feature — a standalone pattern a user interacts with (List, Grid, Form).
• Capability — a composable blueprint that adds state/behavior onto a host feature (Async, Paginated, Selectable).

Illustration

This app's rendered, interactive presentation of a single blueprint. blueprints is a gallery of illustrations. "Illustration" is the noun for the whole per-blueprint screen; do not use "demo" (implies a live working widget — these are static) or "page" (routing concept, not domain).

Viewer

The one reusable component that renders any blueprint's illustration. It draws the generic parts from a blueprint's typed data and slots in that blueprint's bespoke Specimen. Every illustration is the Viewer applied to one blueprint.

Specimen

The interactive-looking but static visual mock of the blueprint's actual UI — the left pane of the Viewer. Bespoke per blueprint (a Grid specimen looks nothing like a List's). Selecting a Function highlights the region of the specimen that function owns. Not "mockup", not "demo".

Readout

The right pane of the Viewer: the blueprint's formal contract for the selected Function — source capability, responsibility, state touched, behaviors (pre → effect), invariants, failure modes, critical-performance thresholds.

Companion

A supporting schematic shown below the Viewer's two panes. Two kinds exist so far: the composition map (how a feature extends/composes with capabilities) and the state machine (the blueprint's lifecycle). A blueprint may have neither, one, or both.

Function

One row of a blueprint's "Functional analysis" — a named responsibility of the pattern (e.g. List's Display, Scroll, Load). Functions are the unit the Viewer lets you explore, tab by tab. Distinct from Behavior (a concrete state transition like loadMore()); behaviors are the mechanics underneath a function.

Gallery

The app's index (landing screen): every blueprint in the ontology, each as a card linking to its illustration — including blueprints not yet illustrated, shown as planned.