# Baseline & Dark Mode

Three theme properties decide what your app looks like before you style anything, and what it looks like at night: `baseline`, `darkColors`, and `colorScheme`.

## `baseline`

`baseline` controls whether Sovrium's prebuilt components come with a look attached.

| Value     | Behavior                                                                                                                                                                               |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `extend`  | _(default)_ Components inherit Sovrium's default design-system tokens — cards have a border and shadow, buttons have a fill, form controls have focus rings. Your tokens layer on top. |
| `replace` | Components drop the default look and start from a neutral, unstyled floor. Nothing is prestyled; every surface is yours to define.                                                     |

Start with `extend`. It gets a usable app on screen with a handful of color tokens, and any individual prestyle can still be overridden — an author-supplied `props.className` is appended last, so it wins the Tailwind cascade. Reach for `replace` only when you are building a design system of your own and the defaults are actively in the way.

```yaml
theme:
  baseline: extend
```

## `darkColors`

`darkColors` mirrors the `colors` structure and supplies the values used in dark mode. One theme therefore ships both palettes, and no component needs a `dark:` variant written by hand.

```yaml
theme:
  colors:
    background: '#ffffff'
    surface: '#f8fafc'
    text: '#0f172a'
    muted: '#64748b'
    primary: '#4f46e5'
  darkColors:
    background: '#0f172a'
    surface: '#1e293b'
    text: '#f8fafc'
    muted: '#94a3b8'
    primary: '#818cf8'
```

Only the tokens that need to change have to appear in `darkColors`. A token you leave out keeps its light value in both schemes — correct for a brand accent, and usually wrong for anything with `background` or `text` in the name.

:::callout
**Check contrast in both palettes, not one.** A `primary` tuned against a white background is frequently too dark against a near-black one — which is why the example above lightens it rather than reusing it. The pair is two designs, not one design with the lights off.
:::

## `colorScheme`

`colorScheme` sets which palette a first-time visitor gets, before any preference of theirs is known.

| Value    | First-time visitor sees                                          |
| -------- | ---------------------------------------------------------------- |
| `light`  | The light palette, regardless of their operating system setting. |
| `dark`   | The dark palette, regardless of their operating system setting.  |
| `system` | Whichever their operating system reports.                        |

A visitor who has since made a choice always overrides this — the stored preference wins on every subsequent visit. `colorScheme` is the default, not the policy.

It is applied before the page's content renders, so a dark-first app does not flash a white page on load.

## The Switch

The visitor-facing control is a component, not a theme property: add a [`theme-toggle`](/en/docs/interactive-components) to your header and it writes the stored preference that overrides `colorScheme`.

```yaml
- type: container
  element: header
  props: { className: 'flex items-center justify-between p-4' }
  children:
    - { type: text, tag: strong, content: 'Acme' }
    - { type: theme-toggle }
```

Omit the toggle and the app simply follows `colorScheme` forever — a legitimate choice for a single-palette design.

## Related Pages

- [Theme Overview & Colors](/en/docs/theme) — the `colors` block `darkColors` mirrors.
- [Typography](/en/docs/theme-typography) — type roles, which are scheme-independent.
- [Spacing, Radius & Shadows](/en/docs/theme-spacing) — the remaining token categories.
- [Interactive Components](/en/docs/interactive-components) — the `theme-toggle` component.