@skunkworksai/ui-kit 0.1.18

package/AGENTS.md

@@ -0,0 +1,250 @@
+# @skunkworksai/ui-kit — AI Agent Guide
+
+This file ships with the package (`@skunkworksai/ui-kit`). It tells AI agents how to use `@skunkworksai/ui-kit` correctly in consumer applications.
+
+---
+
+## What this package is
+
+`@skunkworksai/ui-kit` is a React component library built on shadcn/ui + Radix UI + Tailwind CSS v4. It exports two layers of components:
+
+- **Primitives (`App*`)** — brand-wrapped wrappers around shadcn base components. These are what you use in product code.
+- **Blocks** — pre-composed product sections built from primitives (dashboards, headers, table managers).
+
+---
+
+## Installation
+
+```bash
+pnpm add @skunkworksai/ui-kit
+```
+
+---
+
+## Project setup
+
+If the user asks you to set up `@skunkworksai/ui-kit` in a new project (scaffold tokens, assets, configure imports), read `node_modules/@skunkworksai/ui-kit/README.md` → "Setup" section and follow it exactly. Do not attempt setup from memory — steps must be exact (file paths, import order, scaffold script).
+
+For agent setup specifically, ensure the consumer project has this line in its `CLAUDE.md` or `AGENTS.md`:
+
+```
+@node_modules/@skunkworksai/ui-kit/AGENTS.md
+```
+
+---
+
+## Import pattern
+
+Always import from the package root:
+
+```tsx
+// ✅ Correct
+import { AppButton, AppCard, AppInput } from '@skunkworksai/ui-kit'
+
+// ❌ Wrong — internal paths and direct Radix imports are not allowed
+import { Button } from '@skunkworksai/ui-kit/dist/components/ui/button'
+import { Dialog } from '@skunkworksai/ui-kit/src/components/ui/dialog'
+import * as RadixDialog from '@radix-ui/react-dialog'
+```
+
+Assets are NOT exported from the package. Import from your scaffolded copy:
+
+```tsx
+import { PrimaryLogo } from './assets/logos'
+import { DashboardIcon } from './assets/icons'
+```
+
+---
+
+## Three-layer architecture
+
+```
+ui/          ← Layer 1: shadcn/ui base. DO NOT import directly in product code.
+primitives/  ← Layer 2: App* wrappers. USE THESE in product code.
+blocks/      ← Layer 3: Pre-composed sections. USE THESE for full page sections.
+```
+
+**Always use `App*` primitives** — never raw shadcn base components. The `App*` prefix signals brand-compliant components.
+
+---
+
+## Token & styling rules
+
+All colors, spacing, and radii come from CSS custom properties. Never hardcode values.
+
+```tsx
+// ✅ Correct — semantic token classes
+<div className="bg-background text-foreground border-border" />
+<div className="bg-primary text-primary-foreground" />
+
+// ❌ Wrong — hardcoded
+<div className="bg-blue-500 text-white" />
+<div style={{ color: '#3B82F6' }} />
+```
+
+- Dark mode handled automatically by CSS variables — no manual `dark:` color overrides
+- Use `cn()` for className merging — never string concatenation
+- Use `gap-*` not `space-x-*` / `space-y-*`
+- Use `size-*` when width and height are equal
+- Never inline `style={{}}` — use Tailwind arbitrary properties instead:
+  ```tsx
+  // ✅ Correct
+  <div className="[--sidebar:transparent]" />
+  // ❌ Wrong
+  <div style={{ '--sidebar': 'transparent' }} />
+  ```
+- No `z-index` on overlay components — Dialog, Sheet, Popover manage their own stacking
+
+---
+
+## Composition rules
+
+Build pages from `App*` primitives and blocks — never from raw HTML or shadcn `ui/` components.
+
+**Required sub-components:**
+- `AppAvatar` → always include `AvatarFallback`
+- `AppDialog` / `AppSheet` / `AppDrawer` → always include `DialogTitle` / `SheetTitle` / `DrawerTitle` (use `sr-only` if visually hidden)
+
+**Slot composition:** Many block components (`AppDashboard`, `AppHeader`, etc.) accept `ReactNode` slots. Always fill slots with `App*` components — never raw HTML elements with className.
+
+```tsx
+// ✅ Correct
+<AppDashboard header={{
+  searchbar: <AppInput placeholder="Search..." value={q} onChange={e => setQ(e.target.value)} />
+}} />
+
+// ❌ Wrong — raw <input> with inline classes
+<AppDashboard header={{
+  searchbar: <input className="flex h-9 rounded-md border ..." />
+}} />
+```
+
+If a slot accepts `ReactNode` and you need a form element, find the matching `App*` primitive:
+
+| Raw element | Use instead |
+|-------------|-------------|
+| `<input>` | `AppInput` |
+| `<button>` | `AppButton` |
+| `<select>` | `AppSelect` |
+| `<textarea>` | `AppTextarea` |
+| `<label>` | `AppLabel` |
+| `<table>` | `AppTable` + sub-components |
+
+---
+
+## App layout pattern
+
+Every page in the app is rendered inside a single `AppDashboard` shell. The shell owns the sidebar and header — these are configured **once at the app/router level**, never rebuilt per page.
+
+```
+AppDashboard
+├── sidebar (nav, brand/logo) ← configured once via `nav` + `brand` props
+├── header (search, actions)  ← configured once via `header` prop
+└── children                  ← per-page content goes HERE
+```
+
+```tsx
+import { useNavigate } from "react-router-dom"
+
+// app.tsx or layout.tsx — configured once
+function Shell() {
+  const navigate = useNavigate()
+
+  return (
+    <AppDashboard
+      nav={[
+        {
+          title: "Dashboard",
+          icon: LayoutDashboard,
+          isActive: location.pathname === "/",
+          url: "/",
+          onClick: (e) => { e.preventDefault(); navigate("/") },
+        },
+        {
+          title: "Sites",
+          icon: MapPin,
+          isActive: location.pathname === "/sites",
+          url: "/sites",
+          onClick: (e) => { e.preventDefault(); navigate("/sites") },
+        },
+      ]}
+      header={{
+        searchbar: <AppInput placeholder="Search..." value={q} onChange={e => setQ(e.target.value)} />,
+      }}
+    >
+      <Outlet /> {/* or {children} */}
+    </AppDashboard>
+  )
+}
+
+// per-page — declare title co-located with the page, no shell wiring needed
+import { usePageTitle } from "@skunkworksai/ui-kit"
+
+export default function SitesPage() {
+  usePageTitle({
+    title: "Sites",
+    breadcrumbs: [{ label: "Dashboard", href: "/" }, { label: "Sites" }],
+  })
+  return (
+    <div className="flex flex-col gap-6">
+      <AppCard>...</AppCard>
+      <TableManager ... />
+    </div>
+  )
+}
+```
+
+**Rules — one shell per app:**
+- Don't wrap individual pages in their own `AppDashboard`
+- Don't re-pass `nav` or `header` props on every page render
+- Don't add sidebar or header markup inside page components
+- Don't build custom layout wrappers — `AppDashboard` handles sidebar, header, scroll, and responsive behaviour
+- Don't use DOM queries to bridge sidebar clicks to a router — use `onClick` + `url` on nav items
+- Don't manage page title in the shell via a growing switch/map — use `usePageTitle()` in each page instead
+
+---
+
+## Gap-fill: using raw shadcn components
+
+If no `App*` primitive exists for a UI need, you may use the raw shadcn base as a gap-fill. When you do:
+
+1. Import from `@skunkworksai/ui-kit` (not from `@radix-ui/*` or internal paths)
+2. Keep usage minimal and isolated
+3. **Append an entry to `design-gaps.md`** at the project root so the design team can create a proper primitive
+
+### `design-gaps.md` entry format
+
+```markdown
+## Gap: [ComponentName] — YYYY-MM-DD
+
+- **File:** `src/path/to/file.tsx`
+- **Used:** `<ComponentName>` (raw shadcn — no App* equivalent exists)
+- **Needed primitive:** `AppXxx` — [brief description / variants needed]
+- **Context:** [one sentence on why this was needed]
+```
+
+Send `design-gaps.md` to the design team (email design@skunkworks.ai or paste in the design Slack channel) so gaps get prioritized into the ui-kit backlog. The `app/no-raw-shadcn-imports` ESLint rule (warn level) flags these usages as a reminder.
+
+---
+
+## Per-component rules
+
+Before using a component, read `node_modules/@skunkworksai/ui-kit/rules/<name>.md` for props reference, examples, and dos/don'ts. Replace `<name>` with the component name (examples: `button.md`, `alert-dialog.md`, `data-table.md`).
+
+Available: accordion, alert, alert-dialog, aspect-ratio, avatar, badge, bento-menu, breadcrumb, button, button-group, calendar, card, carousel, chart, checkbox, collapsible, combobox, command, context-menu, dashboard, data-table, date-picker, dialog, drawer, dropdown-menu, empty, field, form, header, hover-card, icons, input, kbd, label, location-tree-filter, logo, menubar, navigation-menu, notifications-menu, pagetitle, pagination, popover, profile, progress, radio-group, scroll-area, scroll-text, select, separator, sheet, sidebar, skeleton, spinner, switch, table, table-manager, tabs, textarea, toaster, toggle, toggle-group, tokens, tooltip, typography.
+
+---
+
+## What NOT to do
+
+| ❌ Never | ✅ Instead |
+|----------|-----------|
+| Use inline `style` props for styling | Tailwind classes or `[--var:value]` |
+| Hardcode color values (`oklch(...)`, `hsl(...)`, `#hex`) | CSS variable classes (`bg-primary`, `text-foreground`) |
+| Import from `@radix-ui/*` directly | Import from `@skunkworksai/ui-kit` |
+| Use raw shadcn `Button`, `Dialog`, etc. | Use `AppButton`, `AppDialog`, etc. |
+| Put raw `<input className="...">` in a slot | Use `AppInput` in the slot |
+| Put raw `<button className="...">` in a slot | Use `AppButton` in the slot |
+| Import from internal paths (`/src/`, `/dist/`) | Import from package root |
+| Import logos or icons from `@skunkworksai/ui-kit` | Import from `./assets/logos` or `./assets/icons` |
+| Attempt project setup from memory | Read `README.md` → Setup section, follow exactly |

package/README.md

@@ -0,0 +1,429 @@
+# @skunkworksai/ui-kit
+
+A React component library built on [shadcn/ui](https://ui.shadcn.com), Tailwind CSS v4, and Radix UI. Exports brand-wrapped `App*` primitives and pre-composed blocks for building product UIs.
+
+---
+
+## Installation
+
+This package is published to GitHub Packages. Authentication is required.
+
+### 1. Create a GitHub Personal Access Token (PAT)
+
+You need a GitHub token with `read:packages` permission to pull from GitHub Packages.
+
+1. Sign in to [github.com](https://github.com)
+2. Click your **profile photo** (top-right) → **Settings**
+3. Scroll to the bottom of the left sidebar → **Developer settings**
+4. Choose **Personal access tokens → Tokens (classic)**
+5. Click **Generate new token → Generate new token (classic)**
+6. Give it a name (e.g. `skunkworks-ui-kit`)
+7. Under **Select scopes**, check **`read:packages`** — nothing else needed
+8. Click **Generate token**
+9. **Copy the token immediately** — GitHub only shows it once
+
+> **Fine-grained tokens:** GitHub's newer fine-grained PATs do not currently support GitHub Packages. Use **classic** tokens.
+
+### 2. Configure `.npmrc`
+
+Add to your project's `.npmrc` (or `~/.npmrc` for global):
+
+```
+@skunkworksai:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${NPM_TOKEN}
+```
+
+Set the env var to your copied token:
+
+```bash
+# macOS / Linux — add to ~/.zshrc or ~/.bashrc to persist
+export NPM_TOKEN=ghp_yourTokenHere
+
+# Windows (PowerShell)
+$env:NPM_TOKEN="ghp_yourTokenHere"
+
+# Windows (cmd)
+set NPM_TOKEN=ghp_yourTokenHere
+```
+
+> **CI/CD:** add `NPM_TOKEN` as a secret in your GitHub Actions / CI settings and it will be available automatically — no code changes needed.
+
+### 3. Install
+
+```bash
+pnpm add @skunkworksai/ui-kit
+```
+
+To get the latest release:
+
+```bash
+pnpm add @skunkworksai/ui-kit@latest
+```
+
+Peer dependencies — your project must already have React 18 or 19:
+
+```bash
+pnpm add react@>=18 react-dom@>=18
+```
+
+---
+
+## Agent setup (Claude, Gemini, etc.)
+
+Run once in your project root:
+
+```bash
+echo "@node_modules/@skunkworksai/ui-kit/AGENTS.md" >> CLAUDE.md
+```
+
+This auto-loads component rules, naming conventions, token guidelines, and dos/don'ts at every Claude Code session. Per-component rules live in `node_modules/@skunkworksai/ui-kit/rules/` and are referenced from `AGENTS.md`.
+
+Once set up, your agent can guide you through the Setup steps below — including scaffolding tokens and assets, wiring imports, and building your first page.
+
+---
+
+## Setup
+
+### 1. Import the stylesheet
+
+In your app entry (e.g. `main.tsx`):
+
+```ts
+import '@skunkworksai/ui-kit/styles'
+```
+
+This imports Tailwind utilities and component CSS. **It does not include color values** — those come from your token file (next step).
+
+### 2. Scaffold your token file
+
+Copy the token source into your project using the included scaffold script (works on all platforms):
+
+```bash
+node node_modules/@skunkworksai/ui-kit/scripts/scaffold.mjs
+```
+
+This copies `tokens-source.css` → `src/tokens.css` and `dist/assets/` → `src/assets/` in one step. Skip to step 5 after running it.
+
+Alternatively, copy manually:
+
+```bash
+# macOS / Linux
+cp node_modules/@skunkworksai/ui-kit/dist/tokens-source.css src/tokens.css
+
+# Windows (PowerShell)
+Copy-Item node_modules\@skunkworksai\ui-kit\dist\tokens-source.css src\tokens.css
+```
+
+This gives you a `src/tokens.css` with all color, radius, font, and shadow tokens. You own this file — edit it freely to match your brand or use [tweakcn.com](https://tweakcn.com) to adjust values visually.
+
+### 3. Import your token file
+
+In your app entry, import `tokens.css` **after** the stylesheet:
+
+```ts
+// main.tsx
+import '@skunkworksai/ui-kit/styles'  // infrastructure first
+import './tokens.css'                   // your tokens second — order matters
+```
+
+Without this, all CSS variables are unresolved and the UI renders with no colors.
+
+### 4. Scaffold assets
+
+Copy logos, icons, and service applet images into your project:
+
+```bash
+# macOS / Linux
+cp -r node_modules/@skunkworksai/ui-kit/dist/assets src/assets
+
+# Windows (PowerShell)
+Copy-Item -Recurse node_modules\@skunkworksai\ui-kit\dist\assets src\assets
+```
+
+Or use the scaffold script from step 2 — it copies both tokens and assets in one command.
+
+You own these files. Import from your own copy, not from the package:
+
+```tsx
+import { PrimaryLogo, WhiteLogo } from './assets/logos'
+import { DashboardIcon, DashboardActiveIcon } from './assets/icons'
+import { AudienceMeasurementImg } from './assets/Service-applets-apps'
+```
+
+On package upgrades, re-run the copy and diff `src/assets/` against the new `dist/assets/` to pick up any changed files.
+
+### 5. Use components
+
+```tsx
+import { AppButton, AppCard, AppCardHeader, AppCardTitle, AppCardContent, AppBadge } from '@skunkworksai/ui-kit'
+
+export default function Example() {
+  return (
+    <AppCard>
+      <AppCardHeader>
+        <AppCardTitle>Hello</AppCardTitle>
+      </AppCardHeader>
+      <AppCardContent className="flex items-center gap-2">
+        <AppButton variant="default">Click me</AppButton>
+        <AppBadge variant="secondary">New</AppBadge>
+      </AppCardContent>
+    </AppCard>
+  )
+}
+```
+
+---
+
+## Component architecture
+
+Three layers — always use `App*` primitives in product code, never the raw `ui/` base:
+
+```
+src/components/
+├── ui/          ← Layer 1: shadcn/ui base. Internal only. Do not import directly.
+├── primitives/  ← Layer 2: App* brand wrappers. Use these in your app.
+└── blocks/      ← Layer 3: Pre-composed product sections (dashboard, table manager, etc.)
+```
+
+---
+
+## Available components
+
+### Primitives
+
+| Component | Exports |
+|-----------|---------|
+| Accordion | `AppAccordion`, `AppAccordionItem`, `AppAccordionTrigger`, `AppAccordionContent` |
+| Alert | `AppAlert`, `AppAlertTitle`, `AppAlertDescription`, `AppAlertContent` |
+| AlertDialog | `AppAlertDialog`, `AppAlertDialogTrigger`, `AppAlertDialogContent`, `AppAlertDialogHeader`, `AppAlertDialogFooter`, `AppAlertDialogTitle`, `AppAlertDialogDescription`, `AppAlertDialogAction`, `AppAlertDialogCancel` |
+| AspectRatio | `AppAspectRatio` |
+| Avatar | `AppAvatar`, `AppAvatarImage`, `AppAvatarFallback` |
+| Badge | `AppBadge` |
+| Breadcrumb | `AppBreadcrumb`, `AppBreadcrumbList`, `AppBreadcrumbItem`, `AppBreadcrumbLink`, `AppBreadcrumbPage`, `AppBreadcrumbSeparator` |
+| Button | `AppButton` |
+| ButtonGroup | `AppButtonGroup` |
+| Calendar | `AppCalendar` |
+| Card | `AppCard`, `AppCardHeader`, `AppCardTitle`, `AppCardDescription`, `AppCardAction`, `AppCardContent`, `AppCardFooter` |
+| Carousel | `AppCarousel`, `AppCarouselContent`, `AppCarouselItem`, `AppCarouselPrevious`, `AppCarouselNext`, `AppCarouselApi`, `useAppCarousel` |
+| Chart | `AppChartContainer`, `AppChartTooltip`, `AppChartTooltipContent`, `AppChartLegend`, `AppChartLegendContent`, `AppChartStyle`, `useAppChart`, `AppChartConfig` |
+| Checkbox | `AppCheckbox` |
+| Collapsible | `AppCollapsible`, `AppCollapsibleTrigger`, `AppCollapsibleContent` |
+| Combobox | `AppCombobox`, `AppComboboxInput`, `AppComboboxContent`, `AppComboboxList`, `AppComboboxItem`, `AppComboboxEmpty`, `AppComboboxSeparator` |
+| Command | `AppCommand`, `AppCommandDialog`, `AppCommandInput`, `AppCommandList`, `AppCommandEmpty`, `AppCommandGroup`, `AppCommandItem`, `AppCommandShortcut`, `AppCommandSeparator` |
+| ContextMenu | `AppContextMenu`, `AppContextMenuTrigger`, `AppContextMenuContent`, `AppContextMenuItem`, `AppContextMenuLabel`, `AppContextMenuSeparator`, … |
+| DataTable | `AppDataTable` |
+| DatePicker | `AppDatePicker` |
+| Dialog | `AppDialog`, `AppDialogTrigger`, `AppDialogContent`, `AppDialogHeader`, `AppDialogTitle`, `AppDialogDescription` |
+| Drawer | `AppDrawer`, `AppDrawerTrigger`, `AppDrawerContent`, `AppDrawerHeader`, `AppDrawerFooter`, `AppDrawerTitle`, `AppDrawerDescription` |
+| DropdownMenu | `AppDropdownMenu`, `AppDropdownMenuTrigger`, `AppDropdownMenuContent`, `AppDropdownMenuItem`, `AppDropdownMenuLabel`, `AppDropdownMenuSeparator`, … |
+| Empty | `AppEmpty`, `AppEmptyHeader`, `AppEmptyMedia`, `AppEmptyTitle`, `AppEmptyDescription`, `AppEmptyContent` |
+| Field | `AppField`, `AppFieldLabel`, `AppFieldControl`, `AppFieldDescription`, `AppFieldError`, `AppFieldContent`, `AppFieldTitle`, `AppFieldGroup`, `AppFieldSet`, `useAppField` |
+| Form | `AppForm`, `AppFormItem`, `AppFormLabel`, `AppFormControl`, `AppFormDescription`, `AppFormMessage`, `AppFormField` |
+| HoverCard | `AppHoverCard`, `AppHoverCardTrigger`, `AppHoverCardContent` |
+| Input | `AppInput` |
+| Kbd | `AppKbd`, `AppKbdGroup` |
+| Label | `AppLabel` |
+| Menubar | `AppMenubar`, `AppMenubarMenu`, `AppMenubarTrigger`, `AppMenubarContent`, `AppMenubarItem`, `AppMenubarSeparator`, `AppMenubarLabel`, … |
+| NavigationMenu | `AppNavigationMenu`, `AppNavigationMenuList`, `AppNavigationMenuItem`, `AppNavigationMenuTrigger`, `AppNavigationMenuContent`, `AppNavigationMenuLink` |
+| Pagination | `AppPagination`, `AppPaginationContent`, `AppPaginationItem`, `AppPaginationLink`, `AppPaginationPrevious`, `AppPaginationNext`, `AppPaginationEllipsis` |
+| Popover | `AppPopover`, `AppPopoverTrigger`, `AppPopoverContent` |
+| Progress | `AppProgress` |
+| RadioGroup | `AppRadioGroup`, `AppRadioGroupItem` |
+| ScrollArea | `AppScrollArea`, `AppScrollBar` |
+| ScrollText | `AppScrollText` |
+| Select | `AppSelect`, `AppSelectTrigger`, `AppSelectValue`, `AppSelectContent`, `AppSelectItem`, `AppSelectLabel` |
+| Separator | `AppSeparator` |
+| Sheet | `AppSheet`, `AppSheetTrigger`, `AppSheetContent`, `AppSheetHeader`, `AppSheetTitle`, `AppSheetDescription` |
+| Skeleton | `AppSkeleton` |
+| Spinner | `AppSpinner` |
+| Switch | `AppSwitch` |
+| Table | `AppTable`, `AppTableHeader`, `AppTableBody`, `AppTableFooter`, `AppTableHead`, `AppTableRow`, `AppTableCell`, `AppTableCaption` |
+| Tabs | `AppTabs`, `AppTabsList`, `AppTabsTrigger`, `AppTabsContent` |
+| Textarea | `AppTextarea` |
+| Toggle | `AppToggle` |
+| ToggleGroup | `AppToggleGroup`, `AppToggleGroupItem` |
+| Tooltip | `AppTooltip`, `AppTooltipProvider`, `AppTooltipTrigger`, `AppTooltipContent` |
+| Typography | `AppTypography` |
+| Toaster | `AppToaster`, `sonnerToast` |
+| ThemeProvider | `AppThemeProvider`, `useAppTheme`, `AppThemeToggle` |
+
+### Blocks
+
+| Block | Exports |
+|-------|---------|
+| Dashboard | `AppDashboard`, `AppDashboardBackground`, `AppDashboardContent`, `AppDashboardMain` |
+| Header | `AppHeader`, `AppHeaderContent`, `AppHeaderTitle`, `AppHeaderSearchbar`, `AppHeaderActions`, `AppHeaderNetworkCombobox` |
+| BentoMenu | `AppBentoMenu`, `AppBentoMenuItem`, `DEFAULT_BENTO_APPS` |
+| NotificationsMenu | `AppNotificationsMenu`, `type AppNotification`, `type AppNotificationVariant` |
+| PageTitle | `AppPageTitle` |
+| Profile | `AppProfile`, `type AppProfileUser`, `type AppProfileItem` |
+| TableManager | `TableManager`, `TableManagerToolbar`, `TableManagerSearch`, `TableManagerToolbarActions`, `TableManagerMultiFilter`, `TableManagerDateRange`, `TableManagerRowsPerPage`, `TableManagerPagination`, `TableManagerColumnToggle`, `TableManagerExport`, `TableManagerContent`, `TableManagerFooter` |
+| LocationTreeFilter | `AppLocationTreeFilter` |
+
+### Assets
+
+Assets ship as raw files in `dist/assets/`. After running the scaffold step in Setup (step 4), import from `src/assets/` — not from the package directly.
+
+```tsx
+import { PrimaryLogo, DarkLogo, WhiteLogo } from './assets/logos'
+import { PrimarySymbol, DarkSymbol, WhiteSymbol } from './assets/logos'
+import { DashboardIcon, DashboardActiveIcon } from './assets/icons'
+import { AudienceMeasurementImg } from './assets/Service-applets-apps'
+```
+
+---
+
+## Styling rules
+
+- All colors from CSS variables — never hardcode `#hex`, `hsl()`, or `oklch()` values
+- Use `className` with Tailwind utilities — never inline `style` props
+- Dark mode handled automatically via CSS variables — no manual `dark:` color overrides needed
+- Use `clsx` or your own `cn` helper for className merging
+
+```tsx
+import { clsx } from 'clsx'
+
+<AppButton className={clsx('w-full', isLoading && 'opacity-50')} />
+```
+
+---
+
+## Building pages with AI agents
+
+After adding `CLAUDE.md` (see Agent setup above), your agent knows every component, its props, token rules, and composition patterns. Describe what you want to build — the agent picks the right components and wires them together correctly.
+
+**Tip:** Be outcome-focused. Don't specify component names unless you know exactly what you need — the agent reads the rules files and picks the right ones.
+
+### Dashboard page
+
+```
+Build a dashboard page using AppDashboard with:
+- Sidebar with sections: Dashboard, Sites, Users, Reports, Settings
+- Header with a search bar and user avatar
+- Three stat cards at the top showing total sites, active sessions, and uptime
+- A data table below with pagination
+
+Use the ui-kit rules for each component.
+```
+
+### Settings page
+
+```
+Build a settings page with:
+- AppHeader with title "Settings"
+- AppTabs for General / Security / Notifications
+- AppCard sections within each tab using AppForm, AppInput, AppLabel, AppSwitch
+- AppButton for save actions
+Follow the rules in node_modules/@skunkworksai/ui-kit/rules/ for each component used.
+```
+
+### Custom component
+
+```
+Create a user profile card using ui-kit components that shows:
+- AppAvatar with fallback initials
+- User name and role using AppTypography
+- A row of AppBadge for skills/tags
+- AppButton for "Edit Profile" and "Message"
+Do not hardcode any colors. Use token classes only.
+```
+
+Agents read the relevant `rules/*.md` files automatically and produce token-compliant, accessible output without you specifying every prop.
+
+---
+
+## Theming
+
+All design tokens are CSS custom properties defined in your `src/tokens.css` (scaffolded in Setup step 2). Edit that file directly to change colors, radius, fonts, or shadows — no Tailwind config or build step required.
+
+Use [tweakcn.com](https://tweakcn.com) to adjust values visually: paste your `src/tokens.css` in, tweak, paste back.
+
+```css
+/* src/tokens.css — edit any token */
+:root {
+  --primary: oklch(0.6 0.2 250);
+  --primary-foreground: oklch(1 0 0);
+  --radius: 0.75rem;
+  --font-sans: 'Inter', ui-sans-serif, sans-serif;
+}
+```
+
+### Available tokens
+
+| Token | Default role |
+|-------|-------------|
+| `--primary` | Brand color — buttons, links, focus rings |
+| `--primary-foreground` | Text on primary backgrounds |
+| `--secondary` | Secondary surfaces |
+| `--secondary-foreground` | Text on secondary backgrounds |
+| `--background` | Page background |
+| `--foreground` | Default text color |
+| `--muted` | Muted surface (inputs, subtle areas) |
+| `--muted-foreground` | Placeholder / secondary text |
+| `--accent` | Hover states, highlights |
+| `--accent-foreground` | Text on accent backgrounds |
+| `--destructive` | Error / danger color |
+| `--destructive-foreground` | Text on destructive backgrounds |
+| `--success` | Success states |
+| `--warning` | Warning states |
+| `--border` | Default border color |
+| `--input` | Input border color |
+| `--ring` | Focus ring color |
+| `--radius` | Base border radius |
+| `--font-sans` | Sans-serif font stack |
+| `--sidebar` | Sidebar background |
+| `--chart-1` … `--chart-5` | Chart color palette |
+
+### Dark mode
+
+Dark mode tokens are set automatically when a `.dark` class is applied to a parent element. Override dark mode tokens with:
+
+```css
+.dark {
+  --primary: oklch(0.65 0.2 250);
+  --background: oklch(0.1 0.02 265);
+}
+```
+
+---
+
+## Development (contributing to this repo)
+
+```bash
+# Install dependencies
+pnpm install
+
+# Storybook component explorer
+pnpm dev
+
+# Library build (outputs to dist/)
+pnpm build:lib
+
+# Docs site
+cd docs && pnpm install && pnpm dev
+
+# Typecheck
+pnpm typecheck
+
+# Lint
+pnpm lint
+```
+
+See `AGENTS.dev.md` for the full contributor workflow (build → review → publish phases, component addition guide, architecture rules).
+
+---
+
+## Tech stack
+
+- React ≥ 18
+- Tailwind CSS v4
+- Radix UI primitives
+- shadcn/ui base components
+- Vite (library build + Storybook)
+- TypeScript
+
+---
+
+## License
+
+MIT