@skunkworksai/ui-kit 0.1.18

package/rules/accordion.md

@@ -0,0 +1,60 @@
+# AppAccordion
+
+> Docs: https://ui-kit.vercel.app/docs/components/accordion
+
+```tsx
+import { AppAccordion, AppAccordionItem, AppAccordionTrigger, AppAccordionContent } from "@/components/primitives/AppAccordion"
+```
+
+## AppAccordion
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `"single" \| "multiple"` | — | Determines whether a single or multiple items can be opened at once |
+| `collapsible` | `boolean` | `false` | When `type` is "single", allows closing the open item by clicking the trigger |
+| `defaultValue` | `string \| string[]` | — | The value of the item(s) to expand by default |
+| `value` | `string \| string[]` | — | Controlled value of the expanded item(s) |
+| `onValueChange` | `(value: string \| string[]) => void` | — | Event handler called when the expanded state changes |
+
+## AppAccordionItem
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string` | — | A unique value for the item |
+| `disabled` | `boolean` | `false` | When `true`, prevents the user from interacting with the item |
+
+## Usage
+
+### Basic
+```tsx
+<AppAccordion type="single" collapsible>
+  <AppAccordionItem value="item-1">
+    <AppAccordionTrigger>Is it accessible?</AppAccordionTrigger>
+    <AppAccordionContent>
+      Yes. It adheres to the WAI-ARIA design pattern.
+    </AppAccordionContent>
+  </AppAccordionItem>
+</AppAccordion>
+```
+
+### Multiple
+```tsx
+<AppAccordion type="multiple">
+  <AppAccordionItem value="item-1">
+    <AppAccordionTrigger>First Item</AppAccordionTrigger>
+    <AppAccordionContent>Content for first item.</AppAccordionContent>
+  </AppAccordionItem>
+  <AppAccordionItem value="item-2">
+    <AppAccordionTrigger>Second Item</AppAccordionTrigger>
+    <AppAccordionContent>Content for second item.</AppAccordionContent>
+  </AppAccordionItem>
+</AppAccordion>
+```
+
+## Rules
+- ✅ Always use `AppAccordion` components together as a set
+- ✅ Provide a unique `value` to each `AppAccordionItem`
+- ✅ Use `collapsible` with `type="single"` if you want users to be able to close all items
+- ❌ Do not place interactive elements (buttons, links) inside `AppAccordionTrigger`
+- ❌ Do not override the chevron rotation or transition manually — it is handled by the primitive
+- ❌ If a prop you need is missing, stop and inform the design team

package/rules/alert-dialog.md

@@ -0,0 +1,62 @@
+# AppAlertDialog
+
+> Docs: https://ui-kit.vercel.app/docs/components/alert-dialog
+
+```tsx
+import {
+  AppAlertDialog,
+  AppAlertDialogTrigger,
+  AppAlertDialogContent,
+  AppAlertDialogHeader,
+  AppAlertDialogFooter,
+  AppAlertDialogTitle,
+  AppAlertDialogDescription,
+  AppAlertDialogAction,
+  AppAlertDialogCancel,
+} from "@/components/primitives/AppAlertDialog"
+```
+
+## AppAlertDialogAction / AppAlertDialogCancel
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `"default" \| "destructive" \| "secondary" \| "outline"` | `"default"` | Visual style of the action/cancel button |
+
+## Usage
+
+### Basic
+```tsx
+<AppAlertDialog>
+  <AppAlertDialogTrigger asChild>
+    <AppButton variant="outline">Show Dialog</AppButton>
+  </AppAlertDialogTrigger>
+  <AppAlertDialogContent>
+    <AppAlertDialogHeader>
+      <AppAlertDialogTitle>Are you absolutely sure?</AppAlertDialogTitle>
+      <AppAlertDialogDescription>
+        This action cannot be undone.
+      </AppAlertDialogDescription>
+    </AppAlertDialogHeader>
+    <AppAlertDialogFooter>
+      <AppAlertDialogCancel>Cancel</AppAlertDialogCancel>
+      <AppAlertDialogAction>Continue</AppAlertDialogAction>
+    </AppAlertDialogFooter>
+  </AppAlertDialogContent>
+</AppAlertDialog>
+```
+
+### Destructive Action
+```tsx
+<AppAlertDialogFooter>
+  <AppAlertDialogCancel variant="outline">Cancel</AppAlertDialogCancel>
+  <AppAlertDialogAction variant="destructive">Delete Item</AppAlertDialogAction>
+</AppAlertDialogFooter>
+```
+
+## Rules
+- ✅ Use `AppAlertDialog` for actions that require explicit confirmation and interrupt the workflow
+- ✅ Always provide both an action and a cancel button in the `AppAlertDialogFooter`
+- ✅ Use `variant="destructive"` for actions that permanently delete or change data
+- ❌ Do not use `AppAlertDialog` for simple information or non-critical choices — use `AppDialog` instead
+- ❌ Do not place complex forms inside `AppAlertDialog` — use `AppDialog` for form-based interactions
+- ❌ If a prop you need is missing, stop and inform the design team

package/rules/alert.md

@@ -0,0 +1,61 @@
+# AppAlert
+
+> Docs: https://ui-kit.vercel.app/docs/components/alert
+
+```tsx
+import { AppAlert, AppAlertTitle, AppAlertDescription, AppAlertContent } from "@/components/primitives/AppAlert"
+```
+
+## AppAlert
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `"default" \| "destructive" \| "success" \| "warning" \| "info"` | `"default"` | Visual style of the alert |
+
+## Usage
+
+### Basic
+```tsx
+<AppAlert>
+  <TerminalIcon className="size-4" />
+  <AppAlertContent>
+    <AppAlertTitle>Heads up!</AppAlertTitle>
+    <AppAlertDescription>
+      You can add components to your app using the cli.
+    </AppAlertDescription>
+  </AppAlertContent>
+</AppAlert>
+```
+
+### Semantic Variants
+```tsx
+<AppAlert variant="success">
+  <CheckCircleIcon className="size-4" />
+  <AppAlertTitle>Success</AppAlertTitle>
+</AppAlert>
+
+<AppAlert variant="destructive">
+  <AlertCircleIcon className="size-4" />
+  <AppAlertTitle>Error</AppAlertTitle>
+</AppAlert>
+```
+
+### With Action
+```tsx
+<AppAlert>
+  <InfoIcon className="size-4" />
+  <AppAlertContent>
+    <AppAlertTitle>Update Available</AppAlertTitle>
+    <AppAlertDescription>A new version is ready to install.</AppAlertDescription>
+  </AppAlertContent>
+  <AppButton size="sm" variant="outline" className="ml-auto">Update</AppButton>
+</AppAlert>
+```
+
+## Rules
+- ✅ Always use `AppAlertContent` to wrap title and description for proper alignment
+- ✅ Use the semantic variants (`success`, `warning`, `info`, `destructive`) for status-driven messaging
+- ✅ Icons should be placed as direct children of `AppAlert`, outside `AppAlertContent`
+- ❌ Do not use `AppAlert` for transient messages — use `AppToaster` or `toast` instead
+- ❌ Do not manually style colors when a semantic variant exists
+- ❌ If a prop you need is missing, stop and inform the design team

package/rules/aspect-ratio.md

@@ -0,0 +1,47 @@
+# AppAspectRatio
+
+> Docs: https://ui-kit.vercel.app/docs/components/aspect-ratio
+
+```tsx
+import { AppAspectRatio } from "@/components/primitives/AppAspectRatio"
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `ratio` | `number` | `1` | The desired aspect ratio (e.g., 16/9, 4/3, 1) |
+
+## Usage
+
+### Basic (16:9)
+```tsx
+<div className="w-[450px]">
+  <AppAspectRatio ratio={16 / 9}>
+    <img
+      src="..."
+      alt="Image"
+      className="rounded-md object-cover"
+    />
+  </AppAspectRatio>
+</div>
+```
+
+### Square (1:1)
+```tsx
+<div className="w-[200px]">
+  <AppAspectRatio ratio={1}>
+    <img
+      src="..."
+      alt="Profile"
+      className="rounded-full object-cover"
+    />
+  </AppAspectRatio>
+</div>
+```
+
+## Rules
+- ✅ Always wrap `AppAspectRatio` in a container with a defined width
+- ✅ Use `object-cover` on images inside `AppAspectRatio` to ensure they fill the container without distortion
+- ❌ Do not set a height on the `AppAspectRatio` container — height is determined by the ratio and width
+- ❌ If a prop you need is missing, stop and inform the design team

package/rules/avatar.md

@@ -0,0 +1,52 @@
+# AppAvatar
+
+> Docs: https://ui-kit.vercel.app/docs/components/avatar
+
+```tsx
+import { AppAvatar, AppAvatarImage, AppAvatarFallback } from "@/components/primitives/AppAvatar"
+```
+
+## AppAvatar
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | — | Additional Tailwind classes for size and styling |
+
+## Usage
+
+### Basic
+```tsx
+<AppAvatar>
+  <AppAvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
+  <AppAvatarFallback>CN</AppAvatarFallback>
+</AppAvatar>
+```
+
+### Custom Sizes
+```tsx
+<AppAvatar className="h-12 w-12">
+  <AppAvatarImage src="..." />
+  <AppAvatarFallback>JD</AppAvatarFallback>
+</AppAvatar>
+```
+
+### Avatar Group
+```tsx
+<div className="flex -space-x-2">
+  <AppAvatar className="border-2 border-background">
+    <AppAvatarImage src="..." />
+    <AppAvatarFallback>U1</AppAvatarFallback>
+  </AppAvatar>
+  <AppAvatar className="border-2 border-background">
+    <AppAvatarImage src="..." />
+    <AppAvatarFallback>U2</AppAvatarFallback>
+  </AppAvatar>
+</div>
+```
+
+## Rules
+- ✅ Always provide `AppAvatarFallback` for cases where the image fails to load or is not provided
+- ✅ Use `alt` text on `AppAvatarImage` for accessibility
+- ✅ Use `border-background` on avatars when used in a group to create visual separation
+- ❌ Do not use raw `<img>` tags for user avatars — use `AppAvatar` to handle loading and fallback states automatically
+- ❌ If a prop you need is missing, stop and inform the design team

package/rules/badge.md

@@ -0,0 +1,55 @@
+# AppBadge
+
+> Docs: https://ui-kit.vercel.app/docs/components/badge
+
+```tsx
+import { AppBadge } from "@/components/primitives/AppBadge"
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `"default" \| "secondary" \| "destructive" \| "warning" \| "outline" \| "ghost" \| "link"` | `"default"` | Visual style of the badge |
+| `asChild` | `boolean` | `false` | Renders as child element via Radix Slot |
+
+## Usage
+
+### Basic
+```tsx
+<AppBadge>Active</AppBadge>
+<AppBadge variant="secondary">Draft</AppBadge>
+<AppBadge variant="outline">Pending</AppBadge>
+<AppBadge variant="destructive">Error</AppBadge>
+<AppBadge variant="warning">Warning</AppBadge>
+```
+
+### With Icons
+```tsx
+<AppBadge>
+  <CheckIcon className="size-3" />
+  Verified
+</AppBadge>
+
+<AppBadge variant="secondary" className="gap-1 pr-1">
+  React
+  <AppButton size="icon" variant="ghost" className="size-3.5 p-0">
+    <XIcon className="size-2.5" />
+  </AppButton>
+</AppBadge>
+```
+
+### As a Link
+```tsx
+<AppBadge asChild>
+  <a href="/tags/react">React</a>
+</AppBadge>
+```
+
+## Rules
+- ✅ Use `AppBadge` for status indicators, tags, or small labels
+- ✅ Use `asChild` when the badge should behave as a link
+- ✅ Use `gap-1` when adding icons or small buttons inside the badge
+- ❌ Do not use `AppBadge` for main navigation actions — use `AppButton` instead
+- ❌ Do not use long text strings inside a badge — keep it to 1-2 words
+- ❌ If a prop you need is missing, stop and inform the design team

package/rules/bento-menu.md

@@ -0,0 +1,86 @@
+# AppBentoMenu
+
+App-switcher popover displaying a grid of app tiles. Trigger defaults to a ghost icon button; pass `children` to use a custom trigger.
+
+## Exports
+
+```ts
+import {
+  AppBentoMenu,
+  AppBentoMenuItem,
+  DEFAULT_BENTO_APPS,
+  type BentoApp,
+  type AppBentoMenuProps,
+  type AppBentoMenuItemProps,
+} from '@skunkworksai/ui-kit'
+```
+
+## Props
+
+### `AppBentoMenu`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `apps` | `BentoApp[]` | `DEFAULT_BENTO_APPS` | Apps to display in the grid |
+| `cols` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `2` | Number of grid columns |
+| `children` | `ReactNode` | ghost icon button | Custom popover trigger |
+| `className` | `string` | — | Extra classes on the popover content |
+
+### `BentoApp`
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | ✓ | Unique key |
+| `label` | `string` | ✓ | Display label below icon |
+| `icon` | `string \| ComponentType<SVGProps<SVGSVGElement>>` | ✓ | PNG/SVG URL or SVG React component |
+| `active` | `boolean` | — | Highlights tile with `ring-2 ring-primary` |
+| `href` | `string` | — | Wraps tile in an `<a>` tag |
+
+### `AppBentoMenuItem`
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `app` | `BentoApp` | ✓ | App data |
+| `className` | `string` | — | Extra classes on the tile button |
+
+## Usage
+
+### Default (built-in apps)
+
+```tsx
+<AppBentoMenu />
+```
+
+### Custom app list
+
+```tsx
+const MY_APPS: BentoApp[] = [
+  { id: "app-a", label: "App A", icon: appAIcon, active: true, href: "/app-a" },
+  { id: "app-b", label: "App B", icon: appBImg },
+]
+
+<AppBentoMenu apps={MY_APPS} cols={3} />
+```
+
+### Custom trigger
+
+```tsx
+<AppBentoMenu apps={MY_APPS}>
+  <AppButton variant="outline" size="sm">Apps</AppButton>
+</AppBentoMenu>
+```
+
+### Standalone tile (advanced)
+
+```tsx
+<AppBentoMenuItem app={{ id: "x", label: "X", icon: XIcon }} />
+```
+
+## Rules
+
+- Use `DEFAULT_BENTO_APPS` as base and spread in overrides — don't hardcode the full list in app code unless you need full control.
+- Set `active: true` on the app that matches the current route.
+- Supply `href` on each app for navigation; omit only if clicks are handled via an `onClick` on the parent.
+- `cols` accepts 1–6; values outside this range fall back to 2-column grid.
+- Never hardcode icon pixel sizes — the tile container is fixed at `size-12` (48×48px); icons fill it automatically.
+- If a prop you need is missing, stop and inform the design team.

package/rules/breadcrumb.md

@@ -0,0 +1,80 @@
+# AppBreadcrumb
+
+> Docs: https://ui-kit.vercel.app/docs/components/breadcrumb
+
+```tsx
+import {
+  AppBreadcrumb,
+  AppBreadcrumbList,
+  AppBreadcrumbItem,
+  AppBreadcrumbLink,
+  AppBreadcrumbPage,
+  AppBreadcrumbSeparator,
+  AppBreadcrumbEllipsis,
+} from "@/components/primitives/AppBreadcrumb"
+```
+
+## AppBreadcrumbLink
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `asChild` | `boolean` | `false` | Renders as child element (e.g., for Next.js Link) |
+| `href` | `string` | — | Link destination |
+
+## Usage
+
+### Basic
+```tsx
+<AppBreadcrumb>
+  <AppBreadcrumbList>
+    <AppBreadcrumbItem>
+      <AppBreadcrumbLink href="/">Home</AppBreadcrumbLink>
+    </AppBreadcrumbItem>
+    <AppBreadcrumbSeparator />
+    <AppBreadcrumbItem>
+      <AppBreadcrumbLink href="/components">Components</AppBreadcrumbLink>
+    </AppBreadcrumbItem>
+    <AppBreadcrumbSeparator />
+    <AppBreadcrumbItem>
+      <AppBreadcrumbPage>Breadcrumb</AppBreadcrumbPage>
+    </AppBreadcrumbItem>
+  </AppBreadcrumbList>
+</AppBreadcrumb>
+```
+
+### With Ellipsis
+```tsx
+<AppBreadcrumbList>
+  <AppBreadcrumbItem>
+    <AppBreadcrumbLink href="/">Home</AppBreadcrumbLink>
+  </AppBreadcrumbItem>
+  <AppBreadcrumbSeparator />
+  <AppBreadcrumbItem>
+    <AppBreadcrumbEllipsis />
+  </AppBreadcrumbItem>
+  <AppBreadcrumbSeparator />
+  <AppBreadcrumbItem>
+    <AppBreadcrumbPage>Current Page</AppBreadcrumbPage>
+  </AppBreadcrumbItem>
+</AppBreadcrumbList>
+```
+
+## Rules
+- ✅ Always end the breadcrumb trail with `AppBreadcrumbPage` for the current location
+- ✅ Use `AppBreadcrumbSeparator` between items
+- ✅ Use `asChild` with `AppBreadcrumbLink` when using framework routers (like Next.js `Link`)
+- ❌ Do not use breadcrumbs as the primary navigation system
+- ❌ Do not use more than one `AppBreadcrumbEllipsis` in a single trail
+- ❌ If a prop you need is missing, stop and inform the design team
+
+## Responsive
+
+`AppBreadcrumbItem` and `AppBreadcrumbSeparator` accept a `hideOnMobile` prop (`boolean`); pass it on middle segments to hide them below `sm` (640px). `AppPageTitle` applies this automatically when the trail has more than 2 segments.
+
+```tsx
+// Manual usage
+<AppBreadcrumbItem hideOnMobile>
+  <AppBreadcrumbLink href="/admin">Admin</AppBreadcrumbLink>
+</AppBreadcrumbItem>
+<AppBreadcrumbSeparator hideOnMobile />
+```

package/rules/button-group.md

@@ -0,0 +1,58 @@
+# AppButtonGroup
+
+> Docs: https://ui-kit.vercel.app/docs/components/button-group
+
+```tsx
+import { AppButtonGroup } from "@/components/primitives/AppButtonGroup"
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | — | Additional Tailwind classes |
+
+## Usage
+
+### Button Group
+```tsx
+<AppButtonGroup>
+  <AppButton variant="outline">Copy</AppButton>
+  <AppButton variant="outline">Paste</AppButton>
+  <AppButton variant="outline">Clear</AppButton>
+</AppButtonGroup>
+```
+
+### Split Button
+```tsx
+<AppButtonGroup>
+  <AppButton>Publish</AppButton>
+  <AppDropdownMenu>
+    <AppDropdownMenuTrigger asChild>
+      <AppButton size="icon">
+        <ChevronDownIcon className="size-4" />
+      </AppButton>
+    </AppDropdownMenuTrigger>
+    <AppDropdownMenuContent align="end">
+      <AppDropdownMenuItem>Schedule</AppDropdownMenuItem>
+      <AppDropdownMenuItem>Save draft</AppDropdownMenuItem>
+    </AppDropdownMenuContent>
+  </AppDropdownMenu>
+</AppButtonGroup>
+```
+
+### Input with Button
+```tsx
+<AppButtonGroup>
+  <AppInput placeholder="Search..." />
+  <AppButton variant="outline">Search</AppButton>
+</AppButtonGroup>
+```
+
+## Rules
+- ✅ Use `AppButtonGroup` to visually join related inputs and buttons
+- ✅ Ensure all buttons within a group use the same `size` and `variant` for visual consistency
+- ✅ Use `AppButtonGroup` for "Split Buttons" (primary action + dropdown)
+- ❌ Do not use `AppButtonGroup` for disparate actions that aren't related
+- ❌ Do not manually override border-radii of children — `AppButtonGroup` handles this automatically
+- ❌ If a prop you need is missing, stop and inform the design team

package/rules/button.md

@@ -0,0 +1,66 @@
+# AppButton
+
+> Docs: https://ui-kit.vercel.app/docs/components/button
+
+```tsx
+import { AppButton } from "@/components/primitives/AppButton"
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `"default" \| "outline" \| "secondary" \| "ghost" \| "destructive" \| "link"` | `"default"` | Visual style of the button |
+| `size` | `"default" \| "xs" \| "sm" \| "lg" \| "icon" \| "icon-xs" \| "icon-sm" \| "icon-lg"` | `"default"` | Size of the button |
+| `loading` | `boolean` | `false` | Shows a spinner and disables the button |
+| `iconLeft` | `ReactNode` | — | Icon rendered before the label |
+| `iconRight` | `ReactNode` | — | Icon rendered after the label |
+| `disabled` | `boolean` | `false` | Disables the button |
+| `asChild` | `boolean` | `false` | Renders as child element via Radix Slot |
+| `className` | `string` | — | Additional Tailwind classes |
+
+## Usage
+
+### Basic
+```tsx
+<AppButton>Save</AppButton>
+<AppButton variant="outline">Cancel</AppButton>
+<AppButton variant="destructive">Delete account</AppButton>
+<AppButton variant="ghost">Dismiss</AppButton>
+```
+
+### Sizes
+```tsx
+<AppButton size="sm">Small</AppButton>
+<AppButton size="lg">Large</AppButton>
+<AppButton size="icon"><TrashIcon /></AppButton>
+```
+
+### Loading state
+```tsx
+<AppButton loading>Saving...</AppButton>
+<AppButton loading variant="outline">Submitting</AppButton>
+```
+
+### With icons
+```tsx
+<AppButton iconLeft={<PlusIcon />}>Add item</AppButton>
+<AppButton iconRight={<ArrowRightIcon />}>Continue</AppButton>
+<AppButton iconLeft={<DownloadIcon />} variant="outline">Export</AppButton>
+```
+
+### As a link
+```tsx
+<AppButton asChild>
+  <a href="/dashboard">Go to dashboard</a>
+</AppButton>
+```
+
+## Rules
+- ✅ Always use `AppButton` — never use a raw `<button>` element
+- ✅ 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
+- ❌ 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