Forem: Aleksey Alekseev

kovax-react 0.8: Tailwind v4 preset, FormField adapters, ColorModeScript, and Storybook

Aleksey Alekseev — Mon, 25 May 2026 17:54:19 +0000

kovax-react 0.8.0 is on npm. This release connects Kovax to the wider ecosystem: Tailwind CSS v4 utilities backed by --kx-* tokens, thin form adapters for popular libraries, a FOUC guard for theme mode, and a Storybook catalog beside the existing playground.

📦 npm: kovax-react@0.8.0
🧑‍💻 Repo: github.com/MrKamura/kovax
🧪 Playground: mrkamura.github.io/kovax
📖 Storybook: mrkamura.github.io/kovax/storybook

TL;DR — everything since 0.7.0

Area	What shipped
Tailwind v4	`kovax-react/tailwind` — generated `@theme inline` preset; `bg-kx-primary-500`, `p-kx-md`, `rounded-kx-md`, …
Forms	`kovax-react/react-hook-form`, `kovax-react/tanstack-form` — `FormField`, `FormFieldError`, ref/value injection
Theme / FOUC	`ColorModeScript` (Chakra-style), `buildColorModeInitScript`, shared *`KOVAX_`** constants
Storybook	autoDocs, `@storybook/addon-a11y`, Visual Tests; deployed to `/storybook` on GitHub Pages
Docs	`TAILWIND.md`, updated `Form.md`, `QUICK_START.md`, `RELEASES.md`

npm install kovax-react@0.8.0

Optional peers: react-hook-form, @tanstack/react-form, Tailwind v4.

Tailwind v4 — theme-reactive utilities

Kovax components already use ThemeProvider and var(--kx-…). 0.8 exports a Tailwind v4 preset so utility classes read the same variables:

@import "tailwindcss";
@import "kovax-react/tailwind";

<div className="bg-kx-primary-500 text-kx-base-white p-kx-md rounded-kx-md shadow-kx-sm">
  Kovax tokens in Tailwind
</div>

Why @theme inline: utilities resolve var(--kx-…) at use-site — light/dark palette swaps from ThemeProvider stay reactive.

Kovax token	Example utility
`--kx-color-primary-500`	`bg-kx-primary-500`
`--kx-spacing-md`	`p-kx-md`, `gap-kx-lg`
`--kx-radius-md`	`rounded-kx-md`
`--kx-text-lg`	`text-kx-lg`

Mix with Kovax components:

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

<Box className="border border-kx-secondary-200 bg-kx-secondary-50 p-kx-lg">
  <Button variant="solid" color="primary">Submit</Button>
</Box>

Guide: TAILWIND.md.

FormField adapters

FormControl context ( isInvalid, isRequired, isDisabled ) now wires automatically from form libraries.

react-hook-form

import { useForm } from "react-hook-form";
import { FormField, FormFieldError } from "kovax-react/react-hook-form";
import { FormControl, FormLabel, Input, Button, VStack } from "kovax-react";

type Values = { email: string };

export function SignIn() {
  const { control, handleSubmit } = useForm<Values>();

  return (
    <form onSubmit={handleSubmit(console.log)}>
      <VStack gap={16} align="stretch">
        <FormField control={control} name="email" rules={{ required: true }}>
          <FormControl>
            <FormLabel>Email</FormLabel>
            <Input type="email" />
            <FormFieldError />
          </FormControl>
        </FormField>
        <Button type="submit">Sign in</Button>
      </VStack>
    </form>
  );
}

TanStack Form

import { useForm } from "@tanstack/react-form";
import { FormField, FormFieldError } from "kovax-react/tanstack-form";
import { FormControl, FormLabel, Input, VStack } from "kovax-react";

export function ProfileForm() {
  const form = useForm({ defaultValues: { name: "" } });

  return (
    <VStack gap={16} align="stretch">
      <FormField form={form} name="name">
        <FormControl>
          <FormLabel>Name</FormLabel>
          <Input />
          <FormFieldError />
        </FormControl>
      </FormField>
    </VStack>
  );
}

Peers are optional — install only the adapter you need.

Docs: Form.md.

ColorModeScript — no theme flash

Blocking inline script in <head> sets data-kovax-theme before first paint (localStorage + prefers-color-scheme).

// app/layout.tsx — Next.js App Router
import { ColorModeScript } from "kovax-react/server";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <ColorModeScript storageKey="kovax-color-mode" />
      </head>
      <body>{children}</body>
    </html>
  );
}

// app/providers.tsx
"use client";
import { ThemeProvider } from "kovax-react";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <ThemeProvider storageKey="kovax-color-mode" defaultColorMode="system">
      {children}
    </ThemeProvider>
  );
}

Use the same storageKey / defaultColorMode on script and provider.

Plain HTML: buildColorModeScriptTag() from kovax-react/server.

Storybook alongside the playground

Site	URL
Playground (docs + live demos, EN/RU)	mrkamura.github.io/kovax
Storybook (autoDocs, a11y, visual tests)	mrkamura.github.io/kovax/storybook

npm run dev:storybook
npm run build:storybook

autoDocs — props tables from TypeScript (tags: ['autodocs']).
@storybook/addon-a11y — axe in the Accessibility panel.
@chromatic-com/storybook — Visual Tests (connect a Chromatic project for baselines).

Stories resolve library source via Vite aliases — no root npm run build required for local dev.

Recap: 0.6 and 0.7

Version	Highlights
0.6	Avatar, Badge, Menu, Skeleton, Pagination, useBreakpointUp
0.7	`kovax-react/server`, `"use client"`, jest-axe, size-limit, NEXTJS_APP_ROUTER.md

Drafts: dev-to-v0.6.md, dev-to-v0.7.md.

Changelog

CHANGELOG.md · playground Releases tab.

Issues and PRs on GitHub — thanks for reading.

kovax-react 0.7: Next.js App Router, kovax-react/server, and jest-axe in every test

Aleksey Alekseev — Wed, 20 May 2026 18:59:37 +0000

kovax-react 0.7.0 is on npm. After 0.6 shipped product UI (Avatar, Menu, Pagination, breakpoint hooks), 0.7 focuses on production ergonomics: clear Server vs Client boundaries for the App Router, automated a11y checks in Jest, and bundle size transparency per entry point.

📦 npm: kovax-react@0.7.0
🧑‍💻 Repo: github.com/MrKamura/kovax
🧪 Live docs: mrkamura.github.io/kovax

TL;DR — everything since 0.6.0

Area	What shipped
RSC / Next.js	`kovax-react/server` — RSC-safe `Box`, `Stack`, `Container`, `Text`, `Heading`
Client bundles	`"use client"` prepended to client-only `tsup` outputs after build
Deep imports	Unchanged RSC-safe entries: `kovax-react/typography`, `/badge`, `/progress`
Testing	`jest-axe`, `expectNoAxeViolations()`, automatic axe pass in `setupTests.ts`
DatePicker	`aria-label` on popover panel and datetime `type="time"` fields
Tooling	`.size-limit.json`, `npm run size`, README size-limit + bundlejs badges
npm	Expanded keywords (`nextjs`, `rsc`, `a11y`, `server-components`, …)
Docs	`docs/NEXTJS_APP_ROUTER.md` — ThemeProvider placement, FOUC, import matrix

No new runtime peer dependencies.

npm install kovax-react@0.7.0

Why this release exists

Three recurring questions after 0.6:

Which imports work in Server Components?
How do we keep accessibility from regressing?
How big is each deep import really?

0.7 answers all three without adding runtime deps.

`"use client"` boundaries

After npm run build, client bundles include "use client" so Next.js (and similar RSC stacks) treat them correctly.

Import	`"use client"`	Use in
`kovax-react`	yes	Client Components
`kovax-react/server`	no	Server Components
`kovax-react/typography`, `/badge`, `/progress`	no	Server Components
`kovax-react/tokens`, `/form`, `/overlays`, …	yes	Client only

Rule of thumb: hooks, context, effects → client entry. Static markup → server entry.

kovax-react/server

// app/page.tsx — Server Component
import { Container, Heading, Text } from "kovax-react/server";
import { SignInForm } from "./sign-in-form";

export default function Page() {
  return (
    <Container maxW="lg">
      <Heading level={1}>Welcome</Heading>
      <Text size="lg">Sign in to continue.</Text>
      <SignInForm />
    </Container>
  );
}

// app/sign-in-form.tsx
"use client";

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

export function SignInForm() {
  return (
    <VStack gap={16} align="stretch">
      <FormControl>
        <FormLabel htmlFor="email">Email</FormLabel>
        <Input id="email" type="email" />
      </FormControl>
      <Button type="submit" variant="solid" color="primary">
        Sign in
      </Button>
    </VStack>
  );
}

Mount ThemeProvider in a client providers.tsx wrapper — full walkthrough: NEXTJS_APP_ROUTER.md.

FOUC and data-kovax-theme

0.7 documents an inline script pattern for data-kovax-theme before first paint (system / stored color mode).

0.8 ships ColorModeScript as a drop-in (Chakra-style). On 0.7, follow the doc; upgrade to 0.8 when you want the component API.

jest-axe in component tests

import { render } from "@testing-library/react";
import { expectNoAxeViolations } from "../test-utils";
import { Button } from "./Button";

it("has no axe violations", async () => {
  const { container } = render(<Button>Solid</Button>);
  await expectNoAxeViolations(container);
});

setupTests.ts wires axe globally — npm test catches many a11y regressions early.

size-limit and README badges

.size-limit.json enforces gzip budgets per entry; npm run size fails CI on bundle bloat.

README tables link size-limit badges and bundlejs.com analysis for kovax-react, /server, /form, /overlays, etc. — useful when picking deep imports in App Router apps.

DatePicker accessibility

Labeled popover panel (aria-label).
Datetime variant (variant="datetime") labels time inputs.

Small but important for calendar + time pickers in forms.

Documentation

docs/NEXTJS_APP_ROUTER.md — RSC import matrix, providers layout, FOUC notes.
Playground Foundation topic links to the guide.
Cross-links in README and Getting started.

Try live: mrkamura.github.io/kovax (EN/RU UI).

Changelog & upgrade path

Full list: CHANGELOG.md.

0.8 adds Tailwind v4 preset, form library adapters, ColorModeScript, and Storybook — see dev-to-v0.8.md.

Issues and PRs welcome on GitHub.

Thanks for reading.

kovax-react 0.6: Pagination, breakpoint hooks, and one source of truth for responsive layout

Aleksey Alekseev — Mon, 18 May 2026 21:10:25 +0000

kovax-react 0.6 is on npm. If you already use kovax-react 0.5 with ThemeProvider and CSS-variable theming, this release is the “admin panel polish” follow-up: a pagination component you can drop next to tables and search results, plus responsive hooks that read the same breakpoint.* tokens as themeToken and your stylesheets — no duplicate 768px constants in JS.

📦 npm: kovax-react@0.6.0
🧑‍💻 Repo: github.com/MrKamura/kovax
🧪 Live docs & playground: mrkamura.github.io/kovax

TL;DR

Area	What shipped
`Pagination`	Semantic `nav`, prev/next, numbered pages, ellipsis windows, `aria-current="page"`, motion from *`duration.` / `easing.`, honors `prefers-reduced-motion`*
Tree-shaking	Optional `kovax-react/pagination` entry exports `Pagination` + `getPaginationItems`
Responsive	`useMediaQuery`, `useBreakpointUp`, `breakpointMinMediaQuery`, `breakpointMinWidth`, `breakpointMinMediaQueryFromToken` — all aligned with `breakpoints` (`sm` … `2xl` in `em`)
Docs	Pagination.md, playground Components → Pagination, Documentation topic with EN/RU UI copy

No new runtime peer dependencies beyond what you already use for kovax-react.

Install

npm install kovax-react@0.6.0

Wrap your app in ThemeProvider as before — Pagination and the media-query hooks pick up the same CSS variables and token scale as the rest of the library.

Why another minor release?

After 0.5, two gaps showed up in real apps:

Lists and tables need a pager — not just “page 3 of 40” text, but keyboard-friendly controls, clear current-page state, and ellipsis when there are dozens of pages.
Breakpoints were defined twice — once in design tokens / CSS, again as magic numbers in React. That drifts the moment someone tweaks breakpoint.md.

0.6 closes both without pulling in a routing or data-fetching layer: you keep page / pageCount controlled in parent state (or your router) and wire onPageChange.

Pagination

Basics

import { Pagination } from "kovax-react";
import { useState } from "react";

export function SearchResultsPager() {
  const [page, setPage] = useState(1);

  return (
    <Pagination
      page={page}
      pageCount={40}
      onPageChange={setPage}
      variant="outline"
      size="sm"
      aria-label="Search results"
    />
  );
}

Props worth knowing:

variant: soft (default) or outline
size: sm | md
siblingCount: how many page numbers sit beside the current page (default 1); increase for wider “windows” on dense UIs
disabled: freeze controls while a request is in flight
i18n: previousAriaLabel, nextAriaLabel, getPageAriaLabel, optional visible previousLabel / nextLabel

<Pagination
  page={page}
  pageCount={12}
  onPageChange={setPage}
  siblingCount={2}
  previousAriaLabel="Previous"
  nextAriaLabel="Next"
  getPageAriaLabel={(p) => `Page ${p}`}
/>

The component renders nothing when pageCount < 1, so you can skip conditional JSX around empty result sets.

Accessibility and motion

Root is a nav with your aria-label (required for a meaningful landmark).
Active page uses aria-current="page".
Ellipsis markers are aria-hidden; navigation stays on real buttons.
Hover/active feedback uses theme motion tokens; when the user prefers reduced motion, scale animations are skipped.

Custom layout, same gap logic

Need your own button components or a mobile-specific strip? Export the algorithm:

import { getPaginationItems } from "kovax-react/pagination";

const items = getPaginationItems(page, pageCount, 1);
// → (number | "ellipsis")[]

return (
  <nav aria-label="Results">
    {items.map((item, i) =>
      item === "ellipsis" ? (
        <span key={`e-${i}`} aria-hidden>…</span>
      ) : (
        <button
          key={item}
          type="button"
          aria-current={item === page ? "page" : undefined}
          onClick={() => setPage(item)}
        >
          {item}
        </button>
      ),
    )}
  </nav>
);

Smaller bundles

Full barrel:

import { Pagination, getPaginationItems } from "kovax-react";

Pagination-only entry (same API, less to parse if you only ship a pager):

import { Pagination, getPaginationItems } from "kovax-react/pagination";

Full prop reference: Pagination.md.

Breakpoints in JavaScript

Design tokens already expose em breakpoints (sm 30em, md 48em, lg 62em, …). They respect root font size — a nicer default than hard-coded pixels for accessibility.

Hooks and helpers:

API	Role
`useBreakpointUp("md")`	`true` when viewport ≥ token `md`
`useMediaQuery(query, options?)`	Generic `matchMedia` subscription
`breakpointMinMediaQuery("md")`	`"(min-width: 48em)"` string for CSS-in-JS or tests
`breakpointMinWidth("md")`	Raw token value (`48em`)
`breakpointMinMediaQueryFromToken("breakpoint.md")`	Same as above via `themeToken` path

import {
  useBreakpointUp,
  useMediaQuery,
  breakpointMinMediaQuery,
  themeToken,
} from "kovax-react";

const isMdUp = useBreakpointUp("md");
const isWide = useMediaQuery(`(min-width: ${themeToken("breakpoint.lg")})`);
const mqForCss = breakpointMinMediaQuery("md"); // "(min-width: 48em)"

SSR and hydration

useMediaQuery is built on useSyncExternalStore, so server and first client paint can agree via defaultMatches:

// Desktop-first layout: fewer “flash from mobile to desktop” warnings
const isLgUp = useBreakpointUp("lg", { defaultMatches: true });

On the server, getServerSnapshot returns defaultMatches (default false). After hydration, the real matchMedia result takes over and listeners update on resize.

Token docs (including breakpoint table): Tokens.md.

Example: responsive columns without duplicating constants

import { Grid, useBreakpointUp } from "kovax-react";

export function ProductGrid({ children }: { children: React.ReactNode }) {
  const threeCols = useBreakpointUp("lg");

  return (
    <Grid columns={threeCols ? 3 : 1} gap={16}>
      {children}
    </Grid>
  );
}

Try it in the playground

The live site is still statically prerendered (SEO-friendly routes, sitemap). For 0.6, open:

Components → Pagination — variants, sizes, ellipsis, disabled state, code tabs
Components → Design tokens — breakpoint scale next to spacing, motion, z-index
Documentation → Pagination — the same Markdown as the repo, with EN/RU chrome

No local install required to click through examples.

Changelog and what’s next

Full release notes (including a Russian summary block): CHANGELOG.md.

From the 0.5 roadmap, items still on the radar include Breadcrumb, richer Toast patterns, and more overlay polish. Menu already exists on the Popover primitives in the current tree — feedback on API shape is welcome.

If something’s missing, open an issue or PR — or leave a comment here; I read them.

Thanks for reading — happy paging.

Meet kovax-react: a typed React UI library with CSS-variable theming

Aleksey Alekseev — Thu, 14 May 2026 16:11:02 +0000

I just shipped kovax-react 0.5 — a small, typed React UI library aimed at apps that want layout primitives + forms + overlays + tables + design tokens without dragging in a framework. This post is a quick tour: what's inside, what's new, and how to try it in 60 seconds.

📦 npm: kovax-react
🧑‍💻 Repo: github.com/MrKamura/kovax
🧪 Live docs & playground: mrkamura.github.io/kovax

TL;DR

Typed design tokens (themeToken, colorToken) for colors, spacing, radii, typography, shadows, motion, z-index, breakpoints.
ThemeProvider injects CSS variables (--kx-*), supports light / dark / system color modes, scoped subtrees, palette overrides, and CSP nonce — SSR-safe with hex fallbacks.
30+ components: Box, Flex, Grid, Stack, Heading, Text, Button, Input, Textarea, Checkbox, Radio, Switch, Select / useCombobox, FormControl, Tabs, Accordion, Alert, Progress, Tooltip, Popover, Dialog, Modal, Toast, DatePicker, Table / DataTable, and now Avatar + Badge.
Deep imports for smaller bundles: kovax-react/layout, /form, /overlays, /table, /badge, /avatar, …
React 16+ peer; react-day-picker only when you use date pickers.
MIT-licensed, written in TypeScript, tested with Jest.

Install

npm install kovax-react
# only if you use the date pickers
npm install react-day-picker

Theming in 6 lines

Wrap your app once, and everything reads from CSS variables:

import { ThemeProvider, Button, themeToken } from "kovax-react";

export function App() {
  return (
    <ThemeProvider defaultColorMode="system">
      <Button color="primary" style={{ marginTop: themeToken("spacing.md") }}>
        Hello, kovax
      </Button>
    </ThemeProvider>
  );
}

Switching modes is instant — components consume var(--kx-…, fallback) under the hood, so SSR has no flash and "no provider" still renders with the original palette.

Need a brand palette? Override per side, the rest is inherited:

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

const brandPrimary = {
  50: "#f5f3ff",  100: "#ede9fe", 200: "#ddd6fe", 300: "#c4b5fd",
  400: "#a78bfa", 500: "#7c3aed", 600: "#6d28d9", 700: "#5b21b6",
  800: "#4c1d95", 900: "#3b0a76",
};

<ThemeProvider
  palettes={{ light: { colors: { ...lightPalette.colors, primary: brandPrimary } } }}
/>

You can also scope a ThemeProvider to a ref — render a dark widget inside an otherwise light page (or vice-versa) without forking components.

New in 0.5

`ThemeProvider` + dark mode

colorMode: light | dark | system
useColorMode() and useTheme() hooks
target: documentElement or a RefObject for scoped theming
palettes per side, storageKey persistence, onColorModeChange callback
nonce for strict CSP

`Avatar`

Photo, initials from name, or a custom fallback (icon, emoji, anything). Sizes xs–xl, circle / rounded, semantic fallback colorScheme. Robust to broken image URLs (auto fallback on onError).

import { Avatar, HStack } from "kovax-react";

<HStack gap={12}>
  <Avatar name="Jane Doe" />               {/* → "JD" */}
  <Avatar src="/jane.jpg" alt="Jane Doe" name="Jane Doe" size="lg" />
  <Avatar name="Live" colorScheme="success" />
</HStack>

`Badge`

Compact status / count pill. Variants solid / outline / subtle, semantic colors, optional leading dot, sizes sm / md.

import { Badge, HStack } from "kovax-react";

<HStack gap={8}>
  <Badge dot color="success">Live</Badge>
  <Badge color="primary" variant="outline">Pro</Badge>
  <Badge color="neutral" size="sm">12</Badge>
</HStack>

What I actually use it for

Layout primitives (Box, HStack, VStack, Grid, Container, Sticky) keep markup boring and consistent.
Forms (FormControl, Input, Textarea, Select, useCombobox, Switch, Checkbox, Radio) play nice with react-hook-form (used in the playground demos, but not a library dep).
Overlays (Tooltip, Popover, Dialog, Modal, Toast) cover most app needs without a separate floating-ui setup.
Tables — Table.* primitives plus a DataTable with controlled sort and row headers.

Try it without installing

The live playground is statically prerendered (so SEO works) and includes Preview / Code tabs per example, EN/RU UI, and the same Markdown docs from the repo. Sections to peek at:

Components → ThemeProvider — color modes, scoped themes, brand palette overrides
Components → Avatar / Badge — the new bits
Components → Table — DataTable + sortable columns
Components → Design tokens — every palette / spacing / radius / shadow / motion / z-index / breakpoint, live

What's next

Likely candidates for 0.6: a richer Skeleton, Breadcrumb, Pagination, a Menu built on the same Popover primitives, and a small useMediaQuery exposing the design tokens' breakpoints.

If you find something missing, file an issue or PR on GitHub — or just leave a comment here, I read them all.

Thanks for reading 🙏 — happy to answer questions in the comments.

Forem: Aleksey Alekseev

kovax-react 0.8: Tailwind v4 preset, FormField adapters, ColorModeScript, and Storybook

TL;DR — everything since 0.7.0

Tailwind v4 — theme-reactive utilities

FormField adapters

react-hook-form

TanStack Form

ColorModeScript — no theme flash

Storybook alongside the playground

Recap: 0.6 and 0.7

Changelog

kovax-react 0.7: Next.js App Router, kovax-react/server, and jest-axe in every test

TL;DR — everything since 0.6.0

Why this release exists

"use client" boundaries

kovax-react/server

FOUC and data-kovax-theme

jest-axe in component tests

size-limit and README badges

DatePicker accessibility

Documentation

Changelog & upgrade path

kovax-react 0.6: Pagination, breakpoint hooks, and one source of truth for responsive layout

TL;DR

Install

Why another minor release?

Pagination

Basics

Accessibility and motion

Custom layout, same gap logic

Smaller bundles

Breakpoints in JavaScript

SSR and hydration

Example: responsive columns without duplicating constants

Try it in the playground

Changelog and what’s next

Meet kovax-react: a typed React UI library with CSS-variable theming

TL;DR

Install

Theming in 6 lines

New in 0.5

ThemeProvider + dark mode

Avatar

Badge

What I actually use it for

Try it without installing

What's next

`"use client"` boundaries

`ThemeProvider` + dark mode

`Avatar`

`Badge`