CSS

CSS should make interfaces easier to use and easier to maintain — not create specificity wars, !important graveyards, or files nobody dares to touch. When styling needs detective work, the system is failing the team.

These standards describe how to structure CSS so teams can read, debug, extend, and delete styles with confidence — built for real delivery, not clever one-offs.

See code formatting and style for indentation, declarations, and media-query layout in examples.

This site uses LSCSS (Layered Semantic CSS). Declare layer order once in your stylesheet entry file, then place styles in the matching layer — the order below is what this site follows.

Layer order

@layer legacy, settings, base, utilities, layout, components, theme, hacks;

Recommended folders

• legacy/ — vendor CSS, old frameworks, third-party stylesheets (optional; sometimes called thirdparty elsewhere in LSCSS)
• settings/ — non-colour tokens (spacing, type, radius, motion)
• base/ — reset and global element defaults
• utilities/ — skip link, .vh, .is_hidden, focus, motion helpers
• layout/ — page shell, containers, regions
• components/ — named UI blocks
• theme/ — colour tokens and presentation overrides on :root
• hacks/ — temporary fixes (should feel embarrassing)

Settings

Font faces, breakpoints, z-index scales, spacing scales. Non-colour configuration only — no rendered component styles.

Base

Typography, links, forms, tables, lists, media defaults. Low specificity. No component styling.

Utilities

Helpers for real repeated problems — not a second styling language that grows without discipline. Use .vh for visually hidden text that screen readers should still read — error prefixes, step status, tooltip descriptions linked with aria-describedby. Use .is_hidden only when content is removed from the page (display: none) — panels closed by JavaScript, not for screen-reader-only copy.

Components

Self-contained UI blocks with two-word class names where possible — for example .content-card, .site-header, .action-button. Styles should not depend heavily on page context.

Layout

Page shells, containers, and structural regions. Layout rules should not leak heavily into components.

Theme

Colour custom properties and theme-specific presentation — for examplecolors.css on :root. Keeps palette changes separate from component structure.

Hacks

Short-term fixes only. If hacks become permanent, refactor properly and move the code where it belongs.

Legacy

Quarantine CSS you do not own yet — Bootstrap remnants, widget vendor sheets, tag-manager injectors wrapped as imports. Import with layer(legacy) so settings, base, and components can override deliberately while you migrate. Empty on greenfield projects; essential on incremental rewrites.

Component class names should use two words where possible (.site-header, .content-card) — not single words like .card or .hero. Names should explain purpose, not visual accidents or one-off layout hacks.

Good

/* Two-word components */
.site-header { }
.content-chapter { }
.content-card { }

/* Children scoped to the parent */
.site-header > .logo { }
.content-card > .title { }

/* Variants */
.action-button--primary { }
.content-chapter--tinted { }

/* Generic state */
.is_active { }
.is_hidden { }
.has_error { }

Bad

/* Single-word components — too generic */
.hero { }
.card { }
.button { }

/* Appearance, not role */
.red-text-box-left-small { }

State classes

Make state explicit with generic classes such as .is_active, .is_hidden, and .has_error — not names like.is-nav-open, and not mixed up with -- variants. Prefer class toggles over inline styles scattered from JavaScript unless there is a strong reason not to.

Do not use .is_hidden for screen-reader-only text — that removes content from the accessibility tree. Use the utility .vh instead. Reserve .is_hidden for UI you genuinely take off the page until opened or shown again.

Layout

Use Grid for two-dimensional layout. Use Flexbox for one-dimensional distribution. Pick based on the problem, not habit.

Typography

Typography is infrastructure. Prioritise readable line length, sensible line-height, clear hierarchy, and text sizes that work for real users — not decorative noise.

Line length

Cap prose width with max-inline-size (or max-width) using the ch unit — one ch is roughly the width of the 0 glyph in the current font, so 65ch targets about sixty-five characters per line regardless of font size. Store shared limits as tokens (for example --content-measure: 65ch for body copy, a shorter ch value for display lines).

.article-body {
    max-inline-size: 65ch;
}

.display-line {
    max-inline-size: 22ch;
}

ch is a hint, not a precise character count — mixed scripts, italics, and font metrics shift the real count. Tune by reading real content, not by chasing a perfect number in DevTools.

Text wrapping

text-wrap: balance evens out line lengths on short headings so you avoid a single orphan word on its own line. text-wrap: pretty does the same kind of tidy-up for body copy — fewer short last lines and lone words stranded at the end of a paragraph. Both are enhancements: copy stays readable without them.

.card-title {
    text-wrap: balance;
}

.card-body {
    text-wrap: balance;
    text-wrap: pretty;
}

For body copy, declare balance first, then pretty on the next line. Browsers that understand pretty use it; browsers that do not ignore the invalid value and keep balance — you do not need@supports for that fallback. Use @supports only when you want different rules entirely, not for this stack.

Browser support: ch is safe everywhere a modern baseline expects. text-wrap: balance is widely available in current evergreen browsers (Baseline 2024). text-wrap: pretty lags behind, but the cascade above is a safe progressive enhancement. Do not rely on either value for layout stability (no fixed heights that assume a line count).

Use balance on headings and short labels; reserve pretty for paragraphs and lists where orphan lines would show. Skip both on long continuous text if performance becomes measurable — the cost is usually negligible on typical pages, but worth knowing for very large DOMs.

When in doubt, ask: Would another developer understand and safely change this CSS in six months? If not, simplify before you merge.