Skip to content

theme/derive

import { … } from 'zidane-ui'ui/src/theme/derive.ts

Functions#

derivePaletteFunction#

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

TypeScript
function derivePalette(seed: ThemeSeed): ResolvedPalette
Parameters
NameTypeDescription
seedThemeSeed

The colours the theme author chose.

ResolvedPalette

The resolved palette.

ui/src/theme/derive.ts:486

inferAppearanceFunction#

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

TypeScript
function inferAppearance(canvas: string): Appearance
Parameters
NameTypeDescription
canvasstring

The window background colour.

Appearance

The appearance.

ui/src/theme/derive.ts:475

Constants#

CONTRASTConstant#

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.

TypeScript
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 }

ui/src/theme/derive.ts:329

Interfaces#

ChipColorsInterface#

Background and text colour of a reference chip.

TypeScript
interface ChipColors
ChipColors properties
NameTypeDescription
bgstring

Chip background.

fgstring

Chip text colour.

ui/src/theme/derive.ts:197

DiffColorsInterface#

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

TypeScript
interface DiffColors
DiffColors properties
NameTypeDescription
addBgstring

Background of an added line.

addContentBgstring

Stronger background behind the changed text inside an added line.

addFgstring

Text colour of an added line.

removeBgstring

Background of a removed line.

removeContentBgstring

Stronger background behind the changed text inside a removed line.

removeFgstring

Text colour of a removed line.

ui/src/theme/derive.ts:95

DotColorsInterface#

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).

TypeScript
interface DotColors
DotColors properties
NameTypeDescription
accentstring

Dot colour for accent.

accentAltstring

Dot colour for accentAlt.

dangerstring

Dot colour for danger.

infostring

Dot colour for info.

successstring

Dot colour for success.

warnstring

Dot colour for warn.

ui/src/theme/derive.ts:181

ResolvedPaletteInterface#

Every colour role the renderer paints with, derived from a ThemeSeed and checked for contrast against the surfaces it sits on.

TypeScript
interface ResolvedPalette
ResolvedPalette properties
NameTypeDescription
accentstring

Brand and interactive colour, checked for contrast against bg.

accentAltstring

Secondary hue, often a green.

accentFgstring

Text on top of accent-filled controls.

accentFillstring

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).

accentFillFgstring

Text and glyph colour on accentFill.

accentFillHoverstring

Hover state of accentFill, one step deeper.

accentHoverstring

Hover state of accent: brighter in dark, deeper in light.

accentSoftstring

Translucent accent for quiet backgrounds.

accentSoftStrongstring

Stronger translucent accent, for hover on soft backgrounds.

accentWashstring

The sent prompt's bubble: the accent's wash, lighter in light where an alpha tint reads far stronger.

appearanceAppearance

Whether the palette is light or dark.

bgstring

Window background (the canvas).

borderstring

Default border and divider colour.

borderStrongstring

Stronger border, for inputs and emphasis.

chipsRecord<ChipKind, ChipColors>

Reference chip colours, by kind.

codeBgstring

Code block background.

codeFgstring

Code block text, checked for contrast against codeBg.

dangerstring

Danger and error status colour.

dangerFillstring

Solid fill for destructive commits: danger stepped darker like accentFill, so white clears CONTRAST.accentFg on it.

dangerFillFgstring

Text and glyph colour on dangerFill.

dangerFillHoverstring

Hover state of dangerFill, one step deeper.

dangerSoftstring

Translucent danger for backgrounds.

diffDiffColors

Diff colours.

dotsDotColors

Decorative fills for dots, the orb and window lights. They are shapes, not text.

hoverWashstring

Alpha wash for hover on arbitrary surfaces.

infostring

Info status colour.

infoSoftstring

Translucent info for backgrounds.

modelstring

Tint that identifies the model.

moneystring

Colour of cost figures.

ringstring

Focus ring and active rim colour.

scrimstring

Backdrop colour behind modal layers.

selectedstring

Selected row (neutral, no accent tint).

selectionstring

Text selection background.

shadowstring

Base shadow colour.

successstring

Success status colour.

successSoftstring

Translucent success for backgrounds.

surface1string

Elevated surface: sidebar, composer card, code block chrome.

surface2string

Hover / pressed surface.

surface3string

Overlay surface: popovers, menus, modals.

surfacesSurfaceLadder

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.

textstring

Body text.

textMutedstring

Secondary text.

textStrongstring

Primary text where it reads strongest (the sidebar and the inbox in dark).

textSubtlestring

Tertiary text, such as hints.

throbberreadonly [string, string]

The two colours of the busy indicator.

warnstring

Warning status colour.

warnSoftstring

Translucent warn for backgrounds.

ui/src/theme/derive.ts:208

SphereShadingInterface#

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.

TypeScript
interface SphereShading
SphereShading properties
NameTypeDescription
glowstring

Scale of the halo, as a number in a string.

rimstring

How much of tone the bottom rim takes, as a CSS percentage.

shadestring

How much of tone the body's far side takes, as a CSS percentage.

tonestring

Base colour the sphere shades from.

ui/src/theme/derive.ts:164

SurfaceLadderInterface#

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.

TypeScript
interface SurfaceLadder
SurfaceLadder properties
NameTypeDescription
fillSheenstring

Background-image over a solid accent fill: light falling from above.

hairlinestring

Low-contrast edge, only where tone alone can't separate two layers.

overlaystring

Floating surfaces (menus, popovers, palette, modals): above whatever they open from.

raisedstring

A surface set into a tray, or a control lifted off it: the lightest step.

raisedEdgestring

The border of a raised surface: the hairline in dark, softer in light where the shadow draws the edge.

rowHoverstring

Row hover inside any surface: a wash, never a slab.

shadowFillstring

Box-shadow for solid accent fills: top light, bottom edge, a drop tinted by the fill.

shadowFloatstring

Box-shadow for floating surfaces: top light + a deep, soft, layered drop.

shadowInsetstring

Box-shadow for trays and tracks: pressed in from the top.

shadowLivestring

The same, one step up, while a surface is live (a run streaming).

shadowRaisedstring

Box-shadow for raised things: top light + a tight soft drop.

shadowWellstring

Box-shadow for wells: shade under the top edge, a lip of light on the bottom one.

sphereSphereShading

How a small lit sphere (the daemon orb) shades: see SphereShading.

trackstring

A recessed track for grouped controls, set into a raised surface.

traystring

The bed a surface sits in: a soft step toward depth (darker in both modes).

trayRingstring

The ring a raised card sits in (the composer): the tray in dark, a half step in light, so it frames without banding.

wellstring

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.

ui/src/theme/derive.ts:117

ThemeSeedInterface#

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

TypeScript
interface ThemeSeed
ThemeSeed properties
NameTypeDescription
accentstring

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.

canvasstring

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.

ui/src/theme/derive.ts:36

Types#

AppearanceType#

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

TypeScript
type Appearance = 'light' | 'dark'

ui/src/theme/derive.ts:30

ChipKindType#

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

TypeScript
type ChipKind = 'default' | 'skills' | 'files'

ui/src/theme/derive.ts:111