@l3mpire/ui

React component library for the lemDS design system. Built with CVA (Class Variance Authority), Tailwind CSS v4, and Radix UI primitives.

Installation

pnpm add @l3mpire/ui @l3mpire/tokens @l3mpire/icons

Peer dependencies:

pnpm add react react-dom @l3mpire/icons

Setup

1. Import the global stylesheet

In your app's root CSS file:

@import "@l3mpire/ui/globals.css";

This file:

• Imports all design tokens as CSS custom properties
• Registers tokens with Tailwind CSS v4's @theme
• Sets up dark mode via data-theme="dark" custom variant
• Defines component animations

2. Configure Tailwind (if using Tailwind in your project)

Add the UI package to your content sources so Tailwind can scan component classes:

@source "../node_modules/@l3mpire/ui/dist";

Usage

import { Button, Badge, TextInput, Toast } from "@l3mpire/ui";
import { Icon, faCheck } from "@l3mpire/icons";

function Example() {
  return (
    <>
      <Button appearance="solid" intent="brand" size="md" leftIcon={faCheck}>
        Confirm
      </Button>

      <Badge appearance="solid" intent="primary" size="md">
        New
      </Badge>

      <TextInput
        placeholder="Enter your email"
        size="md"
      />

      <Toast type="success" title="Saved!" description="Your changes have been saved." />
    </>
  );
}

Components

Actions

| Component | Variants | Description | |-----------|----------|-------------| | Button | appearance: solid, outlined, ghost | Primary action element | | | intent: brand, alert | | | | size: sm, md, lg | | | Link | variant: brand, neutral | Text link with hover/pressed states |

Data Display

| Component | Variants | Description | |-----------|----------|-------------| | Avatar | size: sm, md, lg, xl | User profile image with initials fallback | | | shape: rounded, squared | | | Badge | appearance: solid, light, outlined | Inline label / status indicator | | | intent: primary, success, critical, warning, neutral | | | Tag | variant: brand, neutral | Removable inline tag | | Tooltip | variant: default, invert | Contextual hover tooltip |

Feedback

| Component | Variants | Description | |-----------|----------|-------------| | InfoMessage | type: info, success, alert, warning, empty | Alert / notification banner | | Toast | type: info, success, alert, warning | Notification toast |

Forms

| Component | Description | |-----------|-------------| | Checkbox | Checkbox with label (Radix UI) | | InputLabel | Form label with optional/mandatory indicator | | SearchBar | Search input with magnifying glass icon | | Select | Custom dropdown select with chevron | | Switch | Toggle switch with label (Radix UI) | | TextArea | Multi-line input with character counter | | TextInput | Single-line input with icon and validation |

Data

| Component | Description | |-----------|-------------| | Table | Low-level table primitives (Header, Body, Row, Cell, Caption) | | DataTable | Data-driven table powered by TanStack Table | | | Features: sorting, filtering, pagination, row selection, column resizing, column drag reorder | | DataTablePagination | Pagination controls with page size selector | | EmptyState | Placeholder with icon, title, description, and optional action | | Cell Renderers | AvatarCell, StatusCell, NumberCell, DateCell, EmailCell, LinkCell, ButtonCell, EditableCell | | RowActions | Hover-reveal action buttons for table rows |

Navigation

| Component | Description | |-----------|-------------| | DropdownMenu | Menu with items, headings, sections, and clear action | | ProductLogo | Product logo with optional text | | Sidebar | Collapsible app sidebar with header, sections, footer | | SidebarItem | Navigation item with icon, badge, avatar support | | SidebarHeadingItem | Section heading label for sidebar | | Typography | Text component with variant presets | | UserMenu | User profile dropdown with info rows and sections |

Component Patterns

CVA Variants

All components use CVA for variant management:

<Button appearance="solid" intent="brand" size="md">Click me</Button>
<Button appearance="ghost" intent="brand" size="sm">Cancel</Button>

Polymorphic Rendering (asChild)

Components support the asChild prop via Radix UI's Slot, allowing you to render as any element:

<Button asChild>
  <a href="/dashboard">Go to Dashboard</a>
</Button>

Icons in Components

Pass FontAwesome icon definitions directly:

import { faPen, faTrash } from "@l3mpire/icons";

<Button leftIcon={faPen} size="md">Edit</Button>
<Button rightIcon={faTrash} intent="alert" size="md">Delete</Button>
<Button leftIcon={faPlus} iconOnly size="sm" />

Dark Mode

Toggle dark mode by setting the data-theme attribute:

<html data-theme="dark">

All component tokens automatically switch to their dark mode values.

Utility: cn()

A clsx + tailwind-merge utility is exported for combining classes:

import { cn } from "@l3mpire/ui";

<div className={cn("p-md rounded-base", isActive && "bg-blue-500")} />

Exports

Every component exports its React component, CVA variants function (when applicable), and TypeScript props type:

import {
  Button,
  buttonVariants,  // CVA variants function
  type ButtonProps, // TypeScript type
} from "@l3mpire/ui";

// Use buttonVariants() to get classes without rendering:
const classes = buttonVariants({ appearance: "solid", intent: "brand", size: "md" });

Storybook

Browse the full component documentation with interactive examples:

# From the monorepo root
pnpm --filter @l3mpire/storybook dev

Opens at http://localhost:6006.