Controlled UI Governance

Requirement A workspace MUST record one shared UI package in litespec.project.json, and each controlled frontend names its density profile against it.

Rationale A second general-purpose visual system in one workspace makes every component choice ambiguous. A frontend outside the contract declares another platform and says what replaces the contract.

A project chooses the density per frontend rather than per workspace, because density is a property of the audience. public-light suits a surface a visitor meets once. application-balanced suits a surface a signed-in user works in. admin-dense suits a surface an operator reads all day.

Requirement A workspace MUST install the pinned baseline from litespec.manifest.json once, into its shared UI package.

Rationale Installing per application makes a fourth copy, where a fourth drift is invisible. An additional baseline source is permitted under an exception recorded against this provision.

Requirement A workspace MUST publish one design contract with its shared UI package, carrying the required sections: Brand, Tokens, Vocabulary, Patterns, Do, Do not, Motion, Voice.

Rationale An author that has read no contract picks its own tokens, its own motion, and its own voice. The picks differ on the next page, and the difference is what a reader sees as clutter. One contract keeps the answers in one file.

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

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

Requirement The Patterns section of the design contract MUST list every floorplan the package provides, each with a when-to-use rule.

Rationale A floorplan with no rule for choosing it leaves the choice to resemblance, and two authors then pick different floorplans for one kind of page. A floorplan outside the list is a design decision rather than a route-level choice.

Example 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. |

Requirement A route MUST render exactly one floorplan from the declared set, unless it is a recorded freestyle route.

Rationale The floorplan fixes the layout, the heading position, and the slots, so a reviewer reads which floorplan a route composes. The slots take domain values: the business record state, the use cases that state permits, and the refusal results of the called use case.

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

Requirement Route code MUST NOT declare layout outside its floorplan and display composites.

Rationale A layout declaration in a route file is a second layout beside the floorplan, and the next route copies it. Floorplan and display composites own layout, so one change reaches every route composing them.

Requirement A route that composes no declared floorplan MUST name the decision record that justifies its layout.

Rationale A freestyle route is the first consumer of a new floorplan or a genuine one-off. A named decision makes either case reviewable, and it keeps the declared set closed. A second route of the same shape is the signal to add a floorplan.

Requirement Every route MUST name its page type's reference, with a freestyle route naming its decision record instead.

Rationale An author with no named reference invents a page from primitives, and the next author invents another. A reference that resolves keeps every page of one type on one reference.

Requirement A state indicator MUST take one tone from the closed set, each application declaring its state-to-tone mapping once as an exhaustive table of language terms.

Rationale A page that picks a color picks a meaning nobody agreed to. One mapping means the same state reads the same way on every screen. A new state then fails to compile until its tone and its word exist.

Requirement An application MUST use the shared token definition and declare no value, with no literal color in any shipped definition.

Rationale One token definition is what makes two applications look like one product. An application uses it and declares no value, so a second definition never introduces a value the first has no opinion about. A definition the shared package ships declares no literal color.

Requirement A token definition MUST carry only the values the declared baseline publishes, except under a recorded exception.

Rationale A token value outside the published ramp is a second palette beside the declared one, and the next author copies it. A recorded exception keeps the deliberate departure visible in the design contract.

Requirement A structural separator or input border MUST NOT be darker than the border step the declared base color publishes.

Rationale A heavier rule beside a lighter one reads as emphasis, so authors stop trusting the token. The border step keeps every separator at one weight.

Requirement A command MUST use the surface the Concepts table assigns to its input.

Rationale A form dialog with more inputs than the table allows scrolls, loses its title, and hides the refusal beside the field that caused it. A confirmation dialog for an action taking nothing reads as a warning rather than as a question.

Requirement Every error the user sees MUST show its trace identifier in copyable form in the error detail, from the problem body or the X-Trace-Id header.

Rationale Support reads the identifier to find the failure, and the reader copies it without retyping. A headline carries what happened; the identifier belongs in the detail.

Requirement Every route MUST pass each route suite check.

Rationale The Concepts section names the checks. They cover the floorplan, the reference, accessibility, the heading, the landmark, reflow, keyboard use, and status announcements. One suite visits every route, so a new route is checked without a specification written for it.

Requirement Every result a called use case returns MUST be proved by a passing test or a known-gap record with owner and end date.

Rationale A refusal a reader can reach and no test provokes is a refusal nobody sees render. The calls come from the route code, so the obligation follows the code rather than a declaration.

Example A test calls the use case and asserts one refusal result.

Requirement A style MUST use a semantic token rather than a raw value.

Rationale The approved style surface is the shared package definition, holding the tokens, the fonts, and the documented resets.

Requirement A behavior package MUST name the decision record approving it for the capability it supplies, and render through baseline components and tokens.

Rationale Approval follows the capability rather than the visual catalog, so a package is not adopted for components the baseline already provides.

Requirement A primitive, composite, token, source, floorplan, or route change MUST name the evidence in the matrix in this section.

Rationale The matrix maps each change class to the narrowest evidence that represents its risk.

Requirement A frontend outside the controlled platforms MUST declare an entry point record naming that platform and the boundaries replacing this contract.

Rationale A device client with no shared component and no router sits outside the floorplan set and the component rules. Declaring the platform keeps the decision visible instead of reporting as a frontend with nothing to check.