HTML and CSS playbook

A playbook for organising the HTML and CSS of any website or web app. It covers where styles live, how the cascade is kept in order, how classes and states are named, and how markup is reused. It gives no advice on colours, fonts or layout. Those choices belong to your designer.

Stylesheets rot quietly. A rule added at the end of a file wins over an older one, and nobody notices until a page breaks. Each rule here closes one of those gaps with a limit that a linter or a build script can check.

AI agents write a lot of CSS fast. Give them these rules and the checks, and every new component lands in the same place, with the same names, inside the same limits.

Chapters

1. Structure and files

   Give every style one home. One entry file loads the layers in a fixed order, and each component owns exactly one stylesheet that no other file touches.

   • Required 4
   • Recommended 1

2. The cascade

   Decide which style wins before anyone writes one. Declare the layer order once, cap selector specificity, and never let file order settle a conflict.

   • Required 6
   • Avoid 1

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

4. HTML structure and reuse

   Build pages from native elements and small templates that take data. Every repeated pattern comes from one place, with stable ids and no extra wrappers.

   • Required 4
   • Recommended 1

5. Checks in code

   Turn every HTML and CSS rule into a linter rule or build check. A style that breaks a limit then stops the build before anyone has to spot it.

   • Required 5
   • Recommended 1

All 29 rules on one page

Related playbooks

• Site architecture

  In the Website playbook. Build every repeated piece of HTML from one module, with class names that module owns.

• Styles and components

  In the App interface playbook. Take every style value from design tokens and build each control once, with variants.

• End-to-end and browser tests

  In the Testing playbook. Prove in a browser that pages still render and work after a change to shared CSS.

• Rules as code

  In the Engineering playbook. Turn each CSS and HTML rule into a check that fails the build, not a review comment.