@bloomneo/uikit v2.0.0

React components
built for agentic coding

UIKit is a React component library designed for agentic code workflows. 45+ typed components, 5 OKLCH themes, and 6 production layouts under one canonical pattern — with machine-readable specs (llms.txt + AGENTS.md) so AI coding agents generate correct TSX, and developers review work they actually understand.

npm ↗ GitHub ↗ llms.txt ↗
Install

One npm install, every component

npm install @bloomneo/uikit

For AI coding agents (Claude, Cursor, Copilot, Windsurf)

This page is written for humans. Agents should fetch /uikit/llms.txt and /uikit/AGENTS.md as the authoritative specs — every component's exact prop shape, canonical setup, and what NOT to do. Same files ship inside the published npm package under node_modules/@bloomneo/uikit/ and are regenerated on every release.

Read llms.txt → Read AGENTS.md →
What you can build

One component library. Every React surface.

UIKit is the React library teams reach for when they need to ship — not evaluate five headless kits and style them by hand.

What NOT to do (for you and your agent)

The five mistakes UIKit won't let you make twice

These are the only ways to silently break UIKit code. Memorise them — or point your AI agent at AGENTS.md where they're spelled out line by line.

The universal pattern — controlled props

Every stateful component, the same convention

Four handler families. Picking the right one is the single biggest thing agents and humans get wrong. Memorise this table.

Component familyValue propChange handler
Native inputs — Input, Textarea, PasswordInputvalueonChange(e) — ChangeEvent
Radix pickers — Select, Combobox, Slider, Tabs, AccordionvalueonValueChange(newValue)
Radix checkables — Checkbox, Switch, RadioGroupcheckedonCheckedChange(checked)
Overlays — Dialog, Sheet, PopoveropenonOpenChange(open)

In 2.0, <Combobox> switched from onChange to onValueChange to match <Select>. No alias kept — this is drift-checked in CI.

Setup — one time per app

Three steps to a working UI

// 1. Import the core stylesheet ONCE at your app entry (e.g. main.tsx)
import '@bloomneo/uikit/styles';

// Optional: import theme fonts (Elegant, Metro, Studio, Vivid)
import '@bloomneo/uikit/styles/fonts';

// 2. Wrap your app with providers
import { ThemeProvider, ToastProvider, ConfirmProvider } from '@bloomneo/uikit';

<ThemeProvider theme="base" mode="light">
  <ToastProvider position="bottom-right" />
  <ConfirmProvider>
    <App />
  </ConfirmProvider>
</ThemeProvider>

// 3. Add FOUC prevention in index.html <head> — prevents theme flash before React mounts
import { foucScript } from '@bloomneo/uikit/fouc';
<script dangerouslySetInnerHTML={{ __html: foucScript() }} />
One canonical import path

Flat imports only

There is exactly ONE supported import path for normal use. Always use the flat import:

import {
  Button, Input, Card, CardHeader, CardTitle, CardContent,
  Alert, AlertDescription, Badge, DataTable, Dialog,
  DialogContent, DialogHeader, DialogTitle, DialogFooter,
  Select, Combobox, DatePicker, Skeleton, EmptyState,
  PageHeader, PermissionGate, PermissionProvider,
  FormField, PasswordInput, toast, useToast, useConfirm,
  useTheme, useApi, usePagination, useBreakpoint,
  formatBytes, formatCurrency, formatDate, timeAgo,
} from '@bloomneo/uikit';

// Deep imports like '@bloomneo/uikit/button' exist for tree-shaking
// but are NOT the canonical form. Don't mix styles in one file.
5 OKLCH themes

Perceptually uniform color science

OKLCH color space ensures colors look consistent across devices and scale predictably — no muddy mid-tones or clipped highs. Each theme ships in light and dark mode.

base

Clean neutral foundation. Good default for any product.

elegant

Refined, subdued palette. Professional and polished.

metro

High contrast, bold. Inspired by transit design systems.

studio

Creative, warm. For design tools and media apps.

vivid

Saturated, energetic. For consumer and marketing apps.

const { theme, mode, availableThemes, setTheme, toggleMode } = useTheme();

setTheme('elegant');   // switch theme at runtime
toggleMode();          // light ↔ dark

// All available themes:
// 'base' | 'elegant' | 'metro' | 'studio' | 'vivid' | (your custom theme)
Component — Button
import { Button } from '@bloomneo/uikit';

// Variants
<Button>Default</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="outline">Outline</Button>
<Button variant="ghost">Ghost</Button>
<Button variant="destructive">Delete</Button>

// Sizes
<Button size="sm">Small</Button>
<Button size="lg">Large</Button>

// States
<Button disabled>Disabled</Button>
<Button loading>Saving...</Button>
Component — Card
import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter, Button } from '@bloomneo/uikit';

<Card>
  <CardHeader>
    <CardTitle>User Settings</CardTitle>
    <CardDescription>Manage your account preferences</CardDescription>
  </CardHeader>
  <CardContent>
    <p>Content goes here</p>
  </CardContent>
  <CardFooter>
    <Button>Save changes</Button>
  </CardFooter>
</Card>
Component — DataTable

Sortable, filterable, paginated table with row actions. Define columns once and let the table handle the rest.

import { DataTable, type DataTableColumn, type RowAction } from '@bloomneo/uikit';
import { Pencil, Trash2 } from 'lucide-react';

type User = { id: string; name: string; email: string; role: 'admin' | 'user'; createdAt: string; };

const columns: DataTableColumn<User>[] = [
  { id: 'name',      header: 'Name',  accessorKey: 'name',      sortable: true },
  { id: 'email',     header: 'Email', accessorKey: 'email' },
  { id: 'role',      header: 'Role',  accessorKey: 'role',      sortable: true },
  { id: 'createdAt', header: 'Joined', accessorKey: 'createdAt', sortable: true, dataType: 'date' },
];

const actions: RowAction<User>[] = [
  { id: 'edit',   label: 'Edit',   icon: <Pencil size={14} />, onClick: (row) => handleEdit(row) },
  { id: 'delete', label: 'Delete', icon: <Trash2 size={14} />, onClick: (row) => handleDelete(row), destructive: true },
];

<DataTable<User>
  data={users}
  columns={columns}
  rowActions={actions}
  searchable
  pagination
  pageSize={10}
  getRowId={(row) => row.id}
/>
Component — Forms
import { FormField, Input, PasswordInput, Select, Combobox, Button } from '@bloomneo/uikit';

// FormField wraps any input with label, error, and helper text
<FormField label="Email" required error={emailError} helper="We'll never share this">
  <Input type="email" value={email} onChange={(e) => setEmail(e.target.value)} />
</FormField>

<FormField label="Password" required>
  <PasswordInput value={password} onChange={(e) => setPassword(e.target.value)} />
</FormField>

// Searchable select with async loading
<Combobox
  value={country}
  onValueChange={setCountry}
  options={countries}
  placeholder="Select a country"
  searchPlaceholder="Search countries..."
  clearable
/>
Component — Toast

Mount <ToastProvider /> once at the root. Call toast.* from anywhere — no hooks, no context drilling.

import { toast } from '@bloomneo/uikit';

// Simple toasts
toast.success('Changes saved');
toast.error('Something went wrong');
toast.info('Heads up — deployment is running');
toast.warning('Your session expires in 5 minutes');

// With description and action
toast('Saved', {
  description: 'Your changes are now live',
  action: {
    label: 'Undo',
    onClick: () => toast.info('Undone'),
  },
});
Component — Confirm Dialog

useConfirm() returns a promise — true if confirmed, false if cancelled. No boilerplate modal state needed.

import { useConfirm } from '@bloomneo/uikit';

function DeleteButton() {
  const confirm = useConfirm();

  async function handleDelete() {
    const ok = await confirm({
      title: 'Delete this record?',
      description: 'This cannot be undone.',
      confirmLabel: 'Delete',
      tone: 'destructive',
    });
    if (!ok) return;
    await deleteRecord();
    toast.success('Deleted');
  }

  // High-stakes: user must type a phrase before confirm enables
  async function handleHardDelete() {
    const ok = await confirm.destructive({
      title: 'Delete account',
      description: 'This will permanently delete the account and all its data.',
      verifyText: 'delete my account',
    });
    if (ok) await nukeAccount();
  }

  return <Button variant="destructive" onClick={handleDelete}>Delete</Button>;
}
Component — Dialog
import { useState } from 'react';
import { Button, Dialog, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogFooter } from '@bloomneo/uikit';

export function EditProfileDialog() {
  const [open, setOpen] = useState(false);
  return (
    <>
      <Button onClick={() => setOpen(true)}>Edit profile</Button>
      <Dialog open={open} onOpenChange={setOpen}>
        <DialogContent>
          <DialogHeader>
            <DialogTitle>Edit profile</DialogTitle>
            <DialogDescription>Make changes and save when you're done.</DialogDescription>
          </DialogHeader>
          <p className="text-sm text-muted-foreground">Form fields go here.</p>
          <DialogFooter>
            <Button variant="outline" onClick={() => setOpen(false)}>Cancel</Button>
            <Button onClick={() => setOpen(false)}>Save changes</Button>
          </DialogFooter>
        </DialogContent>
      </Dialog>
    </>
  );
}
Component — PageHeader
import { Users } from 'lucide-react';
import { Button, PageHeader } from '@bloomneo/uikit';

<PageHeader
  icon={<Users />}
  title="User management"
  description="View and manage all users in your workspace"
  breadcrumbs={[
    { label: 'Admin', href: '/admin' },
    { label: 'Users' },
  ]}
  actions={<Button>Add user</Button>}
/>
Component — EmptyState
import { Inbox } from 'lucide-react';
import { Button, EmptyState } from '@bloomneo/uikit';

<EmptyState
  icon={<Inbox />}
  title="No invoices yet"
  description="Create your first invoice to get started."
  action={<Button onClick={handleCreate}>Create invoice</Button>}
/>
Component — PermissionGate
import { PermissionGate, PermissionProvider, Button } from '@bloomneo/uikit';

// Bring your own auth source — just provide a check function
const check = (perm: string) => currentUser.roles.includes(perm);

<PermissionProvider check={check}>
  {/* Single permission */}
  <PermissionGate when="admin">
    <Button variant="destructive">Delete user (admin only)</Button>
  </PermissionGate>

  {/* OR logic across multiple roles */}
  <PermissionGate when={['admin', 'moderator']} fallback={<span>Restricted</span>}>
    <Button>Moderate content</Button>
  </PermissionGate>

  {/* Custom predicate */}
  <PermissionGate when={() => currentUser.plan === 'pro'}>
    <ProFeature />
  </PermissionGate>
</PermissionProvider>
Utilities — Format
import { formatBytes, formatCurrency, formatDate, timeAgo, Time } from '@bloomneo/uikit';

formatCurrency(1234.56, { currency: 'USD' })             // '$1,234.56'
formatCurrency(1234.56, { currency: 'INR', locale: 'en-IN' }) // '₹1,234.56'
formatDate(new Date(), { preset: 'long' })               // 'April 12, 2026'
timeAgo(new Date(Date.now() - 10 * 60 * 1000))           // '10 minutes ago'
formatBytes(1_572_864)                                    // '1.5 MB'

// Auto-updating relative time component
<Time date={publishedAt} />
Hooks

Data fetching, theme, breakpoints, pagination

import { useApi, useTheme, usePagination, useBreakpoint, useActiveBreakpoint, useMediaQuery } from '@bloomneo/uikit';

// API hook — managed loading/data/error state
const api = useApi({ baseURL: 'http://localhost:3000' });
await api.get('/api/users');
// api.data, api.loading, api.error available reactively

// Theme hook
const { theme, mode, setTheme, toggleMode, availableThemes } = useTheme();

// Pagination hook — works with any data source
const pagination = usePagination({ total: 234, pageSize: 10 });
const visible = allItems.slice(pagination.startIndex, pagination.endIndex);
// pagination.page, pagination.pageCount, pagination.hasPrev, pagination.hasNext
// pagination.prev(), pagination.next(), pagination.goTo(n), pagination.pages

// Responsive breakpoints
const isAtLeastMd = useBreakpoint('md');          // true when ≥ 768px
const isMobile    = useBreakpoint('md', 'down');  // true when < 768px
const active      = useActiveBreakpoint();         // 'sm' | 'md' | 'lg' | 'xl' | '2xl'
const reduced     = useMediaQuery('(prefers-reduced-motion: reduce)');
Layout components

Six production-ready layouts

  • Header / HeaderLogo / HeaderNavSticky top nav with logo and navigation links
  • FooterPage footer with configurable column layout
  • Sidebar / SidebarNavCollapsible sidebar with nested navigation support
  • PageLayoutFull-page wrapper with header, sidebar, content, and footer slots
  • Section / ContainerContent containers with spacing variants and max-width constraints
  • MobileLayout / TabBar / SafeAreaMobile-specific layouts for Capacitor apps
Form components

Every form primitive, typed

  • Input / TextareaStandard text inputs with consistent styling
  • PasswordInputPassword input with show/hide toggle
  • SelectDropdown select for static option lists
  • ComboboxSearchable select with async option loading and clearable
  • DatePicker / DateRangePickerCalendar-based date and date-range selection
  • Checkbox / Radio / SwitchBoolean and choice inputs
  • FileUploadDrag-and-drop file input with preview and progress
  • FormFieldWrapper providing label, required marker, error, and helper text
Data display components

Tables, lists, stats, badges

  • DataTableSortable, filterable, paginated table with row actions and column definitions
  • DataListKey-value display for detail views
  • StatCardMetric card with label, value, change indicator, and optional sparkline
  • BadgeStatus / label chip in multiple color variants
  • Alert / AlertDescriptionInline status messages with info, warning, error, success variants
  • SkeletonLoading placeholder that matches the shape of real content
Cookbook — CRUD page pattern

A full CRUD page in ~80 lines

A complete user list with search, sort, row actions, and delete-with-confirm:

import { useState } from 'react';
import { Pencil, Trash2, Users } from 'lucide-react';
import {
  Button, ConfirmProvider, DataTable, PageHeader,
  ThemeProvider, ToastProvider, toast, useConfirm,
  type DataTableColumn, type RowAction,
} from '@bloomneo/uikit';

type User = { id: string; name: string; email: string; role: 'admin' | 'user' };

function UserListPage() {
  const [users, setUsers] = useState<User[]>(initialUsers);
  const confirm = useConfirm();

  const columns: DataTableColumn<User>[] = [
    { id: 'name',  header: 'Name',  accessorKey: 'name',  sortable: true },
    { id: 'email', header: 'Email', accessorKey: 'email' },
    { id: 'role',  header: 'Role',  accessorKey: 'role',  sortable: true },
  ];

  const actions: RowAction<User>[] = [
    { id: 'edit',   label: 'Edit',   icon: <Pencil size={14} />, onClick: handleEdit },
    {
      id: 'delete', label: 'Delete', icon: <Trash2 size={14} />, destructive: true,
      onClick: async (user) => {
        const ok = await confirm({ title: `Delete ${user.name}?`, tone: 'destructive' });
        if (!ok) return;
        setUsers(prev => prev.filter(u => u.id !== user.id));
        toast.success(`${user.name} deleted`);
      },
    },
  ];

  return (
    <>
      <PageHeader icon={<Users />} title="Users" actions={<Button>Add user</Button>} />
      <DataTable data={users} columns={columns} rowActions={actions} searchable pagination getRowId={r => r.id} />
    </>
  );
}

export default function App() {
  return (
    <ThemeProvider theme="base" mode="light">
      <ToastProvider position="bottom-right" />
      <ConfirmProvider>
        <UserListPage />
      </ConfirmProvider>
    </ThemeProvider>
  );
}
Cross-platform

One component library, four targets

Web

Vite + React. Full component library with all themes. SSR-compatible.

Desktop

Electron renderer process. Same components, same themes, same API.

Mobile

Capacitor + React. Touch-optimised with MobileLayout, TabBar, SafeArea.

Extensions

Browser extension popup. Constrained layout variants for small viewports.

FAQ

Frequently asked questions

What is @bloomneo/uikit?
@bloomneo/uikit is a React component library designed for agentic code workflows — the era where developers and AI coding agents (Claude Code, Cursor, GitHub Copilot, Windsurf) build UIs together. It ships 45+ typed components, 5 OKLCH themes, 6 production layouts, and includes llms.txt and AGENTS.md machine-readable specs in every release so agents generate correct JSX on the first try.
How is UIKit different from shadcn/ui, Mantine, MUI, Chakra, or Radix directly?
UIKit is a composable React component library built on Radix primitives + Tailwind. Unlike shadcn (copy-paste source into your repo) or MUI (opinionated visual design you can't escape), UIKit ships as a versioned npm package with unified conventions: one canonical import path, one provider tree, one controlled-prop convention, and cross-platform targets (web, desktop, mobile, extensions). Every component carries @llm-rule JSDoc so AI agents pick the correct API on the first try.
Does UIKit work with Next.js App Router?
Yes. All 44 interactive components in src/components/ui/*.tsx ship the "use client" directive and work in the App Router. Server Components can import non-interactive primitives like Card, Badge, Alert directly. SSR and FOUC are handled via the foucScript() helper for <head>.
Can I use UIKit without Tailwind?
Not out of the box — UIKit compiles to Tailwind utility classes and relies on Tailwind's design-token CSS variables at runtime. You don't need a tailwind.config.js in your app (the bundled stylesheet is self-contained), but you do need to import @bloomneo/uikit/styles.
How do I use UIKit with Claude Code, Cursor, or GitHub Copilot?
Three options. (1) Point your agent at https://dev.bloomneo.com/uikit/llms.txt and /uikit/AGENTS.md — authoritative machine-readable specs. (2) Install the package; the same files ship inside node_modules/@bloomneo/uikit/. (3) Claude Code users: copy skills/bloomneo-uikit/ into your repo's .claude/skills/ for auto-triggered per-component guidance.
Does UIKit support TypeScript?
UIKit is written in TypeScript and ships full type definitions. Zero any in the public surface — DataTable<User>, RowAction<User>, formatters and hooks all infer correctly so agent autocomplete actually works. A drift-checked public-surface test in CI prevents accidental API changes.
What themes does UIKit ship with?
Five OKLCH themes — base, elegant, metro, studio, vivid — each in light and dark mode. Switch at runtime with useTheme().setTheme('elegant'). Custom themes are first-class: run npx uikit generate theme <name> to scaffold one with OKLCH tokens and a dark-mode variant.
Can I build cross-platform apps (desktop, mobile, extensions)?
Yes. UIKit is web-first (React DOM) but ships platform-detection helpers (isTauri(), isNative(), isExtension()) and mobile-specific layouts (MobileLayout, TabBar, SafeArea). Use the same components for web, Electron desktop, Capacitor mobile, and browser extension popups from one codebase.
Is UIKit production-ready?
Yes. UIKit v2.0.0 is stable and semver-tracked. Every component ships with typed errors (UIKitError subclasses — DataTableError, FormFieldError, ThemeError, etc.), docs-URL links in error messages, and a drift-checked public surface enforced in CI. The unified controlled-prop convention means agents never silently generate broken handlers.
What license is UIKit under?
MIT. Use it in commercial projects, fork it, vendor it — no attribution required. The source lives on GitHub at github.com/bloomneo/uikit.
AI agent reference

Machine-readable specs for coding agents

llms.txt

One canonical snippet per component. No hallucinated prop shapes. View →

AGENTS.md

Always-do, never-do rules: one import path, required providers, canonical patterns. View →

Cookbook patterns

CRUD page, dashboard, login flow, settings page, delete flow — full working examples in llms.txt.