[@layout]: ../docs.layout.md

# Theme a site

Give a site its own colors, typeface and type scale, then style one kind of page.

You'll theme a small print studio site that works in light and dark schemes.
Start from an initialized [Quickstart project](../start/first-site.guide.md) and
keep `bun run dev` open to watch each change.

---

## Add a theme stylesheet

Replace `paths/index.md`:

```md
[@layout.default]: ./site.layout.md

# Harbor Print Studio

Weekly open studio for relief, screen and risograph printing.

## Materials

Bring paper you love. Inks, rollers and the press are ready when you arrive.

### Paper weights

Thicker paper takes more pressure.
```

Create `paths/site.layout.md`. It links the theme stylesheet for every page, in
the theme cascade layer:

```md
[@styles.global.theme]: ./styles/theme.css

<header class="studio-header"><a href="/">Harbor Print Studio</a></header>
<main class="studio-main"><x-source-content /></main>
```

---

## Choose colors for both schemes

Create `paths/styles/theme.css`. Pair each color with `light-dark()` so the site
follows the reader's scheme:

```css
:root {
  --pmx-color-bg: light-dark(#f7f3ec, #16181d);
  --pmx-color-fg: light-dark(#1f2430, #ece8e1);
  --pmx-color-muted: light-dark(#5c6170, #a7a39b);
  --pmx-color-surface: light-dark(#efe8dc, #20232a);
  --pmx-color-border: light-dark(#ddd3c4, #363941);
  --pmx-color-accent: light-dark(#b8400c, #fb923c);
  --pmx-color-link: var(--pmx-color-accent);
}
```

The page turns warm paper with burnt-orange links, and charcoal with orange links
when your system uses a dark scheme. To design for one scheme instead, lock it in
the root index; see [Colors and schemes](./themes.reference.md#colors-and-schemes).

---

## Add a heading typeface

Download a variable font with an open license as a `.woff2` file, save it as
`paths/styles/fonts/display.woff2`, and keep its license file beside it. Add to the
top of `theme.css`:

```css
@font-face {
  font-family: "Studio Display";
  src: url("./fonts/display.woff2") format("woff2");
  font-weight: 200 800;
  font-display: swap;
}
```

Then add the heading stack inside the `:root` rule:

```css
  --pmx-font-heading: "Studio Display", var(--pmx-font-body);
```

Headings switch to the new face; body text keeps the system font.

---

## Set the type scale

The default ratio is `1.25`. A print studio can take more contrast; add inside the
same `:root` rule:

```css
  --pmx-prose-scale: 1.333;
```

Every heading level rebalances: on a laptop the title grows to about 3.2 times the
body size, and each level below steps down by the same ratio. Phones use a gentler
ratio derived from it. See
[Heading sizes](./typography.reference.md#heading-sizes) for other ratios.

---

## Space headings and introduce the page

Add after the `:root` rule:

```css
.pmx-heading.level-h2 { margin-block: 2.5rem 0.75rem; }
.level-h1 + p { font-size: 1.25rem; color: var(--pmx-color-muted); }
```

Sections gain room above their headings, and the sentence under the title reads
as an introduction. [Heading blocks](./typography.reference.md#heading-blocks)
explains the markup these rules target.

---

## Style a kind of page

Give events their own layout and stylesheet. Add to `paths/index.md`, below the
first line:

```md
[@layout.event]: ./event.layout.md
```

Create `paths/event.layout.md`:

```md
[@layout]: ./site.layout.md
[@styles]: ./styles/event.css

<article class="studio-event"><x-source-content /></article>
```

Create `paths/styles/event.css`:

```css
.studio-event {
  border-inline-start: 0.35rem solid var(--pmx-color-accent);
  padding-inline-start: 1.25rem;
}
```

Create `paths/events/open-studio.event.md`:

```md
# Open studio night

Drop in to print. Thursday, 6–9 pm.
```

Open `/events/open-studio.event`: it keeps the site's theme and adds an accent rule
beside the content. The home page does not load `event.css`. See
[Style a kind of page](./layouts.reference.md#style-a-kind-of-page) for folder
landing pages.

---

## Check the result

- Switch your system between light and dark schemes and compare text, links and
  focus rings in each.
- Narrow the browser to phone width and confirm nothing scrolls sideways.
- If the site uses [Player](../learning/player.reference.md), check reading, Focus
  and Slides.

## Related

- [Themes](./themes.reference.md)
- [Typography](./typography.reference.md)
- [Stylesheets](./styles.reference.md)
- [Layouts](./layouts.reference.md)