Sort styles into five layers

How to do it

Tokens hold custom properties only, as Take every style value from design tokens describes. Base styles bare elements such as body, a and table, with no classes. Layout places regions of the page. Components style one module each. Utilities are the few single-purpose classes on the written list from Give every module its own class names. A later layer may use what an earlier layer defines, never the other way 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.

CSS example

/* tokens/index.css: custom properties only */
:root { --surface: Canvas; --text: CanvasText; }

/* base/elements.css: bare elements, no classes */
a { color: var(--text); }

/* components/order-card.css: one module */
.order-card { background: var(--surface); }

JavaScript example

// A build check: base files contain no class selectors
import { readFileSync, readdirSync } from 'node:fs';
const failures = readdirSync('styles/base')
  .filter(file => /\.[a-z][\w-]*\s*[{,:]/.test(readFileSync(`styles/base/${file}`, 'utf8')));
failures.forEach(file => console.log(`FAIL styles/base/${file} selects a class`));
process.exit(failures.length ? 1 : 0);

Python example

# The same check in Python
import pathlib, re, sys
failures = [p for p in pathlib.Path("styles/base").glob("*.css")
            if re.search(r"\.[a-z][\w-]*\s*[{,:]", p.read_text())]
for p in failures:
    print(f"FAIL {p} selects a class")
sys.exit(1 if failures else 0)

How to check

Every CSS file sits in one of the five folders. Files in tokens/ declare only custom properties. Files in base/ contain no class selectors. Files in utilities/ define only classes on the written list.

Related rules

• Load every stylesheet from one entry file in HTML and CSS
• Take every style value from design tokens in App interface
• Give every module its own class names in Website
• Declare the layer order once in HTML and CSS