@tollerud/ui 1.1.1 → 1.1.2

package/AGENTS.md

@@ -0,0 +1,472 @@
+# Tollerud Design System — AI Agent Guide
+
+Guidance for AI coding assistants (Claude Code, Cursor, GitHub Copilot, Codex, etc.) working in projects that use `@tollerud/ui`.
+
+---
+
+## Set up the Claude Code skill (do this first)
+
+This package ships a maintained [`SKILL.md`](https://github.com/Tollerud/ui/blob/main/SKILL.md) with the verified component catalog, prop signatures, aesthetic rules, and known gotchas (Server Component imports, `Button`/`Link` composition, etc.). If you're Claude Code (or another agent that supports project skills) and this project doesn't already have it:
+
+1. Fetch the raw file from `https://raw.githubusercontent.com/Tollerud/ui/main/SKILL.md`
+2. Write it verbatim to `.claude/skills/tollerud-ui/SKILL.md` in this project
+3. Use it as your source of truth for `@tollerud/ui` going forward — it reflects the package's *actual current exports*, which is more reliable than this file's component list (kept here mainly for human readers and non-Claude tools)
+
+Re-sync it whenever you bump the `@tollerud/ui` version and notice the local copy looks stale relative to `CHANGELOG.md`.
+
+---
+
+## Install
+
+```bash
+npm install @tollerud/ui clsx tailwind-merge tailwindcss
+# Optional — only if using NoirGlowBackground
+npm install @paper-design/shaders-react
+```
+
+For the footer alone (no full design system dependency):
+```bash
+npm install @tollerud/footer
+```
+
+## Tailwind Setup
+
+The design system ships a Tailwind preset that provides all tokens. **Always apply it** — without it, `text-tollerud-yellow`, `bg-tollerud-noir-900`, etc. will not resolve.
+
+```ts
+// tailwind.config.ts
+import type { Config } from 'tailwindcss'
+import tollerudPreset from '@tollerud/ui/preset'
+
+const config: Config = {
+  presets: [tollerudPreset],
+  content: ['./src/**/*.{ts,tsx}'],
+}
+export default config
+```
+
+Import the CSS in your root layout or `globals.css`:
+```css
+@import "tailwindcss/preflight";
+@import "tailwindcss/utilities";
+```
+And import the design system tokens/base styles from `@tollerud/ui/globals.css` or copy them locally.
+
+---
+
+## Aesthetic Rules
+
+**Never violate these:**
+
+- Dark surfaces only. Background: `#0A0A0A` (`bg-tollerud-noir-950`). Never white or light gray backgrounds.
+- Yellow accent (`#FFFF00`, `text-tollerud-yellow`) is for CTAs, focus rings, active states, and key data points — not decoration.
+- Never put yellow text on white. The ratio is 1.7:1 — it fails contrast.
+- Borders are decorative thin lines (`border-tollerud-noir-600` or `border-tollerud-noir-700`). Use them freely; reach for shadows only for overlays.
+- Monochrome everywhere except the single yellow accent. No blues, no greens, no brand gradients.
+
+---
+
+## Color Tokens
+
+| Token | Value | Use |
+|-------|-------|-----|
+| `tollerud-yellow` | `#FFFF00` | Accent, CTA, focus, key data |
+| `tollerud-yellow-warm` | `#E8D500` | Secondary yellow, gradients, warm states |
+| `tollerud-noir-950` | `#0A0A0A` | Page background |
+| `tollerud-noir-900` | `#111111` | Card / surface |
+| `tollerud-noir-800` | `#1A1A1A` | Elevated surface |
+| `tollerud-noir-700` | `#222222` | Hover states |
+| `tollerud-noir-600` | `#333333` | Borders |
+| `tollerud-text-primary` | `#F5F5F5` | Body text |
+| `tollerud-text-secondary` | `#AAAAAA` | Secondary / labels |
+| `tollerud-text-muted` | `#666666` | Placeholders, hints |
+
+---
+
+## Components
+
+> **Full, verified catalog with props lives in [SKILL.md](SKILL.md)** — that file is checked against the actual `components/index.ts` exports and is the source of truth. The list below is a quick-reference subset.
+
+All components import from `@tollerud/ui`. Use named imports.
+
+```tsx
+// Core / forms
+import { Button, buttonVariants, cn, Card, Badge, Input, StatusDot, Kbd } from '@tollerud/ui'
+import { CommandMenu, ActionRow, DataTable, LogViewer, Timeline, CodeBlock, StatCard, Container } from '@tollerud/ui'
+import { Checkbox, Switch, RadioGroup, Radio, Select, Textarea } from '@tollerud/ui'
+import { PasswordInput, Combobox, TagInput, Slider, FormRow } from '@tollerud/ui'
+// Primitives & navigation (added in 1.0.9)
+import { Divider, Pill, Avatar, AvatarGroup } from '@tollerud/ui'
+import { Breadcrumb, Pagination, Segmented, Stepper } from '@tollerud/ui'
+import { Panel, Meter, PricingCard } from '@tollerud/ui'
+import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from '@tollerud/ui'
+import { DatePicker, FileUpload } from '@tollerud/ui'
+// Overlays & feedback
+import { Empty, EmptyHeader, EmptyIcon, EmptyTitle, EmptyDescription, EmptyContent } from '@tollerud/ui'
+import { Dialog, DialogTrigger, DialogContent, DialogHeader, DialogFooter, DialogTitle, DialogDescription } from '@tollerud/ui'
+import { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from '@tollerud/ui'
+import { Tabs, TabsList, TabsTrigger, TabsContent } from '@tollerud/ui'
+import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem } from '@tollerud/ui'
+import { Sheet, SheetTrigger, SheetContent, SheetHeader, SheetTitle } from '@tollerud/ui'
+import { Skeleton, Progress, Toaster, GlowCard, NoirGlowBackground, BentoDashboard, Alert } from '@tollerud/ui'
+// Infra / homelab set
+import { HostCard, ServiceHealthCard, DockerStackCard, IncidentCard } from '@tollerud/ui'
+import { ApprovalCard, ActionDiff, AlertInbox, RollbackPlan, BackupStatusPanel } from '@tollerud/ui'
+// Footer
+import { Footer } from '@tollerud/ui' // or: import { Footer } from '@tollerud/footer'
+```
+
+### Button
+
+```tsx
+<Button variant="primary" size="md">Deploy</Button>
+<Button variant="secondary">Cancel</Button>
+<Button variant="ghost" size="sm">More</Button>
+<Button variant="destructive">Delete host</Button>
+<Button variant="terminal" size="sm">start_building</Button>
+
+// Styling a <Link> as a button — Button only renders a native <button>,
+// so use asChild (Radix Slot) or buttonVariants() instead of nesting <a> in <button>
+<Button asChild variant="primary"><Link href="/deploy">Deploy</Link></Button>
+<Link href="/deploy" className={buttonVariants({ variant: 'primary' })}>Deploy</Link>
+```
+
+Variants: `primary` · `secondary` · `ghost` · `destructive` · `terminal`
+Sizes: `sm` · `md` · `lg`
+`asChild` and `buttonVariants` require `@tollerud/ui >= 1.0.7`.
+
+### Card
+
+```tsx
+<Card>Content</Card>
+<Card accent>Highlighted with yellow border</Card>
+```
+
+### Badge
+
+```tsx
+<Badge>Default</Badge>
+<Badge variant="accent">New</Badge>
+<Badge variant="success">Online</Badge>
+<Badge variant="error">Down</Badge>
+<Badge variant="info">Info</Badge>
+<Badge variant="warning">Degraded</Badge>
+```
+
+### StatusDot
+
+```tsx
+<StatusDot status="online" label="SSH Connected" />
+<StatusDot status="warning" label="CPU 87%" />
+<StatusDot status="offline" label="Unreachable" />
+<StatusDot status="idle" label="Idle" />
+```
+
+### Input / Textarea / Select / Checkbox / Switch / RadioGroup
+
+```tsx
+<Input label="Server Name" placeholder="e.g. emma.tollerud.no" error={errors.name} />
+<Textarea label="Notes" rows={4} error={errors.notes} />
+<Select label="Region" options={[{ value: 'eu', label: 'EU' }]} value={region} onChange={setRegion} />
+<Checkbox label="Enable backups" checked={enabled} onChange={...} />
+<Switch label="Dark mode" defaultChecked />
+<RadioGroup label="Target" error={error}>
+  <Radio value="staging" label="Staging" name="target" />
+  <Radio value="production" label="Production" name="target" />
+</RadioGroup>
+```
+
+### Kbd — Keyboard shortcut chip
+
+```tsx
+<Kbd keys="⌘K" />
+<Kbd keys={["⌘", "⇧", "S"]} size="sm" />
+```
+
+### CommandMenu — Raycast-style command palette
+
+```tsx
+const [open, setOpen] = useState(false)
+
+<Button onClick={() => setOpen(true)}>Open</Button>
+<CommandMenu
+  open={open}
+  onOpenChange={setOpen}
+  groups={[
+    {
+      label: 'Servers',
+      items: [
+        { id: 'emma', label: 'emma.tollerud.no', description: 'SSH · uptime 14d', onSelect: () => {} },
+      ],
+    },
+  ]}
+  toggleShortcut="k"
+/>
+```
+
+Built-in `⌘K` / `Ctrl+K` listener, arrow navigation, Esc to close, search across all groups.
+
+### StatCard
+
+```tsx
+<StatCard label="Active Sessions" value={42} change={{ value: "+12%", direction: "up" }} />
+```
+
+### CodeBlock
+
+```tsx
+<CodeBlock promptPrefix showCopy code={`systemctl status tollerud-agent`} />
+```
+
+### DataTable
+
+```tsx
+<DataTable
+  columns={[
+    { key: 'hostname', label: 'Host', sortable: true },
+    { key: 'status', label: 'Status', render: (_v, row) => <Badge variant={row.status === 'online' ? 'success' : 'error'}>{row.status}</Badge> },
+  ]}
+  data={hosts}
+  rowKey="id"
+  onRowClick={(row) => {}}
+  emptyMessage="No hosts found"
+/>
+```
+
+### Empty (empty states)
+
+```tsx
+<Empty>
+  <EmptyHeader>
+    <EmptyIcon>{/* icon */}</EmptyIcon>
+    <EmptyTitle>No hosts connected</EmptyTitle>
+    <EmptyDescription>Connect your first machine and Tia will start watching it.</EmptyDescription>
+  </EmptyHeader>
+  <EmptyContent><Button variant="primary" size="sm">Connect a host</Button></EmptyContent>
+</Empty>
+```
+
+### Infra / homelab components
+
+```tsx
+<HostCard hostname="emma" ip="10.0.10.10" status="online" cpu="23%" memory="6.2/16 GB" disk="45%" uptime="14d" containers={4} />
+<ServiceHealthCard service="emma.tollerud.no" status="online" uptime="14d 3h" responseTime="23ms" />
+<IncidentCard title="High CPU" severity="high" timestamp="2026-05-26 14:32" description="CPU at 92% for 5 min" service="emma" />
+<ApprovalCard action="restart_container" description="Restart emma:hermes" state="pending" onApprove={() => {}} onReject={() => {}} />
+<LogViewer lines={[{ text: 'Health check passed', level: 'info', timestamp: '14:32:01', source: 'hermes' }]} follow searchable showLineNumbers height="300px" />
+<AlertInbox alerts={[{ id: '1', title: 'emma high CPU', severity: 'high', timestamp: '14:32', acknowledged: false }]} onAcknowledge={(id) => {}} />
+```
+
+Severity scale: `critical` · `high` · `medium` · `low` · `info`
+
+
+---
+
+## Layout Patterns
+
+### Navigation lockup
+
+The monogram must always appear left of the project name with `gap-2`. Never show the name without the monogram or the monogram alone in a nav context.
+
+```tsx
+import logo from '@tollerud/ui/tollerud-logo.svg'
+
+// Top bar
+<nav className="tollerud-glass fixed top-0 inset-x-0 z-50 h-14 flex items-center px-6 gap-6">
+  <div className="flex items-center gap-2 shrink-0">
+    <img src={logo} alt="Tollerud" className="h-5 w-auto" />
+    <span className="font-semibold text-sm text-white">Project Name</span>
+  </div>
+  <div className="flex items-center gap-4 ml-4">
+    <a href="/overview" className="text-sm text-tollerud-text-secondary hover:text-white transition-colors">Overview</a>
+  </div>
+  <div className="ml-auto flex items-center gap-3">
+    <Button variant="ghost" size="sm">Sign in</Button>
+    <Button variant="primary" size="sm">Get started</Button>
+  </div>
+</nav>
+<main className="pt-14">…</main>
+```
+
+Monogram sizing: top bar/sidebar expanded → `h-5`, sidebar collapsed → `h-6`, footer → `h-4` (handled automatically by `<Footer />`).
+
+### Glass nav
+
+```html
+<nav class="tollerud-glass fixed top-0 left-0 right-0 z-50 h-16 flex items-center px-6">…</nav>
+```
+
+### Grid background
+
+```html
+<section class="tollerud-grid-bg">…</section>
+```
+
+### Display headings
+
+```html
+<h1 class="tollerud-display text-[70px]">Dark. Monochrome.</h1>
+<h2 class="tollerud-display--secondary text-[40px]">Yellow where it counts</h2>
+```
+
+### Container
+
+```tsx
+<Container>Content capped at 1100px with 24px padding</Container>
+```
+
+### Density
+
+Apply `data-density="compact"` to any container to tighten spacing for tables, forms, and panels inside it.
+
+```html
+<div data-density="compact">…dense tables / forms…</div>
+```
+
+### Elevation
+
+Use borders as the primary separation method. Only add shadows to lift overlays. Shadow scale: `--shadow-sm` `--shadow-md` `--shadow-lg` `--shadow-xl` `--shadow-glow`. Drawers use `--shadow-xl`; popovers `--shadow-lg`.
+
+---
+
+## Copy & Voice
+
+- Labels are short and action-first: "Deploy", "View Logs", "Restart" — not "Click here to initiate deployment"
+- Terminal-style CTAs for technical actions: `❯ deploy --env production`, `$ init`
+- Error messages name the cause: "Connection to emma.tollerud.no timed out" — not "Something went wrong"
+- Avoid exclamation marks and corporate filler ("Oops!", "Great!", "Please try again later")
+
+---
+
+## Accessibility
+
+- Every interactive element needs a visible focus ring: `focus-visible:outline-2 focus-visible:outline-tollerud-yellow focus-visible:outline-offset-2` (or `.tollerud-focus-ring`)
+- Icon-only buttons must have `aria-label`
+- Inputs must have `<label>` — always use the `label` prop on `Input`, `Select`, `Textarea`
+- Error messages use `role="alert"` or `aria-live="polite"`
+- Never convey information by color alone
+- Respect `prefers-reduced-motion: reduce` — disable shimmer and animations
+
+---
+
+## What NOT to do
+
+| Don't | Why |
+|-------|-----|
+| Use light/white backgrounds | The system is dark-only |
+| Put yellow text on white | Fails contrast at 1.7:1 |
+| Recolor the monogram | Yellow on dark is non-negotiable |
+| Use non-system colors (blue, green, purple) | Only yellow accent + monochrome grays |
+| Add drop shadows or glows to the monogram | Glow is for interactive UI, not branding |
+| Show the project name without the monogram | The lockup is the brand |
+| Use verbose copy or exclamation marks | Violates voice guidelines |
+
+---
+
+## Updating the npm package (for agents working in this repo)
+
+When asked to add components, fix bugs, or cut a release:
+
+### 1. Build and typecheck before committing
+
+```bash
+npx tsc --noEmit -p tsconfig.build.json   # must be clean
+npx tsup                                   # verify the bundle builds
+```
+
+### 2. Every new component needs all four of these
+
+| What | Where |
+|------|-------|
+| Component file | `components/ComponentName.tsx` |
+| Named export + type export | `components/index.ts` |
+| Registry entry | `registry.json` — add a `kebab-case` key with `name`, `description`, `files`, `dependencies`, `registryDependencies`, `type: "components:ui"` |
+| Docs preview | `examples/docs-nextjs/components/ComponentPreviews.tsx` (export function) + `examples/docs-nextjs/app/components/page.tsx` (section entry + import) |
+
+### 3. Version bump rules
+
+| Change | Version bump |
+|--------|-------------|
+| New components, no breaking changes | minor (`1.x.0`) |
+| Bug fixes only | patch (`1.0.x`) |
+| Prop renames, removed exports, token renames | major (`x.0.0`) |
+
+Edit `package.json` version, then update these to match:
+- `COMPLETENESS_ROADMAP.md` — header line `### npm package (components/*.tsx) — vX.X.X`
+- `registry.json` — top-level `"version"` field
+
+### 4. Always update these files in the same commit
+
+- `CHANGELOG.md` — add an entry at the top following the existing style (date · version · summary + bullet points)
+- `COMPLETENESS_ROADMAP.md` — move completed items to the done list, strike through fixed quality items
+- `SKILL.md` — add new components to the catalog, update version notes
+- `AGENTS.md` (this file) — update the component import blocks if new exports were added
+
+### 5. Commit and push
+
+```bash
+git add <changed files>
+git commit -m "Brief description — vX.X.X"
+git push origin main
+```
+
+---
+
+## Fixing copy/paste component patterns (for agents working in consumer projects)
+
+Older versions of projects that use `@tollerud/ui` sometimes copied component source files directly into the repo (e.g. `src/components/ui/Button.tsx` copied from the design system). These need to be replaced with package imports.
+
+### How to detect it
+
+```bash
+# Find files that look like copied DS components (contain tollerud- tokens but aren't node_modules)
+grep -rl "tollerud-yellow\|tollerud-noir\|tollerud-surface" src --include="*.tsx" --include="*.ts"
+```
+
+Also check for a local `components/ui.ts` or `components/ui/index.ts` that re-exports from relative paths instead of `@tollerud/ui`.
+
+### How to fix it
+
+1. **Verify `@tollerud/ui` is installed** — check `package.json`. If not: `npm install @tollerud/ui clsx tailwind-merge`.
+
+2. **Replace the local copy with a package import** — for each copied component:
+   ```tsx
+   // Before (copied file)
+   import { Button } from '@/components/ui/Button'
+
+   // After
+   import { Button } from '@tollerud/ui'
+   ```
+
+3. **Delete the copied files** once all imports are updated and the project builds.
+
+4. **Check for prop drift** — copied files may be outdated. Verify against `SKILL.md` (or `.claude/skills/tollerud-ui/SKILL.md`) that prop names haven't changed (e.g. `onValueChange` vs `onChange`, `label` vs `children` on form components).
+
+5. **Check for inline token usage** — copied files sometimes hardcode hex values instead of using tokens. Replace any hardcoded `#FFFF00`, `#0A0A0A`, `#E8D500` etc. with `text-tollerud-yellow`, `bg-tollerud-noir-950`, `text-tollerud-yellow-warm`.
+
+6. **Run typecheck** — `npx tsc --noEmit`. Prop signatures in the package may differ slightly from the copied version; fix any type errors before committing.
+
+### Common copy/paste patterns to look for
+
+| Pattern | Fix |
+|---------|-----|
+| `src/components/ui/Button.tsx` with `tollerud-btn` classes | Delete, import from `@tollerud/ui` |
+| `lib/utils.ts` defining `cn()` manually | Replace with `import { cn } from '@tollerud/ui'` |
+| `components/ui.ts` re-exporting from `'../../../components/Button'` | Replace all with `export * from '@tollerud/ui'` or direct named imports |
+| Inline `bg-[#FFFF00]` or `text-[#0A0A0A]` | Replace with `bg-tollerud-yellow` / `text-tollerud-noir-950` |
+| `import { toast } from 'sonner'` without a `<Toaster />` mount | Add `<Toaster />` near app root |
+
+---
+
+## Reference
+
+| File | Contents |
+|------|----------|
+| [SKILL.md](SKILL.md) | **Verified** component catalog, props, gotchas — source of truth for what's actually shipped |
+| [COMPONENTS.md](COMPONENTS.md) | Prop tables — includes both shipped and planned/roadmap components, check against SKILL.md before relying on an entry |
+| [BRAND.md](BRAND.md) | Logo usage, nav lockup, sizing rules |
+| [ACCESSIBILITY.md](ACCESSIBILITY.md) | Contrast ratios, focus, ARIA patterns |
+| [VOICE.md](VOICE.md) | Copy tone, terminal-style CTAs, error messages |
+| [KEYBOARD.md](KEYBOARD.md) | Keyboard contract for CommandMenu and navigation |
+| [BACKGROUNDS.md](BACKGROUNDS.md) | NoirGlowBackground props and fallback rules |
+| [GETTING_STARTED.md](GETTING_STARTED.md) | Install, Tailwind config, registry usage |

package/SKILL.md

@@ -0,0 +1,452 @@
+---
+name: tollerud-ui
+description: Use the @tollerud/ui design system correctly — components, props, Tailwind tokens, aesthetic rules, and known gotchas (Server Component imports, Button/Link composition). Trigger whenever a project imports from @tollerud/ui or @tollerud/footer, or when building UI that should match the Tollerud noir aesthetic.
+---
+
+# @tollerud/ui — Design System Skill
+
+Dark, monochrome + single yellow-accent design system ("noir" aesthetic). This skill documents the package's **actual current exports** (verified against `components/index.ts` in the source repo) — not aspirational docs. If you see a component referenced elsewhere that isn't listed below, it does not exist yet; don't import it.
+
+---
+
+## Install & setup
+
+```bash
+npm install @tollerud/ui clsx tailwind-merge tailwindcss
+# Optional — only if using NoirGlowBackground
+npm install @paper-design/shaders-react
+```
+
+Apply the Tailwind preset — without it, `text-tollerud-yellow`, `bg-tollerud-noir-900`, etc. won't resolve:
+
+```ts
+// tailwind.config.ts
+import type { Config } from 'tailwindcss'
+import tollerudPreset from '@tollerud/ui/preset'
+
+const config: Config = {
+  presets: [tollerudPreset],
+  content: ['./src/**/*.{ts,tsx}'],
+}
+export default config
+```
+
+Import base styles/tokens from `@tollerud/ui/globals.css` (or `@tollerud/ui/tokens.css`) in your root layout / `globals.css`, alongside Tailwind's own layers:
+```css
+@import "tailwindcss/preflight";
+@import "tailwindcss/utilities";
+@import "@tollerud/ui/globals.css";
+```
+
+---
+
+## Critical gotchas (read before writing code)
+
+### 1. Server Components — just import normally (≥ 1.0.8)
+`@tollerud/ui` ships as a single bundled file marked `'use client'`. As of **v1.0.8**, importing anything from it — components, hooks, or plain helpers like `buttonVariants` and `cn` — works fine from a Server Component file; the import itself doesn't force your file to become a Client Component, since you're just pulling in already-client-bundled code or plain functions.
+- **If you're on `< 1.0.8`, upgrade first** — older versions crash on any import from a Server Component (the bundle wasn't marked `'use client'`, despite containing hook-based components).
+
+### 2. `<Button>` only renders a native `<button>` — use `asChild` for links (≥ 1.0.7)
+`Button` extends `ButtonHTMLAttributes<HTMLButtonElement>` and has no `href`. **Never nest `<a>` inside `<button>` or vice versa** — it's invalid HTML and breaks accessibility. Two ways to style a `<Link>`/`<a>` like a Button:
+
+```tsx
+// Option A — asChild (Radix Slot merges Button's classes/props onto the child)
+import { Button } from '@tollerud/ui'
+import Link from 'next/link'
+
+<Button asChild variant="primary">
+  <Link href="/deploy">Deploy</Link>
+</Button>
+```
+
+```tsx
+// Option B — buttonVariants() when wrapping is awkward
+import { buttonVariants } from '@tollerud/ui'
+import Link from 'next/link'
+
+<Link href="/deploy" className={buttonVariants({ variant: 'primary', size: 'md' })}>
+  Deploy
+</Link>
+```
+
+For a real `<button>` (form submit, logout, toggle, dialog/menu trigger), just use `<Button>` directly — no `asChild` needed.
+
+### 3. `cn` is exported — use it, don't reimplement
+`@tollerud/ui` exports `cn` (clsx + tailwind-merge). Use it for conditional/merged class names instead of template strings or writing your own helper.
+
+---
+
+## Aesthetic rules (never violate)
+
+- **Dark surfaces only.** Page background `#0A0A0A` / `bg-tollerud-noir-950`. Never white or light-gray backgrounds.
+- **Yellow is for meaning, not decoration** — CTAs, focus rings, active states, key data points (`text-tollerud-yellow`, `#FFFF00`).
+- **Never put yellow text on white** — contrast ratio is ~1.7:1, fails WCAG.
+- **Borders over shadows.** Use `border-tollerud-noir-600` / `border-tollerud-noir-700` for separation; reserve shadows/glow for overlays (drawers, popovers, dialogs).
+- **Strict monochrome + single accent.** No blues, greens, purples, or brand gradients — yellow is the only chromatic color (status colors like success/error/info exist as semantic exceptions inside `Badge`, `IncidentCard`, `Alert`, etc.).
+
+## Color tokens
+
+| Token | Value | Use |
+|---|---|---|
+| `tollerud-yellow` | `#FFFF00` | Accent, CTA, focus ring, key data |
+| `tollerud-yellow-warm` | `#E8D500` | Secondary yellow, gradients, warm states |
+| `tollerud-noir-950` | `#0A0A0A` | Page background |
+| `tollerud-noir-900` | `#111111` | Card / surface |
+| `tollerud-noir-800` | `#1A1A1A` | Elevated surface |
+| `tollerud-noir-700` | `#222222` | Hover states |
+| `tollerud-noir-600` | `#333333` | Borders |
+| `tollerud-text-primary` | `#F5F5F5` | Body text |
+| `tollerud-text-secondary` | `#AAAAAA` | Secondary text / labels |
+| `tollerud-text-muted` | `#666666` | Placeholders, hints |
+
+Standard focus ring (apply to every interactive element): `focus-visible:outline-2 focus-visible:outline-tollerud-yellow focus-visible:outline-offset-2`
+
+---
+
+## Component catalog (verified against actual exports)
+
+Import everything as named exports from `@tollerud/ui`.
+
+### Core / forms
+
+```tsx
+import {
+  Button, buttonVariants, cn,
+  Card, Badge, StatusDot, Kbd,
+  Input, Textarea, Select, Checkbox, Switch, RadioGroup, Radio,
+  PasswordInput, Combobox, TagInput, Slider, FormRow,
+  Container, CodeBlock, StatCard, ActionRow, CommandMenu,
+} from '@tollerud/ui'
+```
+
+**Button** — `variant`: `primary` · `secondary` · `ghost` · `destructive` · `terminal`. `size`: `sm` · `md` · `lg`. `asChild?: boolean`.
+```tsx
+<Button variant="primary" size="md">Deploy</Button>
+<Button variant="destructive">Delete host</Button>
+<Button variant="terminal" size="sm">start_building</Button>
+```
+
+**Card** — `accent?: boolean`, `density?: 'comfortable' | 'compact'`. Plain `<div>` wrapper — safe to nest in `<Link>`.
+```tsx
+<Card accent>Highlighted with yellow border</Card>
+```
+
+**Badge** — `variant`: `default` · `accent` · `success` · `error` · `info` · `warning`.
+```tsx
+<Badge variant="success">Online</Badge>
+```
+
+**StatusDot** — `status`: `online` · `offline` · `warning` · `idle` (exported as `Status`); `label?`, `noPulse?`.
+```tsx
+<StatusDot status="online" label="SSH Connected" />
+```
+
+**Input / Textarea / Select / Checkbox / Switch / RadioGroup**
+```tsx
+<Input label="Server Name" placeholder="e.g. emma.tollerud.no" error={errors.name} />
+<Textarea label="Notes" rows={4} error={errors.notes} />
+<Select label="Region" options={[{ value: 'eu', label: 'EU' }]} value={region} onChange={setRegion} />
+<Checkbox label="Enable backups" checked={enabled} onChange={...} />
+<Switch label="Dark mode" defaultChecked />
+<RadioGroup label="Target" error={error}>
+  <Radio value="staging" label="Staging" name="target" />
+  <Radio value="production" label="Production" name="target" />
+</RadioGroup>
+```
+All form primitives require a `label` (renders an actual `<label>` for a11y) and accept `error?: string`.
+
+**Kbd** — keyboard shortcut chip. `keys: string | string[]`, `size?: 'sm' | 'md'`.
+```tsx
+<Kbd keys={["⌘", "⇧", "S"]} size="sm" />
+```
+
+**ActionRow** / **CommandMenu** — Raycast-style command palette.
+```tsx
+const [open, setOpen] = useState(false)
+<CommandMenu
+  open={open}
+  onOpenChange={setOpen}
+  groups={[{ label: 'Servers', items: [
+    { id: 'emma', label: 'emma.tollerud.no', description: 'SSH · uptime 14d', onSelect: () => {} },
+  ]}]}
+  toggleShortcut="k"      // built-in ⌘K / Ctrl+K listener
+/>
+```
+
+**StatCard** — `label`, `value`, `change?: { value: string; direction: 'up' | 'down' }`, `accent?`.
+```tsx
+<StatCard label="Active Sessions" value={42} change={{ value: '+12%', direction: 'up' }} />
+```
+
+**CodeBlock** — `code?`, `promptPrefix?`, `showCopy?`. Renders a `<pre>`.
+```tsx
+<CodeBlock promptPrefix showCopy code={`systemctl status tollerud-agent`} />
+```
+
+**Container** — `as?: 'div' | 'section' | 'article' | 'main' | 'header' | 'footer'`, capped width + padding.
+
+**PasswordInput** — same API as `Input` (label, error, id, …) plus built-in show/hide toggle.
+```tsx
+<PasswordInput label="Password" placeholder="Enter password" error={errors.password} />
+```
+
+**Combobox** — searchable single-select. `options: { value, label, disabled? }[]`, `value?`, `onChange?`, `placeholder?`, `filter?`, `label?`, `error?`.
+```tsx
+<Combobox label="Connect to host" value={host} onChange={setHost} options={hostOptions} />
+```
+
+**TagInput** — chip-style multi-value input. `value?: string[]`, `onChange?`, `max?`, `placeholder?`, `label?`, `error?`. Enter/comma to add, Backspace to remove last.
+```tsx
+<TagInput label="Tags" value={tags} onChange={setTags} placeholder="Add tag…" max={10} />
+```
+
+**Slider** — native range input styled with yellow thumb. `label?`, `showValue?`, `onChange?: (value: number) => void`, plus all native `<input type="range">` props.
+```tsx
+<Slider label="Alert threshold" showValue value={threshold} onChange={setThreshold} min={0} max={100} />
+```
+
+**FormRow** — accessible field wrapper. `label?`, `description?`, `error?`, `required?`, `htmlFor?`. Wires `aria-describedby` automatically.
+```tsx
+<FormRow label="Hostname" htmlFor="hostname" description="Unique within your network." required error={errors.hostname}>
+  <Input id="hostname" placeholder="e.g. embla" />
+</FormRow>
+```
+
+### Navigation & layout primitives
+
+```tsx
+import {
+  Divider, Pill, Avatar, AvatarGroup,
+  Breadcrumb, Pagination, Segmented, Stepper,
+  Panel, Meter, Accordion, AccordionItem, AccordionTrigger, AccordionContent,
+  DatePicker, FileUpload, PricingCard,
+} from '@tollerud/ui'
+```
+
+**Divider** — `orientation?: 'horizontal' | 'vertical'`, `label?: ReactNode`.
+```tsx
+<Divider />
+<Divider label="or" />
+<Divider orientation="vertical" className="h-6" />
+```
+
+**Pill** — `variant?: 'outline' | 'solid' | 'accent'`.
+```tsx
+<Pill variant="accent">production</Pill>
+```
+
+**Avatar / AvatarGroup** — `src?`, `name?` (derives initials), `fallback?`, `size?: 'sm' | 'md' | 'lg'`. `AvatarGroup` takes `max?` and shows a +N chip.
+```tsx
+<Avatar name="Mathias Tollerud" size="md" />
+<AvatarGroup max={3}><Avatar name="Emma" /><Avatar name="Iris" /></AvatarGroup>
+```
+
+**Breadcrumb** — `items: { label, href?, onClick? }[]`, `separator?`.
+```tsx
+<Breadcrumb items={[{ label: 'Servers', href: '/servers' }, { label: 'Embla' }]} />
+```
+
+**Pagination** — `page` (1-indexed), `pageCount`, `onChange`, `siblingCount?`.
+```tsx
+<Pagination page={page} pageCount={20} onChange={setPage} />
+```
+
+**Segmented** — `options: { value, label, disabled? }[]`, `value`, `onChange`, `size?: 'sm' | 'md'`.
+```tsx
+<Segmented value={view} onChange={setView} options={[{ value: 'grid', label: 'Grid' }, { value: 'list', label: 'List' }]} />
+```
+
+**Stepper** — `steps: { label, description? }[]`, `current` (0-indexed), `orientation?: 'horizontal' | 'vertical'`.
+```tsx
+<Stepper steps={onboardingSteps} current={1} orientation="vertical" />
+```
+
+**Panel** — `title?`, `description?`, `actions?: ReactNode` (renders in header), `children` (body with padding).
+```tsx
+<Panel title="Overview" description="Live metrics" actions={<Button size="sm">Refresh</Button>}>…</Panel>
+```
+
+**Meter** — `value`, `max?` (default 100), `label?`, `showValue?`, `tone?: 'default' | 'success' | 'warning' | 'error'`.
+```tsx
+<Meter value={72} label="RAM" showValue tone="warning" />
+```
+
+**Accordion** — compound. `multiple?: boolean`, `defaultOpen?: string | string[]`. Items use `value` prop to identify.
+```tsx
+<Accordion defaultOpen="faq-1">
+  <AccordionItem value="faq-1">
+    <AccordionTrigger>What is Tia?</AccordionTrigger>
+    <AccordionContent>An infrastructure assistant for homelabs.</AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+**DatePicker** — `value?: Date | null`, `onChange?`, `label?`, `error?`, `placeholder?`, `formatDate?`.
+```tsx
+<DatePicker label="Schedule deployment" value={date} onChange={setDate} />
+```
+
+**FileUpload** — `accept?`, `multiple?`, `onFilesChange?`, `label?`, `description?`, `error?`.
+```tsx
+<FileUpload label="Upload config" accept=".yaml,.json" onFilesChange={handleFiles} />
+```
+
+**PricingCard** — `name`, `price`, `period?`, `description?`, `features?: ReactNode[]`, `ctaLabel?`, `onCtaClick?`, `featured?`, `badge?`.
+```tsx
+<PricingCard name="Pro" price="$9" period="/month" features={['Unlimited servers']} featured badge="Most popular" />
+```
+
+### Overlays (Radix-based, all need `'use client'` boundary in the *consumer* component)
+
+```tsx
+import {
+  Dialog, DialogTrigger, DialogContent, DialogHeader, DialogFooter, DialogTitle, DialogDescription, DialogClose,
+  Tooltip, TooltipTrigger, TooltipContent, TooltipProvider,
+  Tabs, TabsList, TabsTrigger, TabsContent,
+  DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuLabel,
+  Sheet, SheetTrigger, SheetContent, SheetHeader, SheetTitle, SheetDescription, SheetClose,
+  Toaster,
+} from '@tollerud/ui'
+```
+- `Dialog` / `Sheet` / `DropdownMenu` follow the standard shadcn/Radix composition pattern — `Trigger` wraps the activating element with `asChild`. `Sheet` takes a `side?: 'left' | 'right'`.
+- `Tooltip` requires a `<TooltipProvider>` ancestor.
+- `Toaster` is the toast renderer (Sonner-based) — mount it once near the app root.
+
+### Empty states & loading
+
+```tsx
+import { Empty, EmptyHeader, EmptyIcon, EmptyTitle, EmptyDescription, EmptyContent, Skeleton, Progress } from '@tollerud/ui'
+
+<Empty>
+  <EmptyHeader>
+    <EmptyIcon>{/* icon */}</EmptyIcon>
+    <EmptyTitle>No hosts connected</EmptyTitle>
+    <EmptyDescription>Connect your first machine and Tia will start watching it.</EmptyDescription>
+  </EmptyHeader>
+  <EmptyContent><Button variant="primary" size="sm">Connect a host</Button></EmptyContent>
+</Empty>
+```
+
+### Visual / decorative
+
+```tsx
+import { GlowCard, NoirGlowBackground, BentoDashboard } from '@tollerud/ui'
+```
+- **GlowCard** — `children`, `className?`, `glowColor?`, `intensity?: number`. Mouse-tracked glow card.
+- **NoirGlowBackground** — animated WebGL shader background (needs `@paper-design/shaders-react`). `shape?: 'corners' | 'wave' | 'dots' | 'truchet' | 'ripple' | 'blob' | 'sphere'`, `intensity?: 'subtle' | 'medium' | 'loud'`, `speed?: 'still' | 'slow' | 'medium' | 'fast'`, `grain?: 'none' | 'soft' | 'high'`, `colors?: string[]`, `forceCssFallback?: boolean`.
+- **BentoDashboard** — composed dashboard shell taking arrays of `HostCardProps`, `StatCardProps`, `ServiceHealthCardProps`, incidents, `BackupJob[]`.
+
+### Data & tables
+
+```tsx
+import { DataTable } from '@tollerud/ui'
+
+<DataTable
+  columns={[
+    { key: 'hostname', label: 'Host', sortable: true },
+    { key: 'status', label: 'Status', render: (_v, row) => <Badge variant={row.status === 'online' ? 'success' : 'error'}>{row.status}</Badge> },
+  ]}
+  data={hosts}
+  rowKey="id"
+  onRowClick={(row) => {}}
+  emptyMessage="No hosts found"
+/>
+```
+Note the prop is `data`/`columns`/`label` (not `rows`/`header` — older docs may say otherwise).
+
+### Infra / homelab set
+
+```tsx
+import {
+  HostCard, ServiceHealthCard, DockerStackCard, IncidentCard, ApprovalCard,
+  ActionDiff, LogViewer, AlertInbox, Timeline, RollbackPlan, BackupStatusPanel,
+} from '@tollerud/ui'
+import type { IncidentSeverity } from '@tollerud/ui'
+```
+
+```tsx
+<HostCard hostname="emma" ip="10.0.10.10" status="online" cpu="23%" memory="6.2/16 GB" disk="45%" uptime="14d" containers={4} />
+<ServiceHealthCard service="emma.tollerud.no" status="online" uptime="14d 3h" responseTime="23ms" />
+<DockerStackCard name="hermes" services={[{ name: 'web', status: 'online' }]} composePath="compose.yml" />
+<IncidentCard title="High CPU" severity="high" timestamp="2026-05-26 14:32" description="CPU at 92% for 5 min" service="emma" />
+<ApprovalCard action="restart_container" description="Restart emma:hermes" state="pending" onApprove={() => {}} onReject={() => {}} />
+<ActionDiff label="docker-compose.yml" lines={[{ text: 'image: nginx:1.27', type: 'add', newLine: 12 }]} />
+<LogViewer lines={[{ text: 'Health check passed', level: 'info', timestamp: '14:32:01', source: 'hermes' }]} follow searchable showLineNumbers height="300px" />
+<AlertInbox alerts={[{ id: '1', title: 'emma high CPU', severity: 'high', timestamp: '14:32', acknowledged: false }]} onAcknowledge={(id) => {}} />
+<Timeline items={[{ id: '1', time: '14:32', title: 'Deploy started', status: 'online' }]} active loading={false} />
+<RollbackPlan name="hermes-v2.1-rollback" steps={[{ id: '1', label: 'Stop container', status: 'success' }]} executing />
+<BackupStatusPanel jobs={[{ name: 'nightly-db', status: 'online', lastRun: '02:00', nextRun: 'tomorrow 02:00', size: '4.2 GB' }]} totalSize="120 GB" />
+```
+
+`IncidentSeverity` = `critical | high | medium | low | info` · `Status` (StatusDot/HostCard/etc) = `online | offline | warning | idle` · `LogLevel` = `debug | info | warn | error | trace` · `RollbackStepStatus` = `pending | running | success | failed | skipped` · `ApprovalState` = `pending | approved | rejected`.
+
+### Footer & branding
+
+```tsx
+import { Footer } from '@tollerud/ui'
+import logo from '@tollerud/ui/tollerud-logo.svg'
+
+<Footer layout="responsive" accent labels={{ tollerudProject: 'A Tollerud Project' }} />
+```
+The monogram must always sit left of the project name with `gap-2`. Never show the name without the monogram, or the monogram alone, in nav contexts.
+
+```tsx
+<div className="flex items-center gap-2 shrink-0">
+  <img src={logo} alt="Tollerud" className="h-5 w-auto" />
+  <span className="font-semibold text-sm text-white">Project Name</span>
+</div>
+```
+Monogram sizing: top bar/sidebar expanded → `h-5`, collapsed → `h-6`, footer → `h-4` (handled automatically by `<Footer />`).
+
+---
+
+## Layout utility classes
+
+```html
+<nav class="tollerud-glass fixed top-0 inset-x-0 z-50 h-14 flex items-center px-6">…</nav>
+<section class="tollerud-grid-bg">…</section>
+<h1 class="tollerud-display text-[70px]">Dark. Monochrome.</h1>
+<h2 class="tollerud-display--secondary text-[40px]">Yellow where it counts</h2>
+<div data-density="compact">…dense tables / forms…</div>
+```
+
+Shadow scale: `--shadow-sm` `--shadow-md` `--shadow-lg` `--shadow-xl` `--shadow-glow`. Drawers/Sheets use `--shadow-xl`; popovers/tooltips `--shadow-lg`. Borders are the default separator — only reach for shadows on overlays.
+
+---
+
+## Copy & voice
+
+- Action-first labels: "Deploy", "View Logs", "Restart" — not "Click here to initiate deployment"
+- Terminal-style CTAs for technical actions: `❯ deploy --env production`, `$ init`
+- Name the cause in errors: "Connection to emma.tollerud.no timed out" — not "Something went wrong"
+- No exclamation marks or corporate filler ("Oops!", "Great!", "Please try again later")
+
+## Accessibility checklist
+
+- Every interactive element gets a visible focus ring (see token section above, or class `.tollerud-focus-ring`)
+- Icon-only buttons need `aria-label`
+- Always pass `label` to `Input` / `Select` / `Textarea` / `Checkbox` / `Switch` / `Radio` — never rely on placeholder-as-label
+- Error text uses `role="alert"` or `aria-live="polite"`
+- Never convey state by color alone — pair `StatusDot` / `Badge` color with text/icon
+- Respect `prefers-reduced-motion: reduce` — disable shimmer/pulse/shader animations
+
+## What NOT to do
+
+| Don't | Why |
+|---|---|
+| Use light/white backgrounds | System is dark-only |
+| Put yellow text on white | Fails contrast at ~1.7:1 |
+| Recolor or add glow to the monogram | Yellow-on-dark branding is non-negotiable; glow is for interactive UI only |
+| Introduce non-system chromatic colors (blue, green, purple) for decoration | Only the yellow accent + monochrome grays (status semantics are the lone exception) |
+| Nest `<a>`/`<Link>` inside `<Button>` (or vice versa) | Invalid HTML — use `asChild` or `buttonVariants()` instead |
+| Import a component name you saw in older docs without checking it exists | Some legacy docs list aspirational or since-shipped components. As of **1.0.9** all 19 previously "missing" components (`Divider`, `Pill`, `Avatar`, `AvatarGroup`, `Breadcrumb`, `Pagination`, `Segmented`, `Stepper`, `Panel`, `Meter`, `FormRow`, `Accordion`, `Slider`, `PasswordInput`, `Combobox`, `DatePicker`, `FileUpload`, `TagInput`, `PricingCard`) are exported. Components still **not** in the package: charts, marketing blocks (`HeroBlock`, `FeatureCard`, `CTABand`), `Drawer`, `EmptyState` (use `Empty`), `Toast` (use `Toaster` + `sonner`'s `toast()`) |
+
+---
+
+## Version notes
+
+- **`asChild` / `buttonVariants` require `@tollerud/ui >= 1.0.7`**
+- **Server Component import safety requires `@tollerud/ui >= 1.0.8`** (earlier versions crash when imported into a Server Component file — the bundle wasn't marked `'use client'`)
+- **19 new components (`Divider`, `Pill`, `Avatar`/`AvatarGroup`, `Breadcrumb`, `Pagination`, `Segmented`, `Stepper`, `Panel`, `Meter`, `FormRow`, `Accordion`, `Slider`, `PasswordInput`, `Combobox`, `DatePicker`, `FileUpload`, `TagInput`, `PricingCard`) require `>= 1.0.9`**
+- **`Combobox` + `DatePicker` close on window resize (≥ 1.1.0)** — earlier versions left the popover open and misaligned after viewport changes
+- Always pin to the latest patch and check `CHANGELOG.md` in the design-system repo for breaking changes (e.g. the 1.0.5 yellow token rename: `tollerud-yellow-bright` → `tollerud-yellow`, old `tollerud-yellow` `#E8D500` → `tollerud-yellow-warm`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tollerud/ui",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "Tollerud User Interface — dark, monochrome + yellow accent. Noir aesthetic meets modern utility.",
   "private": false,
   "type": "module",
@@ -46,7 +46,9 @@
     "tollerud-logo.svg",
     "tollerud-avatar.svg",
     "tollerud-avatar.png",
-    "tia-full-figure.svg"
+    "tia-full-figure.svg",
+    "AGENTS.md",
+    "SKILL.md"
   ],
   "scripts": {
     "build": "tsup",