Getting Started | Kuzan | Primitives Docs
Primitives

Getting Started

Install and configure kuzan in your Koze application

Installation

npm install @kuratchi/kuzan

kuzan is a regular package — there is no framework-level wiring. Three steps to get a styled app: import the theme stylesheet, set the initial color scheme on <html>, and (optionally) drop in the theme-init script.

Add the theme stylesheet

Import kuzan/styles/theme.css from your global stylesheet at src/app.css:

/* src/app.css */
@import '@kuratchi/kuzan/styles/theme.css';

Koze auto-discovers src/app.css, runs every Vite CSS plugin on it, and injects <link rel="stylesheet"> into your app shell — you don't write the <link> tag.

Set the initial color scheme

Pick a default by setting a class on <html> in your layout:

<!-- src/routes/layout.koze -->
<!doctype html>
<html lang="en" class="dark">
  <!-- ... -->
</html>

Use class="dark" for dark mode, omit the class for light mode. The runtime can override this on first paint via the theme-init script (next section).

Initialize theme (optional)

To prevent flash of unstyled content (FOUC) when using theme persistence, add <ThemeInit /> to the layout's <head>:

<script>
  import ThemeInit from '@kuratchi/kuzan/theme-init.koze';
</script>

<!doctype html>
<html lang="en" class="dark">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>My App</title>
    <ThemeInit />
  </head>
  <body>
    <slot></slot>
  </body>
</html>

<ThemeInit /> reads the saved theme from localStorage['kui-theme'] and applies it before the page renders.

Using components

Import components as .koze files in your route scripts:

<script>
  import Badge from '@kuratchi/kuzan/badge.koze';
  import Card from '@kuratchi/kuzan/card.koze';
  import Alert from '@kuratchi/kuzan/alert.koze';
</script>

<h1>Welcome</h1>

<Alert data_variant="info">
  This is an informational alert.
</Alert>

<Card title="Getting Started">
  <p>Start building with Koze UI components.</p>
  <Badge data_variant="success">Active</Badge>
</Card>

Component props

Components accept props via the props object. Use underscores for data attributes:

<Badge data_variant="success">Live</Badge>
<Card title="My Card" data_compact>
  Content here
</Card>

Common props:

  • class — Add custom CSS classes
  • data_variant — Style variant (e.g., "primary", "danger", "success")
  • data_size — Size variant (e.g., "sm", "lg")
  • Boolean data attributes (e.g., data_compact, data_dismissible)

Semantic HTML defaults

kuzan styles semantic HTML elements, so you can build UIs without component imports:

<main>
  <header>
    <h1>Dashboard</h1>
    <p>Overview of your application</p>
  </header>

  <section>
    <article>
      <a href="/settings">
        <strong>Settings</strong>
        <small>Manage your account</small>
      </a>
    </article>
    <article>
      <a href="/profile">
        <strong>Profile</strong>
        <small>Update your information</small>
      </a>
    </article>
  </section>
</main>

Styled elements include:

  • <main> — Page container with max-width and padding
  • <header> — Sticky app header or page header
  • <section> — Card-like container with border
  • <article> — Row inside a section
  • <nav> — Horizontal navigation links
  • <button>, <input>, <select>, <textarea> — Form controls

Adding a theme toggle

Use the ThemeToggle component to let users switch between light and dark modes:

<script>
  import ThemeToggle from '@kuratchi/kuzan/theme-toggle.koze';
</script>

<header>
  <a href="/">My App</a>
  <ThemeToggle />
</header>

The toggle automatically:

  • Switches the .dark class on <html>
  • Persists the choice to localStorage under "kui-theme"
  • Updates all toggle instances on the page

Next steps