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.
function derivePalette(seed: ThemeSeed): ResolvedPaletteParameters
| Name | Type | Description |
|---|---|---|
| seed | ThemeSeed | The colours the theme author chose. |
Returns
ResolvedPaletteThe resolved palette.
inferAppearanceFunction#
Picks the appearance that suits a canvas: dark when its luminance is low, else light.
function inferAppearance(canvas: string): AppearanceParameters
| Name | Type | Description |
|---|---|---|
| canvas | string | The window background colour. |
Returns
AppearanceThe appearance.
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.
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 }Interfaces#
ChipColorsInterface#
Background and text colour of a reference chip.
interface ChipColorsProperties
| Name | Type | Description |
|---|---|---|
| bg | string | Chip background. |
| fg | string | Chip text colour. |
DiffColorsInterface#
Colours of a diff: backgrounds for added and removed lines, a stronger background for the changed text inside them, and the text colours.
interface DiffColorsProperties
| Name | Type | Description |
|---|---|---|
| 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. |
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).
interface DotColorsProperties
| Name | Type | Description |
|---|---|---|
| accent | string | Dot colour for |
| accentAlt | string | Dot colour for |
| danger | string | Dot colour for |
| info | string | Dot colour for |
| success | string | Dot colour for |
| warn | string | Dot colour for |
ResolvedPaletteInterface#
Every colour role the renderer paints with, derived from a ThemeSeed and checked for
contrast against the surfaces it sits on.
interface ResolvedPaletteProperties
| Name | Type | Description |
|---|---|---|
| accent | string | Brand and interactive colour, checked for contrast against |
| accentAlt | string | Secondary hue, often a green. |
| accentFg | string | Text on top of |
| accentFill | string | Solid fill for buttons and markers: the accent, stepped darker along
its own hue until white clears |
| accentFillFg | string | Text and glyph colour on |
| accentFillHover | string | Hover state of |
| accentHover | string | Hover state of |
| accentSoft | string | Translucent |
| accentSoftStrong | string | Stronger translucent |
| 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 |
| danger | string | Danger and error status colour. |
| dangerFill | string | Solid fill for destructive commits: |
| dangerFillFg | string | Text and glyph colour on |
| dangerFillHover | string | Hover state of |
| dangerSoft | string | Translucent |
| 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 |
| 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 |
| 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 |
| 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 |
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.
interface SphereShadingProperties
| Name | Type | Description |
|---|---|---|
| glow | string | Scale of the halo, as a number in a string. |
| rim | string | How much of |
| shade | string | How much of |
| tone | string | Base colour the sphere shades from. |
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.
interface SurfaceLadderProperties
| Name | Type | Description |
|---|---|---|
| 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 |
| 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. |
ThemeSeedInterface#
The few colours a theme author chooses: canvas and accent are required, the rest are
overrides that derivePalette derives when omitted.
interface ThemeSeedProperties
| Name | Type | Description |
|---|---|---|
| accent | string | Brand / interactive hue: buttons, links, focus, selected states. |
| accentAlt? | string | Secondary hue (the TUI's |
| appearance? | Appearance | Forced appearance; inferred from |
| border? | string | Default border and divider colour. |
| borderStrong? | string | Stronger border, for inputs and emphasis. |
| canvas | string | Window background. The only required color besides |
| chips? | Partial<Record<ChipKind, ChipColors>> | Colours of the reference chips, by kind. Any left out come from |
| codeBg? | string | Code block background. Defaults to a step off |
| danger? | string | Danger and error status colour. Pushed until it clears its contrast floor on |
| diff? | Partial<DiffColors> | Diff colours. Any left out are mixed from |
| info? | string | Info status colour. Pushed until it clears its contrast floor on |
| 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 |
| selection? | string | Text selection background. Defaults to a translucent |
| success? | string | Success status colour. Pushed until it clears its contrast floor on |
| surface1? | string | Elevated surface: sidebar, composer card. Derived from |
| surface2? | string | Hover and pressed surface. Derived from |
| surface3? | string | Overlay surface: popovers, menus, modals. Derived from |
| text? | string | Body text. Derived from |
| 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, |
| 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 |
| warn? | string | Warning status colour. Pushed until it clears its contrast floor on |
Types#
AppearanceType#
Whether a palette is built for a light or a dark canvas.
type Appearance = 'light' | 'dark'ChipKindType#
The kind of a reference chip: default, skills or files.
type ChipKind = 'default' | 'skills' | 'files'