# CSS layers

> How the theme uses CSS cascade layers and how to work with them in your own styles.

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:

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

- **at.tokens** --- CSS custom properties (design tokens) for colours,
  typography, spacing, and layout
- **at.base** --- element-level resets and base styles (headings, paragraphs,
  links, tables, code blocks)
- **at.components** --- styles for specific theme components (Nav, Footer, Card,
  and others)

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:

```css
/* 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:

```css
@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.
