harebear-ui 0.5.0 → 0.7.0

package/docs/guides/getting-started.md

@@ -0,0 +1,217 @@
+# Getting started
+
+harebear-ui needs React 19 and Tailwind CSS v4 in your app. Pick your framework below; each setup is about five minutes.
+
+- [Vite](#vite)
+- [Next.js (App Router)](#nextjs-app-router)
+- [React Router v7 (framework mode)](#react-router-v7-framework-mode)
+- [Check it works](#check-it-works)
+- [Troubleshooting](#troubleshooting)
+
+The fast path for any framework that already has Tailwind v4:
+
+```bash
+npm i harebear-ui
+npx harebear-ui init
+```
+
+`init` finds the CSS file that contains `@import "tailwindcss"`, adds `@import "harebear-ui/styles.css";` after it, writes a harebear-ui section into `AGENTS.md` (or `CLAUDE.md` if that is what you have), and installs a Claude Code skill in `.claude/skills/harebear-ui/`. It is safe to run again: the CSS import is not duplicated and the agent section is replaced in place.
+
+| Flag           | Effect                                                        |
+| -------------- | ------------------------------------------------------------- |
+| `--css <file>` | Use this CSS file. Needed when several files import Tailwind. |
+| `--no-agents`  | Skip the `AGENTS.md` / `CLAUDE.md` section.                   |
+| `--no-skill`   | Skip the Claude Code skill.                                   |
+
+Then wrap your root (framework sections below show where).
+
+## Vite
+
+```bash
+npm create vite@latest my-app -- --template react-ts
+cd my-app
+npm i tailwindcss @tailwindcss/vite harebear-ui
+```
+
+```ts
+// vite.config.ts
+import tailwindcss from "@tailwindcss/vite"
+import react from "@vitejs/plugin-react"
+import { defineConfig } from "vite"
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+})
+```
+
+```css
+/* src/index.css: replace the contents */
+@import "tailwindcss";
+@import "harebear-ui/styles.css";
+```
+
+```tsx
+// src/main.tsx
+import { StrictMode } from "react"
+import { createRoot } from "react-dom/client"
+import { ThemeProvider, Toaster, TooltipProvider } from "harebear-ui"
+import App from "./App"
+import "./index.css"
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <ThemeProvider>
+      <TooltipProvider>
+        <App />
+        <Toaster />
+      </TooltipProvider>
+    </ThemeProvider>
+  </StrictMode>,
+)
+```
+
+Tailwind's Vite guide: https://tailwindcss.com/docs/installation/using-vite
+
+## Next.js (App Router)
+
+```bash
+npx create-next-app@latest my-app --typescript --tailwind --app
+cd my-app
+npm i harebear-ui
+```
+
+`create-next-app --tailwind` sets up Tailwind v4 with `@tailwindcss/postcss`. Add the stylesheet after the Tailwind import:
+
+```css
+/* app/globals.css */
+@import "tailwindcss";
+@import "harebear-ui/styles.css";
+```
+
+```tsx
+// app/layout.tsx
+import type { ReactNode } from "react"
+import { ThemeProvider, ThemeScript, Toaster, TooltipProvider } from "harebear-ui"
+import "./globals.css"
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <ThemeScript />
+      </head>
+      <body>
+        <ThemeProvider>
+          <TooltipProvider>
+            {children}
+            <Toaster />
+          </TooltipProvider>
+        </ThemeProvider>
+      </body>
+    </html>
+  )
+}
+```
+
+- `ThemeScript` sets the `.dark` class before first paint, so dark-mode users don't see a light flash. `suppressHydrationWarning` on `<html>` is needed because that class is added before React hydrates.
+- Every component module ships with `"use client"`, so you can import harebear-ui from server components (layouts, pages) and pass server data in as props.
+- Remove the starter's own `:root` color variables and `body` styles from `globals.css`; they fight the harebear tokens.
+- `AppShell` renders plain `<a>` links by default. Pass `linkComponent={Link}` (from `next/link`) for client-side navigation.
+
+Tailwind's Next.js guide: https://tailwindcss.com/docs/installation/framework-guides/nextjs
+
+## React Router v7 (framework mode)
+
+```bash
+npx create-react-router@latest my-app
+cd my-app
+npm i harebear-ui
+```
+
+The template ships Tailwind v4 through `@tailwindcss/vite`. Add the stylesheet:
+
+```css
+/* app/app.css */
+@import "tailwindcss";
+@import "harebear-ui/styles.css";
+```
+
+```tsx
+// app/root.tsx (Layout only; keep the rest of the file)
+import { ThemeProvider, ThemeScript, Toaster, TooltipProvider } from "harebear-ui"
+
+export function Layout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <meta charSet="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <ThemeScript />
+        <Meta />
+        <Links />
+      </head>
+      <body>
+        <ThemeProvider>
+          <TooltipProvider>
+            {children}
+            <Toaster />
+          </TooltipProvider>
+        </ThemeProvider>
+        <ScrollRestoration />
+        <Scripts />
+      </body>
+    </html>
+  )
+}
+```
+
+If the template's `app.css` sets its own font (`@theme { --font-sans: ... }`) or page colors (`html, body { @apply bg-white dark:bg-gray-950 }`), remove them, along with any Google Fonts `links` export in `root.tsx`. Geist is bundled and the tokens handle both modes.
+
+## Check it works
+
+Render a few components and look at them in both modes:
+
+```tsx
+import { Button, Card, CardContent, CardHeader, CardTitle, StatusBadge, ThemeToggle } from "harebear-ui"
+import { PlusIcon } from "lucide-react"
+
+export default function App() {
+  return (
+    <main className="mx-auto flex max-w-3xl flex-col gap-5 p-8">
+      <div className="flex items-center justify-between">
+        <h1 className="font-semibold text-2xl">Hello harebear</h1>
+        <ThemeToggle />
+      </div>
+      <Card>
+        <CardHeader>
+          <CardTitle>Deploys</CardTitle>
+        </CardHeader>
+        <CardContent className="flex items-center gap-3">
+          <StatusBadge tone="success">Healthy</StatusBadge>
+          <Button>
+            <PlusIcon /> New deploy
+          </Button>
+        </CardContent>
+      </Card>
+    </main>
+  )
+}
+```
+
+`lucide-react` is a dependency of harebear-ui; add it to your own `package.json` if you import icons directly (`npm i lucide-react`).
+
+You should see a white card on a light grey page with Geist text and a blue button. The toggle flips to the dark theme.
+
+## Troubleshooting
+
+| Symptom                                   | Cause and fix                                                                                                                              |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| Components render unstyled                | The stylesheet import is missing or comes before `@import "tailwindcss"`. It must come after.                                              |
+| Some classes are missing (spacing, color) | Tailwind v3 is installed. harebear-ui needs v4 (`npm ls tailwindcss`).                                                                     |
+| Flash of light theme on load (SSR)        | Render `<ThemeScript />` in `<head>`. If you pass `storageKey` or `defaultMode` to `ThemeProvider`, pass the same values to `ThemeScript`. |
+| Accent or radius flashes on load (SSR)    | `accent` and `radius` props apply after hydration. For SSR, set `--brand` and `--radius` in CSS instead (see [Theming](theming.md)).       |
+| Tooltips don't show                       | `TooltipProvider` is missing near the root.                                                                                                |
+| `toast()` does nothing                    | `<Toaster />` is not mounted. Import `toast` from `sonner`.                                                                                |
+| `init` says several Tailwind entry files  | Pass the one your app loads: `npx harebear-ui init --css src/index.css`.                                                                   |
+
+Next: [Theming](theming.md) · [Working with AI agents](agents.md) · [Component catalog](../COMPONENTS.md)

package/docs/guides/theming.md

@@ -0,0 +1,98 @@
+# Theming
+
+Every harebear-ui component reads shadcn-named CSS variables. You change the look in three places, from least to most effort:
+
+1. `ThemeProvider` props: accent, radius, font, default mode.
+2. CSS variables after the stylesheet import: any token, per mode.
+3. `className` on a component: one-off layout. Not for colors.
+
+## ThemeProvider
+
+```tsx
+;<ThemeProvider defaultMode="system" accent="#0f8a7e" radius={10} font="Inter">
+  <App />
+</ThemeProvider>
+```
+
+| Prop          | Default            | What it does                                                                                  |
+| ------------- | ------------------ | --------------------------------------------------------------------------------------------- |
+| `defaultMode` | `"system"`         | `"light"`, `"dark"` or `"system"`. Used until the user picks a mode.                          |
+| `accent`      | `#2f5bd3`          | Any CSS color. Sets `--brand`; `primary`, `primary-soft`, rings and `chart-1` derive from it. |
+| `radius`      | `14`               | Base corner radius in px. The `rounded-sm` to `rounded-4xl` scale derives from it.            |
+| `font`        | Geist              | Body font family name. Load the font yourself; Geist and Geist Mono are bundled.              |
+| `storageKey`  | `"harebear-theme"` | localStorage key for the chosen mode. `null` turns persistence off.                           |
+
+In dark mode `primary` is the accent mixed 26% toward white, so one accent reads well on both backgrounds.
+
+### Change it at runtime
+
+```tsx
+import { useTheme } from "harebear-ui"
+
+function AccentPicker() {
+  const { accent, setAccent, radius, setRadius, mode, setMode } = useTheme()
+  return (
+    <>
+      <input type="color" value={accent ?? "#2f5bd3"} onChange={(e) => setAccent(e.target.value)} />
+      <input type="range" min={0} max={24} value={radius ?? 14} onChange={(e) => setRadius(Number(e.target.value))} />
+      <button type="button" onClick={() => setMode(mode === "dark" ? "light" : "dark")}>
+        Toggle mode
+      </button>
+    </>
+  )
+}
+```
+
+`ThemeToggle` is the ready-made light/dark icon button. `UserMenu` includes a Light / Dark / System choice.
+
+## CSS variables
+
+Override tokens after the import. `:root` is light mode, `.dark` is dark mode:
+
+```css
+@import "tailwindcss";
+@import "harebear-ui/styles.css";
+
+:root {
+  --brand: #0f8a7e;
+  --radius: 0.625rem;
+}
+
+.dark {
+  --background: #0b0b0d;
+  --card: #141417;
+}
+```
+
+Use CSS rather than props when the first paint must be right (SSR apps): `ThemeProvider` applies `accent` and `radius` in an effect, after hydration.
+
+The full token list, with what each is for, is in the [component catalog](../COMPONENTS.md#tokens) (`npx harebear-ui docs Tokens`). The ones you will use most:
+
+| Token                               | Tailwind utilities                                |
+| ----------------------------------- | ------------------------------------------------- |
+| `background`, `foreground`          | `bg-background`, `text-foreground`                |
+| `card`                              | `bg-card` (raised surfaces)                       |
+| `muted`, `muted-foreground`         | `bg-muted` (inputs, quiet panels), secondary text |
+| `primary`, `primary-soft`           | `bg-primary`, `bg-primary-soft text-primary`      |
+| `success`, `warning`, `destructive` | `text-success`, `bg-success/12`, and so on        |
+| `border`                            | `border-border` (the default border color)        |
+| elevation                           | `shadow-card` (the one shadow)                    |
+
+## Rules that keep a themed app consistent
+
+- Colors come from tokens only. No hex values, no Tailwind palette colors (`bg-blue-500`), no inline `style={{ color }}`. A palette color will look wrong in one of the two modes.
+- Status is a tone, not a color: `tone="success" | "warning" | "danger" | "info" | "neutral"` on `StatusBadge`, `StatusDot`, `Badge`, `Timeline`, `StatusBars`, `LinkTile`.
+- Cards are `rounded-xl`, controls are `rounded-md`. Both follow `--radius`.
+- If you reach for `className` to fix a harebear component's color, spacing or border, that is a gap in the library. Open an issue rather than overriding it per screen.
+
+## Fonts
+
+Geist (sans) and Geist Mono are bundled and on by default. To use another family, load it however your framework does (`next/font`, `@fontsource`, a `<link>`), then pass its name:
+
+```tsx
+<ThemeProvider font="Inter">
+```
+
+Or set it in CSS: `:root { --hb-font-sans: "Inter", ui-sans-serif, system-ui, sans-serif; }`. Code uses `--hb-font-mono`.
+
+Next: [Working with AI agents](agents.md) · [Component catalog](../COMPONENTS.md)

package/llms.txt

@@ -20,6 +20,10 @@
 ## Docs
 
 - [Component catalog](docs/COMPONENTS.md): every export with props and examples. In an installed app: node_modules/harebear-ui/docs/COMPONENTS.md
+- Look up single entries instead of reading it all: `npx harebear-ui docs DataTable StatCard` (export names, a prefix like `Prompt`, or a section like `Tokens`). Exits 1 when nothing matches.
+- [Getting started](docs/guides/getting-started.md): setup for Vite, Next.js App Router and React Router v7, plus troubleshooting.
+- [Theming](docs/guides/theming.md): ThemeProvider props, CSS token overrides, fonts, SSR.
+- [Working with AI agents](docs/guides/agents.md): what init installs, per-tool setup, prompts, review checklist.
 - [Agent skill](skills/harebear-ui/SKILL.md): Claude Code skill, installed by `npx harebear-ui init`.
 - [Example screens](https://github.com/hmilbradt/harebear-ui/tree/main/playground/screens): admin dashboard, AI chat, data table + detail panel, status home page, auth pages, component catalog.
 - [Source](https://github.com/hmilbradt/harebear-ui)
@@ -28,8 +32,9 @@
 
 Theme: ThemeProvider, useTheme, ThemeToggle, ThemeScript
 Layout/admin: SidebarLayout, SidebarCollapseButton, AppShell, AppBrand, PageHeader, StatCard, SearchInput, StatusDot, StatusBadge, UsageMeter, ActivityFeed, Timeline, KeyValueGrid, UserChip, UserMenu, Callout, LinkTile, ConfirmDialog, CopyField
+Layout and text: Stack, Row, Grid, Text, Heading, Metric, MetricGroup, MediaItem, ShowMore
 Data: DataTable, createDataTableColumnHelper, TrendChart, TrendLegend, BarList, Sparkline, StatusBars
-AI/chat composites: ChatShell, ChatPanel, ChatThread, ChatMessage, AssistantAvatar, MessageActions, PromptInput, PromptInputChip, PromptInputSelect, ModelPicker, ConversationList, NewConversationButton, groupByDate, ToolCall, ToolGroup, ToolStep, ToolStatusIcon, ApprovalCard, ApprovalResult, TypingIndicator, CodeSnippet, InlineCode, Prose
+AI/chat composites: ChatShell, ChatPanel, ChatThread, ChatMessage, AssistantAvatar, MessageActions, PromptInput, PromptInputChip, PromptInputSelect, ModelPicker, ConversationList, NewConversationButton, groupByDate, formatWhen, ToolCall, ToolGroup, ToolStep, ToolStatusIcon, ApprovalCard, ApprovalResult, TypingIndicator, CodeSnippet, InlineCode, Prose
 AI/chat primitives (shadcn): Message, Bubble, MessageScroller, Attachment, Trace, Marker, Questionnaire, CodeBlock
 Auth: AuthLayout, LoginForm, SignupForm, GitHubIcon, GoogleIcon, AppleIcon
 Primitives (the full shadcn/ui registry): Accordion, Alert, AlertDialog, AspectRatio, Attachment, Avatar, Badge, Breadcrumb, Bubble, Button, ButtonGroup, Calendar, Card, Carousel, Chart, Checkbox, CodeBlock, Collapsible, Combobox, Command, ContextMenu, Dialog, DirectionProvider, Drawer, DropdownMenu, Empty, Field, HoverCard, Input, InputGroup, InputOTP, Item, Kbd, Label, Marker, Menubar, Message, MessageScroller, NativeSelect, NavigationMenu, Pagination, Popover, Progress, Questionnaire, RadioGroup, Resizable, ScrollArea, Select, Separator, Sheet, Sidebar, Skeleton, Slider, Spinner, Switch, Table, Tabs, Textarea, Toaster, Toggle, ToggleGroup, Tooltip, Trace

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harebear-ui",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Opinionated, pre-themed shadcn/ui component library for React 19 + Tailwind CSS v4. Admin, data, and AI chat building blocks, ready for agents.",
   "license": "MIT",
   "author": "Harrison Milbradt",
@@ -58,6 +58,7 @@
     "lint": "biome check .",
     "format": "biome check --write .",
     "test": "vitest run",
+    "shots": "node scripts/screenshots.mjs",
     "check": "pnpm lint && pnpm typecheck && pnpm test && pnpm build && publint && attw --pack . --profile esm-only --exclude-entrypoints ./styles.css ./llms.txt",
     "prepublishOnly": "pnpm check"
   },

package/skills/harebear-ui/SKILL.md

@@ -10,7 +10,7 @@ This project uses `harebear-ui` for all UI. Its theme, tokens, and components ar
 
 ## Before writing UI
 
-1. Read the catalog: `node_modules/harebear-ui/docs/COMPONENTS.md`. It lists every export with props and examples.
+1. Read the catalog: `node_modules/harebear-ui/docs/COMPONENTS.md`. It lists every export with props and examples. To pull only what you need, run `npx harebear-ui docs DataTable StatCard` (export names, a name prefix such as `Prompt`, or a section such as `Tokens`).
 2. Pick existing components first. Build new components only by composing harebear-ui parts.
 3. For a whole screen, start from the closest reference screen: admin dashboard, AI chat, data table with detail panel, status home page, or auth (https://github.com/hmilbradt/harebear-ui/tree/main/playground/screens).