# Scheme data

This directory holds the theme data of the `color-schemes` plugin as typed
TypeScript sources. `lib/client.js` is bundled from `src/client.ts` and this
directory; add or edit schemes here, then run the build script.

```
schemes/
├── README.md          this file
├── types.ts           Palette / SchemeDef / ColorMode types (shared)
├── tokens.ts          compact palette -> ~80 semantic tokens (typed)
├── index.ts           imports every family; import order = menu order
├── catppuccin.ts  everforest.ts  nord.ts
```

## A scheme

```ts
import type { SchemeDef } from "./types.ts";

{
  id: "my-scheme-dark",       // unique id; also the persisted identifier
  colorScheme: "dark",        // "light" | "dark"
  label: { zh: "My Scheme", en: "My Scheme" },  // menu copy
  palette: { ... }            // compact palette, see below
}
```

Scheme names are proper nouns and stay untranslated by default. Set
`label.zh` if you want localized copy. The `SchemeDef` type checks ids,
color modes and complete palettes at compile time; the build script re-checks
the registry at build time.

## Palette fields

`expandTokens(palette, scheme)` derives every `--dsw-*` token from these
fields. Required fields are marked.

| Field | Req | Role |
|---|---|---|
| `bg` | yes | App background (`bg-base`) |
| `bg1` | yes | First raised surface (`bg-layer-1`, sidebar, bubbles) |
| `bg2` | yes | Second raised surface (`bg-layer-2`, code blocks, toast) |
| `bg3` | yes | Third surface / menu / overlay (`bg-layer-3`, `bg-overlay`) |
| `bg4` | yes | Hover fill, selected states |
| `bg5` | yes | Dimmed text surfaces (`label-dimmed`) |
| `muted1` | yes | Darkest neutral (ghost borders, skeleton) |
| `muted2` | yes | Mid neutral (border source, caption) |
| `muted3` | yes | Near-text neutral (tertiary text) |
| `text2` | yes | Secondary text (`label-secondary`) |
| `text` | yes | Primary text; also the rgba source for borders/bars |
| `accent` | yes | Brand accent (links, business states, selection) |
| `accent2` | yes | Primary button fill (CTA) |
| `blue` | yes | Info buttons, blue labels |
| `teal` | yes | Success secondary, info hover |
| `green` | yes | Success states |
| `yellow` | yes | Warning states |
| `orange` | yes | Warning secondary; error-secondary fallback |
| `red` | yes | Error states |
| `redSoft` | no | Soft error secondary; falls back to `orange` then `red` |
| `onAccent` | no | Foreground on the CTA; default: white (light), `bg2` (dark) |
| `sidebar` | no | Sidebar fill; default: `bg1` (light), `bg2` (dark) |

Conventions: background steps darken along
`bg -> bg1 -> bg2`, then `bg3 -> bg4 -> bg5`; text brightens along
`muted1 -> muted2 -> muted3 -> text2 -> text`. Use official palette values
and flatten duplicate steps when a palette lacks them.

Translucent values (borders, hovers, masks) are derived automatically via
`rgba(hex, alpha)` in `tokens.ts`.

## Build

```bash
npm run build
```

The script validates the registry (non-empty, unique ids, labels), type-checks
the sources, expands every palette via the bundled `tokens.ts`, bundles
`src/client.ts` with esbuild, and rewrites `lib/client.js`.

- Only `schemes/` or `src/` changed: rebuild, then refresh the page.
- Package or composition changed: restart `dsh web`.

## Runtime

The selected scheme is stored in localStorage (`dsh.color-schemes.state`).
Default is the first scheme in the registry until a choice is made; the
plugin re-asserts
the choice on theme changes and paints the tokens instantly through a
stylesheet, so the colors are applied at boot and stay applied.

## Built-in schemes

| id | mode |
|---|---|
| `catppuccin-latte / -frappe / -macchiato / -mocha` | light / dark |
| `everforest-dark / -light` | dark / light |
| `nord` | dark |