Frontend Components

When two applications each hold a copy of one primitive, the first upstream update changes one copy and misses the other. Both copies still compile, so nothing reports the split, and the two applications drift into two visual languages. One package gives every application the same component, so one update reaches every screen.

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

Reviewed forWhich shared primitives or composites live outside the shared package? Look in the workspace packages and the application sources.

Marked guidance: a reviewer answers this question.

A composite fixes its layout and exposes only the inputs its job needs, so every page that uses it draws the same shape. If page code could reach past the composite to the primitives, one page would tune spacing or order for itself, and the next page would copy that tuning instead of the composite. The product would then hold as many layouts as pages.

An expense section in the expenses app draws its facts, its state, and its commands through shared composites, and declares no element, class, or style binding.

EntitySection "title"
  StatusBadge "state"
  DetailActions "commands"

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.

Checked bylitespec model check reports [litespec/frontend/components#compose-composites-in-page-code] with the file and the refused import. Run it at the consumer root.

Marked checkable: the tool named here checks it.

The floorplan and the display composites own every spacing, size, and placement choice on a page. A class or style binding in route code is a second layout that answers to no composite, and the next route copies it because it looks like the local way to draw. Two sources of layout then disagree on the first redesign, so keeping classes out of page code leaves the floorplan as the one place a visual change lands.

Each stack page names the class and style bindings this rule covers for its stack.

Reviewed forWhich class or style bindings appear in route and module sources? Look in route and module sources; each stack page names the bindings its lint refuses.

Marked guidance: a reviewer answers this question.

A raw element is only markup: it carries no focus handling, no state behavior, and no accessibility wiring, so each page that declares one rebuilds behavior the composite already carries, usually worse. The lint refusal names the composite to use instead, so the author gets the replacement in the same message as the refusal and does not have to search the shared package.

Reviewed forWhich layout or interactive elements appear in route and module sources? Look in route and module sources; each stack page names the refused elements and the composite each refusal names.

Marked guidance: a reviewer answers this question.

The composite holds the product's decision for one job: which layout, which behavior, which tone. The bare primitive holds none of those, so a page that imports it makes each decision again for itself, and two pages answer the same question two ways. Refusing the replaced primitive in page code sends every page to the decision already made.

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

Reviewed forWhich page sources import a primitive where the shared package provides a composite? Look in route and module imports.

Marked guidance: a reviewer answers this question.

Some drawings have no composite: a budget treemap, a receipt-scan preview, or a public marketing frame. Refusing them entirely would push the drawing into arbitrary values that no token governs, which is harder to find and restyle than a declared exception. The exception file keeps the drawing visible: its name says this page draws outside the composites, and semantic tokens keep it inside the product palette. Each stack page names the file pattern that marks an exception for its stack.

Reviewed forWhich custom styling sits outside the files whose names mark drawings outside the composites, or uses values other than semantic theme tokens? Look in the exception files each stack page names.

Marked guidance: a reviewer answers this question.

The second page that needs a layout, control, or surface proves the piece is shared, not page-specific. Written inside one application, it is reviewed against one use, styled for one context, and invisible to the floorplans that would carry it, so the third page writes it a third time or copies the first copy. Adding it to the shared package puts it where every page finds it and where its design is judged against every use.

Reviewed forWhich layout, control, or surface drawn by two pages is missing from the shared package exports? Look in the shared package exports and the drawing pages.

Marked guidance: a reviewer answers this question.

Keyboard operation, visible focus, semantic elements, programmatic labels, and status announcements come free with platform controls and all break at once in a custom control. A mouse-only control locks out keyboard readers, a missing label leaves screen-reader users guessing, and a silent update leaves anyone who does not see the screen change unaware of it. Starting from a platform control keeps all five properties, and the composite keeps them for every page that uses it.

The five properties above are the ones a component can satisfy on its own. WCAG 2.2 adds criteria that only a flow or a page can satisfy, so each route answers them where the criterion applies:

The level column marks which target each criterion belongs to: AA for every project, AAA for a project that targets AAA.

Reviewed forWhich interactive UI lacks keyboard operation, visible focus, semantic elements, programmatic labels, or status announcements? Look in the route suite output.

Marked guidance: a reviewer answers this question.

A component that renders only its ready state leaves the reader with a blank region while data loads, after it fails, or when there is nothing to show. Each missing state is a screen with no design and no test visiting it. Naming every arrival state up front gives each one a designed drawing.

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

Reviewed forWhich data components miss a loading, empty, error, forbidden, or ready state, or name a state outside the glossary? Look in the shared package components and the glossary.

Marked guidance: a reviewer answers this question.

A control with no disabled state invites a second submission while the first is still in flight, and a control with no pending state shows no sign that anything is happening. Blocking the duplicate submission and keeping recovery usable give the reader one safe path: wait, or recover. State names are glossary terms, as under litespec/frontend/components#render-data-states.

Reviewed forWhich controls miss a disabled or pending state, allow a second submission while one is in flight, or leave recovery unusable? Look in the shared package components.

Marked guidance: a reviewer answers this question.

The shared package serves applications it was not written against. A composite that takes a client, a store, or an aggregate takes one application's data model as its input, so it fits no application with a different model, and a change to that model breaks the shared package. Values and callbacks keep the composite free of any application's shape: the page translates its model into plain inputs, and the composite renders what it is given.

Reviewed forWhich composite inputs name a client, a store, or an aggregate instead of values and callbacks? Look in the shared package component signatures.

Marked guidance: a reviewer answers this question.

When each composite writes its own pixel values, colors, or conditional branches for one variant, the copies start equal and drift with every later edit, because nothing points the author at the other copies. The variant helper holds each variant once, in theme tokens, so a change to the variant reaches every composite that uses it and every value stays inside the theme.

Reviewed forWhich repeated variants bypass the shared variant helper or carry literal values in composites? Look in the shared package components.

Marked guidance: a reviewer answers this question.

Rich content written by one user renders in another user's browser, so unsanitized markup is a script injection path: whoever writes the content runs code as every reader. The recorded decision names the sanitizer, the allowed elements and attributes, the link policy, and the test cases, so the boundary is explicit and reviewable instead of a different ad-hoc escape on every page.

Reviewed forWhich untrusted rich content renders without a recorded decision naming the sanitizer, the allowed elements and attributes, the link policy, and the test cases? Look in the decision records and the rendering components.

Marked guidance: a reviewer answers this question.

An informative image needs meaningful alternative text, and a decorative image needs empty alternative text so assistive tools skip it. A source and label written directly in a page bypass both rules: the author tracks which kind each image is and writes the matching text, on every page. The shared image component owns the shape, the sizing, the fallback, and the text policy, so each image gets the handling its kind needs. The raw-element rule refuses unwrapped images in page code under litespec/frontend/components#use-composites-for-layout-and-interaction-in-page-code.

Reviewed forWhich content images render outside the shared image component or against the text policy for their kind? Look in page sources for unwrapped images.

Marked guidance: a reviewer answers this question.