@tollerud/ui 1.1.1 → 1.1.3

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 |