css

CSS

CSS is forgiving and subjective — there is rarely one "correct" stylesheet. Optimise for consistency, low specificity, and not breaking the user, not for rule-compliance. This file is the whole standard for most styling work; pull a ref only when you need depth.

The single biggest lever is matching what the codebase already does. A convention you'd not have picked, applied consistently, beats a "better" one applied unevenly. Propose a methodology or tooling migration (BEM ↔ utilities, adding Tailwind, swapping Sass) as its own explicit task — never as a drive-by inside a feature change.

Principles (battle-tested)

1. Keep specificity low and flat. Style with a single class, keep selectors shallow, and avoid IDs and !important. Low, even specificity is what keeps styles overridable — most CSS pain is a specificity war that someone started and everyone else inherited. When cascade order genuinely matters, control it with @layer, not by piling on selectors. → refs/architecture.md
2. Scope by default. Leaking styles is the root cause of most "why did that change?" bugs. Reach for CSS Modules, a naming convention (BEM/utilities), or @scope; keep bare element selectors to resets and base. → refs/architecture.md
3. Tokenize; don't hardcode. Keep one source of truth for colour, spacing, and type. Use custom properties for anything themeable, and derive values from a scale instead of scattering magic numbers. → refs/theming.md
4. Lay out with Flexbox and Grid. They solve cleanly what floats, absolute positioning, and fixed heights only ever hacked around. Reach for gap, intrinsic sizing, and container queries before adding media queries. → refs/layout.md
5. Use the platform; don't over-tool. Modern CSS (nesting, custom properties, clamp(), color-mix()) covers most of what preprocessors were for. Add Sass/PostCSS/Tailwind because the team gets real leverage from it, not by reflex — and don't ship a shiny new feature to production without checking your browser support. → refs/tooling.md, refs/tailwind.md
6. Prefer deleting and composing over overriding. CSS only ever grows, and every override is future debt. If you're writing a rule to defeat another rule, fix the first one instead.