03804b10dc
Refactor the List-specific screen into a data-driven, reusable viewer: - generic Blueprint type + shared LoadState machine + registry - vue-router: / (gallery) and /b/:slug (illustration) - BlueprintViewer renders any blueprint; specimens stay bespoke - add Grid blueprint (6 functions incl. Position) + GridSpecimen
66 lines
2.7 KiB
Markdown
66 lines
2.7 KiB
Markdown
# 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**.
|