Learn

Shared language

Good systems need consistent words. If three developers use the word component to mean four different things, the CSS is usually only the second problem.

Ownership

The answer to where CSS belongs. Before writing selectors, decide whether something belongs in settings, base, utilities, layout, components, theme, legacy, thirdparty (low layers), or hacks. Wrong ownership creates most future problems.

Component

A reusable UI pattern with clear responsibility. Components should have semantic names, shallow selectors, and obvious boundaries. If a repeated pattern needs explanation twice, it probably needs a component.

Modifier

A permanent reusable variation of a component. Example: a featured card or large button. Modifiers describe stable variants, not temporary behaviour. In HTML, apply the modifier withthe base class on the same element (product-card product-card--featured). In CSS, target the variant in the component partial — flat (.product-card--featured), nested (&--featured), or chained when the project needs extra guarding.

State

Temporary or conditional UI behaviour. Loading, expanded, active, or disabled states should use clear .is_* or.has_* classes (underscore after the prefix, not-- like modifiers). If it disappears when the user leaves, it is probably state. Seemodifiers and statefor the naming signal.

Theme

Presentation changes without structural responsibility. Theme changes colour, visual treatment, and appearance. It should not quietly become layout or component architecture.

Utility

A small universal helper in the CSS utilities layer—usually for accessibility or genuinely shared behaviour—not utility-first styling in HTML. Utilities are exceptions, not architecture. Repeated class stacks in markup are unnamed components, not utilities.

Hacks

Temporary fixes for urgent delivery needs. The hacks layer exists so these fixes stay visible. If a hack survives six months, it is probably not temporary, and should be reviewed as architecture.

Legacy

Inherited first-party CSS carried forward because rewriting everything would be theatre, not engineering. Legacy belongs in a controlled low layer, not quietly copied into new component files. Vendor CSS may share this bucket or use a separate third-party layer.

Third-party layer

Optional low layer for CSS you do not own: npm packages, widgets, and CMS plugins. Use when legacy is the wrong name or when both inherited first-party CSS and vendor CSS need separate buckets — declarethirdparty before legacy in@layer. See layer guidance.

Calm CSS

Predictable, boring, understandable CSS. Clear ownership, shallow selectors, token consistency, and fewer surprises. Calm CSS beats clever CSS because teams ship faster when nobody needs detective work.