# Colour

Source: https://material.spynejs.com/foundations/color
Part of: Material shell gallery, Google's Material Design 3 for SpyneJS. Index: https://material.spynejs.com/llms.txt

Material's colour roles. Every colour in the template is one of them, in a light and a dark scheme. A style reads a role by its custom property; a model does not choose colours.

## In an app model

Nothing. A model does not choose colours. Every app on the template has the roles, in both schemes, and the visitor changes the scheme with the button in the header.

## The custom properties

A role is a custom property named `--md-sys-color-` and then the role. A style of your own reads it with `var()`:

```css
.my-note {
  background: var(--md-sys-color-secondary-container);
  color: var(--md-sys-color-on-secondary-container);
}
```

- Content on a fill takes the fill’s own `on-` role: `on-primary` on `primary`, `on-surface` on any surface. That pairing is what keeps text readable in both schemes.
- The page itself is `surface`. A surface set off from the page takes one of five container roles, from `surface-container-lowest` to `surface-container-highest`, each a step further from the page’s own. Content on any of them is `on-surface`; quieter content is `on-surface-variant`.
- Write no colour value by hand. A role changes with the scheme; a typed value does not.
- The roles are set on `main#app`, and again for the dark scheme on `main#app[data-theme='dark']`.
- The Shell’s older names (`--brand`, `--paper`, `--text-muted` and the rest) still work: each is defined from a role.
- Two roles the page does not show: `--md-sys-color-shadow`, the colour of a shadow, and `--md-sys-color-scrim`, the layer behind the open drawer.

## Where it is in the template

| File | What it holds | By name |
| --- | --- | --- |
| `src/scss/00-spynejs-design-system/tokens/_material.scss` | reads Google’s tokens (`@material/web`) at build time; the only file that does |  |
| `src/scss/00-spynejs-design-system/theme/_light.scss` | the light scheme, and every token that does not change with the scheme |  |
| `src/scss/00-spynejs-design-system/theme/_dark.scss` | the dark scheme: only what differs |  |
| `src/scss/00-spynejs-design-system/theme/_bridge.scss` | the Shell’s own variable names, each defined from a role |  |

The template is public: https://github.com/spynejs/application-shell-material. An app made from it has these same files.

## As the page shows it

The page’s own words, in its own order, read from the page as it is drawn in the light colour scheme. They were written for someone looking at the page: “above”, “below” and “marked” mean the drawn page. A thing the page draws is named here in its place (`Button:`, `Field:`, `Switch:`), and a box that reports what the reader does is as it starts, empty. What depends on the reader’s own window is left out.

### Colour roles

Every colour in the template is one of these roles. Each swatch is filled from the role's own custom property, so it is the colour the app is using now; the value beside it is read from the swatch. Change the colour scheme with the button in the header and the values follow.

#### Primary

The app's main colour: the filled button, the focused text field.

| Role | Custom property | Light | Dark |
| --- | --- | --- | --- |
| primary | `--md-sys-color-primary` | #6750a4 | #d0bcff |
| on-primary | `--md-sys-color-on-primary` | #ffffff | #381e72 |
| primary-container | `--md-sys-color-primary-container` | #eaddff | #4f378b |
| on-primary-container | `--md-sys-color-on-primary-container` | #4f378b | #eaddff |

#### Secondary

Less prominent components: the tonal button, the selected destination.

| Role | Custom property | Light | Dark |
| --- | --- | --- | --- |
| secondary | `--md-sys-color-secondary` | #625b71 | #ccc2dc |
| on-secondary | `--md-sys-color-on-secondary` | #ffffff | #332d41 |
| secondary-container | `--md-sys-color-secondary-container` | #e8def8 | #4a4458 |
| on-secondary-container | `--md-sys-color-on-secondary-container` | #4a4458 | #e8def8 |

#### Tertiary

A contrasting accent. The template does not use it yet.

| Role | Custom property | Light | Dark |
| --- | --- | --- | --- |
| tertiary | `--md-sys-color-tertiary` | #7d5260 | #efb8c8 |
| on-tertiary | `--md-sys-color-on-tertiary` | #ffffff | #492532 |
| tertiary-container | `--md-sys-color-tertiary-container` | #ffd8e4 | #633b48 |
| on-tertiary-container | `--md-sys-color-on-tertiary-container` | #633b48 | #ffd8e4 |

#### Error

An invalid field and the line of text under it.

| Role | Custom property | Light | Dark |
| --- | --- | --- | --- |
| error | `--md-sys-color-error` | #b3261e | #f2b8b5 |
| on-error | `--md-sys-color-on-error` | #ffffff | #601410 |
| error-container | `--md-sys-color-error-container` | #f9dedc | #8c1d18 |
| on-error-container | `--md-sys-color-on-error-container` | #8c1d18 | #f9dedc |

#### Surfaces

What everything stands on: the page, the cards, the app bar once the page has scrolled.

| Role | Custom property | Light | Dark |
| --- | --- | --- | --- |
| surface | `--md-sys-color-surface` | #fef7ff | #141218 |
| surface-dim | `--md-sys-color-surface-dim` | #ded8e1 | #141218 |
| surface-bright | `--md-sys-color-surface-bright` | #fef7ff | #3b383e |
| surface-container-lowest | `--md-sys-color-surface-container-lowest` | #ffffff | #0f0d13 |
| surface-container-low | `--md-sys-color-surface-container-low` | #f7f2fa | #1d1b20 |
| surface-container | `--md-sys-color-surface-container` | #f3edf7 | #211f26 |
| surface-container-high | `--md-sys-color-surface-container-high` | #ece6f0 | #2b2930 |
| surface-container-highest | `--md-sys-color-surface-container-highest` | #e6e0e9 | #36343b |

#### Content and lines

Text and icons on a surface, and the lines that divide it.

| Role | Custom property | Light | Dark |
| --- | --- | --- | --- |
| on-surface | `--md-sys-color-on-surface` | #1d1b20 | #e6e0e9 |
| on-surface-variant | `--md-sys-color-on-surface-variant` | #49454f | #cac4d0 |
| outline | `--md-sys-color-outline` | #79747e | #938f99 |
| outline-variant | `--md-sys-color-outline-variant` | #cac4d0 | #49454f |

#### Inverse

The snackbar.

| Role | Custom property | Light | Dark |
| --- | --- | --- | --- |
| inverse-surface | `--md-sys-color-inverse-surface` | #322f35 | #e6e0e9 |
| inverse-on-surface | `--md-sys-color-inverse-on-surface` | #f5eff7 | #322f35 |
| inverse-primary | `--md-sys-color-inverse-primary` | #d0bcff | #6750a4 |
