Kovax UI documentation

Component and foundation docs live next to this file. Links are relative to the repository root.

Foundation

• Design tokens — palettes, spacing, typography, motion, z-index, breakpoints. Live gallery: Components → Design tokens on the playground.

Components

Layout

• Box
• Flex
• Grid
• Stack / HStack / VStack
• Center
• Container
• AspectRatio
• Separator
• Bleed
• VisuallyHidden
• Sticky

Typography

• Text
• Heading
• Link
• Code / Kbd
• Blockquote
• List / ListItem
• Avatar — photo / initials / custom fallback (kovax-react/avatar)
• Badge — status / count pills (kovax-react/badge)

Forms

• Form primitives — FormControl, FormLabel, FormError, FormHelperText, FormGroup
• Input
• Textarea
• Checkbox / Radio / Switch
• Select & Combobox
• Date picker — DatePicker, DateRangePicker (react-day-picker + Kovax Popover)
• Tooltip, Dialog, Modal, Toast & Popover

Other

• Tabs — Tabs.Root, Tabs.List, Tabs.Trigger, Tabs.Content
• Accordion & Collapsible — Collapsible.*, Accordion.*
• Alert — inline banner / live region (tone, optional dismiss)
• Progress — LinearProgress, CircularProgress (indeterminate, palettes)
• Table — Table primitives + DataTable (columns/rows, optional sort)
• Button

Guides

• Getting started
• Design system overview

---

Getting started

Install

npm install kovax-react

Install peers if they are not already in your app:

npm install react react-dom

Supported range: React and React DOM >= 16 and < 20 (see peerDependencies in package.json).

Import

ESM and CJS builds are published from the package exports field. Typical import:

import { Box, Button, Input, VStack } from "kovax-react";

Design tokens (objects and the string helper themeToken):

import { colors, sizes, themeToken } from "kovax-react";

Compose with Box

Spacing and layout props are documented on Box. Unknown props are passed to the underlying DOM element (for example data-*, aria-*, id, onClick).

Use ref when you need the native element (focus, measurements):

import { useRef } from "react";
import { Box } from "kovax-react";

const ref = useRef<HTMLDivElement>(null);
return (
  <Box ref={ref} as="div" p={16}>
    Content
  </Box>
);

Next steps

• Design system / tokens
• Component index

---

🎨 Design Tokens

Kovax React ships a typed token system — palettes, spacing, radii, typography, motion, layering, and breakpoints — so every component speaks the same visual language. Tokens are plain objects on top of themeToken("…"), so they work with inline styles, CSS-in-JS, and emit calc-friendly strings (e.g. "1.25rem", "cubic-bezier(...)").

Looking for a visual gallery? Open Components → Design tokens in the live documentation.

📦 Exports

import {
  // Palettes
  colors,
  baseColors,

  // Scales
  sizes,            // { text, spacing, borderRadius }
  fontWeights,
  lineHeights,
  letterSpacings,
  shadows,
  motion,           // { duration, easing }
  transitions,      // legacy composite strings
  zIndices,
  breakpoints,

  // Helpers
  colorToken,
  themeToken,

  // Types
  ColorName,
  ColorShade,
  ColorToken,
  ShadowKey,
  TransitionKey,
  TextSizeKey,
  SizeKey,
  BorderRadiusKey,
  FontWeightKey,
  LineHeightKey,
  LetterSpacingKey,
  DurationKey,
  EasingKey,
  ZIndexKey,
  BreakpointKey,
  ThemeToken,
} from "kovax-react";

🎨 Colors

Five semantic palettes with a 50 → 900 ladder. Use 50–200 for surfaces, 300–500 for accents, and 600–900 for text and active states.

colors.primary[500];   // "#3b82f6"
colors.success[600];   // "#059669"
themeToken("error.50") // "#fef2f2"

Palettes: primary, secondary, success, warning, error.

Base colors

Neutral values outside the palette ladder — useful for contrasting text on accent fills.

import { baseColors } from "kovax-react";

baseColors.white; // "#ffffff"
baseColors.black; // "#000000"

🔤 Typography

sizes.text is the size ramp; fontWeights, lineHeights, letterSpacings are dedicated scales (numbers / em-based strings).

const titleStyle = {
  fontSize: themeToken("text.3xl"),
  fontWeight: themeToken("fontWeight.semibold"),
  lineHeight: themeToken("lineHeight.tight"),
  letterSpacing: themeToken("letterSpacing.tighter"),
};

📏 Spacing

Backwards-compatible rem ladder with none / 2xs / 2xl / 3xl / 4xl / 5xl additions for marketing layouts.

sizes.spacing.xs;   // "0.5rem"
sizes.spacing["2xl"]; // "2.5rem"
themeToken("spacing.none"); // "0rem"

🟦 Border radius

sizes.borderRadius.md;     // "0.5rem"
sizes.borderRadius["2xl"]; // "1.25rem"
sizes.borderRadius.full;   // "9999px"

New: none / xs / xl / 2xl / 3xl. Existing sm / md / lg / full keep their values.

🌫️ Shadows

Elevation ladder with two utility shadows for inset surfaces and focus rings.

shadows.md;         // soft card
shadows["2xl"];     // marketing hero
shadows.inner;      // sunken surfaces
shadows.focusRing;  // 3px blue ring for a11y

⚡ Motion

motion.duration and motion.easing compose into transitions. The legacy transitions object is preserved.

const t = `background-color ${themeToken(
  "duration.fast",
)} ${themeToken("easing.standard")}`;

// Legacy composite (still exported):
themeToken("transition.default");

Durations: instant / fast / normal / slow / slower. Easings: linear / standard / decelerate / accelerate / bounce.

🗂️ Z-index

Predictable stacking order for overlays. Higher value renders above lower one.

zIndices.dropdown; // 1000
zIndices.modal;    // 1400
zIndices.tooltip;  // 1800
themeToken("zIndex.modal"); // "1400"

Ladder: hide < base < docked < dropdown < sticky < banner < overlay < modal < popover < skipLink < toast < tooltip.

🧭 Breakpoints

Em-based viewport breakpoints — they scale with the user's root font size, which is more accessible than rigid px values.

breakpoints.md; // "48em" ≈ 768px

const css = `@media (min-width: ${themeToken("breakpoint.lg")}) { … }`;

🧪 String tokens (themeToken)

One helper for every namespace.

Unknown namespaced keys are returned as-is, so it's safe to feed runtime values through themeToken for fall-through behaviour.

🧩 Types

type ColorName = "primary" | "secondary" | "success" | "warning" | "error";
type ColorShade = 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;

const getColor = (name: ColorName, shade: ColorShade) => colors[name][shade];

ThemeToken unions every accepted dotted string (palette + scale namespaces) so IDEs auto-complete tokens.

🧭 Example: composite card

import { themeToken } from "kovax-react";

export const Card = () => (
  <div
    style={{
      backgroundColor: themeToken("primary.50"),
      border: `1px solid ${themeToken("primary.200")}`,
      borderRadius: themeToken("borderRadius.xl"),
      boxShadow: themeToken("shadow.lg"),
      padding: themeToken("spacing.lg"),
      fontSize: themeToken("text.base"),
      fontWeight: themeToken("fontWeight.medium"),
      lineHeight: themeToken("lineHeight.snug"),
      transition: `box-shadow ${themeToken(
        "duration.normal",
      )} ${themeToken("easing.standard")}`,
    }}
  >
    Hello Kovax
  </div>
);

🧱 Token principles

• Consistency — shared visual language across every component.
• Composability — primitives over presets; themeToken("…") works in inline styles, style objects, or CSS-in-JS.
• Type safety — ThemeToken, ColorToken, ColorName, ColorShade, and the per-scale keys keep autocomplete honest.
• Backwards compatibility — every key added in v0.5+ is additive; previous code keeps working.
• Accessibility-aware — em-based breakpoints and prefers-reduced-motion friendly motion.duration.instant.

---

Design system

Visual language is driven by TypeScript tokens that resolve to CSS custom properties (var(--kx-…)) with a static hex / rem fallback. Mount ThemeProvider once at the app root to enable runtime theming and dark mode; without it every themeToken("…") call falls back to the default palette, so existing apps keep working unchanged.

Theme provider & color mode

import { ThemeProvider, useColorMode } from "kovax-react";

export function App() {
  return (
    <ThemeProvider defaultColorMode="system">
      <Page />
    </ThemeProvider>
  );
}

function ColorModeToggle() {
  const { resolvedColorMode, toggleColorMode } = useColorMode();
  return (
    <button onClick={toggleColorMode}>
      {resolvedColorMode === "dark" ? "Light" : "Dark"}
    </button>
  );
}

• colorMode / defaultColorMode — "light", "dark", "system" (follows prefers-color-scheme).
• palettes={{ light, dark }} — pass partial overrides for brand colors.
• target — a RefObject<HTMLElement> scopes the theme to a subtree instead of :root.
• storageKey — persists the user's choice in localStorage; pass false to disable.
• useColorMode() — { colorMode, resolvedColorMode, setColorMode, toggleColorMode }.
• useTheme() — full context (current palette, scope selector, both palettes).

The provider emits a <style> block with CSS variables on :root and on :root[data-kovax-theme="dark"], so consumers can also style their own surfaces with the same tokens (background: var(--kx-color-secondary-50)).

Tokens

All base scales live in components/Tokens.md. For a live, paginated reference open Components → Design tokens in the playground.

• colors — palettes primary, secondary, success, warning, error (50 → 900 ladder)
• baseColors — neutral white / black
• sizes — spacing (sizes.spacing), typography (sizes.text), radii (sizes.borderRadius)
• fontWeights / lineHeights / letterSpacings — typography refinement scales
• shadows — elevation ladder plus inner and focusRing utilities
• motion — motion.duration.* and motion.easing.* (legacy transitions.* retained)
• zIndices — predictable stacking order for overlays
• breakpoints — em-based viewport breakpoints
• themeToken — string access to every namespace (themeToken("secondary.200"), themeToken("spacing.md"), themeToken("zIndex.modal"), …). Returns var(--kx-…, <fallback>) so values stay correct without ThemeProvider and theme-aware with it.

Import from the package entry:

import {
  colors,
  baseColors,
  sizes,
  fontWeights,
  lineHeights,
  letterSpacings,
  shadows,
  motion,
  transitions,
  zIndices,
  breakpoints,
  themeToken,
  ThemeProvider,
  useColorMode,
  useTheme,
  lightPalette,
  darkPalette,
} from "kovax-react";

Typography

The Text, Heading, Link, Code, Kbd, Blockquote, List, and ListItem components — see Text and sibling files under docs/components/Typography/.

Spacing props

Layout primitives (Box, stacks, grid, etc.) share SpacingProps: margin and padding shorthands (m, p, mx, …), dimensions (w, h, minW, …), flex and grid fields, and common visual props such as backgroundColor and borderRadius. See the Box documentation for the full picture.

Forms and validation

Form field wrappers propagate isInvalid, isRequired, and isDisabled to custom child components only (native elements like <label> are not cloned with those props). See Form components.