# theme/derive (zidane-ui)

Import: `import { … } from 'zidane-ui'`. Source: [ui/src/theme/derive.ts](https://github.com/Tahul/zidane/blob/main/ui/src/theme/derive.ts).

## Functions

### `derivePalette`

Function.

Derives a complete, contrast-checked palette from a seed. Anything the seed leaves out is
computed from `canvas` and `accent`. Pure, with no DOM.

```ts
function derivePalette(seed: ThemeSeed): ResolvedPalette
```

**Parameters**

- `seed` (`ThemeSeed`): The colours the theme author chose.

**Returns** `ResolvedPalette`: The resolved palette.

Source: [ui/src/theme/derive.ts:486](https://github.com/Tahul/zidane/blob/main/ui/src/theme/derive.ts#L486)

### `inferAppearance`

Function.

Picks the appearance that suits a canvas: `dark` when its luminance is low, else `light`.

```ts
function inferAppearance(canvas: string): Appearance
```

**Parameters**

- `canvas` (`string`): The window background colour.

**Returns** `Appearance`: The appearance.

Source: [ui/src/theme/derive.ts:475](https://github.com/Tahul/zidane/blob/main/ui/src/theme/derive.ts#L475)

## Constants

### `CONTRAST`

Constant.

Minimum contrast targets. Body text follows WCAG AA (4.5); muted/subtle
relax on purpose. Text on accent-filled controls and chips uses the WCAG
UI-component threshold (3.0): it keeps white labels on bright accents,
which every platform button does, instead of flipping to dark text.

```ts
const CONTRAST: { readonly accentFg: 3; readonly diffFg: 4; readonly dot: 1.5; readonly status: 3; readonly text: 4.5; readonly textMuted: 3.4; readonly textSubtle: 2.2 }
```

Source: [ui/src/theme/derive.ts:329](https://github.com/Tahul/zidane/blob/main/ui/src/theme/derive.ts#L329)

## Interfaces

### `ChipColors`

Interface.

Background and text colour of a reference chip.

```ts
interface ChipColors
```

**Properties**

- `bg` (`string`): Chip background.
- `fg` (`string`): Chip text colour.

Source: [ui/src/theme/derive.ts:197](https://github.com/Tahul/zidane/blob/main/ui/src/theme/derive.ts#L197)

### `DiffColors`

Interface.

Colours of a diff: backgrounds for added and removed lines, a stronger background for the
changed text inside them, and the text colours.

```ts
interface DiffColors
```

**Properties**

- `addBg` (`string`): Background of an added line.
- `addContentBg` (`string`): Stronger background behind the changed text inside an added line.
- `addFg` (`string`): Text colour of an added line.
- `removeBg` (`string`): Background of a removed line.
- `removeContentBg` (`string`): Stronger background behind the changed text inside a removed line.
- `removeFg` (`string`): Text colour of a removed line.

Source: [ui/src/theme/derive.ts:95](https://github.com/Tahul/zidane/blob/main/ui/src/theme/derive.ts#L95)

### `DotColors`

Interface.

Decorative fills: dots, the orb, window lights, badge pips. Colour that
is a shape, not text, so it isn't held to the text floors the status
tokens carry. Dark: the status colour itself (already bright). Light: the
same hue lifted to a vivid, light-appropriate tone (see `dotFor`).

```ts
interface DotColors
```

**Properties**

- `accent` (`string`): Dot colour for `accent`.
- `accentAlt` (`string`): Dot colour for `accentAlt`.
- `danger` (`string`): Dot colour for `danger`.
- `info` (`string`): Dot colour for `info`.
- `success` (`string`): Dot colour for `success`.
- `warn` (`string`): Dot colour for `warn`.

Source: [ui/src/theme/derive.ts:181](https://github.com/Tahul/zidane/blob/main/ui/src/theme/derive.ts#L181)

### `ResolvedPalette`

Interface.

Every colour role the renderer paints with, derived from a [`ThemeSeed`](https://zidane.si/docs/reference/ui-theme-derive.md#ThemeSeed) and checked for
contrast against the surfaces it sits on.

```ts
interface ResolvedPalette
```

**Properties**

- `accent` (`string`): Brand and interactive colour, checked for contrast against `bg`.
- `accentAlt` (`string`): Secondary hue, often a green.
- `accentFg` (`string`): Text on top of `accent`-filled controls.
- `accentFill` (`string`): Solid fill for buttons and markers: the accent, stepped darker along
  its own hue until white clears `CONTRAST.accentFg` on it, so glyphs on
  filled controls are white on every theme. Text-on-canvas keeps
  `accent` (contrast is checked against the background there).
- `accentFillFg` (`string`): Text and glyph colour on `accentFill`.
- `accentFillHover` (`string`): Hover state of `accentFill`, one step deeper.
- `accentHover` (`string`): Hover state of `accent`: brighter in dark, deeper in light.
- `accentSoft` (`string`): Translucent `accent` for quiet backgrounds.
- `accentSoftStrong` (`string`): Stronger translucent `accent`, for hover on soft backgrounds.
- `accentWash` (`string`): The sent prompt's bubble: the accent's wash, lighter in light where an alpha tint reads far stronger.
- `appearance` (`Appearance`): Whether the palette is light or dark.
- `bg` (`string`): Window background (the canvas).
- `border` (`string`): Default border and divider colour.
- `borderStrong` (`string`): Stronger border, for inputs and emphasis.
- `chips` (`Record<ChipKind, ChipColors>`): Reference chip colours, by kind.
- `codeBg` (`string`): Code block background.
- `codeFg` (`string`): Code block text, checked for contrast against `codeBg`.
- `danger` (`string`): Danger and error status colour.
- `dangerFill` (`string`): Solid fill for destructive commits: `danger` stepped darker like `accentFill`, so white clears `CONTRAST.accentFg` on it.
- `dangerFillFg` (`string`): Text and glyph colour on `dangerFill`.
- `dangerFillHover` (`string`): Hover state of `dangerFill`, one step deeper.
- `dangerSoft` (`string`): Translucent `danger` for backgrounds.
- `diff` (`DiffColors`): Diff colours.
- `dots` (`DotColors`): Decorative fills for dots, the orb and window lights. They are shapes, not text.
- `hoverWash` (`string`): Alpha wash for hover on arbitrary surfaces.
- `info` (`string`): Info status colour.
- `infoSoft` (`string`): Translucent `info` for backgrounds.
- `model` (`string`): Tint that identifies the model.
- `money` (`string`): Colour of cost figures.
- `ring` (`string`): Focus ring and active rim colour.
- `scrim` (`string`): Backdrop colour behind modal layers.
- `selected` (`string`): Selected row (neutral, no accent tint).
- `selection` (`string`): Text selection background.
- `shadow` (`string`): Base shadow colour.
- `success` (`string`): Success status colour.
- `successSoft` (`string`): Translucent `success` for backgrounds.
- `surface1` (`string`): Elevated surface: sidebar, composer card, code block chrome.
- `surface2` (`string`): Hover / pressed surface.
- `surface3` (`string`): Overlay surface: popovers, menus, modals.
- `surfaces` (`SurfaceLadder`): The surface ladder (canvas → tray → raised) and its edges. Separation
  comes from tone and light, not outlines; each appearance derives it its
  own way (see `SURFACE`). `.zg-tray` / `.zg-raised` / `.zg-segment` in
  styles/primitives.css are the only consumers components should need.
- `text` (`string`): Body text.
- `textMuted` (`string`): Secondary text.
- `textStrong` (`string`): Primary text where it reads strongest (the sidebar and the inbox in dark).
- `textSubtle` (`string`): Tertiary text, such as hints.
- `throbber` (`readonly [string, string]`): The two colours of the busy indicator.
- `warn` (`string`): Warning status colour.
- `warnSoft` (`string`): Translucent `warn` for backgrounds.

Source: [ui/src/theme/derive.ts:208](https://github.com/Tahul/zidane/blob/main/ui/src/theme/derive.ts#L208)

### `SphereShading`

Interface.

A lit sphere's shading, per appearance. Dark shades toward black, deep;
light shades toward a cool slate, shallow, so a vivid fill stays vivid
instead of turning to mud. `shade` / `rim` are how much of `tone` the
body's far side and its bottom rim take; `glow` scales the halo.

```ts
interface SphereShading
```

**Properties**

- `glow` (`string`): Scale of the halo, as a number in a string.
- `rim` (`string`): How much of `tone` the bottom rim takes, as a CSS percentage.
- `shade` (`string`): How much of `tone` the body's far side takes, as a CSS percentage.
- `tone` (`string`): Base colour the sphere shades from.

Source: [ui/src/theme/derive.ts:164](https://github.com/Tahul/zidane/blob/main/ui/src/theme/derive.ts#L164)

### `SurfaceLadder`

Interface.

The surface ladder from canvas to tray to raised to overlay: its tones, edges, shadows and
sphere shading. Each appearance derives it its own way.

```ts
interface SurfaceLadder
```

**Properties**

- `fillSheen` (`string`): Background-image over a solid accent fill: light falling from above.
- `hairline` (`string`): Low-contrast edge, only where tone alone can't separate two layers.
- `overlay` (`string`): Floating surfaces (menus, popovers, palette, modals): above whatever they open from.
- `raised` (`string`): A surface set into a tray, or a control lifted off it: the lightest step.
- `raisedEdge` (`string`): The border of a raised surface: the hairline in dark, softer in light where the shadow draws the edge.
- `rowHover` (`string`): Row hover inside any surface: a wash, never a slab.
- `shadowFill` (`string`): Box-shadow for solid accent fills: top light, bottom edge, a drop tinted by the fill.
- `shadowFloat` (`string`): Box-shadow for floating surfaces: top light + a deep, soft, layered drop.
- `shadowInset` (`string`): Box-shadow for trays and tracks: pressed in from the top.
- `shadowLive` (`string`): The same, one step up, while a surface is live (a run streaming).
- `shadowRaised` (`string`): Box-shadow for raised things: top light + a tight soft drop.
- `shadowWell` (`string`): Box-shadow for wells: shade under the top edge, a lip of light on the bottom one.
- `sphere` (`SphereShading`): How a small lit sphere (the daemon orb) shades: see `SphereShading`.
- `track` (`string`): A recessed track for grouped controls, set into a raised surface.
- `tray` (`string`): The bed a surface sits in: a soft step toward depth (darker in both modes).
- `trayRing` (`string`): The ring a raised card sits in (the composer): the tray in dark, a half step in light, so it frames without banding.
- `well` (`string`): Input wells: a translucent shade, so the field is carved into whatever it
  sits on (canvas, tray or raised card) instead of carrying an absolute tone
  that only reads on one of them.

Source: [ui/src/theme/derive.ts:117](https://github.com/Tahul/zidane/blob/main/ui/src/theme/derive.ts#L117)

### `ThemeSeed`

Interface.

The few colours a theme author chooses: `canvas` and `accent` are required, the rest are
overrides that `derivePalette` derives when omitted.

```ts
interface ThemeSeed
```

**Properties**

- `accent` (`string`): Brand / interactive hue: buttons, links, focus, selected states.
- `accentAlt?` (`string`): Secondary hue (the TUI's `accent`; success green in most themes).
- `appearance?` (`Appearance`): Forced appearance; inferred from `canvas` luminance when omitted.
- `border?` (`string`): Default border and divider colour.
- `borderStrong?` (`string`): Stronger border, for inputs and emphasis.
- `canvas` (`string`): Window background. The only required color besides `accent`.
- `chips?` (`Partial<Record<ChipKind, ChipColors>>`): Colours of the reference chips, by kind. Any left out come from `accent` and `model`.
- `codeBg?` (`string`): Code block background. Defaults to a step off `canvas`.
- `danger?` (`string`): Danger and error status colour. Pushed until it clears its contrast floor on `canvas` and the active row.
- `diff?` (`Partial<DiffColors>`): Diff colours. Any left out are mixed from `canvas` and the status colours.
- `info?` (`string`): Info status colour. Pushed until it clears its contrast floor on `canvas` and the active row.
- `model?` (`string`): Model-identity tint.
- `money?` (`string`): Colour of cost figures. Defaults to the muted text colour.
- `ring?` (`string`): Focus ring / active rim. Defaults to `accent`.
- `selection?` (`string`): Text selection background. Defaults to a translucent `accent`.
- `success?` (`string`): Success status colour. Pushed until it clears its contrast floor on `canvas` and the active row.
- `surface1?` (`string`): Elevated surface: sidebar, composer card. Derived from `canvas` when omitted.
- `surface2?` (`string`): Hover and pressed surface. Derived from `canvas` when omitted.
- `surface3?` (`string`): Overlay surface: popovers, menus, modals. Derived from `canvas` when omitted.
- `text?` (`string`): Body text. Derived from `canvas` with a faint tint when omitted.
- `textMuted?` (`string`): Secondary text. Pushed until it clears its contrast floor.
- `textStrong?` (`string`): Primary text where it reads strongest (the sidebar and the inbox in dark). Defaults to white in dark, `text` in light.
- `textSubtle?` (`string`): Tertiary text, such as hints. Pushed until it clears its contrast floor.
- `throbber?` (`readonly [string, string]`): The two colours of the busy indicator. Defaults to `accent` and a muted `accentAlt`.
- `warn?` (`string`): Warning status colour. Pushed until it clears its contrast floor on `canvas` and the active row.

Source: [ui/src/theme/derive.ts:36](https://github.com/Tahul/zidane/blob/main/ui/src/theme/derive.ts#L36)

## Types

### `Appearance`

Type.

Whether a palette is built for a `light` or a `dark` canvas.

```ts
type Appearance = 'light' | 'dark'
```

Source: [ui/src/theme/derive.ts:30](https://github.com/Tahul/zidane/blob/main/ui/src/theme/derive.ts#L30)

### `ChipKind`

Type.

The kind of a reference chip: `default`, `skills` or `files`.

```ts
type ChipKind = 'default' | 'skills' | 'files'
```

Source: [ui/src/theme/derive.ts:111](https://github.com/Tahul/zidane/blob/main/ui/src/theme/derive.ts#L111)