UI kit reference

zidane-ui/appearance

import { … } from 'zidane-ui/appearance'ui/src/appearance/index.ts

Components#

`AppearanceProvider`Component#

Applies the host's appearance to the document and provides it to the hooks below: the active theme and palette, contrast, accent, fonts, the code theme and the motion policy.

TypeScript

function AppearanceProvider(props: AppearanceProviderProps): Element

Parameters

Parameters
Name	Type	Description
props	`AppearanceProviderProps`	See `AppearanceProviderProps`.

Returns

Element

Props

AppearanceProvider props
Name	Type	Description
children	`ReactNode`	The app.
extensions?	`ExtensionsHost`	The extensions host: its `Theme` items are offered too, after the host's own extra themes. One theme id shows once (the appearance host's copy wins: zidane's registry serves extension themes through `host.themes` as well). `AppHostProvider` passes `AppHost.extensions`.
folder?	`string \| null`	The folder whose extra themes are offered (`host.themes`). Without one, the last folder's stay.
host	`AppearanceHost`	Where the preferences live, the extra themes, the snapshot and the window effects.
legacyThemeId?	`string`	A theme id from elsewhere (zidane's shared `Settings.theme`), read once on the first run to seed the pairing.
motion?	`boolean`	Puts the tree under the motion preferences (`MotionProvider`, which writes `html[data-motion]`). Default: true.
root?	`HTMLElement`	Where the theme vars go. Default: `<html>`. Elsewhere, no snapshot is written and the window is left alone.
themesKey?	`string`	Changes when the folder's themes may have changed (its enabled extensions): they are read again.

ui/src/appearance/AppearanceProvider.tsx:117

Functions#

`applyPalette`Function#

Applies palette and contrast to the document. Toggles .light / .dark on the root (UnoCSS dark: and color-scheme key off them); a root other than <html> also gets .zg-theme-scope, so the derived tokens (--zg-text, --zg-tray…) resolve against its own vars instead of the page's. Suppresses transitions for one frame, so a theme swap snaps instead of cross-fading every surface at a different speed. Values equal to the last ones written are a no-op.

TypeScript

function applyPalette(options: ApplyPaletteOptions): void

Parameters

Parameters
Name	Type	Description
options	`ApplyPaletteOptions`	The palette, contrast, extra vars, root and snapshot sink.

ui/src/appearance/apply.ts:35

`codeThemesOf`Function#

The bundled code themes of one appearance, sorted by display name.

TypeScript

function codeThemesOf(type: Appearance): { id: CodeThemeId; name: string }[]

Parameters

Parameters
Name	Type	Description
type	`Appearance`	`'light'` or `'dark'`.

Returns

{ id: CodeThemeId; name: string }[]

ui/src/code/code-themes.ts:183

`codeThemeTypeOf`Function#

The appearance a bundled code theme is made for.

TypeScript

function codeThemeTypeOf(id: string): Appearance | undefined

Parameters

Parameters
Name	Type	Description
id	`string`	A code theme id, such as `nord`.

Returns

Appearance | undefined

'light' or 'dark', or undefined when id is not a bundled theme.

ui/src/code/code-themes.ts:174

`resolveCodeTheme`Function#

The code theme code renders with: the pick for the current appearance, else ('auto', or a pick that is not a bundled theme of that appearance) the app theme's mapping.

TypeScript

function resolveCodeTheme(
  choice: CodeThemeChoice,
  themeId: string,
  appearance: Appearance,
): CodeThemeId

Parameters

Parameters
Name	Type	Description
choice	`CodeThemeChoice`	The code theme per appearance.
themeId	`string`	The active app theme.
appearance	`Appearance`	The active appearance.

Returns

CodeThemeId

ui/src/appearance/AppearanceProvider.tsx:52

`useAppearance`Function#

The appearance state and its setters. Outside an AppearanceProvider the setters do nothing.

TypeScript

function useAppearance(): AppearanceApi

Returns

AppearanceApi

ui/src/appearance/AppearanceProvider.tsx:258

`useAppearanceHost`Function#

The host from the nearest AppearanceProvider, or null outside one.

TypeScript

function useAppearanceHost(): AppearanceHost | null

Returns

AppearanceHost | null

ui/src/appearance/AppearanceProvider.tsx:218

`useAppearanceMotion`Function#

The motion level the preferences resolve to (system follows the OS).

TypeScript

function useAppearanceMotion(): 'off' | 'reduced' | 'full'

Returns

'off' | 'reduced' | 'full'

ui/src/appearance/AppearanceProvider.tsx:228

`useAppearanceReducedMotion`Function#

True for off and reduced: skip decorative JS-driven animation.

TypeScript

function useAppearanceReducedMotion(): boolean

Returns

boolean

ui/src/appearance/AppearanceProvider.tsx:233

`useAppearanceState`Function#

The stored preferences (DEFAULT_APPEARANCE outside an AppearanceProvider).

TypeScript

function useAppearanceState(): AppearanceState

Returns

AppearanceState

ui/src/appearance/AppearanceProvider.tsx:223

`useColors`Function#

The active theme's colors.

TypeScript

function useColors(): ThemeColors

Returns

ThemeColors

ui/src/appearance/AppearanceProvider.tsx:203

`useOsReducedMotion`Function#

Whether the OS asks for reduced motion, followed live. False on the server.

TypeScript

function useOsReducedMotion(): boolean

Returns

boolean

ui/src/appearance/AppearanceProvider.tsx:299

`usePalette`Function#

The active derived palette.

TypeScript

function usePalette(): ResolvedPalette

Returns

ResolvedPalette

ui/src/appearance/AppearanceProvider.tsx:208

`useShikiTheme`Function#

The theme for code right now: the code theme pick for the current appearance, else the app theme's.

TypeScript

function useShikiTheme(): CodeThemeId

Returns

CodeThemeId

ui/src/appearance/AppearanceProvider.tsx:213

`useTheme`Function#

The active theme (the default theme outside an AppearanceProvider).

TypeScript

function useTheme(): Theme

Returns

Theme

ui/src/appearance/AppearanceProvider.tsx:198

Interfaces#

`AppearanceApi`Interface#

The appearance state and its setters, for a settings panel.

TypeScript

interface AppearanceApi

Properties

AppearanceApi properties
Name	Type	Description
activeThemeId	`string`	The active theme's id.
appearance	`Appearance`	The active appearance.
availableThemes	`readonly Theme[]`	Every theme selectable right now (built-in and the host's extra ones).
pickTheme	`(theme: Theme) => void`	Assigns a theme to the slot its own appearance implies (light theme → light slot).
reset	`() => void`	Back to the defaults.
set	`(update: Partial<AppearanceState>) => void`	Merges a change into the preferences.
setMode	`(mode: AppearanceMode) => void`	Sets the mode.
state	`AppearanceState`	The stored preferences.

ui/src/appearance/AppearanceProvider.tsx:238

`AppearanceProviderProps`Interface#

Props for AppearanceProvider.

TypeScript

interface AppearanceProviderProps

Properties

AppearanceProviderProps properties
Name	Type	Description
children	`ReactNode`	The app.
extensions?	`ExtensionsHost`	The extensions host: its `Theme` items are offered too, after the host's own extra themes. One theme id shows once (the appearance host's copy wins: zidane's registry serves extension themes through `host.themes` as well). `AppHostProvider` passes `AppHost.extensions`.
folder?	`string \| null`	The folder whose extra themes are offered (`host.themes`). Without one, the last folder's stay.
host	`AppearanceHost`	Where the preferences live, the extra themes, the snapshot and the window effects.
legacyThemeId?	`string`	A theme id from elsewhere (zidane's shared `Settings.theme`), read once on the first run to seed the pairing.
motion?	`boolean`	Puts the tree under the motion preferences (`MotionProvider`, which writes `html[data-motion]`). Default: true.
root?	`HTMLElement`	Where the theme vars go. Default: `<html>`. Elsewhere, no snapshot is written and the window is left alone.
themesKey?	`string`	Changes when the folder's themes may have changed (its enabled extensions): they are read again.

ui/src/appearance/AppearanceProvider.tsx:88

`ApplyPaletteOptions`Interface#

Options of applyPalette.

TypeScript

interface ApplyPaletteOptions

Properties

ApplyPaletteOptions properties
Name	Type	Description
boot?	`(snapshot: BootSnapshot) => void`	Stores the pre-paint snapshot after a write (`AppearanceHost.boot.write`).
contrast?	`number`	50..200, default 100.
extraVars?	`Record<string, string>`	Extra vars applied in the same frame (fonts) and included in the snapshot.
palette	`ResolvedPalette`	The derived palette.
root?	`HTMLElement`	Where the vars go. Default: `<html>`.

ui/src/appearance/apply.ts:11

Types#

`CodeTheme`Type#

A bundled code theme id, what the highlighters take.

TypeScript

type CodeTheme = ReturnType<typeof shikiThemeFor>

ui/src/appearance/AppearanceProvider.tsx:42

Components#

AppearanceProviderComponent#

Parameters

Returns

Props

Functions#

applyPaletteFunction#

Parameters

codeThemesOfFunction#

Parameters

Returns

codeThemeTypeOfFunction#

Parameters

Returns

resolveCodeThemeFunction#

Parameters

Returns

useAppearanceFunction#

Returns

useAppearanceHostFunction#

Returns

useAppearanceMotionFunction#

Returns

useAppearanceReducedMotionFunction#

Returns

useAppearanceStateFunction#

Returns

useColorsFunction#

Returns

useOsReducedMotionFunction#

Returns

usePaletteFunction#

Returns

useShikiThemeFunction#

Returns

useThemeFunction#

Returns

Interfaces#

AppearanceApiInterface#

Properties

AppearanceProviderPropsInterface#

Properties

ApplyPaletteOptionsInterface#

Properties

Types#

CodeThemeType#

`AppearanceProvider`Component#

`applyPalette`Function#

`codeThemesOf`Function#

`codeThemeTypeOf`Function#

`resolveCodeTheme`Function#

`useAppearance`Function#

`useAppearanceHost`Function#

`useAppearanceMotion`Function#

`useAppearanceReducedMotion`Function#

`useAppearanceState`Function#

`useColors`Function#

`useOsReducedMotion`Function#

`usePalette`Function#

`useShikiTheme`Function#

`useTheme`Function#

`AppearanceApi`Interface#

`AppearanceProviderProps`Interface#

`ApplyPaletteOptions`Interface#

`CodeTheme`Type#