Controlled UI Governance

Two general-purpose visual systems in one workspace make every component choice ambiguous: each screen picks its source, and the product ships two looks. Recording one shared UI package in .litespec/project.json settles the source for every controlled frontend. A frontend outside the contract declares another platform and says what replaces the contract.

Checked bylitespec model check reports controlled frontends with no paths.uiPackage in .litespec/project.json, and [litespec/frontend/ui#select-one-visual-authority] for a second general-purpose visual dependency. Run it at the consumer root.

Marked checkable: the tool named here checks it.

The design baseline installed once in the shared UI package gives every application the same primitives at the same pinned version. Installing per application makes a copy per application, and each copy drifts on its own update schedule with nothing reporting the split. An additional design-baseline source is permitted only under an exception recorded against this provision.

Reviewed forWhich pinned manifest baselines install outside the shared UI package, or install more than once? Look in the shared package manifest and lock, and the application manifests.

Marked guidance: a reviewer answers this question.

An author that has read no contract picks their own tokens, motion, and voice for each page. The picks differ on the next page, and the reader sees the difference as clutter: same product, different looks. One design contract published with the shared UI package keeps every answer in one file, with the required sections Brand, Tokens, Vocabulary, Patterns, Do, Do not, Motion, Voice.

The metadata block names the package and the floorplans it provides.

{
  "kind": "design-contract",
  "schemaVersion": 1,
  "package": "@claimwick/ui",
  "profile": "application-balanced",
  "shell": "app-shell",
  "patterns": ["work-page", "list-page", "entity-page"]
}

Checked bylitespec model check reports [litespec/frontend/ui#publish-a-design-contract] for a missing contract, a missing metadata block, a package mismatch, or a missing required section. Run it at the consumer root.

Marked checkable: the tool named here checks it.

A floorplan with no when-to-use rule leaves the choice to resemblance: two authors pick different floorplans for one kind of page, and the kind ships in two layouts. Listing every floorplan with its rule in the design contract's Patterns section makes the choice mechanical. A floorplan outside the list is a design decision for the package, not a route-level choice.

The section states each floorplan and the question that selects it.

## Patterns

| Floorplan | Component | Use it when the reader |
|:---|:---|:---|
| `list-page` | `ListPage` | Finds one record among many. The page shows the result count. |
| `entity-page` | `EntityPage` | Acts on one record: its facts, its state, and the actions that state permits. |
| `form-page` | `FormPage` | Supplies the input of one command, with one primary action. |

Reviewed forWhich floorplans miss the design contract Patterns section or their when-to-use rule? Look in the design contract.

Marked guidance: a reviewer answers this question.

The floorplan fixes the layout, the heading position, and the slots, so a reviewer reads which floorplan a route composes and knows what the page looks like before opening it. The slots take domain values only: the aggregate state, the use cases that state permits, and the refusal results of the called use case. Exactly one floorplan per route keeps each page to one known shape, unless it is a recorded freestyle route.

An expense route composes the entity floorplan and fills each slot from the expense.

Reviewed forWhich routes render zero or several floorplans without recording a freestyle decision? Look in the route sources and the suite output reading the floorplan name from each frame.

Marked guidance: a reviewer answers this question.

A layout declaration in a route file is a second layout beside the floorplan: the route draws its own spacing while claiming the floorplan's shape. The next route copies the declaration because it looks like the local way to draw, and the floorplan stops describing what routes render. Floorplan and display composites own layout, so one change there reaches every route composing them.

Reviewed forWhich route files declare layout outside floorplan and display composites? Look in the route sources.

Marked guidance: a reviewer answers this question.

A route that composes no declared floorplan is either the first consumer of a floorplan that does not exist yet or a genuine one-off. Naming the decision record that justifies its layout makes either case reviewable and keeps the declared set closed. A second route of the same shape is the signal to add the floorplan instead of recording another freestyle route.

Reviewed forWhich freestyle routes name no decision record justifying their layout? Look in the freestyle routes and the decision records.

Marked guidance: a reviewer answers this question.

An author with no named reference invents a page from primitives, and the next author invents another page for the same type. Naming the page type's reference keeps every page of one type on the one drawing it derives from, so the type stays one design. A freestyle route names its decision record instead, since it derives from no reference.

Reviewed forWhich routes name neither their page type reference nor, for a freestyle route, their decision record? Look in the route sources.

Marked guidance: a reviewer answers this question.

A page that picks its own color picks a meaning nobody agreed to: the same red celebrates on one screen and warns on another. One state-to-tone mapping per application, declared once as an exhaustive table of glossary terms, makes the same state read the same way on every screen. A new state fails to compile until its tone and its word exist, so no state ships uncolored or mislabeled.

Reviewed forWhich applications lack a state-to-tone mapping, or map a state outside the exhaustive table of glossary terms? Look in the application state mapping.

Marked guidance: a reviewer answers this question.

One token definition is what makes two applications look like one product. An application uses the shared definition and declares no value of its own, so no second definition introduces a value the first has no opinion about. A definition the shared package ships declares no literal color, so every value traces to the declared baseline.

Reviewed forWhich applications declare their own token value, and which shipped definitions carry a literal color? Look in the application and shared token definitions.

Marked guidance: a reviewer answers this question.

A token value outside the published ramp is a second palette beside the declared one, and the next author copies the value because it looks intentional. Carrying only the values the declared baseline publishes keeps the palette to what the design baseline designed. A recorded exception keeps a deliberate departure visible in the design contract instead of hidden in the tokens.

Reviewed forWhich token values sit outside the declared baseline without a recorded exception? Look in the token definitions and the exception records.

Marked guidance: a reviewer answers this question.

A separator darker than its neighbors reads as emphasis, so authors stop trusting the token and start picking weights by eye. The border step the declared base color publishes keeps every structural separator and input border at one weight, so weight carries no accidental meaning.

Reviewed forWhich structural separators or input borders run darker than the published border step? Look in the token definitions and the rendered separators.

Marked guidance: a reviewer answers this question.

The surface fits the input: a button for a reversible action, a confirmation dialog for an irreversible one, a form dialog for one to four inputs, and a form page beyond that. A form dialog with more inputs than the table allows scrolls, loses its title, and hides the refusal beside the field that caused it. An oversized surface for a small command costs the reader attention the command has no use for.

Reviewed forWhich commands use a surface other than the one the Concepts table assigns to their input? Look in the command surfaces.

Marked guidance: a reviewer answers this question.

Support reads the trace identifier to find the failed request, and the reader copies it from the detail without retyping. Shown in copyable form from the problem body or the X-Trace-Id header, it connects the reader's report to the server's logs. The headline carries what happened in words; the identifier belongs in the detail.

Reviewed forWhich visible errors hide the trace identifier from copyable detail? Look in the error surfaces.

Marked guidance: a reviewer answers this question.

The route suite visits every route and asserts each check the Concepts section names: the floorplan, the reference, accessibility, the heading, the landmark, reflow, text spacing, keyboard use, and status announcements. The suite discovers its routes from the application route definition, so a new route is checked with no new specification. Every route passing every check keeps each address inside the contract by default.

Reviewed forWhich discovered routes fail a route suite check? Look in the suite output and the CI job logs.

Marked guidance: a reviewer answers this question.

That Behavior provision is the one result obligation for a screen: a sentence in the frontend's refusal dictionary or a browser test asserting the code, checked by refusal-sentence-missing. Stating it again for routes would give one obligation two scopes and two verifications. The screen's computed calls, not a route's declared calls, name the refusals in scope, and success results stay proved through their scenarios.

The expense form's screen reaches spending.receipt-missing through its computed calls, and that refusal has a sentence in the Claimwick web dictionary.

Checked bylitespec model check reports refusal-sentence-missing (level A) for a refusal reachable through a screen's computed calls with neither a dictionary sentence nor a browser test asserting its code.

Marked checkable: the tool named here checks it.

A raw value in a style answers to no token: the theme leaves it unchanged through every restyle, and the next author copies the value instead of the token. The shared package definition is the authoritative style surface, holding the tokens, the fonts, and the documented resets. A style built from semantic tokens stays inside the product's visual language by construction.

Reviewed forWhich styles use raw values instead of semantic tokens? Look in the stylesheets and the shared package definition.

Marked guidance: a reviewer answers this question.

A behavior package adds a capability the design baseline lacks, such as a chart or a rich editor, and naming the decision record that justifies it for that capability keeps the decision tied to the need. The decision follows the capability rather than the visual catalog, so no package duplicates a component the design baseline already provides. Rendering through baseline components and tokens keeps the new capability inside the product's look.

Reviewed forWhich behavior packages name no decision record justifying them, or render outside baseline components and tokens? Look in the package declarations and the decision records.

Marked guidance: a reviewer answers this question.

Each change class carries different risk: a token change reaches every route in every profile, while a primitive change reaches one component. The matrix maps each class to the narrowest evidence that represents its risk, so a change runs the evidence its reach requires and no more.

Reviewed forWhich changes name no evidence the matrix assigns to their class? Look in the change descriptions and the named evidence.

Marked guidance: a reviewer answers this question.

A device client with no shared component and no router sits outside the floorplan set and the component rules: the contract's checks do not apply to it. Declaring an entry point record that names its platform and the boundaries replacing this contract keeps the decision visible, instead of letting the frontend report as one with nothing to check.

Reviewed forWhich frontends outside the controlled platforms declare no entry point record naming their platform and replacement boundaries? Look in the entry point records.

Marked guidance: a reviewer answers this question.