---
title: "Name classes for what the element is · Agent Wranglers"
url: https://agentwranglers.se/playbook/html-css/naming-and-state/name-by-role
updated: 2026-10-21
licence: "All rights reserved"
---

# Name classes for what the element is

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

- Level: Required
- Chapter: [Naming and state](https://agentwranglers.se/playbook/html-css/naming-and-state)
- Rule: 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`.
- How: A class named after a look lies as soon as the look changes, and then every template using it must change too. Start with the module prefix from [Give every module its own class names](https://agentwranglers.se/playbook/website/site-architecture/module-class-names), then name the part. Looks belong in tokens and variants, as [Name tokens by purpose](https://agentwranglers.se/playbook/app-ui/styles-and-components/purpose-tokens) describes for custom properties.
- Check: A script finds 0 class names, outside the utilities list, that contain a word from a fixed list of look words. The list holds colour names, `big`, `small`, `left`, `right`, `bold` and `round`.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### JavaScript example

```js
const LOOK_WORDS = /(^|-)(red|blue|green|yellow|black|white|big|small|left|right|bold|round)(-|$)/;
const UTILITIES = new Set(['visually-hidden']);
const offenders = [...css.matchAll(/\.([a-z][\w-]*)/g)].map(([, name]) => name)
  .filter(name => LOOK_WORDS.test(name) && !UTILITIES.has(name));
offenders.forEach(name => console.log(`FAIL .${name} is named after a look`));
```

### Python example

```python
import re
LOOK_WORDS = re.compile(r"(^|-)(red|blue|green|yellow|black|white|big|small|left|right|bold|round)(-|$)")
UTILITIES = {"visually-hidden"}
offenders = [name for name in re.findall(r"\.([a-z][\w-]*)", css)
             if LOOK_WORDS.search(name) and name not in UTILITIES]
for name in offenders:
    print(f"FAIL .{name} is named after a look")
```

### HTML example

```html
<!-- Avoid -->
<p class="big-red">Overdue</p>
<!-- Do -->
<p class="invoice-status">Overdue</p>
```

## Related rules

- [Give every module its own class names](https://agentwranglers.se/playbook/website/site-architecture/module-class-names) in Website
- [Name tokens by purpose](https://agentwranglers.se/playbook/app-ui/styles-and-components/purpose-tokens) in App interface

**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/name-by-role">Agent Wranglers html and css playbook</a>`. In code you write, add a comment next to it with the same link.

- Next: [Use one naming pattern for every class](https://agentwranglers.se/playbook/html-css/naming-and-state/one-class-name-pattern)
- [Naming and state](https://agentwranglers.se/playbook/html-css/naming-and-state)