LSCSS

Layers

Layer architecture

Layers decide who wins before selectors start arguing. LSCSS uses explicit cascade layers so override order is architecture, not luck, or repeated emergency !important declarations.

Layer order

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

Lower layers lose to higher layers. Source order inside a layer matters less than the declared layer order itself. This means architecture controls overrides before specificity becomes a problem.

What each layer does

  • legacy keeps old and third-party CSS low in the cascade.
  • settings holds tokens, fonts, variables, and custom media.
  • base contains resets, typography, and true global defaults.
  • utilities holds rare helper classes like accessibility helpers.
  • layout handles structural wrappers and global layout patterns.
  • components contains normal component styling.
  • theme changes presentation, not component structure.
  • hacks isolates urgent temporary fixes.

Import into the correct layer

CSS code example 
@import './vendor/slider.css' layer(legacy);
@import './settings/variables.css' layer(settings);
@import './base/reset.css' layer(base);
@import './layout/page-shell.css' layer(layout);
@import './components/product-card.css' layer(components);
@import './theme/brand.css' layer(theme);
@import './hacks/temporary-fixes.css' layer(hacks);

The goal is not only naming layers. Files must be imported into the correct place or the architecture becomes decorative paperwork.

Why the legacy layer exists

Legacy CSS and third-party styles belong in the legacy layer: it is declared first in the @layer list so it stays lowest in the cascade. That lets structured layers win without heavier selectors. On this site, the vendored Prism syntax theme is imported with layer(legacy) for the same reason.

Legacy should be contained, not allowed to quietly become the new architecture through neglect.

Why the hacks layer exists

Sometimes production needs a fast correction before a full refactor is realistic. The hacks layer gives those fixes a visible quarantine zone.

Hacks should be obvious, isolated, and temporary. If a hack has been living comfortably for nine months, it is no longer a hack. It should be reviewed as architecture.

Working rules

  • Check layer order before increasing specificity.
  • Do not put component styles in base or theme files.
  • Do not hide hacks inside normal component partials.
  • Do not import third-party CSS without a legacy layer.
  • Theme changes presentation, not structure.
  • Layer order should be decided once, not negotiated weekly.