Glossary

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, 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.

State

Temporary or conditional UI behaviour. Loading, expanded, active, or disabled states should use clear .is_* or .has_* classes. If it disappears when the user leaves, it is probably state.

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, usually for accessibility or genuinely shared behaviour. Utilities are exceptions, not architecture. If utility combinations repeat, they are often unnamed components.

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

Older 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.

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.