Agent WranglersNaming and state
Name every class for what it is, follow one pattern, and show state through attributes. A selector then says which element it means and why.
- Required 4
- Recommended 2
Required
Name classes for what the element is
RequiredName each class after the element's job in its module, such as
invoice-total. Never name it after a look, such asbig-redorleft-box.Use one naming pattern for every class
RequiredWrite every class name in lowercase words joined by single hyphens, starting with the module prefix. One regular expression describes every class in the project.
Show state through attributes
RequiredExpress state with the attribute that carries it, such as
aria-expanded,aria-current,aria-invalid,disabled,hiddenordata-state. Never add a state class such asis-openoractive.Never style by position or deep nesting
RequiredSelect elements in a component by their own class, never by tag name, position or ancestry. A selector has at most 3 compound parts and 0 type selectors in the components layer.
Recommended
Prefix a component's custom properties with its name
RecommendedName every custom property defined in a component file with the module prefix, such as
--order-card-gap. Set it from a global token, and let variants change only these local properties.Keep script hooks apart from style hooks
RecommendedLet scripts find elements through
data-attributes or ids, never through styling classes. Stylesheets never select the attributes that scripts use as hooks.
Read this with
For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/html-css/naming-and-state">Agent Wranglers html and css playbook</a>. In code you write, add a comment next to it with the same link.