Constructive UI

Build UIs with @constructive-io/ui — 50+ components on Base UI + Tailwind CSS v4.

When to Apply

Building UIs with @constructive-io/ui components
Creating custom components with cva/cn/data-slot
Setting up theming, dark mode, OKLCH tokens
Building forms, overlays, layouts, advanced inputs
Using the shadcn registry
Adding animations with motion/react

Quick Start

Deep Import Convention

// Correct — tree-shakeable
import { Button } from '@constructive-io/ui/button';
import { Dialog, DialogTrigger, DialogPopup } from '@constructive-io/ui/dialog';
import { cn } from '@constructive-io/ui/lib/utils';

// Avoid — barrel import pulls entire library
import { Button } from '@constructive-io/ui';

PortalRoot Setup (Required)

All overlay components (dialogs, popovers, tooltips, sheets) require PortalRoot in your root layout:

import { PortalRoot } from '@constructive-io/ui/portal';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <PortalRoot />
      </body>
    </html>
  );
}

Toaster Setup

Add Toaster to your root layout for toast notifications:

import { Toaster } from '@constructive-io/ui/sonner';
// Place <Toaster /> alongside <PortalRoot /> in your body

Component Architecture

Every component follows: cva for variant definitions, cn() for class merging, data-slot on root, named exports.

'use client';
import { cva, type VariantProps } from 'class-variance-authority';
import { cn } from '@constructive-io/ui/lib/utils';

const myVariants = cva('base-classes', {
  variants: { variant: { default: '...', secondary: '...' } },
  defaultVariants: { variant: 'default' },
});

type MyProps = React.ComponentProps<'div'> & VariantProps<typeof myVariants>;

function MyComponent({ className, variant, ...props }: MyProps) {
  return <div data-slot="my-component" className={cn(myVariants({ variant }), className)} {...props} />;
}

export { MyComponent, myVariants, type MyProps };

Key rules:

React.ComponentProps<'element'> over React.HTMLAttributes
Always set data-slot on root element
cn() to merge className — never concatenate
Named exports only, 'use client' when using hooks/events
Slot + Slottable from @constructive-io/ui/lib/utils for polymorphic asChild

See references/foundations.md for full patterns, Base UI mapping, TypeScript conventions.

Theming & Tokens

OKLCH token system in globals.css with @theme inline for Tailwind v4.

Key Tokens

Category	Tokens
Surface	`background`, `foreground`, `card`, `popover`
Interactive	`primary`, `secondary`, `accent`, `muted`, `destructive`
Status	`info`, `success`, `warning`
Input	`border`, `input`, `ring`
Sidebar	`sidebar`, `sidebar-primary`, `sidebar-accent`, `sidebar-border`
Chart	`chart-1` through `chart-5`

Dark Mode

Class-based via .dark on <html>. Tailwind v4 directive: @custom-variant dark (&:is(.dark *));

// Toggle implementation
document.documentElement.classList.toggle('dark', isDark);
localStorage.setItem('theme', isDark ? 'dark' : 'light');

Tailwind v4 Migration

v3	v4
`shadow-sm`	`shadow-xs`
`shadow`	`shadow-sm`
`rounded-sm`	`rounded-xs`
`rounded`	`rounded-sm`
`outline-none`	`outline-hidden`
`bg-opacity-*`	`bg-black/50`
`bg-[--brand]`	`bg-(--brand)`

See references/theming.md for complete globals.css, z-index layers, shadow utilities. See references/token-values.md for all light/dark OKLCH values.

Registry Installation

Install components via shadcn registry or npm.

// components.json — add constructive registry
{
  "registries": {
    "@constructive": "https://constructive-io.github.io/dashboard/r/{name}.json"
  }
}

npx shadcn@latest add @constructive/button
npx shadcn@latest add @constructive/form-kit      # all form components
npx shadcn@latest add @constructive/overlay-kit    # all overlay components
npx shadcn@latest add @constructive/layout-kit     # all layout components
npx shadcn@latest add @constructive/constructive-theme  # full token system

npm = centralized updates, version-locked. Registry = source ownership, deep customization.

See references/registry.md for full component list, bundles, build pipeline.

Animation System

Import from motion/react (NOT framer-motion). Use presets from @constructive-io/ui/lib/motion/motion-config.

Preset	Use For
`variants.fadeScale`	Modal/dialog enter
`variants.fadeSlideUp`	List items with stagger
`variants.fadeSlideDown`	Toast/notification
`variants.fade`	Subtle presence change
`variants.floatUp`	Hero entrance
`transitions.panel`	Sheet/drawer slide
`springs.snappy`	Button press (`whileTap`)
`transitions.enterExit`	Tab/route transitions

'use client';
import { motion, AnimatePresence } from 'motion/react';
import { variants } from '@constructive-io/ui/lib/motion/motion-config';

<AnimatePresence mode="wait">
  {isOpen && (
    <motion.div key="panel" variants={variants.fadeScale} initial="initial" animate="animate" exit="exit">
      {children}
    </motion.div>
  )}
</AnimatePresence>

See references/motion.md for all presets, stagger patterns, reduced motion, performance rules.

Forms

Three layers: Field (standalone labels), FormControl (floating labels), Form (react-hook-form).

// Layer 1: Field — simple label + input
import { Field } from '@constructive-io/ui/field';
import { Input } from '@constructive-io/ui/input';

<Field label="Email" error={errors.email} required>
  <Input type="email" placeholder="name@example.com" />
</Field>

// Layer 3: Form — react-hook-form integration
import { Form, FormField, FormItem, FormLabel, FormControl, FormMessage } from '@constructive-io/ui/form';

<Form {...form}>
  <form onSubmit={form.handleSubmit(onSubmit)}>
    <FormField control={form.control} name="email" render={({ field }) => (
      <FormItem>
        <FormLabel>Email</FormLabel>
        <FormControl><Input {...field} /></FormControl>
        <FormMessage />
      </FormItem>
    )} />
  </form>
</Form>

InputGroup for addons: InputGroupAddon with position="inline-start|inline-end|block-start|block-end".

See references/forms.md for all form patterns, Zod validation, composition examples. See references/input-components.md for Input, Textarea, Checkbox, RadioGroup, Switch, Select API.

Overlays

Component	Use When
Dialog	Modal form, confirmation, focused content
AlertDialog	Destructive confirmation (blocks interaction)
Sheet	Side panel for details, editing
Popover	Contextual info/controls, filter panels
Tooltip	Brief hints on hover/focus
DropdownMenu	Action menus, context menus
Command	Command palette (Cmd+K), search-driven command execution

// Dialog
import { Dialog, DialogTrigger, DialogPopup, DialogHeader, DialogTitle, DialogFooter } from '@constructive-io/ui/dialog';

<Dialog>
  <DialogTrigger asChild><Button>Open</Button></DialogTrigger>
  <DialogPopup>
    <DialogHeader><DialogTitle>Title</DialogTitle></DialogHeader>
    {/* content */}
    <DialogFooter><Button>Save</Button></DialogFooter>
  </DialogPopup>
</Dialog>

// Sheet
import { Sheet, SheetTrigger, SheetContent, SheetHeader, SheetTitle } from '@constructive-io/ui/sheet';

<Sheet>
  <SheetTrigger asChild><Button>Open Panel</Button></SheetTrigger>
  <SheetContent side="right">{/* content */}</SheetContent>
</Sheet>

Floating elements inside modals auto-elevate z-index via useFloatingOverlayPortalProps().

See references/overlays.md for all overlay components, nesting patterns. See references/sheet-stacking.md for SheetStackProvider deep dive. See references/dropdown-menu-api.md for DropdownMenu sub-component API. See references/command-palette.md for full command palette system — registry, hooks, multi-step wizards, background tasks, keyboard shortcuts.

Layout & Navigation

// Sidebar — full app shell
import { SidebarProvider, Sidebar, SidebarContent, SidebarMenu, SidebarMenuItem,
  SidebarMenuButton, SidebarInset, SidebarTrigger } from '@constructive-io/ui/sidebar';

<SidebarProvider>
  <Sidebar>
    <SidebarContent>
      <SidebarMenu>
        <SidebarMenuItem>
          <SidebarMenuButton isActive tooltip="Home"><Home className="size-4" /><span>Home</span></SidebarMenuButton>
        </SidebarMenuItem>
      </SidebarMenu>
    </SidebarContent>
  </Sidebar>
  <SidebarInset>{/* main content */}</SidebarInset>
</SidebarProvider>

// Tabs
import { Tabs, TabsList, TabsTrigger, TabsContent } from '@constructive-io/ui/tabs';

<Tabs defaultValue="general">
  <TabsList>
    <TabsTrigger value="general">General</TabsTrigger>
    <TabsTrigger value="security">Security</TabsTrigger>
  </TabsList>
  <TabsContent value="general">...</TabsContent>
  <TabsContent value="security">...</TabsContent>
</Tabs>

Also: Breadcrumb, Pagination, Stepper, Collapsible, Resizable, ScrollArea, PageHeader, Dock.

Stack Navigation (iOS-Style Card Navigation)

The primary navigation pattern in the Constructive admin app. Cards push/pop from the right with peek interactions, gestures, and responsive layout.

import { CardStackProvider, useCardStack, CardStackViewport } from '@constructive-io/ui/stack';

// Root layout — wraps entire app
<CardStackProvider layoutMode="side-by-side" defaultPeekOffset={48}>
  {children}
  <ClientOnlyStackViewport />
</CardStackProvider>

// Push cards imperatively
const stack = useCardStack();
stack.push({ title: 'Profile', Component: ProfileCard, props: { userId } });

Layout modes: cascade (overlapping peek) and side-by-side (master-detail). Cards support useCardReady() to defer queries until slide animation completes.

See references/stack-navigation.md for full Stack API — CardSpec, CardStackApi, route registry, peek gestures, mobile behavior.

See references/layout.md for all layout components. See references/sidebar-api.md for Sidebar sub-component props, CSS variables.

Data Display & Feedback

// Badge variants
import { Badge } from '@constructive-io/ui/badge';
<Badge variant="success">Active</Badge>
<Badge variant="destructive">Error</Badge>
<Badge variant="warning">Pending</Badge>

// Table
import { Table, TableHeader, TableBody, TableRow, TableHead, TableCell } from '@constructive-io/ui/table';

// Toast
import { showSuccessToast, showErrorToast } from '@constructive-io/ui/toast';
showSuccessToast('Saved');
showErrorToast('Failed', 'Please try again');

Also: Alert, Avatar, Skeleton, Progress, FlickeringGrid, MotionGrid, ProgressiveBlur.

See references/data-display.md for all data display components.

Advanced Inputs

Need	Component
Search + select one	Autocomplete (simple) or Combobox (richer)
Search + select multiple	Combobox `multiple` or MultiSelect
Tag-style multi-picker	Tags (create-on-enter)
Link/unlink records	RecordPicker (fuzzy search, checkboxes)
Date selection	Calendar / RangeCalendar
JSON editing	JsonInput (with validation)

// Combobox
import { Combobox, ComboboxInput, ComboboxTrigger, ComboboxContent, ComboboxItem, ComboboxList } from '@constructive-io/ui/combobox';

<Combobox value={value} onValueChange={setValue}>
  <ComboboxTrigger><ComboboxInput placeholder="Select..." /></ComboboxTrigger>
  <ComboboxContent>
    <ComboboxList>
      {items.map((item) => <ComboboxItem key={item.value} value={item.value}>{item.label}</ComboboxItem>)}
    </ComboboxList>
  </ComboboxContent>
</Combobox>

See references/advanced-inputs.md for all advanced input components. See references/combobox-api.md for Combobox sub-component props, multiple mode, useComboboxFilter.

Component Catalog

Primitives

button, badge, label, skeleton, card (patterns), separator, alert

Form

input, textarea, checkbox, checkbox-group, radio-group, switch, select, progress, form, form-control, input-group, field

Overlay

dialog, alert-dialog, sheet, drawer, popover, tooltip, dropdown-menu, command

Layout

tabs, collapsible, scroll-area, resizable, sidebar, breadcrumb, pagination, stepper, page-header, dock

Data

table, avatar

Advanced Inputs

autocomplete, combobox, multi-select, tags, record-picker, calendar-rac, json-input

Notifications

sonner, toast

Navigation

stack (full reference)

Utilities

portal, lib/utils (cn, Slot, Slottable, composeRefs, mergeProps, useControllableState), lib/motion/motion-config, globals.css

Effects

flickering-grid, motion-grid, progressive-blur, progressive-blur-scroll-container, responsive-diagram

All imported via @constructive-io/ui/{name}.

Best Practices

Imports: Always use deep imports (@constructive-io/ui/button), never barrel imports
Components: Named exports only, data-slot on root, cn() for class merging, ...props spread
Types: React.ComponentProps<'element'> over React.HTMLAttributes
Client: 'use client' on any component using hooks, events, or browser APIs
Tailwind v4: shadow-xs not shadow-sm, rounded-xs not rounded-sm, bg-black/50 not bg-opacity-*
Tokens: Use semantic tokens (bg-primary) not raw colors (bg-blue-500), define light+dark for custom tokens
Z-index: Use layer variables (--z-layer-floating), never hardcode values
Animation: Use motion-config presets, respect prefers-reduced-motion
Forms: Field for simple forms, Form+FormField for validation, zodResolver over inline rules
Overlays: asChild on triggers, PortalRoot required, AlertDialog for destructive confirms
Icons: size-4 shorthand over w-4 h-4

References

references/foundations.md — Component architecture: cva, cn, Slot, data-slot, Base UI mapping
references/theming.md — OKLCH tokens, globals.css, dark mode, z-index layers, Tailwind v4 migration
references/token-values.md — Complete light/dark OKLCH token value table
references/registry.md — shadcn registry setup, npm vs registry, bundles, troubleshooting
references/motion.md — motion/react presets, AnimatePresence, springs, reduced motion
references/forms.md — Field, FormControl, Form (react-hook-form), InputGroup patterns
references/input-components.md — Input, Textarea, Checkbox, RadioGroup, Switch, Select API
references/overlays.md — Dialog, AlertDialog, Sheet, Popover, Tooltip, DropdownMenu
references/sheet-stacking.md — SheetStackProvider modes, useSheetStack, nested sheets
references/dropdown-menu-api.md — DropdownMenu sub-component props reference
references/layout.md — Sidebar, Tabs, Breadcrumb, Pagination, Stepper, Collapsible, Resizable
references/sidebar-api.md — Sidebar sub-component props, CSS variables, cookie persistence
references/data-display.md — Table, Badge, Alert, Avatar, Skeleton, Progress, Toast, effects
references/advanced-inputs.md — Autocomplete, Combobox, MultiSelect, Tags, RecordPicker, Calendar, JsonInput
references/combobox-api.md — Combobox sub-component props, multiple mode, useComboboxFilter
references/command-palette.md — Full command palette system: registry, hooks, multi-step wizards, background tasks, keyboard shortcuts
references/card-patterns.md — Card variants (default/elevated/flat/ghost/interactive), usage patterns, grid layouts
references/stack-navigation.md — iOS-style card navigation: CardStackApi, route registry, peek gestures, mobile behavior

constructive-ui

Constructive UI

When to Apply

Quick Start

Deep Import Convention

PortalRoot Setup (Required)

Toaster Setup

Component Architecture

Theming & Tokens

Key Tokens

Dark Mode

Tailwind v4 Migration

Registry Installation

Animation System

Forms

Overlays

Layout & Navigation

Stack Navigation (iOS-Style Card Navigation)

Data Display & Feedback

Advanced Inputs

Component Catalog

Primitives

Form

Overlay

Layout

Data

Advanced Inputs

Notifications

Navigation

Utilities

Effects

Best Practices

References