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

# Stylesheets

Link CSS from a Source or layout to style your site. Use your own classes for your
elements and the shared tokens from [Themes](./themes.reference.md) and
[Typography](./typography.reference.md) for appearance.

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

The path resolves relative to the file containing the import. A layout's styles
accompany pages that use it.

Live updates keep unchanged styles mounted. Editing an authored stylesheet or a
local CSS `@import` refreshes its affected styles. The runtime loads replacements
before applying the new document, preserving the current page if loading fails.
Transient failures retry automatically; a status message also offers **Retry now**.

---

## Stylesheet scope

| Import | Applies to |
| --- | --- |
| `[@styles]: ./styles.css` | This Source, including pages using it as a layout. |
| `[@styles.global]: ./styles.css` | Every page in the site. |
| `[@styles.folder]: ./styles.css` | The declaring folder index and its descendants. |
| `[@styles.folder.theme]: ./theme.css` | That folder subtree, in the theme layer. |
| `[@styles.theme]: ./theme.css` | This Source, in the theme cascade layer. |
| `[@styles.global.theme]: ./theme.css` | Every page, in the theme layer. |

Declare folder styles on the canonical folder index, including typed indexes:

```md
[@styles.folder]: ./work.css
[@styles.folder.print]: ./print.css
```

A `.screen` qualifier similarly limits a stylesheet to screens. Paths resolve
beside the declaring index. Folder styles survive `layout: false` and theme resets.
Ordinary `[@styles]` on an index stays local to that index; use `.folder` deliberately
when descendants should share it. Folder scripts, folder scope on non-index Sources,
and combining `.folder` with `.global` are invalid.

Within the existing CSS layer/media rules, assets are collected global first,
then folder styles from root to nearest index, then the page and its layouts in
existing order. Identical asset/media/layer combinations are included once.
CSS specificity still applies; page CSS does not automatically outrank layout CSS.
Scope follows storage folders, including for named instances and included content.

---

## Cascade layers

Core's cascade layers are `pmx.foundation`, `pmx.plugins`, and `pmx.theme`, in
that order. Unlayered repository styles override layered styles. Use your own
classes for layout and the shared tokens for theme changes. Foundation element
styles also apply inside custom Components. Override them with scoped selectors
in your repository stylesheet, for example `.mentor-card button { ... }`, rather
than depending on internal framework DOM. The document reading measure is
`--pmx-document-measure`; see [Body text](./typography.reference.md#body-text).
Authored CSS updates in place; imported Plugin/server modules restart `pmx dev`.
For a full-width tool, give its Source an appropriate authored layout and set the
reading measure in that layout's stylesheet. Render the tool's own heading inside
the Component when appropriate; do not author a duplicate Markdown heading and
then depend on hiding a framework wrapper. Compiled Blocks and hydrated mounts
add wrappers, so target a class your Component owns instead of a direct-child
selector copied from view-source.

---

## Page types

Every rendered Source is an `<article class="pmx-document">` whose `data-type`
names its Source type. Select `.pmx-document[data-type="artist"]` in a global or
folder stylesheet to style that type wherever it appears, including layout-free
openings and included Sources. For styles that belong to a layout's chrome, link
them from a type layout instead; see
[Style a kind of page](./layouts.reference.md#style-a-kind-of-page).

---

## See a small style change

For a complete named stylesheet and consuming page, try
[Attach styles](../authoring/assets.reference.md#attach-styles). The same theme
border and padding pattern renders here:

<p style="border-inline-start: .25rem solid var(--pmx-color-accent); padding-inline-start: 1rem">
  Bring your observations to the workshop.
</p>

The accent follows the active theme. Put the rule in the linked example's CSS
file when reusing it rather than repeating inline styles on every page.

## Related

- [Theme a site](./theme-a-site.guide.md)
- [Themes](./themes.reference.md)
- [Typography](./typography.reference.md)
- [Layouts](./layouts.reference.md)
- [Shared UI](./ui.reference.md)
- [Build a workshop site](../start/build-a-site.guide.md)