Frontend Components

Requirement A workspace MUST hold its shared primitives and its composites in one shared UI package, with no copy in an application.

Rationale A primitive copied into two applications diverges on the first upstream update, and the divergence is invisible because both copies compile.

Example The primitives sit in one folder beside the composites, and the composites import them.

Requirement A component under a route or module folder MUST import only the shared package's documented entry points.

Rationale A composite with a closed property set draws one layout for every caller. A page cannot change spacing for itself and produce the second spacing the next page copies.

Example For example, a loan section in the catalog app draws its facts, its state, and its commands through shared composites, and declares no element, class, or style binding.

<script>
  import { EntitySection, StatusBadge, DetailActions } from '@fixture/ui/floorplans';

  export let loan;
</script>

<EntitySection title={loan.title}>
  <StatusBadge code={loan.state} />
  <DetailActions actions={loan.commands} />
</EntitySection>

The section imports only the shared package entry point, so the layout it draws is the one the shared package owns for every other entity page.

Requirement A component under a route or module folder MUST NOT declare a class or style binding.

Rationale Layout belongs to the floorplan and to the display composites. A class in route code is a second layout beside the floorplan, and the next route copies it.

Each stack realization names the binding for its stack.

Requirement A component under a route or module folder MUST NOT declare a layout or interactive element, and each refusal names the composite to use.

Rationale A raw element carries no focus management, no state, and no accessibility wiring. The reader of the lint message chooses between two answers, so the message gives one.

Requirement Page code MUST import a composite wherever the shared package provides one, and the lint refuses the primitive that composite replaces.

Rationale The composite is where the decision is made once. The primitive is where it has to be made again, per page.

Example Card is Section, Table is DataTable, Badge is StatusBadge, and Input and Field are the form fields.

Requirement An exception file MAY declare custom styling, and uses semantic theme tokens only.

Rationale A stock-location map, a packing-slip preview, and a public frame have no composite. Refusing them pushes the drawing into an arbitrary value that no token governs. The file name is the declaration that this is the exception. Each stack realization names the file pattern.

Requirement A layout, a control, or a surface a second page needs MUST be added to the shared UI package, not written inside an application.

Rationale A component written inside one page cannot be reviewed against its use elsewhere, and it is invisible to the floorplans that depend on it.

Requirement Interactive UI MUST support keyboard operation, visible focus, semantic elements, programmatic labels, and asynchronous status announcements.

Rationale A custom control loses them all at once, so a platform control is the starting point.

These are the properties a component gets wrong on its own. WCAG 2.2 adds criteria that a component cannot satisfy by itself, because each one is a property of a flow or a page:

The AA criteria bind every project. The AAA rows bind only a project that targets AAA.

Requirement A data component MUST render loading, empty, error, forbidden, and ready; a control renders disabled and pending, prevents duplicate submission, and keeps recovery usable.

Rationale Data states describe what arrives; control states describe what the reader may do.

A route adds not-found under litespec/frontend/rendering#represent-route-states, because a missing target resolves at the route rather than inside a component. Each state name is a term in the project's language record.

Requirement A composite MUST receive the values and callbacks it needs, not a client, a store, or a business record.

Rationale The shared package serves applications it does not know, so an input carrying one application's data model couples the two.

Requirement A repeated component variant MUST use theme tokens through the shared package's variant helper rather than repeated literal values.

Rationale Repeated pixel values, colors, or long conditional branches drift apart once more than one composite edits them.

Requirement A component MUST NOT render untrusted rich content without its recorded sanitization decision.

Rationale Stored rich content requires a decision record naming the sanitizer, the allowed elements and attributes, the link policy, and the test cases.

Requirement An informative or decorative image MUST render through the shared image component, which owns its shape, its sizing, and its fallback.

Rationale An informative image carries meaningful alternative text, and a decorative image carries empty alternative text. A source and label written in a page bypass both. The raw-element rule refuses unwrapped images in page code under litespec/frontend/components#use-composites-for-layout-and-interaction-in-page-code.