@zvndev/ui

A StyleX-native React design system for teams that want compile-time styling, centralized theming, and a maintained component package instead of copy-paste sprawl.

ZVN UI is not trying to out-feature every React UI library. The pitch is simpler:

• compile-time styling with StyleX
• package-managed upgrades instead of app-local component drift
• central theme defaults that keep component usage small
• real docs/playground for exploration and testing
• explicit stability boundaries instead of pretending every export is equally mature

Who this is for

ZVN UI is a fit if you:

• already like the StyleX model
• want a maintained React UI package instead of building your own design system from scratch
• care about centralized theming and consistent defaults
• want an interactive docs surface for component discovery

It is not trying to be the broadest React component ecosystem on the market.

What makes it different

• StyleX-native from the start — not a runtime CSS-in-JS wrapper
• Theme-first API design — configure defaults once, keep component calls small
• Maintained package model — closer to a design system product than a copy-paste registry
• AI-readable metadata — a secondary advantage for tooling and docs, not the only story

Install

npm install @zvndev/ui react react-dom @stylexjs/stylex

Required StyleX setup

ZVN UI relies on StyleX at build time, so your app must compile StyleX styles.

npm install -D @stylexjs/babel-plugin vite-plugin-stylex

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import styleX from 'vite-plugin-stylex'

export default defineConfig({
  plugins: [
    react({
      babel: {
        plugins: [
          [
            '@stylexjs/babel-plugin',
            {
              dev: process.env.NODE_ENV !== 'production',
              runtimeInjection: true,
              genConditionalClasses: true,
              treeshakeCompensation: true,
              unstable_moduleResolution: {
                type: 'commonJS',
                rootDir: __dirname,
              },
            },
          ],
        ],
      },
    }),
    styleX(),
  ],
})

Quick start

import {
  ThemeProvider,
  createTheme,
  Button,
  Card,
  CardContent,
  CardTitle,
  Input,
} from '@zvndev/ui'

const theme = createTheme({
  components: {
    button: { defaultVariant: 'secondary', radius: 'full' },
    input: { background: 'muted' },
    card: { shadow: 'md' },
  },
})

export function App() {
  return (
    <ThemeProvider theme={theme} defaultMode="system">
      <Card>
        <CardContent>
          <CardTitle>Contact us</CardTitle>
          <Input placeholder="[email protected]" />
          <Button>Submit</Button>
        </CardContent>
      </Card>
    </ThemeProvider>
  )
}

Stable surface

The public package is focused on the library surface:

• UI components
• theme system
• hooks
• utilities
• StyleX tokens and themes

The docs/playground app exists in this repo for exploration, but it is not positioned as the primary public package API.

For maturity tiers, see docs/stability.md.

Why choose ZVN UI

• Comparison guide: docs/comparison.md
• Example flows: docs/examples.md

Short version

Choose ZVN UI when you want a maintained, package-managed StyleX design system.

Prefer other options when you want:

• full copy-paste ownership (shadcn/ui)
• the biggest ecosystem (MUI, Mantine, Chakra)
• an enterprise-default design language (MUI)

Theme presets

import {
  ThemeProvider,
  minimalTheme,
  roundedTheme,
  brutalistTheme,
  glassTheme,
} from '@zvndev/ui'

Available presets:

• minimalTheme
• roundedTheme
• brutalistTheme
• glassTheme

Development

# app / docs playground
npm run dev
npm run build:app
npm run preview

# library
npm run build:lib

# verification
npm run lint
npm run typecheck
npm run test
npm run pack:check

Trust signals

Current repo checks:

• ESLint
• TypeScript typecheck
• Vitest test suite
• library build
• app build
• published-package sanity check

Support and security

• Stability policy: docs/stability.md
• Security reporting: SECURITY.md
• Contributing guide: CONTRIBUTING.md
• Issues: GitHub Issues

License

MIT