UI Patterns

An interface decision kept in one catalog is found before it is remade: the next author reads the entry and builds the chosen option. A decision kept in chat, in a review thread, or in one author's memory is decided again on the next page, and the two answers differ. One catalog at the configured path, valid against the schema, keeps every decision searchable and every choice comparable.

The project file points at the catalog.

{ "paths": { "uiPatterns": ".litespec/implementation/patterns/catalog.json" } }

Checked bylitespec model check reports [litespec/frontend/patterns#keep-one-pattern-catalog] for a missing catalog, a duplicate id, an unknown group, an unknown library pattern, or a renamed option. Run it at the consumer root.

Marked checkable: the tool named here checks it.

Recording at least two options with their rationale and cost turns a preference into a decision the next team can revisit. When the chosen option stops fitting, the team reads the recorded cost of the alternative instead of repeating the research from nothing. An option recorded without its cost gives them no basis to compare.

An expense list considers two sort options: clickable headers and a menu listing sort fields. The entry records the rationale and cost of each, then names the chosen one.

Checked bylitespec model check reports [litespec/frontend/patterns#record-every-option-considered] for a choice or extension naming no recorded option, and the catalog schema requires at least two options with rationale and cost. Run it at the consumer root.

Marked checkable: the tool named here checks it.

The source tells the reader whether the choice is settled. A recommended choice stands until an owner confirms or changes it; an agent leaves its own choice marked as recommended, so no automated choice poses as a human decision. The catalog then shows at a glance which choices are settled and which still await review.

For example, the Claimwick catalog starts its expense header entry from litespec/frontend/patterns/record-detail#record-header, keeps the pattern option IDs, and records the owner choice.

{
  "id": "expense-header",
  "group": "record-detail",
  "library": "litespec/frontend/patterns/record-detail#record-header",
  "decision": { "option": "title-state-breadcrumb-one-primary-action", "source": "owner" },
  "compact": { "breakpoint": "compact", "behavior": "The header stacks under the title." },
  "implementations": { "svelte": { "status": "adopted" } }
}

The entry names the pattern's default option and records owner as the source, so the choice stands as settled and the platform team builds it in its own components.

Reviewed forWhich decisions lack owner or recommended, pose an agent proposal as an owner choice, or change the choice without naming their record? Look in the catalog decisions.

Marked guidance: a reviewer answers this question.

A pattern with no compact statement breaks on a narrow screen, or each route redraws it for the phone in its own way and the product ships as many compact layouts as routes. Naming one breakpoint and stating whether the chosen option reflows below it or a named option replaces it settles the phone layout once. The breakpoint is a key in the catalog's breakpoints map, so every pattern measures against one width scale.

The entry names breakpoint compact; below it expense rows render as cards.

Checked bylitespec model check reports [litespec/frontend/patterns#declare-the-compact-behavior] for a breakpoint outside the breakpoints map or a compact option naming no recorded option. Run it at the consumer root.

Marked checkable: the tool named here checks it.

The shared UI package implements each chosen pattern once, at the source paths the catalog names per platform, so every route composes the same behavior. A route that redraws the pattern instead makes a second decision the catalog does not track: it looks like the pattern, drifts from it, and no entry records the difference.

The catalog names one shared source path per platform, so every expense route composes its platform path.

Checked bylitespec model check reports [litespec/frontend/patterns#implement-a-chosen-pattern-once] for a named component path that does not exist or an adopted status with no components. Run it at the consumer root.

Marked checkable: the tool named here checks it.

When the catalog waits for a later change, the code ships, the follow-up slips, and the entry describes behavior no route renders. Updating the entry in the same change as its implementation keeps the two in agreement by construction. A deliberate departure in one route names a decision record instead, so the departure stays reviewable.

A route departing from the chosen option names decision.record, such as .litespec/intent/decisions/0014-expense-sort-menu.yaml.

Reviewed forWhich option switches, added options, or extensions land without their implementation, and which single-route departures name no decision record? Look in the change diffs and the catalog entries.

Marked guidance: a reviewer answers this question.

The status tells a reader what is built and what is missing on each platform, so a team adopting the catalog knows which options exist in code and which are still drawings. A partial or pending entry states its gap, so the missing work is named rather than discovered. The Concepts section defines the four values.

A pending entry for one platform states in gap what is missing there.

Checked bylitespec model check reports [litespec/frontend/patterns#state-the-implementation-status] for a partial or pending entry with no gap. Run it at the consumer root.

Marked checkable: the tool named here checks it.

A pattern names behavior and structure: which parts sit where, in what order, with which actions. Each platform then binds that behavior to its own components through implementations, so one catalog serves every selected stack. A component library named in the pattern itself would force a second catalog per platform, and the two would diverge.

An option describes a menu listing sort fields rather than naming the component rendering it.

Reviewed forWhich patterns name a component library outside their implementations? Look in the catalog entries outside implementations.

Marked guidance: a reviewer answers this question.