Skip to main content

CSS layers

The theme organises its styles using CSS cascade layers, giving predictable control over specificity without !important.

Layer structure

The theme declares three layers in this order:

@layer at.tokens, at.base, at.components;

Layers declared earlier have lower priority. So at.components styles can override at.base styles, which can override at.tokens values.

Your styles take precedence

CSS outside any @layer block wins over all layered styles regardless of specificity, so a plain selector overrides the theme:

/* This overrides the theme's heading colour without !important */
h1 {
  color: var(--at-tertiary);
}

This is the recommended approach for most customisation.

Adding your own layers

For finer control, declare your own layers interleaved with the theme’s. The @layer order statement must come before any layer content, so place it at the top of your main CSS file:

@layer at.tokens, at.base, my.utilities, at.components, my.overrides;

@layer my.utilities {
  .visually-hidden {
    position: absolute;
    width: 1px;
    height: 1px;
    overflow: hidden;
    clip: rect(0 0 0 0);
    white-space: nowrap;
  }
}

@layer my.overrides {
  .at-button {
    border-radius: 0;
  }
}

Here my.utilities sits between at.base and at.components; my.overrides comes after all theme layers.

When to use layers vs unlayered CSS

For most sites, unlayered CSS is simplest: write styles normally and they override the theme wherever they conflict.

Layers become useful when building a design system on top of the theme, or with multiple CSS files that need an explicit priority order among themselves — declaring one prevents surprises as the stylesheet grows.