# Set up Klarhimmel UI

You are a coding agent, and your person pointed you here to add Klarhimmel UI to their project. Do every step below in their project without asking, unless a step tells you to stop. It takes a few minutes. Klarhimmel UI is React components and page blocks on one set of design tokens, copied into the project as source with the shadcn CLI. It needs no account and no token.

## 1. Read the project

Read package.json and the config files, then pick the case that fits:

- **Vite + React** or **Next.js** (app or pages router) with React 18 or 19: go on.
- **An empty folder**: create a Vite app first with `npm create vite@latest . -- --template react-ts` and `npm install`, then go on.
- **Tailwind CSS v3** (a tailwind.config.js and `@tailwind base;` in the CSS): stop and ask your person whether to move to Tailwind v4 first. The blocks use v4.
- **No React** (plain HTML, Vue, Svelte, Astro without React): stop and tell your person Klarhimmel UI is for React.

Note two paths for the steps below. SRC is where the source lives: `src/` for Vite and for Next with a src folder, the project root for Next without one. CSS is the main style sheet: `src/index.css` for Vite, `app/globals.css` or `src/app/globals.css` for Next.

## 2. Tailwind CSS v4, only if it is missing

Vite:

```
npm i tailwindcss @tailwindcss/vite

// vite.config.ts
import tailwindcss from '@tailwindcss/vite';
plugins: [react(), tailwindcss()]
```

Next.js: `npm i tailwindcss @tailwindcss/postcss`, a `postcss.config.mjs` of `export default { plugins: { '@tailwindcss/postcss': {} } };`, and `@import 'tailwindcss';` at the top of CSS.

## 3. The @/ alias

Every Klarhimmel file imports from `@/components/klarhimmel/`. Next.js usually maps `@/*` already: check tsconfig.json. Vite does not:

```
// tsconfig.json and tsconfig.app.json, inside "compilerOptions"
"paths": { "@/*": ["./src/*"] }

// vite.config.ts
import path from 'node:path';
resolve: { alias: { '@': path.resolve(import.meta.dirname, './src') } }
```

Vite's root tsconfig.json often has no compilerOptions block: add one with just `paths`. Use `./*` instead of `./src/*` when SRC is the project root. Do not add baseUrl.

## 4. components.json

Create it in the project root; `shadcn init` is not needed. If the project already has one, add only the `registries` entry and keep the rest. Set `tailwind.css` to the CSS path.

```json
{
  "style": "new-york",
  "tailwind": {
    "css": "src/index.css",
    "baseColor": "neutral",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils"
  },
  "registries": {
    "@klarhimmel": "https://ui.klarhimmel.com/r/{name}.json"
  }
}
```

## 5. Add a first block and the design skill

```
npx shadcn@latest add @klarhimmel/hero-split @klarhimmel/skill-design --yes
```

The block's files land in SRC/components/klarhimmel/, with the theme and everything it needs. The design skill lands in `.claude/skills/klarhimmel-design/SKILL.md`.

## 6. Import the tokens

In CSS, right after the Tailwind import, with the path relative to CSS. The tokens are scoped to .kh-root and never reset the project's own theme.

```css
@import 'tailwindcss';
@import './components/klarhimmel/theme/theme.css';
```

## 7. Put the block on the home page

The home page is `src/App.tsx` for Vite and `app/page.tsx` (or `pages/index.tsx`) for Next. If the page is still the starter's demo, replace it, and remove the starter's demo styles too: they box the page in (Vite's `#root` rules and the rest of its index.css below the imports, and App.css; Next's starter rules in globals.css below the Tailwind import). Leave a real page and its styles as they are.

```tsx
import { Theme } from '@/components/klarhimmel/theme/style';
import { BlockSurface } from '@/components/klarhimmel/blocks/surface';
import Hero, { spec } from '@/components/klarhimmel/blocks/hero-split';

<Theme theme="brand">
  <BlockSurface><Hero props={spec.defaults} /></BlockSurface>
</Theme>
```

Next.js app router: the blocks use React state, so render them from a file that starts with `'use client';` (for example SRC/components/klarhimmel-home.tsx) and import that into the page.

## 8. Make sure you read the design skill from now on

- Claude Code reads `.claude/skills/` on its own: nothing more to do.
- Codex: add a line to AGENTS.md (create it if missing): "For any UI work, read and follow .claude/skills/klarhimmel-design/SKILL.md (the Klarhimmel UI design skill)."
- Cursor: create `.cursor/rules/klarhimmel-design.mdc` with front matter `description: Klarhimmel UI design skill` and `alwaysApply: true`, and the same line as its body.
- Any other agent: add the same line to the instructions file you read at the start of a session.

## 9. Check it

Run the project's type check and build (`npm run build`) and fix what fails. If you can, start the dev server and confirm the page shows the block.

## 10. Tell your person

In a few lines: that Klarhimmel UI is set up, the files you changed, the command and address to see the page, and what they can ask you next, for example "Build a landing page for my product with Klarhimmel UI" or "Add a pricing section with three plans". Only if you stopped at step 1, say why and what you need from them.

## After setup

- Every block and component, one line each: https://ui.klarhimmel.com/llms.txt
- Install anything: `npx shadcn@latest add @klarhimmel/<name>`. Use the install names in the design skill; never guess one.
- A prompt for a whole page, per page type: https://ui.klarhimmel.com/agent/prompts/landing-page.md
- Any page of the library as Markdown: add .md to its address.
- Let your agent look things up itself through the read-only, free MCP server at https://ui.klarhimmel.com/mcp (tools: search_items, get_item, setup), added once per agent:
  - Claude Code: `claude mcp add --transport http klarhimmel-ui https://ui.klarhimmel.com/mcp`
  - Codex, in ~/.codex/config.toml: `[mcp_servers.klarhimmel-ui]` with `url = "https://ui.klarhimmel.com/mcp"`
  - Cursor, in .cursor/mcp.json: `{ "mcpServers": { "klarhimmel-ui": { "url": "https://ui.klarhimmel.com/mcp" } } }`
