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.
| Component | Semantic element | Mirror 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 |
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.