# skeehn — the customizable UI foundation for AI products & agents

## What is skeehn?
skeehn is an open-source, zero-runtime-dependency component library for building AI interfaces —
chat, streaming, reasoning, tool calls, agents, voice — plus the core UI + layout to build whole
apps and sites. Copy components in (you own the code) or `npm i`, theme to your brand, ship.

- 32 components (14 core · 15 AI · 3 layout/viz/motion) + composed blocks.
- 8 themes: a neutral **Light/Dark** default (shadcn-like restraint), plus 6 opt-in flagships
  (Editorial dither, Terminal CRT, Brutal, Grain, Print, Mardi Gras).
- A **drop-in for the Vercel AI SDK v5** (`@skeehn/react/ai`) — renders `UIMessage.parts[]`
  with zero hard dependency on `ai`.
- CSS-first + token-driven → framework-agnostic; typed React wrappers in `@skeehn/react`.
- Docs: https://ui.skeehn.com/docs · AI SDK: /docs/ai-sdk · Blocks: /docs/blocks · Theme generator: /docs/theme-generator

## Installation

```bash
# npm (React) — components, hooks, the AI SDK layer, and blocks
npm i @skeehn/react
npm i @skeehn/core                       # framework-agnostic CSS + dither engine

# Copy-paste ownership via the shadcn registry (works in ANY project)
npx shadcn@latest add https://ui.skeehn.com/r/button.json
npx shadcn@latest add https://ui.skeehn.com/r/chat-bubble.json
# every component: https://ui.skeehn.com/r/<name>.json · engine: /r/skeehn-engine.json

# Or the skeehn CLI (fetches inline content from the live registry)
npx skeehn add chat-bubble
npx skeehn add all
npx skeehn init --theme light            # default neutral theme
```

### Package entry points
- `@skeehn/react` — all components + the chat primitives (MessageActions, Sources, ModelPicker…)
- `@skeehn/react/ai` — AI SDK v5 drop-in: `Conversation`, `Message`, `renderParts`
- `@skeehn/react/blocks` — whole-interface blocks: `ChatConsole`, `AgentConsole`, `VoiceConsole`, `HeroSection`
- `@skeehn/react/hooks` — `useChat`, `useCompletion`, `usePacedText`, `useStickyScroll`, `useAsciiStream`
- `@skeehn/core` — CSS + the dither engine (`DitherEngine`, `CanvasRenderer`); `@skeehn/core/styles.css` is batteries-included

## AI SDK v5 drop-in (`@skeehn/react/ai`)

Render `@ai-sdk/react`'s `useChat().messages` directly — no glue, no hard dependency on `ai`
(structural types only).

```tsx
import { useChat } from '@ai-sdk/react';
import { Conversation } from '@skeehn/react/ai';
import '@skeehn/core/styles.css';

export function Chat() {
  const { messages } = useChat();
  return <Conversation messages={messages} />;
}
```

`UIMessage.parts` → skeehn: `text`→ChatBubble · `reasoning`→ThinkingBlock ·
`tool-*`/`dynamic-tool`→ToolCard · `source-*`→CitationCard · `file`→img/FileAttachment ·
`step-start`→Divider · `data-*`→your override. Also `<Message>`, `renderParts`, per-part
overrides, and a `renderMarkdown` hook. Docs: https://ui.skeehn.com/docs/ai-sdk

## Blocks — drop in a whole interface (`@skeehn/react/blocks`)

Pre-composed, themeable surfaces: `ChatConsole` (model picker · conversation · suggestions · input),
`AgentConsole` (status · task · reasoning/tool stream), `VoiceConsole`, `HeroSection`.

```tsx
import { ChatConsole } from '@skeehn/react/blocks';
<ChatConsole messages={messages} busy={status === 'streaming'} onSend={(t) => sendMessage({ text: t })} />
```
Docs: https://ui.skeehn.com/docs/blocks

## Custom brand themes — generator

Generate a complete light + dark theme across the whole `--sk-*` contract from one brand color:
https://ui.skeehn.com/docs/theme-generator  (or set `data-theme` to any built-in theme)

## File Structure

```
engine/reset.css        CSS reset
engine/tokens.css       Design tokens (CSS custom properties, light+dark)
engine/dither.css       8 SVG dither patterns, ASCII border characters
themes/light.css        Neutral light — the default
themes/dark.css         Neutral dark
themes/default.css      Editorial — warm dark + dither (opt-in flagship)
themes/terminal.css     Green phosphor CRT
themes/brutal.css       Heavy ASCII block aesthetic
themes/print.css        Newsprint halftone
themes/grain.css        Warm film grain
themes/mardi-gras.css   Carnival accent theme
components/             32 component directories, each with .html/.css/.js
packages/react/         Typed React wrappers (@skeehn/react)
```

## Components (32 total)

### Core (14)
button, card, input, badge, alert, dialog, tabs, toggle, progress, avatar, tooltip, dropdown, table, accordion

### AI-Native (15)
chat-bubble, chat-input, reasoning-step, tool-card, citation-card, streaming-text, terminal-panel, agent-status, code-block, typing-indicator, markdown, voice-session, thinking-block, prompt-suggestions, file-attachment

### Bundles (3)
layout, dataviz, motion

## Usage Example (Plain HTML)

```html
<!DOCTYPE html>
<html lang="en" data-theme="default">
<head>
  <link rel="stylesheet" href="engine/reset.css">
  <link rel="stylesheet" href="engine/tokens.css">
  <link rel="stylesheet" href="engine/dither.css">
  <link rel="stylesheet" href="components/button/button.css">
  <link rel="stylesheet" href="components/chat-bubble/chat-bubble.css">
  <link rel="stylesheet" href="themes/default.css">
</head>
<body>
  <div class="sk-chat-bubble" data-role="assistant">
    <div class="sk-chat-bubble__content">Hello from skeehn</div>
  </div>
  <button class="sk-btn" data-variant="dither">Send</button>
</body>
</html>
```

## Usage Example (React)

```tsx
// Import CSS in your entry file or globals.css:
// import 'path/to/engine/tokens.css'
// import 'path/to/engine/dither.css'
// import 'path/to/components/chat-bubble/chat-bubble.css'

import { ChatBubble, AgentStatus, ReasoningStep } from '@skeehn/react';

export function Demo() {
  return (
    <>
      <AgentStatus status="thinking" />
      <ChatBubble role="assistant">Hello from skeehn</ChatBubble>
      <ReasoningStep status="completed" title="Checked registry">
        Found 32 components
      </ReasoningStep>
    </>
  );
}
```

## Design Tokens (CSS custom properties)

All color tokens are HSL tuples — use inside hsl():

```css
/* Colors */
hsl(var(--sk-background))
hsl(var(--sk-foreground))
hsl(var(--sk-surface))
hsl(var(--sk-primary))
hsl(var(--sk-primary-fg))
hsl(var(--sk-muted))
hsl(var(--sk-muted-foreground))
hsl(var(--sk-border-color))
hsl(var(--sk-destructive))

/* Borders */
var(--sk-border)           /* full shorthand: 1px solid hsl(...) */
var(--sk-border-color)     /* HSL tuple only */

/* Typography */
var(--sk-font-sans)        /* Geist, -apple-system, ... */
var(--sk-font-mono)        /* Geist Mono, SF Mono, ... */
var(--sk-font-weight-thin)   /* 200 */
var(--sk-font-weight-light)  /* 300 */
var(--sk-font-weight-normal) /* 400 */
var(--sk-font-weight-medium) /* 500 */
var(--sk-letter-spacing-tight) /* -0.025em */
var(--sk-letter-spacing-wide)  /* 0.06em */

/* Spacing (8px grid) */
var(--sk-space-1)   /* 4px  */
var(--sk-space-2)   /* 8px  */
var(--sk-space-4)   /* 16px */
var(--sk-space-6)   /* 24px */
var(--sk-space-8)   /* 32px */
var(--sk-space-16)  /* 64px */
var(--sk-space-24)  /* 96px */

/* Dither patterns (CSS background-image values) */
var(--sk-dither-bayer)
var(--sk-dither-noise)
var(--sk-dither-scanlines)
var(--sk-dither-dots)
var(--sk-dither-crosshatch)
var(--sk-dither-checker)
var(--sk-dither-diagonal)
var(--sk-dither-block)
```

## Theme Switching

```javascript
// Set theme via data attribute
document.documentElement.setAttribute('data-theme', 'dark');

// Load theme CSS dynamically
document.getElementById('theme-link').href = 'themes/dark.css';

// Themes: light (neutral default) | dark (neutral) | default (Editorial flagship) | terminal | brutal | grain | print | mardi-gras
```

## Component HTML Patterns

### Chat bubble
```html
<div class="sk-chat-bubble" data-role="user|assistant|tool|system">
  <div class="sk-chat-bubble__content">Message text</div>
</div>
```

### Agent status
```html
<div class="sk-agent-status" data-status="idle|thinking|acting|done|error">
  <span class="sk-agent-status__dot"></span>
  <span class="sk-agent-status__label">thinking</span>
</div>
```

### Button
```html
<button class="sk-btn" data-variant="dither|solid|outline|ghost|inverted" data-size="sm|md|lg">
  Label
</button>
```

### Chat input (requires chat-input.js)
```html
<sk-chat-input class="sk-chat-input" data-state="idle">
  <div class="sk-chat-input__wrapper">
    <textarea class="sk-chat-input__field" placeholder="Ask..." rows="1"></textarea>
    <div class="sk-chat-input__actions">
      <button class="sk-chat-input__send sk-btn" data-variant="dither" data-size="sm">↑</button>
    </div>
  </div>
</sk-chat-input>
<script type="module" src="components/chat-input/chat-input.js"></script>
```
Listen for user input: `document.addEventListener('sk:submit', e => console.log(e.detail.value))`

### Reasoning step (requires reasoning-step.js)
```html
<div class="sk-reasoning-step" data-status="pending|active|completed|error" data-expanded="false">
  <button class="sk-reasoning-step__header">
    <span class="sk-reasoning-step__indicator">○</span>
    <span class="sk-reasoning-step__title">Step title</span>
    <span class="sk-reasoning-step__chevron">▸</span>
  </button>
  <div class="sk-reasoning-step__content">Step details</div>
</div>
```

## MCP Server

```bash
# Start MCP server
bun run packages/mcp-server/src/index.ts

# Available tools: add_component, set_theme, init_project, list_components
```