zui TypeScript setup

This project is configured for a minimal TypeScript development workflow.

Theme tokens (light/dark variants)

ZUI exposes color tokens with explicit light/dark variants so you can reference a theme color directly regardless of the current theme. Non-suffixed tokens remain theme-aware and map to the appropriate variant automatically.

• Always-available variants (examples):

  • --surface-light, --surface-dark
  • --text-light, --text-dark
  • --border-light, --border-dark
  • Semantic sets include --secondary(-contrast), --info(-contrast), --success(-contrast), --warning(-contrast), --danger(-contrast) with -light/-dark suffixes.

• Theme-aware base tokens (map automatically):

  • --surface, --text, --border, --primary, --secondary, --info, --success, --warning, --danger
  • These resolve to their -light values by default and switch to -dark in dark mode (via prefers-color-scheme: dark or [data-theme="dark"]).

Recommended usage

• For theme-aware styling (preferred):

  • background: var(--surface);
  • color: var(--text);

• For forcing a specific theme value regardless of current theme:

  • background: var(--surface-dark); // always use dark surface
  • border-color: var(--border-light); // always use light border

• To force the theme for a subtree:

  • Add [data-theme="light"] or [data-theme="dark"] on any container to remap base tokens inside it.

Overriding tokens

You can override base tokens or the variants at any scope. For example, tweak the sticky navbar behavior:

.my-page {
    --zui-nav-sticky-top: 12px;
    --zui-nav-sticky-z: 100;
}

This keeps components configurable purely via CSS, without touching TypeScript.

Built-in themes and guidance

ZUI ships with multiple swappable themes. Use swapZuiTheme(href) at runtime or the demo navbar cycler.

• Base (zui-theme.css): Balanced default with light translucency and neutral palette.
• High Contrast (zui-theme-high-contrast.css): Stronger contrast for readability and accessibility.
• Borderless (zui-theme-borderless.css): Removes borders, relies on elevation; --border-width: 0.
• Soft (zui-theme-soft.css): Pastel look, gentle elevation on buttons, borderless by default.
• Liquid (zui-theme-liquid.css): Fluid, high-blur glass with cool hues and saturated accents.
• Glass (zui-theme-glass.css): Neutral frosted glass aesthetic with balanced translucency.
• Metal (zui-theme-metal.css): Fully opaque—no translucency/backdrop blur; crisp panels.
• Bright (zui-theme-bright.css): Vivid saturated palette with crisp whites and moderate translucency.

Design tips:

• Prefer theme tokens (e.g., --surface, --text) to avoid hard-coding colors.
• For borderless variants, use var(--border-width) in component borders so themes can set 0 cleanly.
• Use elevation (--shadow-*, surface opacity) to separate layers when borders are minimized.

Runtime API:

• getAvailableThemes() returns descriptors of built-in themes (id, href, kind, translucency).
• swapZuiTheme(href) replaces the active theme <link> at runtime.

Scripts

• npm run dev — run the entry file with tsx in watch mode
• npm run typecheck — run the TypeScript type checker without emitting files
• npm run build — compile TypeScript to dist/
• npm start — run compiled JavaScript from dist/

Files

• tsconfig.json — TypeScript compiler configuration
• src/index.ts — example entry with an exported function

Getting started

1. Install dependencies
2. Start in watch mode or build