@skunkworksai/ui-kit 0.1.18 → 0.1.23

package/AGENTS.md

@@ -231,7 +231,7 @@ Send `design-gaps.md` to the design team (email design@skunkworks.ai or paste in
 
 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.
+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, wizard-stepper.
 
 ---
 

package/README.md

@@ -6,6 +6,8 @@ A React component library built on [shadcn/ui](https://ui.shadcn.com), Tailwind
 
 ## Installation
 
+> **Do not clone this repository.** This is a private source repo. Consume the package via `pnpm add` only — cloning gives you no working build and no support path.
+
 This package is published to GitHub Packages. Authentication is required.
 
 ### 1. Create a GitHub Personal Access Token (PAT)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skunkworksai/ui-kit",
-  "version": "0.1.18",
+  "version": "0.1.23",
   "private": false,
   "type": "module",
   "main": "./dist/index.cjs",
@@ -48,7 +48,7 @@
     "react-dom": ">=18"
   },
   "dependencies": {
-    "@base-ui/react": "^1.3.0",
+    "@base-ui/react": "^1.5.0",
     "@radix-ui/react-accordion": "^1.2.0",
     "@radix-ui/react-alert-dialog": "^1.1.0",
     "@radix-ui/react-aspect-ratio": "^1.1.0",
@@ -62,7 +62,7 @@
     "@radix-ui/react-label": "^2.1.0",
     "@radix-ui/react-navigation-menu": "^1.2.0",
     "@radix-ui/react-popover": "^1.1.0",
-    "@radix-ui/react-progress": "^1.1.0",
+    "@radix-ui/react-progress": "^1.1.8",
     "@radix-ui/react-radio-group": "^1.1.0",
     "@radix-ui/react-scroll-area": "^1.1.0",
     "@radix-ui/react-select": "^2.1.0",
@@ -78,40 +78,50 @@
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.0.0",
-    "date-fns": "^4.1.0",
+    "date-fns": "^4.3.0",
     "embla-carousel": "^8.6.0",
     "embla-carousel-react": "^8.6.0",
-    "lucide-react": "^0.577.0",
-    "motion": "^12.38.0",
+    "lucide-react": "^1.16.0",
+    "motion": "^12.40.0",
     "radix-ui": "^1.4.3",
-    "react-day-picker": "^9.4.0",
-    "react-hook-form": "^7.54.0",
+    "react-day-picker": "^10.0.1",
+    "react-hook-form": "^7.76.1",
     "recharts": "^3.8.1",
-    "shadcn": "^4.1.0",
-    "sonner": "^1.7.0",
-    "tailwind-merge": "^3.5.0",
+    "sonner": "^2.0.7",
+    "tailwind-merge": "^3.6.0",
     "tw-animate-css": "^1.4.0"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@storybook/addon-a11y": "^8",
     "@storybook/addon-docs": "^8",
     "@storybook/addon-onboarding": "^8",
     "@storybook/react": "^8",
     "@storybook/react-vite": "^8",
     "@tailwindcss/vite": "^4",
-    "@types/node": "^20",
+    "@types/node": "^25",
     "@types/react": "^19",
     "@types/react-dom": "^19",
-    "@vitejs/plugin-react-swc": "^3",
-    "eslint": "^9",
-    "react": "19.2.4",
-    "react-dom": "19.2.4",
+    "@vitejs/plugin-react-swc": "^4",
+    "eslint": "^10",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-react-refresh": "^0.5.2",
+    "globals": "^17.6.0",
+    "react": "19.2.6",
+    "react-dom": "19.2.6",
+    "shadcn": "^4.8.0",
     "storybook": "^8",
     "tailwindcss": "^4",
     "tailwindcss-animate": "^1.0.7",
-    "typescript": "^5",
+    "typescript": "^6",
+    "typescript-eslint": "^8.59.4",
     "vite": "^6",
-    "vite-plugin-checker": "^0.9"
+    "vite-plugin-checker": "^0.13"
   },
-  "packageManager": "pnpm@10.32.1"
+  "packageManager": "pnpm@10.32.1",
+  "pnpm": {
+    "overrides": {
+      "ws@>=8.0.0 <8.20.1": ">=8.20.1"
+    }
+  }
 }

package/rules/button.md

@@ -61,6 +61,7 @@ import { AppButton } from "@/components/primitives/AppButton"
 - ✅ Use the `loading` prop for async actions — do not place `AppSpinner` inside manually
 - ✅ Use `iconLeft` / `iconRight` for icons — do not wrap icons in extra `<div>` or `<span>`
 - ✅ Use `variant` for color intent — do not override button color with Tailwind color classes
+- ✅ `AppButton` forwards refs to the underlying `<button>` element — safe to use as `asChild` child of Radix primitives (e.g. `PopoverTrigger`, `TooltipTrigger`)
 - ❌ Do not use `size="icon"` with text children — icon size is for icon-only buttons
 - ❌ Do not set `gap` or `flex` on the button — icon spacing is controlled by the size variant
 - ❌ If a prop you need is missing, stop and inform the design team

package/rules/dashboard.md

@@ -133,6 +133,58 @@ import { AppDashboardBackgroundWave, AppDashboardBackgroundDots } from '@skunkwo
 | `AppDashboardBackgroundWave` | Perlin noise wave grid + mouse-follow glow. Default. |
 | `AppDashboardBackgroundDots` | Uniform dot grid. Dots fade near cursor (closer = lower opacity). |
 
+### Background preset props
+
+Both presets share the following props in addition to `animated` and `interactive`:
+
+#### `AppDashboardBackgroundDots`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `color` | `string` | `--sidebar-ring` | Dot color. Any valid CSS color string: hex, oklch, hsl, or `var(--token)`. |
+
+#### `AppDashboardBackgroundWave`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `color` | `string` | `--sidebar-ring` | Wave line color. Any valid CSS color string: hex, oklch, hsl, or `var(--token)`. |
+| `glowColor` | `string` | `--sidebar-primary` / `--sidebar-accent` | Cursor glow color. Replaces both glow layers with a single color mixed at different opacities. |
+
+### Customizing background color
+
+```tsx
+import { AppDashboardBackgroundWave, AppDashboardBackgroundDots } from '@skunkworks-ai/ui-kit'
+
+// Wave with custom line + glow color (oklch, hex, hsl, or CSS variable — all valid)
+<AppDashboard background={
+  <AppDashboardBackgroundWave
+    color="oklch(0.75 0.18 150)"
+    glowColor="oklch(0.75 0.18 150)"
+  />
+}>
+  ...
+</AppDashboard>
+
+// Dots with custom dot color
+<AppDashboard background={
+  <AppDashboardBackgroundDots color="#ff6b35" />
+}>
+  ...
+</AppDashboard>
+
+// Using a design token from the consumer's theme
+<AppDashboard background={
+  <AppDashboardBackgroundWave
+    color="var(--brand-primary)"
+    glowColor="var(--brand-primary)"
+  />
+}>
+  ...
+</AppDashboard>
+```
+
+When `color` is omitted, both presets fall back to the resolved value of `--sidebar-ring`. When `glowColor` is omitted on Wave, the glow uses `--sidebar-primary` and `--sidebar-accent`.
+
 ### Custom background contract
 
 Custom backgrounds receive `animated`, `interactive`, and `themeClass` from `AppDashboardBackgroundContext`:
@@ -183,9 +235,11 @@ The canvas animation runs by default. Use `animated` to control it:
 
 **When `animated="auto"` (default):** animation runs normally unless the user's OS has `prefers-reduced-motion: reduce` set, in which case the canvas is skipped automatically. No consumer code needed for accessibility compliance.
 
-## AppThemeProvider requirement
+## AppThemeProvider
+
+`AppDashboard` includes `AppThemeProvider` internally — the theme toggle works out of the box with no extra setup required.
 
-The default header includes a theme toggle that requires `AppThemeProvider` in the tree:
+If you use `AppHeader` standalone (outside `AppDashboard`), wrap your layout with `AppThemeProvider` for the toggle to function:
 
 ```tsx
 import { AppThemeProvider } from '@skunkworksai/ui-kit'
@@ -201,8 +255,6 @@ export default function RootLayout({ children }) {
 }
 ```
 
-Without it, the toggle renders but does nothing.
-
 ## Nav types
 
 ```ts

package/rules/header.md

@@ -20,7 +20,7 @@ All right-side controls are included by default. Each can be removed or replaced
 |------|------|---------|-------------|
 | `searchbar` | `ReactNode` | standard search input | Searchbar slot. Pass `<AppInput />` to customise. `null` removes it entirely. |
 | `actions` | `ReactNode` | network combobox + bento + theme toggle + avatar | Entire right-side slot. `null` removes all actions. Overrides all other action props. |
-| `avatar` | `ReactNode` | `AppAvatar` with fallback `"KA"` | Avatar inside default actions. `null` hides it. Ignored when `actions` is provided. |
+| `avatar` | `ReactNode` | `AppAvatar` with `UserRound` icon | Avatar inside default actions. `null` hides it. Ignored when `actions` is provided. |
 | `networkSelect` | `ReactNode` | `AppHeaderNetworkCombobox` | Network picker inside default actions. `null` hides it. Pass a custom node to override. Ignored when `actions` is provided. |
 | `networks` | `NetworkOption[]` | 2 demo entries | List of networks for the built-in combobox. Ignored when `networkSelect` or `actions` is provided. |
 | `currentNetwork` | `string` | first network in list | Controlled selected network. Omit for uncontrolled. Ignored when `networkSelect` or `actions` is provided. |
@@ -163,6 +163,8 @@ Customize via the `header` prop — never import `AppHeader` directly for this:
 
 Only needed when building a custom layout that does not use `AppDashboard`:
 
+> **Note:** `AppThemeProvider` is required for the theme toggle to function. When using `AppHeader` inside `AppDashboard`, this is handled automatically. For standalone usage, wrap your layout with `AppThemeProvider`.
+
 ```tsx
 import { AppHeader, type NetworkOption } from '@skunkworks/ui'
 
@@ -226,6 +228,23 @@ import { AppInput } from '@skunkworksai/ui-kit'
 <AppDashboard header={{ searchbar: null }}>
 ```
 
+## Consumer Tailwind setup
+
+`AppHeader` uses `md:hidden` to hide the mobile search icon (`AppHeaderSearchbar`) at desktop widths. If the consumer's `@tailwindcss/vite` plugin injects its utilities layer **after** the ui-kit bundle, it overwrites same-named utilities and `md:hidden` stops working.
+
+**Required** — add this to the consumer's `app.css` (or equivalent global CSS entry):
+
+```css
+@layer theme, base, components, utilities;
+@import "tailwindcss/utilities" layer(utilities);
+```
+
+This explicitly names the `utilities` layer so both the ui-kit bundle and the consumer's Tailwind output merge into the same layer in document order.
+
+**Symptom of missing setup:** the mobile search icon is visible at all breakpoints instead of hiding at `md`.
+
+See `rules/tokens.md` for the full consumer setup checklist.
+
 ## Rules
 
 - **Do** provide `networks` with real data — the default 2-entry list is a demo placeholder only.

package/rules/input.md

@@ -12,10 +12,13 @@ import { AppInput } from "@/components/primitives/AppInput"
 |------|------|---------|-------------|
 | `leftAdornment` | `ReactNode` | — | Icon or element rendered inside the left edge of the input |
 | `rightAdornment` | `ReactNode` | — | Icon or element rendered inside the right edge of the input |
+| `wrapperClassName` | `string` | — | Applied to the outer wrapper `<div>` when adornments are present. Use to override the default `w-full`. Silently ignored when no adornments are set. |
 | `type` | `string` | `"text"` | HTML input type (text, email, password, number, etc.) |
 | `placeholder` | `string` | — | Placeholder text |
 | `disabled` | `boolean` | `false` | Disables the input |
-| `className` | `string` | — | Additional Tailwind classes applied to the input element |
+| `className` | `string` | — | Additional Tailwind classes applied to the inner `<input>` element |
+
+> `className` always routes to the inner `<input>`. Use `wrapperClassName` to control the outer wrapper size/layout when adornments are in use.
 
 > Accepts all standard HTML `<input>` attributes in addition to the props above.
 
@@ -43,6 +46,33 @@ import { AppInput } from "@/components/primitives/AppInput"
 />
 ```
 
+### Controlling wrapper width with adornments
+
+Without adornments `className` width classes land directly on `<input>`. With adornments you must use `wrapperClassName` — `className` targets the inner element and a width there does not constrain the wrapper.
+
+```tsx
+{/* Fixed width on desktop, full-width on mobile */}
+<AppInput
+  leftAdornment={<Search className="size-4" />}
+  placeholder="Search..."
+  wrapperClassName="w-full md:w-64"
+/>
+
+{/* Fill remaining space in a flex row */}
+<AppInput
+  leftAdornment={<Search className="size-4" />}
+  placeholder="Search..."
+  wrapperClassName="flex-1"
+/>
+
+{/* Intrinsic width */}
+<AppInput
+  leftAdornment={<Search className="size-4" />}
+  placeholder="Search..."
+  wrapperClassName="w-auto"
+/>
+```
+
 ### Disabled
 ```tsx
 <AppInput disabled placeholder="Not editable" />
@@ -59,8 +89,10 @@ import { AppInput } from "@/components/primitives/AppInput"
 ## Rules
 - ✅ Always use `AppInput` — never use a raw `<input>` element
 - ✅ Use `leftAdornment` / `rightAdornment` for icons inside the input — do not wrap `AppInput` in a relative `<div>` to position them manually
+- ✅ Use `wrapperClassName` to control width/layout when adornments are present — `className` targets the inner `<input>` only
 - ✅ Pair with `AppLabel` using matching `id` and `htmlFor` — never use a raw `<label>`
 - ✅ Pair with `AppField` or `AppForm` for full form field layout with error states
 - ❌ Do not add `pl-*` or `pr-*` padding when using adornments — padding is adjusted automatically
-- ❌ Do not set `width` directly on `AppInput` — control width from the parent container
+- ❌ Do not add width classes via `className` when adornments are present — they land on `<input>`, not the wrapper; use `wrapperClassName` instead
+- ❌ `wrapperClassName` has no effect without adornments — without `leftAdornment` or `rightAdornment` there is no wrapper element
 - ❌ If a prop you need is missing, stop and inform the design team

package/rules/pagetitle.md

@@ -143,12 +143,44 @@ When `breadcrumbs` is omitted, the component reads `window.location.pathname` on
 </AppDashboard>
 ```
 
+## usePageTitle — ReactNode prop stability
+
+`usePageTitle` compares props by identity, not by value. Primitive props (`title`, `subtitle`, `titleColor`) are compared by value and are safe to pass inline. ReactNode props (`actions`, `breadcrumbs`, `icon`) are compared by **reference** — passing them as inline JSX causes the effect to re-run on every render.
+
+**Always memoize ReactNode props:**
+
+```tsx
+// ✅ Correct — stable reference
+const actions = React.useMemo(
+  () => <AppButton onClick={handleAdd}>+ Add Site</AppButton>,
+  [handleAdd]
+)
+usePageTitle({ title: "Sites", actions })
+
+// ✅ Also correct — module-scope constant (never changes)
+const BREADCRUMBS = [
+  { label: "Dashboard", href: "/" },
+  { label: "Sites" },
+]
+usePageTitle({ title: "Sites", breadcrumbs: BREADCRUMBS })
+
+// ❌ Wrong — new object/JSX every render, causes effect churn
+usePageTitle({
+  title: "Sites",
+  actions: <AppButton>+ Add Site</AppButton>,
+  breadcrumbs: [{ label: "Dashboard", href: "/" }, { label: "Sites" }],
+})
+```
+
+> **Note:** Earlier versions used `JSON.stringify` to compare deps, which crashed when ReactNode props contained circular references (e.g. React elements with `$$typeof`). The current implementation compares individual fields by identity — memoization is now required to avoid redundant effect re-runs rather than crashes.
+
 ## Rules
 
 - **Do** use `pageTitle` on `AppDashboard` rather than placing `AppPageTitle` manually inside the page content.
 - **Do** pass `pageTitle={false}` to explicitly suppress the block — do not conditionally omit it based on state.
 - **Do** put action buttons in the `actions` slot — do not place them above the title.
 - **Do** size and style the `icon` yourself — pass `className="size-16 rounded-xl"` on the `<img>` or wrapper. The component does not enforce icon dimensions.
+- **Do** memoize `actions`, `breadcrumbs`, and `icon` when passing to `usePageTitle` — these are compared by identity and inline JSX re-runs the effect every render.
 - **Don't** hardcode breadcrumbs when auto-generation is correct — only override when the URL structure doesn't match the desired labels.
 - **Don't** add additional margin-top to page content — `AppPageTitle` already provides `mb-6` spacing.
 - **Don't** use raw color values for `titleColor` overrides — use the `titleColor` prop, not a `className` on the heading.

package/rules/table-manager.md

@@ -286,6 +286,44 @@ When `headerCell` is provided it fully replaces the header content (text + sort
 </TableManagerToolbarActions>
 ```
 
+## Props — TableManagerToolbar
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `layout` | `"wrap" \| "inline"` | `"wrap"` | Layout mode. See below. |
+| `className` | `string` | — | Extra classes on the toolbar wrapper. |
+
+### `layout` values
+
+| Value | Behaviour |
+|-------|-----------|
+| `"wrap"` | `flex-wrap` — children reflow to multiple rows on narrow viewports. Back-compatible default. |
+| `"inline"` | Mobile: search stacks above actions (`flex-col`). Desktop (md+): search + actions share one row with `justify-between`. Pair with `TableManagerSearch wrapperClassName="w-full md:w-64"` so the search does not stretch full-width on desktop. |
+
+### Responsive inline toolbar recipe
+
+```tsx
+<TableManagerToolbar layout="inline">
+  <TableManagerSearch wrapperClassName="w-full md:w-64" />
+  <TableManagerToolbarActions>
+    <TableManagerMultiFilter ... />
+    <TableManagerPagination />
+    <TableManagerColumnToggle />
+  </TableManagerToolbarActions>
+</TableManagerToolbar>
+```
+
+## Props — TableManagerSearch
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `placeholder` | `string` | `"Search..."` | Input placeholder. |
+| `debounceMs` | `number` | `300` | Debounce delay before `onSearchChange` fires. |
+| `wrapperClassName` | `string` | — | Forwarded to `AppInput.wrapperClassName`. Controls the outer wrapper width. Default `w-64`. |
+| `className` | `string` | — | Applied to the inner `<input>` element. |
+
+`wrapperClassName` overrides merge with the `w-64` default (later class wins via Tailwind Merge). Pass `wrapperClassName="w-full md:w-64"` for a mobile-first responsive width.
+
 ## Rules
 
 - ✅ Always wrap everything in `<TableManager>` before using any sub-component
@@ -295,12 +333,17 @@ When `headerCell` is provided it fully replaces the header content (text + sort
 - ✅ Implement OR logic in `onFilterChange` when a row can belong to multiple filter values
 - ✅ Set `type: "date"` on date columns and `type: "text"` on primary text columns so the default sort works correctly
 - ✅ Use `TableManagerToolbarActions` with `shrink-0` behavior built in — it will not compress when the search input grows
+- ✅ Use `layout="inline"` on `TableManagerToolbar` when search + actions + pagination must coexist on one row at md+
+- ✅ Pair `layout="inline"` with `wrapperClassName="w-full md:w-64"` on `TableManagerSearch` — otherwise search stretches full-width on desktop
 - ❌ Never import sub-components outside of a `<TableManager>` tree — they read from internal context and will throw
 - ❌ Never filter data internally in the block — always pass already-filtered data via the `data` prop
 - ❌ Never add `date-fns` or a date library just for this block — it uses native `Date` methods
 - ❌ Never use arbitrary CSS selectors (`:last-child`, `[&_th:last-child]`) to align column headers — use `headerAlign` / `headerCell` instead
+- ❌ Do not pass a width class via `TableManagerSearch className` to control the wrapper width — `className` targets the inner `<input>`; use `wrapperClassName` instead
 - ❌ If a prop you need is missing, stop and inform the design team
 
 ## Responsive
 
-`TableManagerToolbar` wraps with `flex-wrap` on small screens. `TableManagerToolbarActions` loses its `ml-auto` below `sm` and flows inline with other toolbar children. Wrapping is automatic — no consumer change needed.
+`TableManagerToolbar layout="wrap"` (default) wraps with `flex-wrap` on small screens. `TableManagerToolbarActions` loses its `ml-auto` below `sm` and flows inline with other toolbar children. Wrapping is automatic — no consumer change needed.
+
+`layout="inline"` gives explicit two-tier stacking: search on top on mobile, side-by-side on md+. Use this when `layout="wrap"` produces too many rows on narrow viewports.

package/rules/textarea.md

@@ -12,10 +12,21 @@ import { AppTextarea } from "@/components/primitives/AppTextarea"
 |------|------|---------|-------------|
 | `placeholder` | `string` | — | Placeholder text |
 | `disabled` | `boolean` | `false` | Disables the textarea |
-| `className` | `string` | — | Additional Tailwind classes |
+| `className` | `string` | — | Additional Tailwind classes. Merged after the built-in bg classes so your overrides always win. |
 
 > Accepts all standard HTML `<textarea>` attributes in addition to the props above.
 
+## Dark mode background
+
+`AppTextarea` applies `bg-transparent dark:bg-input/30` internally so the textarea surface is visible in dark mode, matching `AppInput`'s appearance. You do not need to add background classes for dark mode.
+
+`className` is merged last — pass a `bg-*` class to override the default for special cases.
+
+```tsx
+{/* Override background for a specific context */}
+<AppTextarea className="bg-card dark:bg-card" placeholder="Custom bg..." />
+```
+
 ## Usage
 
 ### Basic
@@ -31,8 +42,19 @@ import { AppTextarea } from "@/components/primitives/AppTextarea"
 </div>
 ```
 
+### Controlled height
+```tsx
+{/* Fixed height via rows */}
+<AppTextarea rows={6} placeholder="Detailed description..." />
+
+{/* Tailwind height class */}
+<AppTextarea className="h-40" placeholder="Notes..." />
+```
+
 ## Rules
 - ✅ Always use `AppTextarea` — never use a raw `<textarea>` element
 - ✅ Use `AppLabel` for accessibility
 - ✅ Control height via `rows` attribute or Tailwind `h-*` classes
+- ✅ Dark mode background is handled automatically — no `dark:bg-*` needed unless overriding
+- ❌ Do not add `dark:bg-transparent` to fix a dark-mode visibility issue — `AppTextarea` already applies `dark:bg-input/30` for parity with `AppInput`
 - ❌ If a prop you need is missing, stop and inform the design team

package/rules/wizard-stepper.md

@@ -0,0 +1,207 @@
+# AppWizardStepper
+
+> Docs: https://ui-kit.vercel.app/docs/blocks/wizard-stepper
+
+**This is a block — import from `blocks/AppWizardStepper`, not `primitives/`.**
+
+```tsx
+import {
+  AppWizardStepper,
+  type AppWizardStep,
+  type AppWizardStepperProps,
+} from "@skunkworks-ai/ui-kit"
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `steps` | `AppWizardStep[]` | required | Ordered list of steps. Each step needs a stable `id` and a `label`. |
+| `activeIndex` | `number` | required | 0-based index of the currently active step. Steps before this index are rendered as completed. |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Layout direction. |
+| `onStepClick` | `(step: AppWizardStep, index: number) => void` | — | Fires when a completed or active step is clicked. Upcoming steps are never interactive. |
+| `hideLabels` | `boolean \| undefined` | `undefined` | Controls label visibility. See tristate values below. |
+| `className` | `string` | — | Extra classes on the root `<ol>`. |
+
+### `AppWizardStep` type
+
+```ts
+type AppWizardStep = {
+  id: string          // Stable identifier used as React key and in onStepClick
+  label: string       // Displayed step name
+  description?: string // Optional sub-label shown under the main label
+}
+```
+
+### `hideLabels` tristate
+
+| Value | Behaviour |
+|-------|-----------|
+| `undefined` (default) | Labels hidden below `md`, visible on `md+` (CSS-only; screen-reader visible at all sizes) |
+| `true` | Always hidden — `sr-only` at all breakpoints |
+| `false` | Always visible — no responsive hiding |
+
+## Step states
+
+| State | Condition | Visual |
+|-------|-----------|--------|
+| `completed` | `index < activeIndex` | Filled circle with check icon (`--primary` bg) |
+| `active` | `index === activeIndex` | Outlined circle with primary ring (`--primary` border + ring) |
+| `upcoming` | `index > activeIndex` | Muted circle with number (`--muted` bg, `--border` border) |
+
+## Usage
+
+### Horizontal (default)
+
+```tsx
+const STEPS: AppWizardStep[] = [
+  { id: "details", label: "Details" },
+  { id: "review", label: "Review" },
+  { id: "confirm", label: "Confirm" },
+]
+
+function WizardPage() {
+  const [activeIndex, setActiveIndex] = React.useState(0)
+
+  const handleStepClick = React.useCallback(
+    (_step: AppWizardStep, index: number) => setActiveIndex(index),
+    []
+  )
+
+  return (
+    <AppWizardStepper
+      steps={STEPS}
+      activeIndex={activeIndex}
+      onStepClick={handleStepClick}
+    />
+  )
+}
+```
+
+### Vertical
+
+```tsx
+<AppWizardStepper
+  steps={STEPS}
+  activeIndex={1}
+  orientation="vertical"
+  onStepClick={handleStepClick}
+/>
+```
+
+### With descriptions
+
+```tsx
+const STEPS: AppWizardStep[] = [
+  { id: "account", label: "Account", description: "Basic info" },
+  { id: "profile", label: "Profile", description: "Personal details" },
+  { id: "done", label: "Done", description: "Review & submit" },
+]
+```
+
+### Always show labels
+
+```tsx
+<AppWizardStepper steps={STEPS} activeIndex={1} hideLabels={false} />
+```
+
+### Icon-only (always hidden labels)
+
+```tsx
+<AppWizardStepper steps={STEPS} activeIndex={1} hideLabels={true} />
+```
+
+### Controlled active index (full wizard flow)
+
+```tsx
+function MultiStepForm() {
+  const [activeIndex, setActiveIndex] = React.useState(0)
+
+  const handleNext = () => setActiveIndex((i) => Math.min(i + 1, STEPS.length - 1))
+  const handleBack = () => setActiveIndex((i) => Math.max(i - 1, 0))
+
+  // Gate forward nav yourself — onStepClick only fires for completed/active steps
+  const handleStepClick = React.useCallback(
+    (_step: AppWizardStep, index: number) => setActiveIndex(index),
+    []
+  )
+
+  return (
+    <div className="space-y-6">
+      <AppWizardStepper
+        steps={STEPS}
+        activeIndex={activeIndex}
+        onStepClick={handleStepClick}
+      />
+      <StepContent index={activeIndex} />
+      <div className="flex gap-2">
+        <AppButton variant="outline" onClick={handleBack} disabled={activeIndex === 0}>
+          Back
+        </AppButton>
+        <AppButton onClick={handleNext} disabled={activeIndex === STEPS.length - 1}>
+          Next
+        </AppButton>
+      </div>
+    </div>
+  )
+}
+```
+
+## Clickability gate
+
+`onStepClick` only fires for steps in `completed` or `active` state. Upcoming steps are rendered as static `<div>` elements — not `<button>` elements — so they cannot be focused or activated. This is intentional: forward navigation must be gated by the parent component.
+
+Do not try to navigate forward by clicking an upcoming step indicator — the component will not call `onStepClick` for it.
+
+## Accessibility
+
+- Root element is `<ol role="list" aria-label="Progress">`
+- Each step is `<li role="listitem">`
+- Active step carries `aria-current="step"`
+- Clickable steps are native `<button type="button">` with `aria-label="Go to step N: Label"`
+- Indicator circles are `aria-hidden="true"` — label text provides the accessible name
+- Labels are `sr-only` on mobile by default, ensuring screen readers always have access to step names regardless of the `hideLabels` setting
+
+## Performance
+
+Memoize `steps` and `onStepClick` to avoid unnecessary re-renders. `steps` is typically a module-level constant; `onStepClick` should be wrapped in `useCallback`.
+
+```tsx
+// ✅ Correct
+const STEPS = [{ id: "a", label: "A" }, { id: "b", label: "B" }] // module scope
+
+const handleStepClick = React.useCallback(
+  (_step: AppWizardStep, i: number) => setActive(i),
+  []
+)
+
+// ❌ Wrong — new array + new function every render
+<AppWizardStepper
+  steps={[{ id: "a", label: "A" }]}
+  onStepClick={(_s, i) => setActive(i)}
+  ...
+/>
+```
+
+## Token usage
+
+| Visual element | Token |
+|----------------|-------|
+| Completed circle fill | `--primary` / `--primary-foreground` |
+| Active circle border + ring | `--primary` / `ring-primary/30` |
+| Upcoming circle fill | `--muted` / `--muted-foreground` |
+| Upcoming circle border | `--border` |
+| Connector line (default) | `--border` |
+| Connector line (completed segment) | `--primary` |
+
+## Rules
+
+- ✅ Define `steps` at module scope or memoize — avoid recreating the array on every render
+- ✅ Wrap `onStepClick` in `useCallback`
+- ✅ Gate forward navigation yourself — `onStepClick` only fires for completed/active steps
+- ✅ Use `hideLabels={false}` when you always want labels visible regardless of breakpoint
+- ✅ Use `orientation="vertical"` for tall, sidebar-style step flows
+- ❌ Do not attempt to make upcoming steps clickable — the block intentionally blocks this; gate forward nav in the parent
+- ❌ Do not manage the completed/upcoming state externally — derive it from `activeIndex`; steps before it are automatically completed
+- ❌ Do not add custom color classes to the indicator circle — all step colors come from design tokens
+- ❌ If a prop you need is missing, stop and inform the design team