Theme & dark mode
Three modes — pick one
Section titled “Three modes — pick one”// 1. Auto (default in v2.7) — follows the OS preference reactively<ThemeProvider mode="auto">{children}</ThemeProvider>
// 2. Pinned dark<ThemeProvider mode="dark">{children}</ThemeProvider>
// 3. Pinned light<ThemeProvider mode="light">{children}</ThemeProvider>mode="auto" reads (prefers-color-scheme: dark) on mount and subscribes
to changes — flipping themes live when the user switches their OS.
Read the system preference imperatively
Section titled “Read the system preference imperatively”import { usePrefersColorScheme } from 'tekivex-ui';
function MyComponent() { const scheme = usePrefersColorScheme(); // "dark" | "light" return <p>You prefer {scheme}.</p>;}Custom themes
Section titled “Custom themes”Built-in: quantumDark (default for dark) and auroraLight (default for
light). Compose your own via createTheme:
import { ThemeProvider, createTheme, quantumDark } from 'tekivex-ui';
const myDark = createTheme(quantumDark, { primary: '#ff00aa', secondary: '#7700ff',});
<ThemeProvider theme={myDark}>{children}</ThemeProvider>createTheme validates every token at runtime — invalid hex throws, and
contrast that fails WCAG AA logs a console warning.
Bring your own tokens
Section titled “Bring your own tokens”Already have a design system? You don’t have to re-declare it as a TekiVex
theme object. Every component paints from var(--tkx-<token>), so the only
thing TekiVex needs is a mapping from its twelve tokens to the colours you
already own. Three ways to supply it, pick whichever fits your stack.
themeFromCSSVars builds a ThemeTokens whose values are var() references
to your custom properties. Anything you don’t map falls back to a base
theme (auroraLight by default — pass quantumDark or your own as the second
argument).
import { ThemeProvider, themeFromCSSVars, quantumDark } from 'tekivex-ui';
const theme = themeFromCSSVars( { bg: '--app-canvas', surface: '--app-card', text: '--app-fg', primary: '--brand-500', danger: '--red-600', }, quantumDark, // base for unmapped tokens + the var() fallback);// theme.primary === 'var(--brand-500, #00f5d4)'
<ThemeProvider theme={theme}>{children}</ThemeProvider>The provider emits --tkx-primary: var(--brand-500, #00f5d4), so components
follow your variable live — including your own dark-mode toggle, because the
colour resolves in CSS, not in JS. Contrast checks are skipped for var()
tokens (the browser is the only one who knows the real colour); a one-time
console.info in development says so. To audit the resolved palette at
runtime, call readThemeFromDOM() — it returns the computed --tkx-* values
in the browser and null on the server.
tekivex-ui/tailwind ships a dependency-free preset that maps Tailwind
utilities onto the same --tkx-* variables, so your markup and TekiVex
components read from one source of truth.
// tailwind.config.js (Tailwind v3, or v4 via @config)import { tekivexPreset } from 'tekivex-ui/tailwind';
export default { presets: [tekivexPreset], content: ['./src/**/*.{ts,tsx}'],};<div className="bg-tkx-surface text-tkx-text border border-tkx-border rounded-tkx-lg shadow-tkx-md"> <TkxButton colorScheme="primary">Same palette, no glue code</TkxButton></div>Colours are tkx-bg, tkx-surface, tkx-surface-alt, tkx-border,
tkx-text, tkx-text-muted, tkx-primary, tkx-secondary, tkx-danger,
tkx-warning, tkx-success, tkx-info. Radii (rounded-tkx-md), shadows
(shadow-tkx-lg) and z-index (z-tkx-modal) come from the exported
radii / shadows / zIndex scales.
Prefer a stylesheet over a provider (or want the variables available before React hydrates)? Render any theme to a CSS block and paste it into your globals:
import { tekivexCssVariables } from 'tekivex-ui/tailwind';import { auroraLight, quantumDark } from 'tekivex-ui';
console.log(tekivexCssVariables(auroraLight));console.log(tekivexCssVariables(quantumDark, { selector: 'html[data-theme="dark"]' }));:root { --tkx-bg: #f8f6f1; --tkx-surface: #ffffff; /* … all twelve tokens, plus --tkx-radius-*, --tkx-shadow-*, --tkx-z-* */}html[data-theme="dark"] { --tkx-bg: #0a0a0f; /* … */}Pass { includeScales: false } for colours only. Tailwind v4 users can drop
the same block inside @theme { … }.
Palette generator
Section titled “Palette generator”Generate a 50–900 colour scale from any hex:
import { generatePalette } from 'tekivex-ui';
const brand = generatePalette('#7b2ff7');// → { 50: '#…', 100: '…', 200: '…', …, 900: '…' }Hooking off the active scheme in CSS
Section titled “Hooking off the active scheme in CSS”Inside the React tree, <html> gets a data-tkx-scheme="dark" (or "light")
attribute. Use that to write scheme-aware CSS:
html[data-tkx-scheme='dark'] .my-element { background: rgba(255, 255, 255, 0.04);}TKX atomic CSS
Section titled “TKX atomic CSS”tkx() and cx() are zero-runtime helpers — atomic class names resolved at
build time:
import { tkx, cx } from 'tekivex-ui';
<div className={cx('p-4 rounded-lg', isActive && tkx('bg-primary text-white'))} />No Tailwind dependency. The generated CSS is tree-shaken to only the atoms you actually use.