LSCSS

Theme layer

Theme layer

Theme changes presentation, not structure. It handles brand styling, tokens, and visual consistency without quietly rewriting component architecture behind everyone’s back.

Quick decision rules

TEXT code example 
Ask:
Is this changing presentation only?
→ Theme

Is this changing structure or behaviour?
→ Component

Is this temporary or urgent?
→ Hacks, not theme

Theme should be predictable. If a visual change needs detective work to explain, the architecture is already drifting.

What belongs in the theme layer

Theme contains colour, spacing adjustments, radius, shadows, typography presentation, and brand-level visual decisions shared across components.

Theme does not contain layout fixes, accessibility repairs, JavaScript state handling, or emergency overrides pretending not to be hacks.

Tokens first

Change the token, not twenty unrelated selectors. Tokens protect consistency and stop branding from becoming a treasure hunt for the correct shade of purple.

CSS code example 
:root {
    --colour-accent: #6f3cff;
    --colour-surface: #ffffff;
    --radius-card: 1rem;
}

@layer theme {
    .product-card {
        background: var(--colour-surface);
        border-radius: var(--radius-card);
    }
}

Safe visual overrides

Good theme overrides adjust presentation without rewriting the component. Prefer intentional custom properties exposed by the component instead of surprise selector overrides.

CSS code example 
@layer theme {
    .button {
        --button-background: var(--colour-accent);
    }
}

If the theme needs to change layout or behaviour, the problem is probably in the component layer, not the theme layer.

Avoid random one-off styling

CSS code example 
.button {
    background: purple;
}

.checkout-button {
    background: #7a32ff;
}

.hero-button {
    background: rgb(118 45 255);
}

Random visual overrides spread inconsistency and turn brand styling into guesswork. If one button becomes purple for unclear reasons, the problem is architecture, not creativity.

  • Do not hard-code random colours inside components.
  • Do not use theme as a hiding place for hacks.
  • Do not override component structure from theme.
  • Keep theme decisions intentional and documented.
  • If the change is temporary, it belongs in hacks, not theme.

Next useful pages