Getting Started

Installation

Add Ladom UI to a Next.js app with the ladom-ui CLI: it copies the tokens, the components and the icons into your code.

Requirements

Node 20 or later for the CLI, React 19, and a bundler that handles CSS Modules. Next.js 15 or later works without any configuration.

1. Set up the folder

init writes ladom-ui.json and copies the tokens to components/ladom (change it with --dir). The files are yours: read them, change them, commit them.

npx ladom-ui init

2. Load the tokens and the font

Import the tokens once at the root and load Hanken Grotesk as --font-hanken-grotesk on <html>. Give the body the background and text tokens.

// app/layout.tsx
import { Hanken_Grotesk } from 'next/font/google';
import '@/components/ladom/tokens/index.css';

const hankenGrotesk = Hanken_Grotesk({
  subsets: ['latin', 'latin-ext'],
  variable: '--font-hanken-grotesk',
});

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" className={hankenGrotesk.variable}>
      <body style={{ background: 'var(--color-surface-background)', color: 'var(--color-foreground-high-emphasis)' }}>
        {children}
      </body>
    </html>
  );
}

3. Add components

add copies the components you name, the parts they need and their icons, and keeps components/ladom/index.ts up to date.

npx ladom-ui add button input form-field

Pro components

Components marked Pro need a license key; pass it in LADOM_UI_KEY. See the license.

LADOM_UI_KEY=ldm_pro_… npx ladom-ui add accordion navigation

4. Use them

Import everything from the folder. Components work in server and client components; the interactive ones are client components already.

// app/page.tsx
import { Button, FormField, IconAdd, Input } from '@/components/ladom';

export default function Page() {
  return (
    <form>
      <FormField label="Project name" hint="You can change it later">
        <Input name="name" />
      </FormField>
      <Button type="submit" iconLeft={IconAdd}>Create project</Button>
    </form>
  );
}

Toasts

Toasts need a ToastProvider around the app; put it in a client component and render it from the layout.

// app/providers.tsx
'use client';
import { ToastProvider } from '@/components/ladom';

export function Providers({ children }: { children: React.ReactNode }) {
  return <ToastProvider closeLabel="Close">{children}</ToastProvider>;
}

More icons

Components bring the icons they use. For your own code, copy more by name:

npx ladom-ui icons share calendar

Updating

Updates are not pushed to your project; you pull them. The CLI remembers every file it wrote, so update replaces the files you have not touched and keeps the ones you changed. diff shows how your copy differs from the latest; --overwrite takes the latest anyway.

npx ladom-ui list      # shows (update available)
npx ladom-ui update    # updates the files you have not changed
npx ladom-ui diff button
npx ladom-ui update button --overwrite

5. Themes and modes

Set the modes on <html>. Device modes follow the window width (Mobile below 768px, Tablet below 1280px) unless data-device forces one.

<html data-theme="dark">          {/* Dark theme (opt-in) */}
<html data-density="narrow">      {/* Narrow density */}
<html data-device="mobile">       {/* force a device mode; otherwise it follows the width */}

Your own styles

Use the tokens in your CSS so your screens follow the same scale and themes. Every token is listed under Foundations.

.card {
  padding: var(--space-medium);
  border-radius: var(--radius-card);
  background: var(--color-surface-level-1);
  box-shadow: var(--shadow-card-style-1);
  font: var(--text-ui-text-regular);
}

Other bundlers (Vite)

Outside Next.js, import with relative paths, load the font any way you like and set the variable yourself:

// main.tsx
import './components/ladom/tokens/index.css';
import '@fontsource-variable/hanken-grotesk';

document.documentElement.style.setProperty('--font-hanken-grotesk', "'Hanken Grotesk Variable'");

With Claude

A Claude Code skill, ladom-ui, teaches Claude the components, the tokens and the rules. npx ladom-ui skill adds it to your project’s .claude/skills folder.

Browse the components; each page has a playground and the API.