# Customisation

> How to re-brand the theme and override design tokens with your own styles.

The theme's visual design is controlled entirely through CSS custom properties.
You can change colours, typography, spacing, and layout by redefining the
relevant `--at-*` tokens in your own CSS.

## Re-branding

Every semantic colour token on the web side derives from `--at-primary` via
relative colour syntax, so a full re-brand is a small CSS file that overrides
the palette:

```css
/* src/styles/brand.css */
:root {
  --at-primary: #7c2d12;
  --at-secondary: #0e7490;
  --at-tertiary: #6d28d9;
}
```

Import it in your layout after the theme layout:

```astro
---
import BaseLayout from "astro-theme-university/layouts/BaseLayout.astro";
import "../styles/brand.css";
---

<BaseLayout title="My site">
  <slot />
</BaseLayout>
```

Headings, links, borders, surface tints, table styling, and the deck tint scales
all re-derive from the new palette --- there's nothing else to override. Pair
the CSS with branding props on `BaseLayout` (`logo`, `favicon`,
`acknowledgement`, `legalLinks`, and so on) and the whole site carries your
institution's identity. A branding package can bundle both: a brand stylesheet
plus a props object you spread into `BaseLayout`.

The derived hover and active variants (`--at-primary-hover`,
`--at-primary-active`) update automatically with the palette; brands with
hand-tuned variants can override them directly.

## Overriding individual tokens

For finer-grained changes, redefine semantic tokens instead of, or as well as,
the palette --- for example in `src/styles/overrides.css`:

```css
:root {
  --at-heading: var(--at-text);
  --at-border-radius: 0;
}
```

Because the theme tokens sit in the `at.tokens` layer and your overrides are
unlayered, your values take precedence automatically --- no `!important`, no
specificity games. Most colour tokens resolve light and dark values with
`light-dark()`, so a plain override applies in both modes; use `light-dark()`
yourself for mode-specific values.

## Adjusting typography

To use a different body font, redefine `--at-font-body` and load the font
itself. The easiest path is Astro's
[font system](https://docs.astro.build/en/guides/fonts/): `BaseLayout` emits an
`@font-face` for every font registered in your config's top-level `fonts` array,
and the `preloadFonts` integration option controls which are preloaded (by
default only the theme body font). Fonts loaded outside the font system need a
`<link>` in your layout's `<head>` or your own `@font-face` declaration.

```css
:root {
  --at-font-body: "Inter", sans-serif;
  --at-font-size-base: 1rem;
  --at-line-height: 1.7;
}
```

## Changing spacing and layout

```css
:root {
  --at-content-width: 60rem;
  --at-spacing-lg: 2rem;
  --at-spacing-2xl: 5rem;
}
```

## Dark mode overrides

If you need different values in dark mode, use `light-dark()` in your override,
or scope a rule to the `[data-theme="dark"]` selector. See
[dark mode](https://anucybernetics.github.io/astro-theme-university/docs/styling/dark-mode#adding-custom-dark-mode-styles) for details.

## Practical example

A complete brand file, moving the theme to a crimson palette and tightening the
type scale:

```css
/* src/styles/brand.css */
:root {
  --at-primary: #9f1239;
  --at-secondary: #0f766e;
  --at-tertiary: #1d4ed8;

  --at-spacing-lg: 1.25rem;
  --at-spacing-xl: 1.75rem;

  --at-font-size-base: 1rem;
}
```

This keeps customisations separate from the theme: upgrades stay straightforward
because your overrides continue to replace the same tokens.
