CSS

How CSS is organised in this project, and where to put new styles.

This page covers implementation. For design guidance, see Colours and Typography. For token names and usage patterns, see Tokens.

Where CSS lives

Project CSS lives in /src/styles/, alongside component-scoped styles inside .astro components.

Key files

/src/styles/design-tokens.css – CSS custom properties for colours, typography, spacing, etc.
/src/styles/global.css – base element styles, typography rules, and site-wide defaults.

Design tokens

Tokens are defined as CSS custom properties under :root in design-tokens.css. Use tokens in components instead of hard-coded values.

Examples

color: var(--gloaming);
margin-bottom: var(--space-xl);
transition: opacity var(--transition-fast);

If you need a new token, add it to design-tokens.css so it is available everywhere.

Global styles

Global styles set defaults for typography, headings, links, and baseline layout behaviours. Prefer adjusting global rules only when the change is truly site-wide.

Examples of global rules

Base typography and heading styles
Link styling and hover treatment
Responsive typography variables (via custom properties)

Component styles

Most layout and component-specific styling should live next to the component, inside a <style> block within the relevant .astro file.

Guidelines

Prefer using existing tokens for spacing, colour, and type.
Keep selectors local to the component’s markup.
Only introduce new global selectors when you need a truly shared base pattern.