Skip to main content

Customisation

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:

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

Import it in your layout after the theme layout:

---
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:

: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: 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.

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

Changing spacing and layout

: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 for details.

Practical example

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

/* 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.