Datum UI

Datum Cloud Design System & Component Library

---

About

Datum UI is Datum Cloud's design system and React component library. It provides themed, composable components built on shadcn/ui, Radix UI, and Tailwind CSS v4 with a Figma-driven design token pipeline.

Key Features

• 50+ Components — Buttons, forms, data tables, dialogs, maps, typography, navigation, and more
• Two-Layer Architecture — shadcn/Radix primitives (base) + Datum-customized components (features)
• Compound Form System — Built on Conform.js and Zod with validation, field arrays, and multi-step support
• Interactive Maps — SSR-safe Leaflet integration with drawing tools, layers, clustering, and fullscreen
• Task Queue — Background task engine with progress UI, retry logic, and summary dialogs
• Design Token Pipeline — Figma tokens → purpose tokens → theme classes
• Dark Mode — Built-in theme provider with system preference detection
• TypeScript — Fully typed with exported types for all components

Built With

• React 19 — Latest React with server component support
• Tailwind CSS v4 — Utility-first CSS framework
• Radix UI — Accessible, unstyled primitives
• shadcn/ui — Component foundation layer
• CVA — Class-variance-authority for variant-based component APIs
• Conform.js + Zod — Form state management and schema validation

---

Monorepo Structure

packages/
  datum-ui/        # Component library (@datum-cloud/datum-ui)
  shadcn/          # shadcn/ui primitives (@repo/shadcn)
  config/          # Shared config (TypeScript, Tailwind, ESLint)
apps/
  docs/            # Fumadocs documentation site
  storybook/       # Storybook component explorer

Package	Description	npm
@datum-cloud/datum-ui	Published component library
@repo/shadcn	Internal shadcn/ui primitives	—
@repo/config	Shared TypeScript, Tailwind, and ESLint config	—

---

Prerequisites

• Node.js >= 24 — Required for ESM module resolution with pnpm's strict dependency linking
• pnpm >= 10 — Monorepo package manager

Quick Start (Development)

# Clone and install
git clone https://github.com/datum-cloud/datum-ui.git
cd datum-ui
pnpm install

# Start Storybook (component explorer)
pnpm --filter @repo/storybook dev

# Start documentation site
pnpm --filter @repo/docs dev

# Build the component library
pnpm --filter @datum-cloud/datum-ui build

# Run all checks
pnpm --filter @datum-cloud/datum-ui typecheck
pnpm --filter @datum-cloud/datum-ui lint
pnpm --filter @datum-cloud/datum-ui test

Note: Apps auto-build @datum-cloud/datum-ui before starting via a predev script.

---

Usage (Consumers)

Install the package:

npm install @datum-cloud/datum-ui
# or
yarn add @datum-cloud/datum-ui
# or
pnpm add @datum-cloud/datum-ui
# or
bun add @datum-cloud/datum-ui

Add datum-ui styles to your CSS file, after Tailwind:

@import 'tailwindcss';
@import '@datum-cloud/datum-ui/styles';

Wrap your app with ThemeProvider for light/dark/system switching:

import { ThemeProvider } from '@datum-cloud/datum-ui/theme'
import { Button, Input } from '@datum-cloud/datum-ui'

function App() {
  return (
    <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
      <Input placeholder="Enter your name" />
      <Button type="primary" theme="solid">
        Submit
      </Button>
    </ThemeProvider>
  )
}

Entry Points

Import Path	Description
@datum-cloud/datum-ui	All components, hooks, and utilities
@datum-cloud/datum-ui/styles	CSS (fonts, tokens, theme variables, component styles)
@datum-cloud/datum-ui/theme	ThemeProvider, useTheme
@datum-cloud/datum-ui/hooks	useCopyToClipboard, useDebounce
@datum-cloud/datum-ui/icons	CloseIcon, IconWrapper, SpinnerIcon
@datum-cloud/datum-ui/utils	cn (className merge utility)

Peer Dependencies

All peer dependencies are optional — install only what you use.

Replace npm install with yarn add, pnpm add, or bun add for your package manager.

# Core (required)
npm install react react-dom

# Forms
npm install @conform-to/react @conform-to/zod zod

# Maps
npm install leaflet react-leaflet leaflet-draw leaflet.fullscreen leaflet.markercluster react-leaflet-markercluster

# Charts
npm install recharts

# Date pickers
npm install react-day-picker date-fns date-fns-tz

# Animations
npm install motion

See the full peer dependency list in the package README.

---

Component Overview

Base Components (30)

Thin wrappers around shadcn/Radix primitives with Datum styling.

Alert · Badge · Breadcrumb · Button · ButtonGroup · Calendar · Card · Chart · Checkbox · Collapsible · Command · Dialog · HoverCard · Input · InputGroup · Label · Map · PlaceAutocomplete · Popover · RadioGroup · Select · Separator · Sheet · Skeleton · Spinner · Switch · Table · Tabs · Textarea · Tooltip · Typography · VisuallyHidden

Feature Components (18)

Complex, fully-customized components with significant business logic.

Autocomplete · AvatarStack · CalendarDatePicker · Dropdown · Dropzone · EmptyContent · FileInputButton · Form · Grid · InputNumber · InputWithAddons · LoaderOverlay · MoreActions · NProgress · PageTitle · Sidebar · Stepper · TagInput · TaskQueue · TimeRangePicker · Toast

For the complete component API with props, sub-components, and usage examples, see the package README.

---

Documentation

• Package README — Full component catalog, API reference, and usage examples
• Documentation Site — Component docs, guides, and live previews
• Storybook — Interactive component explorer

---

Contributing

# 1. Create a feature branch
git checkout -b feat/my-feature

# 2. Make changes and verify
pnpm --filter @datum-cloud/datum-ui build
pnpm --filter @datum-cloud/datum-ui typecheck
pnpm --filter @datum-cloud/datum-ui lint
pnpm --filter @datum-cloud/datum-ui test

# 3. Add a changeset
pnpm changeset

# 4. Commit and push
git add .
git commit -m "feat: description of changes"
git push -u origin feat/my-feature

License

MIT