Rule 12 - Markup: Data attributes
When and how to use data-* attributes on HTML elements.
Rules
12.1. Data attributes MUST serve exactly one of three purposes: CSS configuration, JS behavior hooks, or cross-component binding.
12.2. Implementations MUST use data attributes for CSS
configuration when CSS needs to read a value via attr(),
::after, or attribute selectors.
12.3. Implementations MUST use data attributes for JS behavior hooks when JS needs to initialize or control a component. Classes MUST NOT be used for JS binding.
<!-- Correct --><div data-accordion="exclusive">...</div><button data-close aria-label="Close"></button><!-- Wrong --><div class="js-accordion">...</div>
12.4. Cross-component binding via data attributes MAY be used sparingly. Implementations SHOULD prefer HTML structure over attribute binding.
Example:
<button data-tooltip="Launch sequence">Launch</button>
12.5. Data attributes MUST NOT be used for visual variants - use value classes instead.
Wrong:
<button data-variant="subtle">. Correct:<button class="subtle">.
12.6. Data attributes MUST NOT be used for semantic state when an ARIA attribute accurately describes it - use the ARIA attribute instead.
Wrong:
<button data-expanded="true">. Correct:<button aria-expanded="true">.
When no ARIA attribute fits (component-specific or utility-owned
runtime state such as scroll position past a threshold, an
"active trail" highlight, or an enhancement marker), a namespaced
data-{component-or-utility}-{state} attribute is the correct
hook per Rule 24.
12.7. Data attributes MUST NOT be used for interaction triggers - use native elements instead.
Wrong:
<div data-toggle="collapse">. Correct:<details><summary>…</summary>…</details>.
12.8. Class selectors (e.g. .js-accordion) MUST NOT be used for
JS behavior.
12.1-12.8 are review only. See enforcement.md.