Skip to main content

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.


Enforced by

12.1-12.8 are review only. See enforcement.md.