# Colors & themes

Color tokens for surfaces, text, borders, accents and feedback, defined for both themes.

Color names express visual presence across both themes. Subtle surfaces recede; prominent surfaces and rules stand out. Each family has a default level under its bare name, such as `--text`; body text uses it, and headings and links use prominent text. Text adds `--text-muted`, one level beyond subtle. Each family exposes only the levels it needs and lists them in this order: default, prominent, subtle, muted.

## Surfaces

Use the default background for the page and content surfaces. Subtle and prominent variants create levels of separation within that palette.

| Token                    | Role                                                                                   |
| ------------------------ | -------------------------------------------------------------------------------------- |
| `--background`           | Default background for the page and content surfaces.                                  |
| `--background-prominent` | Filled controls and contained surfaces: fields, buttons and messages.                  |
| `--background-subtle`    | Hover feedback, current and selected items, and subtle separation such as code blocks. |

## Text

Choose contrast by the text role. Body and interface text use the default text; headings and links use prominent text. Supporting information and metadata have distinct levels.

| Token              | Role                                                           |
| ------------------ | -------------------------------------------------------------- |
| `--text`           | Default body and interface text.                               |
| `--text-prominent` | Prominent text for headings, links and active elements.        |
| `--text-subtle`    | Supporting descriptions, secondary links and subdued controls. |
| `--text-muted`     | Content metadata, muted labels, markers and peripheral notes.  |

The browser suite checks every text level against the three neutral surfaces in both themes; custom surfaces, transparency and overlays need their own contrast check.

## Borders

Color and opacity control the presence of rules; structural classes and components own their geometry.

| Token                | Role                                                         |
| -------------------- | ------------------------------------------------------------ |
| `--border`           | Default borders for frames, dividers and structural markers. |
| `--border-prominent` | Borders and dividers that stand out.                         |
| `--border-subtle`    | Subtle rules, such as code block edges.                      |
| `--border-opacity`   | Shared alpha for all border levels.                          |

The border levels are deliberately faint and do not identify controls. A boundary that must identify a control uses `--text-muted`, which keeps the 3:1 contrast required for a control boundary in both themes; native fields rely on their fill and label instead, as described in [native forms](native-forms.md).

## Accent

Use the accent for interaction states and decorative markers. One pink serves both themes, so the dark theme does not redefine it; its translucent variant and the keyboard focus color derive from it at the root. An app that overrides `--accent` on a nested scope also sets `--accent-subtle` and `--focus` there.

| Token             | Role                                                              |
| ----------------- | ----------------------------------------------------------------- |
| `--accent`        | Accent color for links, active states, focus and section crosses. |
| `--accent-subtle` | Translucent accent background for hover feedback.                 |

## Feedback

Functional colors identify errors, success, warnings and information without changing the gallery accent. Always pair the color with meaningful text; a color alone does not communicate a state.

| Token                | Role                                              |
| -------------------- | ------------------------------------------------- |
| `--feedback-error`   | Validation errors and failed actions.             |
| `--feedback-success` | Completed actions.                                |
| `--feedback-warning` | Conditions requiring attention before continuing. |
| `--feedback-info`    | Informational status, not a decorative highlight. |

The light values favor saturation over contrast and stay below 4.5:1 on light surfaces; the dark values are checked at 4.5:1 against all three neutral surfaces. They are not background fills; colored surfaces and transparent overlays require separate contrast checks. [Native forms](native-forms.md#native-fields-and-feedback) describe how messages carry their tone and semantics.

## Themes

Light is the `:root` default; the toolkit does not follow the system preference. Applying `data-theme="dark"` to `<html>` selects the dark palette; omitted values retain their inherited definitions. [`ThemeToggle`](../components/theme-toggle.md) persists the choice, and `Page` restores it before first paint, so applications need no theme script.

```html
<html lang="en" data-theme="dark">
  <!-- Application document -->
</html>
```