Skip to main content

Rule 11 - Markup: Rendering modes

How components are rendered in HTML.

Rules​

11.1. If a semantic HTML element exists for the component, implementations MUST use the element as the primary selector. No class is REQUIRED for base styling. A sectioning element that other components use as a structural part (<header> and <footer> inside a card or a modal) is the exception: that component takes its class as the primary selector, so the element form stays free for the parts.

11.2. An element-styled component either pairs a mirror class with the element form (the mirrored styling value) or styles the semantic form alone (the bare styling value). A mirror class MUST produce the identical visual result on a generic element. The value is declared in the component spec as Styling.use(Styling.mirrored) or Styling.use(Styling.bare); Rule 53.21 audits the declaration against the CSS and the template.

11.3. Mirror class selectors and element selectors MUST share the same CSS declarations.

11.4. The element form and the class-based form MUST be visually identical.

11.5. The element form MUST be the primary documented form in Storybook stories.

11.6. The class-based form SHOULD be documented alongside for CMS and framework integration where the HTML element is constrained.

11.7. Shared value words (.subtle, .outline, .sm) MUST work in both forms - added to the root element.

11.8. Components without a semantic HTML element MUST use their component class (e.g. .message, .badge, .carousel).

11.9. Implementations MUST NOT add a mirror class to an element that is already styled by its element selector.

Example: <button class="btn"> is redundant - <button> is already styled.

The rule governs templates and consumer markup. Storybook's Mirror class switch (Rule 53.21) renders the class form on purpose, to show that both forms match.

11.10. A mirror class is the component name (.card, .table, .fieldset), which coincides with the tag name wherever the component is named after its element. Where a mirror uses a registered short form (.btn), the full component name MUST remain canonical for prose and Twig includes.

11.11. When using the class-based form, implementations SHOULD pick a meaningful semantic fallback element (<a>, <span>, <section>) over a bare <div>.

11.12. Context selectors MUST use the shallowest combinator the markup allows: direct child (>) for a part the component renders directly, the descendant combinator only where the markup places an intermediate element the component does not own (table th, with thead or tbody between). A context style on a component's own class needs no class fallback; a context style on a bare element (blockquote footer) MUST have one.

11.13. The component class MUST be applied to the outermost element that the component owns. When a landmark or wrapper element exists (<nav>, <aside>, <dialog>, <details>, <article>, <form>, etc.), the class lives on that element, not on a nested child. Children are styled via direct-child context selectors per Rule 11.12. This keeps the class identifying the component as a whole - selectors, attribute overrides, and JS hooks all target a single, predictable root.

<!-- Correct - class on the landmark wrapper -->
<nav class="pagination" aria-label="Pagination">
<ol>
<li><a href="…" aria-current="page">5</a></li>
</ol>
</nav>

<!-- Wrong - class on a nested child -->
<nav aria-label="Pagination">
<ol class="pagination">
<li><a href="…" aria-current="page">5</a></li>
</ol>
</nav>

Exception - opt-in utility wrappers: When a component conditionally wraps its root in a utility element via an explicit prop (e.g. use_container: true rendering <div class="container"> around the component), the utility wrapper belongs to the wrapped utility, not the component, and does not count as outermost. The component class still lives on the component's own root.

11.14. A story render MUST include the matching component twig rather than hand-author a raw tag that another component owns. <button>, <select>, <textarea>, <blockquote>, <progress> and <fieldset> each belong to a component, and a raw one is permitted only in that component's own stories. Elsewhere, render the component (Button(...)) so the story exercises the shipped markup rather than a copy of it that drifts from it.

// Correct - the form story renders the button component.
render: (args) => `${Field(args)}${Button({ content: 'Save' })}`,

// Wrong - a raw tag the button component owns.
render: (args) => `${Field(args)}<button class="btn">Save</button>`,

Reference - mirror class table​

Every component whose spec declares Styling.mirrored, with the element form its base selector group pairs the mirror class with. A component that gains or loses the value updates this table in the same change.

ComponentSemantic elementMirror class
accordion<details>.accordion
blockquote<blockquote>.blockquote
button<button>.btn
callout<aside role="note">.callout
card<article>.card
deflist<dl>.deflist
fieldset<fieldset>.fieldset
figure<figure>.figure
form<form>.form
group[role="group"].group
image<img>.image
label<label>.label
link<a>.link
message<output>.message
modal<dialog>.modal
search<search>.search
select<select>.select
table<table>.table
textarea<textarea>.textarea
textfield<input> of type text, email, password, tel, url, search.textfield
upload<input type="file">.upload

Enforced by

11.3, 11.14 by yarn cli 11 (findUnpairedMirrorSelectors, findRawComponentTags in packages/cli/src/rules/11.js). 11.1, 11.2, 11.4-11.13 are review only. See enforcement.md.