# Colors & Fonts

## Colors & Fonts

**Files:** `src/styles/theme.css`, `src/config/fonts.json`, `src/config/config.toml` (`[settings.colorScheme]`) · **Skill level:** Beginner

A rebrand in Plumbo is a handful of values, not a search-and-replace. Every component uses named color tokens, so changing a token changes it everywhere, including the logo mark and the generated social cards. Plumbo has a light palette and a dark palette.

<div class="border border-dark">
  ![Plumbo homepage in dark mode](/images/plumbo/dark-mode.jpg)
</div>

### Where The Colors Live
Open `src/styles/theme.css`. The values are in two blocks:

- `:root { ... }`: the **light** palette (the default)
- `:root.dark { ... }`: the **dark** palette

Each value is a `--theme-*` variable. Components never use hex codes: they use Tailwind classes such as `bg-sage` or `text-primary`, which read these variables. Change a value in both blocks, and keep the variable names.

### The Color Tokens
| Role                         | Variable                 | Light     | Dark      | Tailwind classes              |
| ---------------------------- | ------------------------ | --------- | --------- | ----------------------------- |
| Page background              | `--theme-body`           | `#ffffff` | `#0b1220` | `bg-body`                     |
| Cards and white surfaces     | `--theme-card`           | `#ffffff` | `#0b1220` | `bg-card`                     |
| Cool grey panels (reviews, blog, FAQ rows) | `--theme-sage` | `#f4f6f9` | `#121b2b` | `bg-sage`                |
| Peach tint (icon circles, chips) | `--theme-mint`       | `#fdede4` | `#2a1a12` | `bg-mint`                     |
| Soft peach (service cards, quote card, savings tiles) | `--theme-blush` | `#fff3ec` | `#261811` | `bg-blush`  |
| Warm stone (the main homepage) | `--theme-cream`          | `#f6f2ec` | `#15181d` | `bg-cream`                    |
| **Brand orange block** (stats band, emergency band) | `--theme-deep` | `#cf4510` | `#b23c0e` | `bg-deep`       |
| Navy (dark blocks, dark footers) | `--theme-forest`     | `#0f1e33` | `#08101c` | `bg-forest`                   |
| **Text orange** (links, icons, checks) | `--theme-primary` | `#c2410c` | `#ff8a57` | `text-primary`, `bg-primary` |
| Text orange on hover         | `--theme-primary-hover`  | `#a8380a` | `#ffa47c` | `text-primary-hover`          |
| Text on text orange          | `--theme-on-primary`     | `#ffffff` | `#0b1220` | `text-on-primary`             |
| **Button orange** (main pill buttons) | `--theme-accent` | `#cf4510` | `#cf4510` | `bg-accent`                  |
| Button orange on hover       | `--theme-accent-hover`   | `#b33b0d` | `#e0531b` | `bg-accent-hover`             |
| Text on button orange        | `--theme-on-accent`      | `#ffffff` | `#ffffff` | `text-on-accent`              |
| Darker orange for small accents on white | `--theme-accent-strong` | `#a8380a` | `#ff8a57` | `text-accent-strong` |
| Headings (navy ink)          | `--theme-dark`           | `#0f1b2c` | `#eef2f7` | `text-dark`                   |
| Body text                    | `--theme-text-default`   | `#576173` | `#a6b0bf` | `text-text-default`           |
| Borders and dividers         | `--theme-border-light`   | `#e3e7ed` | `#233046` | `border-border-light`         |
| Form field borders           | `--theme-border-input`   | `#7a8494` | `#6d7889` | `border-border-input`         |
| Focus ring                   | `--theme-focus`          | `#cf4510` | `#ff8a57` | `ring-focus`, `outline-focus` |
| States                       | `--theme-danger`, `--theme-success`, `--theme-warning` | `#b42318`, `#1f7a3a`, `#9a5a00` | `#f2726a`, `#5cc283`, `#f0b44c` | `text-danger`, ... |

`--theme-light` and `--theme-primary-soft` repeat the peach tint, and `--theme-sand` repeats the grey panel. Change them together with `--theme-mint` and `--theme-sage`. Some token names (`sage`, `mint`, `forest`) are kept from older versions: the comment at the top of `theme.css` says what each one is now.

<Aside type="note" title="Two oranges: text orange and button orange">
  Plumbo uses two oranges on purpose. `--theme-accent` (`#cf4510`) fills the
  pill buttons and the brand blocks, where the text is white (4.65:1).
  `--theme-primary` (`#c2410c`) is a little darker and is used for small orange
  text, links, and icons, so it keeps 4.5:1 contrast on white, the grey panels,
  and the peach tint. If you change the brand orange, change both, and keep the
  text orange dark enough to read on `#f4f6f9`.
</Aside>

### Copies To Change With The Palette
A few values appear twice in `theme.css`. Update them with the main tokens:

- **`--page-*` variables** at the end of `:root` and `:root.dark` (`--page-primary`, `--page-dark`, `--page-text`, ...). Cards on a colored block (a white card on the orange block) use them to get the page colors back. Keep them equal to the matching `--theme-*` values.
- **Static helpers** in the `@theme inline` block, which stay the same in light and dark mode: `--color-emerald` and `--color-sunflower` (both `#cf4510`, the brand orange; the names are kept), `--color-mist` (`#fdede4`, white button hover), `--color-light` (`#c3cbd8`, text on the navy footers), and `--color-body-dark` (`#0f1b2c`).
- **The colored blocks** under `@layer components`: `.block-deep` (the orange brand block), `.block-forest` (the navy block), and `.block-coral` (the name is kept: an orange block on `--theme-accent`, with white text). They set the text and border colors used inside each block.
- **`.band-ink`**: the navy ink band, which uses the dark palette inside it.

The `#cf4510` orange also appears in `src/assets/images/favicon.svg` and the two standalone logo files. Regenerate the favicon after a color change (see [Site Identity & Logo](/plumbo/customization/site-identity-logo/#favicons)).

<Aside type="tip" title="Picking a button color">
  The main buttons are orange pills with white text (`--theme-on-accent`). If
  your brand button color is light, such as yellow, set `--theme-on-accent` to
  your ink color, and check the contrast: aim for at least 4.5:1 between text
  and its background.
</Aside>

### Button Styles
Buttons in content files take their look from `variant`:

| You write               | Button                                                       |
| ----------------------- | ------------------------------------------------------------ |
| `variant: "fill"`       | The main pill button: button orange with white text          |
| `variant: "accent"`     | A text-orange pill with white text, for form buttons on light panels. One per view |
| `variant: "soft"`       | A peach pill with ink text for the second action; orange on hover |
| `variant: "outline"`    | An outlined pill                                             |
| `variant: "fill-white"` | A white pill, for photos and colored blocks                  |
| `variant: "text"`       | A text link with an arrow                                    |

The styles are in `src/styles/buttons.css`. Some sections change a variant to fit their background; the comment next to `variant:` in the section file says when. See [Common Changes](/plumbo/customization/common-changes/) for every button option.

### Corners
The radius tokens are in the `@theme inline` block of `theme.css`:

| Token             | Value              | Used for                                      | Class           |
| ----------------- | ------------------ | --------------------------------------------- | --------------- |
| `--radius-btn`    | `9999px` (a pill)  | Buttons and icon buttons                      | `rounded-btn`   |
| `--radius-field`  | `0.625rem` (10 px) | Inputs, selects, segmented controls           | `rounded-field` |
| `--radius-ui`     | `1.5rem` (24 px)   | Cards, tiles, images                          | `rounded-ui`    |
| `--radius-panel`  | `2rem` (32 px)     | Large photos and soft panels                  | `rounded-panel` |
| `--radius-block`  | `2rem` (32 px)     | Color blocks and the footer panel             | `rounded-block` |
| `--radius-tag`    | `0.375rem` (6 px)  | Check squares and rating squares              | `rounded-tag`   |

For square buttons, for example, set `--radius-btn: 0.5rem;`. Plumbo uses no shadows: the shadow scales are reset.

### Fonts
Plumbo uses four fonts from Google Fonts, set in `src/config/fonts.json`, one entry per role:

| Font           | Role                                       | `cssVariable`     |
| -------------- | ------------------------------------------ | ----------------- |
| Figtree        | Body text and forms                        | `--font-primary`  |
| Manrope        | Headings, buttons, and big numbers         | `--font-heading`  |
| JetBrains Mono | Prices, totals, and ticket codes           | `--font-code`     |
| IBM Plex Sans Arabic | Arabic text, loaded only on Arabic pages | `--font-arabic` |

```json
{
  "name": "Manrope",
  "variants": [{ "style": "normal", "weight": "400 700" }],
  "preload": true,
  "display": "swap",
  "cssVariable": "--font-heading",
  "provider": "google",
  "subsets": ["latin"],
  "fallback": "sans-serif"
}
```

To change a font, replace `name` with another Google Font name, exactly as Google writes it (`"DM Sans"`, `"Plus Jakarta Sans"`). Keep `cssVariable`, `provider`, and `fallback`, and keep a `weight` range the new font has: Plumbo ships `"400 700"` for both Manrope and Figtree. Add a subset such as `"latin-ext"` if your language needs it. Then **restart `npm run dev`**: fonts are read only when the server starts.

Astro downloads the fonts and serves them from your own site, so visitors don't load anything from Google.

### Type Sizes
Heading sizes are fluid: they grow from phone to desktop between 375 px and 1280 px wide (`--text-h1` from 36 px to 52 px, `--text-display` from 40 px to 64 px). They are in `theme.css` as `--text-display`, `--text-h1` to `--text-h6`, `--text-stat` (big numbers), `--text-lead`, `--text-copy` (body, 16 px), `--text-label` (small caps labels), and `--text-total` / `--text-total-lg` (prices). Each has a `--line-height`, `--letter-spacing`, and `--font-weight` beside it. Headings use weight 500 with tight letter spacing (`-0.03em` on the display size, `h1`, and `h2`).

### Breakpoints
`sm` 540 px, `md` 768 px, `lg` 1024 px, `xl` 1320 px. The mobile action bar shows below `md`; the full header menu shows from `lg`.

### Dark Mode
```toml
# src/config/config.toml
[settings.colorScheme]
  default  = "light" # system | light | dark: used until a visitor picks one
  switcher = true     # Show the light/dark button in the header, mobile menu, and footer
```

- Plumbo ships with `light`. `system` follows the visitor's device setting, and `light` or `dark` starts every visitor on that palette.
- The sun and moon button switches it. The visitor's choice is remembered in their browser.
- `switcher = false` hides every button. Visitors then always get `default`, and an earlier choice is ignored. Use `switcher = false` with `default = "light"` for a site without dark mode.

When you change colors, check both palettes. Photos and the orange buttons stay the same in dark mode.

### Do It With AI
```text
My brand colors are: main [HEX] and button color [HEX]. In src/styles/theme.css, in :root,
set --theme-deep to my main color, and --theme-primary and --theme-primary-hover to darker
shades of it with at least 4.5:1 contrast on #ffffff and #f4f6f9. Set --theme-accent and
--theme-accent-hover to my button color, and --theme-on-accent to black or white, whichever
contrasts more. Make versions for :root.dark. Update the matching --page-* values,
--color-emerald, and --color-sunflower. Keep every variable name. List the values and their
contrast ratios.
```

```text
Change the heading font to [GOOGLE FONT] and the body font to [GOOGLE FONT] in
src/config/fonts.json. Keep the cssVariable values, the provider, and the fallback, and use
weight ranges the fonts have. Don't edit CSS files. Then tell me to restart npm run dev.
```