BEM & styling strategy: Hybrid, not utility-only.
- Tailwind first — layout, spacing, colors from tokens via utilities; shared patterns in helpers (e.g.
navControlButtonClass). - Semantic blocks — BEM-style block names for self-contained UI:
.rich-text,.rich-text-embed,.mux-player. Scoped CSS inassets/styles/components/ortypography/typography.csstargets children inside the block. - When to add a block class — portable text, third-party widgets (Mux, cookie consent), or markup you cannot express cleanly with utilities alone. Keep blocks narrow; avoid global element selectors outside
.rich-text.
CSS variables & tokens Single source of truth in web/src/assets/styles/variables/. tokens.css loads breakpoints, spacing, and font sizes before Tailwind; globals.css adds colors, typography, @theme, and component CSS. Rule: change a --token in variables/*.css and the matching key in tailwind/theme.css when you expose it as a utility.
Colors Semantic --color-* tokens in variables/colors.css — not raw hex in components.
- Text & surfaces —
--color-text,--color-text-muted,--color-heading,--color-bg,--color-surface-muted,--color-border-subtle - Brand & links —
--color-brand,--color-accent,--color-link,--color-hover,--color-active - Code & status —
--color-code-bg+--color-code-text(light:#27272aon#e4e4e7, dark:#e4e4e7on#27272a) ·--color-error,--color-success,--color-danger— not for inline code - Primitives —
--color-white,--color-black,--color-grey(and optional palette comments for extension)
Light defaults on :root; dark overrides on :root[data-theme="dark"]. Tailwind: bg-color-bg, text-color-text, border-color-border-subtle, etc. Cookie banner and theme toggle reuse the same tokens.
Spacing Scale in variables/sizes.css — --space-* mapped to Tailwind as p-sm, gap-md, m-lg, max-w-container.
- min 2px · xs 8px · sm 16px · md 32px · lg 48px · xl 64px · max 96px · extra 192px (steps up at
md,2xl,wide) - Layout —
--content-max-width(2000px /widebreakpoint) ·--container-spacing24→48px side padding ·--footer-heightresponsive
Rich text and modules use --space-* for block gaps (e.g. margin under paragraphs, above headings).