jem-ui-components

Complete reference for AI agents consuming @jem-open/jem-ui in application projects. Covers every component's props, variants, and design tokens so you use the library correctly instead of recreating what already exists.

Step 1 — Check prerequisites

Verify the consuming project is set up to use jem-ui.

Check 1: Package installed

Look for @jem-open/jem-ui in package.json dependencies or devDependencies.

If not found, install it:

npm install @jem-open/jem-ui

Peer dependencies required: react@^18 | ^19, react-dom@^18 | ^19, tailwindcss@^3.4.

Check 2: Styles imported

The app entry point (e.g. layout.tsx, _app.tsx, or main.tsx) must import jem-ui styles:

import "@jem-open/jem-ui/styles.css"

If missing, add it.

Check 3: Tailwind preset configured

tailwind.config.js (or .ts) must include the jem-ui preset and content path:

const jemPreset = require("@jem-open/jem-ui/tailwind-preset");

module.exports = {
  presets: [jemPreset],
  content: [
    "./src/**/*.{ts,tsx}",
    "./node_modules/@jem-open/jem-ui/dist/**/*.{js,mjs}",
  ],
};

If missing, add both the preset and the content path.

Halt if any check fails and cannot be auto-fixed.

Step 2 — Identify needed components

Before writing any UI code, scan this catalog to find existing components that match your needs. Do not recreate components that already exist in the library.

All components are imported from @jem-open/jem-ui:

import { ComponentName } from "@jem-open/jem-ui"

Forms

Navigation

Data Display

Feedback

Design Tokens

Utilities

Step 3 — Use components correctly

Detailed reference for each component. Organized by category.

Forms

Button

import { Button } from "@jem-open/jem-ui"

Props: extends React.ComponentProps<"button">

Example:

<Button variant="primary" size="medium" leftIcon={<Plus />}>
  Add item
</Button>

asChild example (Button as link):

<Button asChild variant="outline">
  <a href="/settings">Settings</a>
</Button>

IconButton

import { IconButton } from "@jem-open/jem-ui"

Props: extends React.ComponentProps<"button">

Example:

<IconButton icon={<Trash2 />} shape="circle" aria-label="Delete item" />

Note: Always provide aria-label for accessibility since there is no visible text.

Input

import { Input } from "@jem-open/jem-ui"

Props: extends React.ComponentProps<"input">

No additional props beyond standard HTML input attributes.

Example:

<Input type="email" placeholder="Enter email" />

InputField

import { InputField } from "@jem-open/jem-ui"

Props: extends Input props

Example:

<InputField
  label="Email"
  description="We'll never share your email"
  helperText={errors.email}
  error={!!errors.email}
  type="email"
  placeholder="name@example.com"
/>

SearchInput

import { SearchInput } from "@jem-open/jem-ui"

Props: extends Input props

Shows a search icon on the left and a clear (X) button when there is a value.

Example:

const [query, setQuery] = useState("")

<SearchInput
  value={query}
  onChange={(e) => setQuery(e.target.value)}
  onClear={() => setQuery("")}
  placeholder="Search..."
/>

Checkbox

import { Checkbox } from "@jem-open/jem-ui"

Props: extends React.ComponentProps<typeof CheckboxPrimitive.Root> (Radix)

Standard Radix checkbox props: checked, onCheckedChange, disabled, name, value.

Example:

<Checkbox checked={agreed} onCheckedChange={setAgreed} />

CheckboxWithLabel

import { CheckboxWithLabel } from "@jem-open/jem-ui"

Plus all Checkbox props.

Example:

<CheckboxWithLabel
  label="Accept terms"
  description="You agree to our terms of service"
  checked={agreed}
  onCheckedChange={setAgreed}
/>

CheckboxCard

import { CheckboxCard } from "@jem-open/jem-ui"

Same props as CheckboxWithLabel but renders as a card-style container.

Example:

<CheckboxCard
  label="Email notifications"
  description="Receive email updates about your account"
  checked={emailNotifs}
  onCheckedChange={setEmailNotifs}
/>

RadioGroup / RadioGroupItem

import { RadioGroup, RadioGroupItem } from "@jem-open/jem-ui"

RadioGroup props: extends React.ComponentProps<typeof RadioGroupPrimitive.Root> (Radix)

• value, onValueChange, disabled, name
• Layout: grid with gap-3

RadioGroupItem props: extends Radix RadioGroup.Item

• value (required)

Example:

<RadioGroup value={plan} onValueChange={setPlan}>
  <RadioGroupItem value="free" />
  <RadioGroupItem value="pro" />
  <RadioGroupItem value="enterprise" />
</RadioGroup>

Also available: RadioGroupItemWithLabel (adds label and description props) and RadioGroupCard (card-style).

RadioGroupItemWithLabel example:

<RadioGroup value={plan} onValueChange={setPlan}>
  <RadioGroupItemWithLabel value="free" label="Free" description="Basic features" />
  <RadioGroupItemWithLabel value="pro" label="Pro" description="All features" />
</RadioGroup>

Select (compound)

import {
  Select, SelectTrigger, SelectContent, SelectItem, SelectValue
} from "@jem-open/jem-ui"

Composable compound component. Must be assembled from parts:

Example:

<Select value={role} onValueChange={setRole}>
  <SelectTrigger>
    <SelectValue placeholder="Select role" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="admin">Admin</SelectItem>
    <SelectItem value="editor">Editor</SelectItem>
    <SelectItem value="viewer">Viewer</SelectItem>
  </SelectContent>
</Select>

Also available: SelectField wraps Select with label and description:

<SelectField label="Role" description="User's permission level">
  <Select value={role} onValueChange={setRole}>
    {/* ... same inner content */}
  </Select>
</SelectField>

Additional parts: SelectGroup, SelectLabel, SelectSeparator, SelectScrollUpButton, SelectScrollDownButton.

DatePicker

import { DatePicker } from "@jem-open/jem-ui"

Example:

<DatePicker
  label="Start date"
  date={startDate}
  onDateChange={setStartDate}
  placeholder="Pick a date"
/>

DateRangePicker

import { DateRangePicker } from "@jem-open/jem-ui"

Shows 2 months side by side. Format: "LLL dd, y" (e.g. "Mar 09, 2026").

Example:

<DateRangePicker
  label="Date range"
  dateRange={range}
  onDateRangeChange={setRange}
  placeholder="Select range"
/>

Calendar

import { Calendar } from "@jem-open/jem-ui"

Standalone calendar component. Props extend React DayPicker. Usually used inside DatePicker — use DatePicker instead unless you need a custom calendar layout.

Example:

<Calendar mode="single" selected={date} onSelect={setDate} />

Textarea / TextareaField

import { Textarea } from "@jem-open/jem-ui"

Textarea props: extends React.ComponentProps<"textarea">. Min height: 115px. Resize disabled.

TextareaField adds form wrapper props:

Example:

<TextareaField
  label="Notes"
  helperText="Max 500 characters"
  placeholder="Enter your notes..."
/>

Switch / SwitchWithLabel

import { Switch } from "@jem-open/jem-ui"

Switch props: extends Radix Switch. Key props: checked, onCheckedChange, disabled.

Checked: pink-900 background. Unchecked: slate-200.

SwitchWithLabel adds label and description props:

<SwitchWithLabel
  label="Dark mode"
  description="Use dark theme across the app"
  checked={darkMode}
  onCheckedChange={setDarkMode}
/>

Label

import { Label } from "@jem-open/jem-ui"

Radix-based label that properly associates with form inputs via htmlFor.

Example:

<Label htmlFor="email">Email address</Label>
<Input id="email" type="email" />

Note: InputField, TextareaField, SelectField, CheckboxWithLabel, and SwitchWithLabel handle labeling automatically. Use Label only when building custom form layouts.

Upload

import { Upload } from "@jem-open/jem-ui"

Example:

<Upload
  state={uploadState}
  progress={uploadProgress}
  fileName={file?.name}
  title="Upload document"
  description="PDF, DOC, or DOCX"
  maxSize="10MB"
  onSelectFile={handleSelectFile}
  onRemoveFile={handleRemoveFile}
  onSubmit={handleSubmit}
/>

Navigation

Accordion (compound)

import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from "@jem-open/jem-ui"

Accordion props: extends Radix Accordion.Root. Key props: type ("single" | "multiple"), collapsible, value, onValueChange.

Example:

<Accordion type="single" collapsible>
  <AccordionItem value="item-1">
    <AccordionTrigger>Section 1</AccordionTrigger>
    <AccordionContent>Content for section 1</AccordionContent>
  </AccordionItem>
  <AccordionItem value="item-2">
    <AccordionTrigger>Section 2</AccordionTrigger>
    <AccordionContent>Content for section 2</AccordionContent>
  </AccordionItem>
</Accordion>

Trigger text turns pink on hover and when open. ChevronDown icon rotates.

Tabs (compound)

import { Tabs, TabsList, TabsTrigger, TabsContent } from "@jem-open/jem-ui"

TabsList variants:

TabsTrigger variants: matches TabsList — use variant="line" on both for line style.

Example (default):

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

Example (line variant):

<Tabs defaultValue="overview">
  <TabsList variant="line">
    <TabsTrigger variant="line" value="overview">Overview</TabsTrigger>
    <TabsTrigger variant="line" value="details">Details</TabsTrigger>
  </TabsList>
  <TabsContent value="overview">Overview content</TabsContent>
  <TabsContent value="details">Details content</TabsContent>
</Tabs>

Breadcrumb (compound)

import {
  Breadcrumb, BreadcrumbList, BreadcrumbItem, BreadcrumbLink,
  BreadcrumbPage, BreadcrumbSeparator
} from "@jem-open/jem-ui"

BreadcrumbSeparator accepts variant: "chevron" (default) or "slash".

BreadcrumbLink supports asChild for use with router links.

Example:

<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="/">Home</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbLink href="/settings">Settings</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbPage>Profile</BreadcrumbPage>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>

Pagination (compound)

import {
  Pagination, PaginationContent, PaginationItem,
  PaginationLink, PaginationPrevious, PaginationNext, PaginationEllipsis
} from "@jem-open/jem-ui"

PaginationLink props: isActive (boolean) — active page gets outline variant with border. size from Button.

Example:

<Pagination>
  <PaginationContent>
    <PaginationItem>
      <PaginationPrevious href="#" />
    </PaginationItem>
    <PaginationItem>
      <PaginationLink href="#" isActive>1</PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationLink href="#">2</PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationEllipsis />
    </PaginationItem>
    <PaginationItem>
      <PaginationNext href="#" />
    </PaginationItem>
  </PaginationContent>
</Pagination>

Link

import { Link } from "@jem-open/jem-ui"

Plus standard anchor attributes.

Example:

<Link href="/privacy" variant="muted" size="sm">Privacy Policy</Link>

Data Display

DataTable (compound)

import { DataTable, DataTableColumnHeader } from "@jem-open/jem-ui"

Uses TanStack React Table. Requires defining columns with ColumnDef.

DataTableColumnHeader enables sorting. Use it in column header definitions.

Example:

import { ColumnDef } from "@tanstack/react-table"

type User = { name: string; email: string; status: string }

const columns: ColumnDef<User>[] = [
  {
    accessorKey: "name",
    header: ({ column }) => <DataTableColumnHeader column={column} title="Name" />,
  },
  {
    accessorKey: "email",
    header: ({ column }) => <DataTableColumnHeader column={column} title="Email" />,
  },
  {
    accessorKey: "status",
    header: "Status",
    cell: ({ row }) => <Tag variant="success">{row.getValue("status")}</Tag>,
  },
]

<DataTable columns={columns} data={users} filterColumn="name" filterPlaceholder="Filter by name..." />

Table (compound)

import {
  Table, TableHeader, TableBody, TableRow, TableHead, TableCell
} from "@jem-open/jem-ui"

Primitive table elements for custom table layouts. Use DataTable for most cases.

Example:

<Table>
  <TableHeader>
    <TableRow>
      <TableHead>Name</TableHead>
      <TableHead>Status</TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell>Alice</TableCell>
      <TableCell>Active</TableCell>
    </TableRow>
  </TableBody>
</Table>

Additional parts: TableCaption, TableFooter.

Tag / DismissibleTag / CountTag

import { Tag, DismissibleTag, CountTag } from "@jem-open/jem-ui"

Tag variants:

Tag example:

<Tag variant="success">Active</Tag>
<Tag variant="pending">Pending review</Tag>

DismissibleTag adds onDismiss callback:

<DismissibleTag variant="default" onDismiss={() => removeTag(id)}>
  Filter: Active
</DismissibleTag>

CountTag — small pink circle with white number:

<CountTag>3</CountTag>

Avatar (compound)

import { Avatar, AvatarImage, AvatarFallback } from "@jem-open/jem-ui"

Avatar sizes:

Example:

<Avatar size="lg">
  <AvatarImage src="/user.jpg" alt="Jane Doe" />
  <AvatarFallback size="lg">JD</AvatarFallback>
</Avatar>

Note: Pass size to both Avatar and AvatarFallback to keep dimensions consistent.

AvatarBadge — online/status indicator (green dot, absolute positioned):

<Avatar>
  <AvatarImage src="/user.jpg" alt="Jane Doe" />
  <AvatarFallback>JD</AvatarFallback>
  <AvatarBadge />
</Avatar>

AvatarGroup / AvatarGroupCount — stacked avatars:

<AvatarGroup>
  <Avatar><AvatarFallback>AB</AvatarFallback></Avatar>
  <Avatar><AvatarFallback>CD</AvatarFallback></Avatar>
  <Avatar><AvatarFallback>EF</AvatarFallback></Avatar>
  <AvatarGroupCount>+5</AvatarGroupCount>
</AvatarGroup>

Progress

import { Progress } from "@jem-open/jem-ui"

Props: extends Radix Progress. Key prop: value (0-100).

Height: 6px. Indicator: secondary-pink-900.

Example:

<Progress value={65} />

Divider

import { Divider } from "@jem-open/jem-ui"

Example:

<Divider spacing="md" />
<Divider label="OR" variant="subtle" spacing="lg" />

Skeleton

import { Skeleton } from "@jem-open/jem-ui"

Loading placeholder. Apply width/height via className.

Example:

<Skeleton className="h-12 w-full" />
<Skeleton className="h-4 w-3/4" />

Feedback

Dialog (compound)

import {
  Dialog, DialogTrigger, DialogContent, DialogHeader,
  DialogTitle, DialogDescription, DialogFooter, DialogClose
} from "@jem-open/jem-ui"

DialogContent props:

Max width: max-w-md. Border radius: rounded-2xl.

DialogTitle variants:

Example:

<Dialog>
  <DialogTrigger asChild>
    <Button>Open dialog</Button>
  </DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Edit profile</DialogTitle>
      <DialogDescription>Make changes to your profile here.</DialogDescription>
    </DialogHeader>
    {/* Form content */}
    <DialogFooter>
      <DialogClose asChild>
        <Button variant="outline">Cancel</Button>
      </DialogClose>
      <Button variant="primary">Save</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>

Also available: DialogContact (shows email link, default "support@example.com").

Drawer (compound)

import {
  Drawer, DrawerTrigger, DrawerContent, DrawerHeader,
  DrawerBody, DrawerFooter, DrawerTitle, DrawerClose
} from "@jem-open/jem-ui"

Drawer props:

DrawerHeader props: showCloseButton (default: true). Background: secondary-pink-50.

DrawerContent: max-w-[455px] for left/right, max-h-[80vh] for top/bottom.

Example:

<Drawer direction="right">
  <DrawerTrigger asChild>
    <Button variant="outline">View details</Button>
  </DrawerTrigger>
  <DrawerContent>
    <DrawerHeader>
      <DrawerTitle>User Details</DrawerTitle>
    </DrawerHeader>
    <DrawerBody>
      {/* Detail content */}
    </DrawerBody>
    <DrawerFooter>
      <Button variant="primary">Edit</Button>
      <DrawerClose asChild>
        <Button variant="outline">Close</Button>
      </DrawerClose>
    </DrawerFooter>
  </DrawerContent>
</Drawer>

Also available: DrawerSection (groups content within DrawerBody), DrawerDescription.

DropdownMenu (compound)

import {
  DropdownMenu, DropdownMenuTrigger, DropdownMenuContent,
  DropdownMenuItem, DropdownMenuSeparator
} from "@jem-open/jem-ui"

DropdownMenuItem props:

Example:

<DropdownMenu>
  <DropdownMenuTrigger asChild>
    <IconButton icon={<MoreHorizontal />} aria-label="Actions" />
  </DropdownMenuTrigger>
  <DropdownMenuContent>
    <DropdownMenuItem>Edit</DropdownMenuItem>
    <DropdownMenuItem>Duplicate</DropdownMenuItem>
    <DropdownMenuSeparator />
    <DropdownMenuItem variant="destructive">Delete</DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>

Additional parts for selection: DropdownMenuCheckboxItem, DropdownMenuRadioGroup, DropdownMenuRadioItem. Nested menus: DropdownMenuSub, DropdownMenuSubTrigger, DropdownMenuSubContent. Grouping: DropdownMenuGroup, DropdownMenuLabel. Keyboard shortcuts: DropdownMenuShortcut.

Tooltip (compound)

import { Tooltip, TooltipProvider, TooltipTrigger, TooltipContent } from "@jem-open/jem-ui"

TooltipContent variants:

Important: Wrap your app or layout in <TooltipProvider> once. Tooltips won't render without it.

Example:

// In layout.tsx — add once
<TooltipProvider>
  {children}
</TooltipProvider>

// In any component
<Tooltip>
  <TooltipTrigger asChild>
    <IconButton icon={<Info />} aria-label="More info" />
  </TooltipTrigger>
  <TooltipContent variant="dark">
    Additional information here
  </TooltipContent>
</Tooltip>

Popover (compound)

import { Popover, PopoverTrigger, PopoverContent } from "@jem-open/jem-ui"

PopoverContent props: align (default: "center"), sideOffset (default: 4).

Example:

<Popover>
  <PopoverTrigger asChild>
    <Button variant="outline">Options</Button>
  </PopoverTrigger>
  <PopoverContent align="start">
    {/* Popover content */}
  </PopoverContent>
</Popover>

Also available: PopoverAnchor, PopoverHeader, PopoverTitle, PopoverDescription.

Alert (compound)

import { Alert, AlertTitle, AlertDescription } from "@jem-open/jem-ui"

Alert variants (each has an automatic icon):

Example:

<Alert variant="warning">
  <AlertTitle>Warning</AlertTitle>
  <AlertDescription>Your session will expire in 5 minutes.</AlertDescription>
</Alert>

EmptyState

import { EmptyState } from "@jem-open/jem-ui"

Variants:

Sizes: sm (max-w-sm), md (max-w-md, default), lg (max-w-lg)

Props:

Example:

<EmptyState
  icon="search"
  title="No results found"
  description="Try adjusting your search or filters"
  primaryAction={{ label: "Clear filters", onClick: clearFilters }}
  variant="card"
/>

Pre-configured variants: EmptyStateNotFound, EmptyStateNoResults, EmptyStateNoData.

Toaster

import { Toaster } from "@jem-open/jem-ui"

Add <Toaster /> once in your root layout. Trigger toasts using toast() from the sonner package:

// layout.tsx
import { Toaster } from "@jem-open/jem-ui"

export default function Layout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Toaster />
      </body>
    </html>
  )
}

// any component
import { toast } from "sonner"

toast.success("Changes saved")
toast.error("Something went wrong")
toast.info("New update available")
toast.warning("Disk space low")

Icons are pre-configured: success (PartyPopper), error (TriangleAlert), info (Bell), warning (TriangleAlert), loading (Loader2 spinning).

Design Tokens (components)

Icon

import { Icon } from "@jem-open/jem-ui"

Sizes:

Example:

import { Icon } from "@jem-open/jem-ui"
import { Settings } from "lucide-react"

<Icon icon={Settings} size="lg" label="Settings" />

Re-exported Lucide icons available from @jem-open/jem-ui: X, Menu, Check, ChevronDown, ChevronUp, ChevronLeft, ChevronRight, Home, Settings, Calendar, Users, Info, CircleAlert, AlertTriangle, Bell, Edit, Trash2, Download, Upload, Copy, Plus, Minus, Search, Filter, Eye, EyeOff, ArrowUp, ArrowDown, ArrowLeft, ArrowRight, ExternalLink, MoreHorizontal, MoreVertical, RefreshCw, Loader2.

PrimaryLogo

import { PrimaryLogo } from "@jem-open/jem-ui"

Example:

<PrimaryLogo variant="bg-white" size="lg" />

SecondaryLogoRound

import { SecondaryLogoRound } from "@jem-open/jem-ui"

SecondaryLogoSquare

import { SecondaryLogoSquare } from "@jem-open/jem-ui"

Same props as SecondaryLogoRound.

Step 4 — Apply design tokens

Use these design tokens for consistent styling. Always prefer semantic tokens over raw color values.

Colors — Semantic tokens

Use semantic tokens for all UI colors. These adapt correctly across themes.

Colors — Base palette

Use sparingly. Prefer semantic tokens above. Available for decorative/custom elements only.

Usage: bg-navy-100, text-pink-900, border-green-500, etc.

Spacing

These tokens work with all Tailwind spacing utilities: p-, px-, py-, m-, mx-, my-, gap-, space-x-, space-y-, w-, h-, etc.

Typography

Font families:

• font-heading — heading font (from --font-family-heading)
• font-body — body font (from --font-family-body)

Font sizes:

Font weights:

Border radius

Step 5 — Avoid common mistakes