UI Pattern Decisions

Intent#

Every recurring interface question is decided once and recorded in one catalog. Each entry holds the options considered, the option chosen, the compact-screen behavior, and the implementation per platform. Implementers build from the chosen option and extend the catalog rather than redrawing the pattern.

Concepts#

Pattern kinds#

A pattern answers one recurring question. Its kind states what the question is about.

The catalog entry#

The catalog is one file valid against schemas/ui-pattern-catalog.schema.json. Each pattern entry carries these fields.

The breakpoints map names viewport widths, and groups collect related patterns. The optional registry field names the command or path rendering every product-added option for review.

Pattern pages#

A pattern page holds one group of patterns, such as docs/frontend/patterns/record-detail.md. The folder holds no stack, so its pages apply wherever docs/frontend/ applies. Each ### heading under ## Patterns names one pattern, and its ID is litespec/frontend/patterns/<group>#<pattern-slug>. The heading is a name rather than an action, so the ID survives a change of default.

A pattern carries four labeled fields, then its options.

Each option is a #### heading of the form #### `option-id`: Option name. It carries one wireframe block, an optional wireframe compact block for a different phone layout, then **Rationale:**, **Cost:** and an optional **Reference:**. An option ID is stable once published. The page's Standards hold the rules every option keeps.

The wireframe language#

A wireframe states the structure of one option: which parts sit where, in what order, which action is primary, and the copy they show. It states no color, font, spacing, or component library. An agent builds the option from the text in its own stack and design system. litespec patterns preview draws the text for a person to choose from.

page
  breadcrumb "Orders" "SO-1042"
  header
    heading "SO-1042"
    status "Paid" positive
    action primary "Mark as shipped"
    menu "More"
      action "Duplicate"
      action destructive "Cancel order"
  split 2:1
    region "Items"
      table 3 "Item" "Qty" "Total"
        item: text "Oak desk lamp" · text "2" · text "EUR 90.00"
    aside
      card "Customer"
        fact "Name" "Maria Garcia"

Each line is one part: its name, its modifiers as bare words, its copy in double quotes, then a count or a ratio. Children are indented by two spaces. A line ending in : takes inline children, which sit side by side. A middle dot, U+00B7, with a space on each side separates them. A line starting with # is a comment. Copy is the real text the product would show, drawn from the Acme Supply cast.

The parts form a closed set.

The modifiers belong to their parts.

The validator holds each block to these rules.

On a phone the drawing reflows unless a wireframe compact block says otherwise. A row or split stacks, an aside follows the main content, a table keeps its first two columns, and a drawer rises from the bottom.

Starting a catalog entry from a LiteSpec pattern#

A catalog entry may set library to one pattern ID, such as litespec/frontend/patterns/record-detail#record-header, to start from that pattern. The entry keeps the pattern's option IDs and names, so a choice stays comparable across products, and it may add options of its own.

The owner chooses among the combined options with the drawings from litespec patterns preview, and records the source. The entry states the compact behavior and the implementation status per platform, and the platform team implements the chosen option in its own components. A choice that differs from the pattern's default records its reason in the entry.

The diagram shows the flow from a LiteSpec pattern through the catalog entry that cites it to the built screen.

The decision lifecycle#

A choice starts as a recommendation and settles when an owner chooses. A later change names the record that made it.

The compact variant#

Each pattern states what happens below one named breakpoint. The chosen option reflows, or a named option replaces it.

The breakpoint names one key of the catalog breakpoints map.

Implementation status#

Each platform entry states how far the chosen option is built there.

A partial or pending entry states its gap in gap.

Patterns and floorplans#

A floorplan implements the chosen option of one page-frame pattern. The pattern decides the behavior, and the floorplan is the shared component carrying it.

Every page-frame pattern therefore resolves to one floorplan, and every floorplan traces to the pattern entry that chooses it.

Standards#

{ "paths": { "uiPatterns": "docs/ui/patterns.json" } }

{
  "id": "loan-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" } }
}

Conventions#

Verification#