The component library

A component belongs in the engine when it is a distinct kind of content that more than one site will have. It belongs in a site when it exists to render that site's subject matter.

Three questions settle almost every case:

1. Is it a different kind of content, or the same content shown differently? A grid of links and a list of properties are different content. That grid in two columns and the same grid in three is one component with a field. A catalogue that models presentation as content ends up with fifteen near-identical blocks nobody can choose between.
2. Would a second site have one? A logo strip saying who a product works with is general. A departure board mockup is not.
3. Does it describe the subject, or the page? A transit stack diagram describes transit. A screenshot figure describes any page that has a picture.

The same rule already governs site.css, and it holds for the same reason: a component appearing on a second site belongs in the shared layer.

Eighteen components ship today. Each has a schema carrying its fields, its limits, the accessibility rules attached to it, and a when_not line distinguishing it from its nearest neighbour. docs/components/ is generated from those schemas, so the reference cannot describe a rule the build does not enforce.

A survey of 17 design systems, CMS block libraries, and docs generators is in dev/research/COMPONENT-RESEARCH.md, with 120 sources. Stripping the seven items that are site chrome here rather than author-placeable blocks, the cross-system frequency runs:

Two genuine gaps, callout and quote, and two deliberate absences.

steps, plain, proof, split and ticks do not rank because they are either domain-specific to this design system or, in the case of steps and code, near-universal among docs systems and absent everywhere else. Both are kept on those grounds.

The migration named these by falling back to prose, ranked by how often:

Four of the five gaps the survey and the migration named between them are now built: callout (9/17, the largest measured gap), quote (5/17), defs (53 terms on one page), and logos (6 pages, identical markup). faq was renamed to disclosure, for the reason given below.

No video component until its cost is accepted. WCAG 1.2.6 through 1.2.9 ask for sign language interpretation, extended audio description, and a full text alternative. When a video component exists, captions, a transcript, and an audio description will be required schema fields, so a page cannot ship a video that fails those criteria. Until a site needs one, the absence is the cheapest way to hold the line.

No carousel. 4 of 17 systems ship one, and every system that does documents that it underperforms. Runyon's Notre Dame study found a 1.07% click-through rate over 3.76 million visits, with 89.1% of all clicks landing on slide one. GDS removed theirs as the most negatively reviewed element they had. Even ECL, which still ships one, warns of "a high risk that users miss content" and recommends cards instead. Worth stating honestly: no design system publishes an outright ban, and Runyon's best-performing carousel was the auto-advancing one, so the usual anti-autoplay argument is weaker than it is normally made. The case against rests on the click distribution, not on the animation. A card grid does the same job with no WCAG 2.2.2 exposure.

No tabs, and this is the interesting one. Tabs rank 6th at 9 of 17, which makes them the most common thing on this list to refuse. Frequency is not evidence of correctness:

• GOV.UK ships tabs while its own guidance states "Tabs hide content from users" and admits "This component has not yet been tried in research with users."
• USWDS proposed tabs in 2022 and still has not shipped them, on the grounds that hiding content "has a cost for all users, particularly those with physical or cognitive disabilities."
• Docusaurus and Starlight, the two most deployed docs frameworks, both omit the tab-to-panel association the ARIA Authoring Practices Guide requires. Neither emits aria-controls on its tabs, and neither emits aria-labelledby on its panels. Docusaurus additionally has no arrow-key handling at all; Starlight implements roving focus with arrow keys, Home and End, and still leaves the association out. Both read from source on main.

That is the argument, and it is worth stating precisely. The pattern is not impossible: each framework got part of it right. But two independent teams building the same component for the same audience both shipped it incomplete, in the same place, and neither documents which parts it implements. Starlight's tabs documentation page contains no mention of ARIA, keyboard, or assistive technology at all.

A component whose correctness cannot be established without reading its source is a component a content library should not offer. It is the same standard this project holds itself to: a thing is not finished when it works, it is finished when someone can tell that it works.

No modal. Not as an author-placeable block. Focus management, return focus, and escape handling are all easy to get wrong and impossible to check from content.

No separate FAQ block. 3 of 17, and its entire justification was FAQPage rich results, which Google restricted to authoritative government and health sites and then removed from Search entirely in June 2025. An FAQ is a disclosure list of question and answer pairs, which is what disclosure is. Confirmed against Google's own documentation, not the report.

No layout components. No columns, no spacer, no container. The survey's advice is to collapse Row, Stack and Grid into one container; this system goes further and has none, because the renderer owns layout entirely and a container block would be presentation modelled as content. That is a real disagreement with the surveyed systems, and it is only available because the component set is closed.

components/<name>/schema.yml      fields, limits, when_not, accessibility
components/<name>/template.njk    the markup
components/<name>/props.js        optional, for anything computed

shots takes a width of column, wide, or bleed.

column is the default and fills the content container, which is what "full width" usually means. It only needed naming because the component had a bug: a single figure was being wrapped in a two-column grid, so one image rendered at half the width it should have. A lone figure now gets the container.

wide overflows the container. bleed runs to the viewport edges, and keeps its caption inside the text column, because a caption is prose and prose has a measure.

The word full was the first name for bleed and it was wrong: it read as "fills its container" to one person and "runs to the edges" to another, in the same conversation. bleed is the print term and carries only the second meaning.

This field is not only layout. Each value declares its own sizes expression, so a bleeding image generates viewport-width variants and a column one does not. The schema mechanism is sizes_by, which points a media slot at a sibling field. Without it, choosing a width would silently ship the wrong image widths.