---
title: "Naming and state · Agent Wranglers"
url: https://agentwranglers.se/playbook/html-css/naming-and-state
updated: 2026-10-21
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Naming and state

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers). Updated 2026-10-21.

For AI agents: [llms.txt](https://agentwranglers.se/llms.txt) is a short guide that sends you to the rules your problem needs, and [rules.json](https://agentwranglers.se/playbook/html-css/rules.json) holds every rule of this playbook as JSON.

> 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.

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/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.

## Recommended

- [Name classes for what the element is](https://agentwranglers.se/playbook/html-css/naming-and-state/name-by-role): Name each class after the element's job in its module, such as `invoice-total`. Never name it after a look, such as `big-red` or `left-box`.
- [Use one naming pattern for every class](https://agentwranglers.se/playbook/html-css/naming-and-state/one-class-name-pattern): Write 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](https://agentwranglers.se/playbook/html-css/naming-and-state/state-in-attributes): Express state with the attribute that carries it, such as `aria-expanded`, `aria-current`, `aria-invalid`, `disabled`, `hidden` or `data-state`. Never add a state class such as `is-open` or `active`.
- [Never style by position or deep nesting](https://agentwranglers.se/playbook/html-css/naming-and-state/no-position-selectors): Select 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.
- [Prefix a component's custom properties with its name](https://agentwranglers.se/playbook/html-css/naming-and-state/component-custom-properties): Name 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](https://agentwranglers.se/playbook/html-css/naming-and-state/separate-script-hooks): Let 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

- [Web app interface playbook](https://agentwranglers.se/playbook/app-ui). Name classes per module and show state with attributes, so components stay reusable.

- Previous: [The cascade](https://agentwranglers.se/playbook/html-css/the-cascade)
- Next: [HTML structure and reuse](https://agentwranglers.se/playbook/html-css/html-structure-and-reuse)
- [All chapters](https://agentwranglers.se/playbook/html-css)