---
title: "HTML and CSS checklist: all 32 rules · Agent Wranglers"
url: https://agentwranglers.se/playbook/html-css/checklist
updated: 2026-10-21
licence: "All rights reserved"
---

# HTML and CSS checklist

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

Every rule in the html and css playbook, by chapter, required rules first. Each links to its own page with how we built it and how to check it.

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

## Structure and files

- [ ] **Required** [Load every stylesheet from one entry file](https://agentwranglers.se/playbook/html-css/structure-and-files/one-css-entry-file): Load all CSS through one entry file that imports every other stylesheet in a fixed order. Pages link that one built file and nothing else.
- [ ] **Required** [Sort styles into five layers](https://agentwranglers.se/playbook/html-css/structure-and-files/five-style-layers): Put every style in one of five layers, in the order tokens, base, layout, components and utilities. Each layer has its own folder, and a file belongs to exactly one layer.
- [ ] **Required** [Give each component exactly one stylesheet](https://agentwranglers.se/playbook/html-css/structure-and-files/component-stylesheet): Keep all CSS for a component in one file named after it. No other file may select that component's classes.
- [ ] **Required** [Write styles only in stylesheets](https://agentwranglers.se/playbook/html-css/structure-and-files/styles-only-in-stylesheets): Keep every style declaration in a stylesheet. Templates have no `style` attributes or `<style>` elements, and scripts never set `element.style` properties.
- [ ] **Recommended** [Keep media and container queries with their component](https://agentwranglers.se/playbook/html-css/structure-and-files/queries-with-the-component): Write every media or container query inside the stylesheet of the component it changes. Never collect them in a separate file for screen sizes or print.

## The cascade

- [ ] **Required** [Declare the layer order once](https://agentwranglers.se/playbook/html-css/the-cascade/declare-layer-order-once): Declare every cascade layer in one `@layer` statement at the top of the entry file. Put every style inside a named layer, so no style is left unlayered.
- [ ] **Required** [Cap selector specificity](https://agentwranglers.se/playbook/html-css/the-cascade/specificity-limit): Keep every selector at a specificity of `0,2,0` or lower. That is at most two classes, attributes or pseudo-classes, with no ids.
- [ ] **Required** [Never style by id](https://agentwranglers.se/playbook/html-css/the-cascade/no-id-selectors): Use ids only for links, labels and scripts. No CSS selector contains an id.
- [ ] **Required** [Keep !important inside the utilities layer](https://agentwranglers.se/playbook/html-css/the-cascade/important-only-in-utilities): Write `!important` only in the utilities layer. Every other layer has 0 `!important` declarations.
- [ ] **Required** [Fence each component's styles in](https://agentwranglers.se/playbook/html-css/the-cascade/scope-component-styles): Make every selector in a component file start at the component's root. Use the module prefix on each class, or wrap the file in `@scope` on the root class.
- [ ] **Required** [Import third-party CSS into its own layer](https://agentwranglers.se/playbook/html-css/the-cascade/vendor-css-layer): Import every third-party stylesheet into a named layer placed before your own layers. Never edit a vendor file in place.
- [ ] **Avoid** [Let source order settle a tie](https://agentwranglers.se/playbook/html-css/the-cascade/source-order-wins): Never depend on which file loads last to decide between two rules of the same layer and specificity.

## Naming and state

- [ ] **Required** [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`.
- [ ] **Required** [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.
- [ ] **Required** [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`.
- [ ] **Required** [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.
- [ ] **Recommended** [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.
- [ ] **Recommended** [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.

## HTML structure and reuse

- [ ] **Required** [Use the native element first](https://agentwranglers.se/playbook/html-css/html-structure-and-reuse/native-elements-first): Use the HTML element made for the job before a `div` or `span` with a role. Actions are `<button>`, navigation is `<a href>`, lists are `<ul>` or `<ol>`, and page regions are `header`, `nav`, `main` and `footer`.
- [ ] **Required** [Pass data to templates instead of markup](https://agentwranglers.se/playbook/html-css/html-structure-and-reuse/partials-take-data): Give every template or component function plain data, such as text, numbers, lists and named options. Callers never pass HTML strings or extra class names into it.
- [ ] **Required** [Keep ids unique and stable](https://agentwranglers.se/playbook/html-css/html-structure-and-reuse/unique-stable-ids): Give each id on a page a value that appears once on that page and stays the same in every build. Make it from the content or the data key, never from a counter or a random number.
- [ ] **Required** [Avoid wrapper elements that only hold a class](https://agentwranglers.se/playbook/html-css/html-structure-and-reuse/no-wrapper-divs): Put the class on the element that already exists instead of adding a `div` around it. A `div` without attributes never wraps another `div` directly.
- [ ] **Recommended** [Give each template one root element](https://agentwranglers.se/playbook/html-css/html-structure-and-reuse/one-root-per-template): Make every template return exactly one root element that carries the module's root class. Callers never wrap it in an extra element to change how it looks.
- [ ] **Recommended** [Clone markup that scripts add from a template element](https://agentwranglers.se/playbook/html-css/html-structure-and-reuse/template-element): Keep every piece of markup that a script inserts in a `<template>` element in the page. Scripts clone it and fill in text, and never build HTML in strings.
- [ ] **Recommended** [Name custom elements with the project prefix](https://agentwranglers.se/playbook/html-css/html-structure-and-reuse/custom-element-names): Give every custom element a name that starts with one project prefix and a hyphen, such as `bakery-basket`. Define each name in exactly one file.

## Checks in code

- [ ] **Required** [Lint styles with one shared config](https://agentwranglers.se/playbook/html-css/checks-in-code/style-linter): Run a style linter such as stylelint over every stylesheet in the build, with one config file in the repository. The build fails on any error or warning.
- [ ] **Required** [Fail on unknown and duplicate CSS](https://agentwranglers.se/playbook/html-css/checks-in-code/unknown-and-duplicate-css): Make the linter reject unknown properties, values, at-rules and type selectors, and duplicate selectors or properties.
- [ ] **Required** [Remove selectors that match nothing](https://agentwranglers.se/playbook/html-css/checks-in-code/unused-selectors): Fail the build when a class or attribute selector in the stylesheets matches no element in any built page. The only exceptions sit on one list of states and classes that scripts add.
- [ ] **Required** [Lint the built markup](https://agentwranglers.se/playbook/html-css/checks-in-code/markup-linter): Run a markup linter such as html-validate over every built page, with rules for structure on top of validity. Turn on rules against inline styles, duplicate ids, redundant roles and ARIA patterns that have a native element.
- [ ] **Required** [Keep every exception in the linter config](https://agentwranglers.se/playbook/html-css/checks-in-code/one-exceptions-list): Write every exception to a lint rule in the config file, with a reason and a file path. Source files contain 0 comments that turn a linter off.
- [ ] **Recommended** [Check the built CSS as well as the source](https://agentwranglers.se/playbook/html-css/checks-in-code/check-built-css): Run the specificity, layer and unused-selector checks on the CSS the build produces, not only on the source files.
- [ ] **Recommended** [Lint every feature against one Baseline target](https://agentwranglers.se/playbook/html-css/checks-in-code/baseline-target): Choose one Baseline target for the project, such as "widely available" or a year. Fail the build on any CSS or HTML feature outside it that no `@supports` test guards.

## Show the badge on your project

When your project passes every Required rule, you can show this badge on your site or in your README. It links to this checklist, so anyone can run the same checks.

```html
<a href="https://agentwranglers.se/playbook/html-css/checklist"><img src="https://agentwranglers.se/badge.svg" alt="Checked against the Agent Wranglers html and css playbook" width="214" height="20"></a>
```

```markdown
[![Checked against the Agent Wranglers html and css playbook](https://agentwranglers.se/badge.svg)](https://agentwranglers.se/playbook/html-css/checklist)
```