@krazdesign/core

Core UI components, theme system, and utilities for the Kraz design system. For project setup, see Quick Start below.

Building with an AI agent? Add the CLI, then run init:

npm install -D @krazdesign/cli   # or: pnpm add -D / yarn add -D / bun add -d
npx kraz init                    # resolves to the CLI you just installed

init writes the Kraz component index into your AGENTS.md/CLAUDE.md so your agent discovers components, templates, and design tokens instead of guessing. Need a single command without installing? Use the scoped package directly — npx @krazdesign/cli <cmd> (or pnpm dlx/bunx @krazdesign/cli). Bare npx kraz only works once @krazdesign/cli is a dependency; before that npm resolves it to an unrelated package. See XDS CLI.

Component Docs

Look up any component's full API (props, variants, examples, best practices, and theming) via the Kraz CLI:

npx @krazdesign/cli init                   # one-time: writes the component guide into AGENTS.md / CLAUDE.md
npx @krazdesign/cli component Button        # full docs for a component
npx @krazdesign/cli component --list        # list all components

Use the scoped @krazdesign/cli to run without installing; bare npx kraz only resolves once the CLI is a dependency.

Page Layouts

Building a full page? Start with a template rather than composing from scratch. Templates are content-only; they compose Layout with header, content, and panel slots into common page patterns (dashboards, settings, forms, detail pages). Wrap them in your own app chrome (AppShell, TopNav, SideNav) to add global navigation.

Requires @krazdesign/cli (npm install -D @krazdesign/cli):

kraz template --list              # browse all page and block templates
kraz template dashboard           # emit full page source
kraz template settings --skeleton # layout skeleton with spatial annotations

Kraz CLI

The CLI (@krazdesign/cli) provides additional tooling:

kraz --help                       # full listing of all commands
kraz component Button             # full docs + related block templates
kraz docs                         # reference docs (principles, tokens, theming, styling)
kraz docs theme                   # theming guide (Theme, defineTheme, light/dark)
kraz docs tokens                  # spacing, color, radius, typography token reference
kraz init                         # initialize Kraz in your project
kraz theme build                  # build theme CSS for production
kraz swizzle Button               # eject component source for customization
kraz upgrade --apply              # run codemods to migrate between versions
kraz discover                     # discover external Kraz packages
kraz gap-report                   # report a missing capability

Prefix these with your runner: npx kraz … / pnpm exec kraz … once the CLI is installed, or npx @krazdesign/cli … to run without installing.

Related Packages

| Package | Description | | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | @krazdesign/cli | CLI tooling: component docs, templates, scaffolding, codemods | | @krazdesign/theme-neutral | Muted, minimal theme (Lucide icons) |

Resources

• Component Storybook
• GitHub Repository

Quick Start

Kraz requires React 19 or later (react and react-dom >= 19.0.0 are peer dependencies).

Install Kraz and a theme:

npm install @krazdesign/core @krazdesign/theme-neutral @stylexjs/stylex

Then pick your setup below based on your framework and styling approach.

Next.js (simplest)

The fastest way to get started. No build plugins, no PostCSS, no Babel config — Kraz ships pre-built CSS and JS, so you import three stylesheets (order matters) and wrap your app in a theme provider.

src/app/globals.css

@import '@krazdesign/core/reset.css';
@import '@krazdesign/core/kraz.css';
@import '@krazdesign/theme-neutral/theme.css';

The import order maps to the layer cascade: reset.css (@layer reset) → kraz.css component styles (@layer kraz-base) → theme.css token overrides (@layer kraz-theme).

src/app/providers.tsx

'use client';

import Link from 'next/link';
import {Theme} from '@krazdesign/core/theme';
import {LinkProvider} from '@krazdesign/core/Link';
import {neutralTheme} from '@krazdesign/theme-neutral/built';

export function Providers({children}: {children: React.ReactNode}) {
  return (
    <Theme theme={neutralTheme}>
      <LinkProvider component={Link}>{children}</LinkProvider>
    </Theme>
  );
}

src/app/layout.tsx

import './globals.css';
import {Providers} from './providers';

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

Next.js + Tailwind

No build plugins needed; Kraz ships pre-built CSS that works alongside Tailwind.

src/app/globals.css

@layer reset, theme, base, kraz-base, kraz-theme, components, utilities;

@import 'tailwindcss/theme.css' layer(theme);
@import 'tailwindcss/preflight.css' layer(base);
@import '@krazdesign/core/reset.css';
@import '@krazdesign/core/kraz.css';
@import '@krazdesign/theme-neutral/theme.css';
@import '@krazdesign/core/tailwind-theme.css';
@import 'tailwindcss/utilities.css' layer(utilities);

The tailwind-theme.css import maps system tokens to Tailwind utilities via @theme inline:

// Without the bridge — verbose:
<div className="rounded-[var(--radius-container)] bg-[var(--color-surface)] text-[var(--color-on-surface)]">

// With the bridge — just works:
<div className="rounded-lg bg-surface text-primary">

Some useful mappings:

| Tailwind class | Kraz token | | --------------------------------------------------------- | --------------------------------------------------- | | text-primary / text-secondary | --color-on-surface / --color-on-surface-variant | | bg-surface / bg-card / bg-body | --color-surface / card / body | | border-border / border-strong | --color-outline-variant / --color-outline | | bg-success / text-error / text-warning | Status tokens | | bg-blue-subtle / border-blue-ring / text-blue-vivid | Hue palette (×10 hues) | | rounded-sm / rounded-md / rounded-lg | --radius-inner / element / container | | shadow-sm / shadow-md / shadow-lg | --shadow-low / med / high |

Spacing references var(--spacing-1) as the base unit, so p-4 = 16px, matching Kraz's --spacing-4. Arbitrary values still work as an escape hatch: bg-[var(--color-surface)].

src/app/providers.tsx

'use client';

import Link from 'next/link';
import {Theme} from '@krazdesign/core/theme';
import {LinkProvider} from '@krazdesign/core/Link';
import {neutralTheme} from '@krazdesign/theme-neutral/built';

export function Providers({children}: {children: React.ReactNode}) {
  return (
    <Theme theme={neutralTheme}>
      <LinkProvider component={Link}>{children}</LinkProvider>
    </Theme>
  );
}

src/app/layout.tsx

import './globals.css';
import {Providers} from './providers';

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

That's it. Start using components:

import {Button} from '@krazdesign/core/Button';

export default function Page() {
  return <Button label="Hello Kraz" variant="primary" />;
}

Next.js + StyleX

Use the pre-built dist alongside StyleX for your own styles.

npm install @krazdesign/core @krazdesign/theme-neutral @stylexjs/stylex

src/app/globals.css

@import '@krazdesign/core/reset.css';
@import '@krazdesign/core/kraz.css';
@import '@krazdesign/theme-neutral/theme.css';

Providers and layout are the same as the Tailwind example (use @krazdesign/theme-neutral/built).

Vite

npm install @krazdesign/core @krazdesign/theme-neutral @stylexjs/stylex

Same CSS imports and providers as above. No build plugins needed; Kraz ships pre-built.

No build step (CDN)

For prototypes, embeds, or pages without a bundler, load the components straight from a public CDN as ES modules. React 19 removed its UMD builds ("To load React 19 with a script tag, we recommend using an ESM-based CDN such as esm.sh"), so an import map is the way in — there is no window.React left for a global bundle to bind to.

The CLI writes this page for you, annotated and pinned to the version you have installed:

npx kraz template --cdn        # writes cdn.template.html

<!doctype html>
<html lang="en" data-kraz-theme="neutral">
  <head>
    <meta charset="utf-8" />
    <link
      rel="stylesheet"
      href="https://fonts.googleapis.com/css2?family=Figtree:wght@400;500;600;700&display=swap" />
    <link
      rel="stylesheet"
      href="https://cdn.jsdelivr.net/npm/@krazdesign/[email protected]/src/reset.css" />
    <link
      rel="stylesheet"
      href="https://cdn.jsdelivr.net/npm/@krazdesign/[email protected]/dist/kraz.css" />
    <link
      rel="stylesheet"
      href="https://cdn.jsdelivr.net/npm/@krazdesign/[email protected]/dist/theme.css" />
    <script type="importmap">
      {
        "imports": {
          "react": "https://esm.sh/[email protected]",
          "react/jsx-runtime": "https://esm.sh/[email protected]/jsx-runtime",
          "react-dom": "https://esm.sh/[email protected]",
          "react-dom/client": "https://esm.sh/[email protected]/client",
          "@krazdesign/core": "https://esm.sh/@krazdesign/[email protected]?external=react,react-dom"
        }
      }
    </script>
    <style>
      body {
        font-family: var(--font-family-body);
      }
    </style>
  </head>
  <body>
    <div id="root"></div>
    <script type="module">
      import * as React from 'react';
      import {createRoot} from 'react-dom/client';
      import {Card, Stack, Heading, Text, Button} from '@krazdesign/core';
      const e = React.createElement;
      createRoot(document.getElementById('root')).render(
        e(
          Stack,
          {padding: 6, align: 'start'},
          e(
            Card,
            {maxWidth: 480, elevation: 'low'},
            e(
              Stack,
              {gap: 3, align: 'start'},
              e(Heading, {level: 1}, 'Hello from a CDN'),
              e(Text, null, 'No bundler, no install, no build step.'),
              e(Button, {variant: 'primary', label: 'Try me'}),
            ),
          ),
        ),
      );
    </script>
  </body>
</html>

Six details carry the whole recipe:

• data-kraz-theme on <html>. Theme CSS is scoped to that attribute, so without it the page renders with the built-in defaults instead of the theme you just loaded.
• ?external=react,react-dom. Without it esm.sh bundles its own React and every hook throws Cannot read properties of null (reading 'useState').
• react/jsx-runtime in the import map. The published bundle imports it; omit the entry and the page dies with Failed to resolve module specifier.
• A font on body. Nothing in the three stylesheets sets a document font: the theme styles prose elements and each component styles itself, and Button is font: inherit. Without that one declaration its label renders in the browser's default serif.
• The webfont itself. The theme names Figtree; it never loads it. Without the Google Fonts link every viewer silently gets the next family in the stack.
• No JSX. Nothing is compiling this file, so elements are created with React.createElement.

Pin every version. Unversioned CDN URLs resolve to the latest release and are cached aggressively (0.4.5 above is a real pin; kraz template --cdn writes yours). The raw ESM entry (dist/index.js) uses bare react imports and will not run from a plain <script src> — the import map is what makes those specifiers resolvable.