# Design

https://vowel.cc/docs/guides/design

## Themes

Choose a theme in `settings.md`:

```yaml
theme: Default
```

| Theme        | Stylesheets                                                        |
| ------------ | ------------------------------------------------------------------ |
| `Reset`      | A CSS reset                                                        |
| `Typography` | Reset, plus typographic defaults                                   |
| `Default`    | Reset, typography, colours and layout. The theme when none is set. |

The name isn't case-sensitive. A theme applies to its folder and every folder beneath it, so a section can use a different theme from the rest of the site.

## Colours

The Default theme generates a colour scheme from two colours:

```yaml
theme: name: Default colors: ["#5119ff", "#00edc6"]
```

The scheme has eight roles, `primary`, `secondary`, `tertiary`, `accent`, `success`, `info`, `warning` and `danger`, each with ten shades from `--color-<role>-01` (darkest) to `--color-<role>-10` (lightest). Use them in your own CSS:

```css
blockquote { border-color: var(--color-secondary-05); }
```

Without `colors`, the scheme is built from Vowel's own pair. If the colours you give can't make a scheme, the build logs the reason and uses Vowel's pair instead.

Four more settings shape the scheme. Each is a number from 0 to 1:

```yaml
theme: name: Default colors: ["#5119ff", "#00edc6"] darkest-shade: 0.2 contrast: 0.5
```

| Key              | Default | Meaning                                                              |
| ---------------- | ------- | -------------------------------------------------------------------- |
| `darkest-shade`  | 0.3     | The lightness of shade `01`                                          |
| `lightest-shade` | 0.99    | The lightness of shade `10`                                          |
| `min-saturation` | 0.2     | The least saturation any shade may have                              |
| `contrast`       | 0       | Above 0, the shades in between crowd toward the darkest and lightest |

A value that isn't a number from 0 to 1 is logged and ignored, and so are a darkest shade and a lightest shade the wrong way round.

## Typography

The Typography and Default themes compute every heading size, weight and letter spacing from a few numbers. Set any of them under `theme`:

```yaml
theme: name: Default heading-size: 2.5 h1-weight: 900
```

| Key                    | Default | Meaning                                                                                        | CSS variable            |
| ---------------------- | ------- | ---------------------------------------------------------------------------------------------- | ----------------------- |
| `heading-size`         | 1.5     | How much larger `h1` is than body text, as a multiple of it: 1.5 makes `h1` 2.5 times the size | `--fontsize-scale`      |
| `heading-size-decay`   | 3       | Higher makes lower-level headings smaller                                                      | `--fontsize-decay`      |
| `h1-weight`            | 800     | Font weight of `h1`                                                                            | `--fontweight-h1`       |
| `h6-weight`            | 600     | Font weight of `h6`                                                                            | `--fontweight-h6`       |
| `weight-decay`         | 2       | How the weight steps from `h1` down to `h6`                                                    | `--fontweight-decay`    |
| `h1-letter-spacing`    | -0.01   | Letter spacing of `h1`, in `ch`                                                                | `--letterspacing-h1`    |
| `h6-letter-spacing`    | 0       | Letter spacing of `h6`, in `ch`                                                                | `--letterspacing-h6`    |
| `letter-spacing-decay` | 2       | How the spacing steps from `h1` down to `h6`                                                   | `--letterspacing-decay` |

A stylesheet can set the CSS variables instead, with a unit where the setting has one (`-0.02ch`). Set them on `:root`, where the heading sizes are worked out once for the whole page: setting one on another element, such as `article`, changes nothing. To change headings for one page or folder, set them on `:root` in a stylesheet linked only there, with `styles`.

```css
:root { --fontsize-scale: 2; }
```

## Fonts

Vowel ships no fonts; pages use the system font stack. To use your own, add the font files to your project (see [Files](https://vowel.cc/docs/guides/files#heading_fonts)), declare them, and name them in these variables:

```css
@font-face { font-family: "Mona Sans"; src: url("/mona-sans.ttf"); } :root { --fontfamily-sans-brand: "Mona Sans"; }
```

The variables are `--fontfamily-sans-brand`, `--fontfamily-serif-brand` and `--fontfamily-monospace-brand`. Each falls back to the system font stack.

## CSS

A file named `styles.css` is linked from every page in its folder and the folders beneath it. A `styles.css` at the root styles the whole site; `blog/styles.css` styles only the blog.

Any other `.css` file is published, but only linked where you ask for it, with `styles`. In a folder's `settings.md` it applies to the pages in that folder and beneath it; in a page's frontmatter, to that page:

```yaml
styles: - ./gallery.css - /print.css
```

Paths work like every other path: `/print.css` is from the root of the site, and `./gallery.css` is beside the file that names it. A path to a file that isn't in your project is skipped, with a warning.

Every page's `<body>` has a class for each folder it's in and one for the page itself, so a rule can target a whole section or a single page. A page's card in a listing carries the same classes.

The homepage is `page_home`. A post at `/blog/travel/hello-world` has three classes: `folder_blog`, `folder_blog_travel` and `page_blog_travel_hello-world`. A secret folder's class uses its name without the salt.

```css
.folder_blog h1 { font-style: italic; } article.page_about { display: none; }
```

The header's menu, the sidebar, the breadcrumb trail and the table of contents are each a `<nav>`, and each is left out of the page when it would have fewer than two links. The homepage has no breadcrumb trail, and a page with one heading has no table of contents. In the menu and the sidebar, the link to the page you're on has `aria-current=page`, and the links to the folders above it have `aria-current=true`. Each `<li>` has the page class of the page it links to, such as `page_blog_hello-world`, and each `<ul>` that lists a folder has that folder's class, such as `folder_blog`.

A page's slogan, date, description and image are direct children of `<main>`, marked with `itemprop` (`[itemprop="slogan"]`, `[itemprop="date"]`), and so are the date, description and image in each card. Every property from the frontmatter also carries its key as a class: `fm_date`, `fm_description`, `fm_client`.

Theme stylesheets are wrapped in [cascade layers](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer), and yours aren't, so your rules win over the theme's regardless of specificity. There is no need for `!important`.

Your CSS is prefixed for older browsers and minified when it is built. Its link carries a hash of its content, so browsers fetch it again only when it changes.
