@skunkworksai/ui-kit 0.1.18

package/rules/dialog.md

@@ -0,0 +1,60 @@
+# AppDialog
+
+> Docs: https://ui-kit.vercel.app/docs/components/dialog
+
+```tsx
+import {
+  AppDialog,
+  AppDialogTrigger,
+  AppDialogContent,
+  AppDialogHeader,
+  AppDialogTitle,
+  AppDialogDescription,
+} from "@/components/primitives/AppDialog"
+```
+
+## AppDialog
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `open` | `boolean` | - | The controlled open state of the dialog. |
+| `onOpenChange` | `(open: boolean) => void` | - | Event handler called when the open state of the dialog changes. |
+
+## AppDialogTrigger
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `asChild` | `boolean` | `false` | Change the default rendered element for the one passed as a child. |
+
+## Usage
+
+### Default Dialog
+```tsx
+<AppDialog>
+  <AppDialogTrigger asChild>
+    <AppButton>Open Dialog</AppButton>
+  </AppDialogTrigger>
+  <AppDialogContent>
+    <AppDialogHeader>
+      <AppDialogTitle>Are you absolutely sure?</AppDialogTitle>
+      <AppDialogDescription>
+        This action cannot be undone. This will permanently delete your account
+        and remove your data from our servers.
+      </AppDialogDescription>
+    </AppDialogHeader>
+  </AppDialogContent>
+</AppDialog>
+```
+
+## Rules
+
+- **Do** always provide an `AppDialogTitle` for accessibility.
+- **Do** use `asChild` on the trigger to use an `AppButton`.
+- **Don't** use `AppDialog` for small tooltips; use `AppTooltip` or `AppPopover` instead.
+- If a prop you need is missing, stop and inform the design team.
+
+## Responsive
+
+On mobile (<768px) `AppDialog` renders as a bottom `Drawer` (Vaul); all sub-components (`AppDialogContent`, `AppDialogHeader`, `AppDialogTitle`, `AppDialogDescription`, `AppDialogTrigger`) switch automatically via internal context. The consumer API is identical at all sizes. Note: Radix-Dialog-specific props (e.g. `onEscapeKeyDown`) passed to `AppDialogContent` are not forwarded on mobile.
+
+> **Implementation note:** `AppDialogContent` must explicitly pass `{children}` on both the mobile (DrawerContent) and desktop (DialogContent) paths. Omitting children on the desktop path renders a blank panel.

package/rules/drawer.md

@@ -0,0 +1,65 @@
+# AppDrawer
+
+> Docs: https://ui-kit.vercel.app/docs/components/drawer
+
+```tsx
+import {
+  AppDrawer,
+  AppDrawerTrigger,
+  AppDrawerContent,
+  AppDrawerHeader,
+  AppDrawerFooter,
+  AppDrawerTitle,
+  AppDrawerDescription,
+  AppDrawerClose,
+} from "@/components/primitives/AppDrawer"
+```
+
+## AppDrawer
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `open` | `boolean` | - | The controlled open state of the drawer. |
+| `onOpenChange` | `(open: boolean) => void` | - | Event handler called when the open state of the drawer changes. |
+| `shouldScaleBackground` | `boolean` | `false` | Whether to scale the background when the drawer is open. |
+
+## AppDrawerTrigger
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `asChild` | `boolean` | `false` | Change the default rendered element for the one passed as a child. |
+
+## Usage
+
+### Default Drawer
+```tsx
+<AppDrawer>
+  <AppDrawerTrigger asChild>
+    <AppButton>Open Drawer</AppButton>
+  </AppDrawerTrigger>
+  <AppDrawerContent>
+    <AppDrawerHeader>
+      <AppDrawerTitle>Edit Profile</AppDrawerTitle>
+      <AppDrawerDescription>
+        Make changes to your profile here. Click save when you are done.
+      </AppDrawerDescription>
+    </AppDrawerHeader>
+    <div className="p-4">
+      {/* Drawer Content */}
+    </div>
+    <AppDrawerFooter>
+      <AppButton>Save Changes</AppButton>
+      <AppDrawerClose asChild>
+        <AppButton variant="outline">Cancel</AppButton>
+      </AppDrawerClose>
+    </AppDrawerFooter>
+  </AppDrawerContent>
+</AppDrawer>
+```
+
+## Rules
+
+- **Do** use `AppDrawer` for mobile-friendly overlays or supplemental content.
+- **Do** ensure `AppDrawerTitle` is provided for accessibility.
+- **Don't** use `AppDrawer` if the content is too small; use `AppDialog` or `AppPopover` instead.
+- If a prop you need is missing, stop and inform the design team.

package/rules/dropdown-menu.md

@@ -0,0 +1,72 @@
+# AppDropdownMenu
+
+> Docs: https://ui-kit.vercel.app/docs/components/dropdown-menu
+
+```tsx
+import {
+  AppDropdownMenu,
+  AppDropdownMenuTrigger,
+  AppDropdownMenuContent,
+  AppDropdownMenuItem,
+  AppDropdownMenuCheckboxItem,
+  AppDropdownMenuRadioItem,
+  AppDropdownMenuLabel,
+  AppDropdownMenuSeparator,
+  AppDropdownMenuShortcut,
+  AppDropdownMenuGroup,
+  AppDropdownMenuSub,
+  AppDropdownMenuSubContent,
+  AppDropdownMenuSubTrigger,
+  AppDropdownMenuRadioGroup,
+} from "@/components/primitives/AppDropdownMenu"
+```
+
+## AppDropdownMenuContent
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `side` | `"top" \| "right" \| "bottom" \| "left"` | `"bottom"` | The preferred side of the trigger to render against when open. |
+| `align` | `"start" \| "center" \| "end"` | `"center"` | The preferred alignment against the trigger. |
+
+## AppDropdownMenuItem
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `onSelect` | `(event: Event) => void` | - | Event handler called when the item is selected. |
+| `disabled` | `boolean` | - | Whether the item is disabled. |
+
+## Usage
+
+### Basic Dropdown Menu
+```tsx
+<AppDropdownMenu>
+  <AppDropdownMenuTrigger asChild>
+    <AppButton>Open Menu</AppButton>
+  </AppDropdownMenuTrigger>
+  <AppDropdownMenuContent className="w-56">
+    <AppDropdownMenuLabel>My Account</AppDropdownMenuLabel>
+    <AppDropdownMenuSeparator />
+    <AppDropdownMenuItem>
+      <UserIcon className="mr-2 h-4 w-4" />
+      <span>Profile</span>
+    </AppDropdownMenuItem>
+    <AppDropdownMenuItem>
+      <SettingsIcon className="mr-2 h-4 w-4" />
+      <span>Settings</span>
+    </AppDropdownMenuItem>
+    <AppDropdownMenuSeparator />
+    <AppDropdownMenuItem>Logout</AppDropdownMenuItem>
+  </AppDropdownMenuContent>
+</AppDropdownMenu>
+```
+
+## Rules
+
+- **Do** use `AppDropdownMenu` for a list of actions or functions.
+- **Do** use `AppDropdownMenuSeparator` to group related items.
+- **Don't** use `AppDropdownMenu` for navigation; use `AppNavigationMenu` if appropriate.
+- If a prop you need is missing, stop and inform the design team.
+
+## Responsive
+
+On mobile (<768px) `AppDropdownMenu` renders as a bottom `Drawer`; `AppDropdownMenuTrigger` becomes a `DrawerTrigger`, `AppDropdownMenuContent` becomes `DrawerContent` with items stacked as styled `<button>` elements, and `AppDropdownMenuShortcut` is hidden. Sub-menus (`AppDropdownMenuSub`) remain desktop-only — do not rely on them at mobile widths.

package/rules/empty.md

@@ -0,0 +1,110 @@
+# AppEmpty
+
+> Docs: https://ui-kit.vercel.app/docs/components/empty
+
+```tsx
+import {
+  AppEmpty,
+  AppEmptyHeader,
+  AppEmptyMedia,
+  AppEmptyTitle,
+  AppEmptyDescription,
+  AppEmptyContent,
+} from "@skunkworksai/ui-kit"
+```
+
+## AppEmpty
+
+Root container. Centered column with `gap-4` and `p-8`.
+
+Accepts all `<div>` HTML attributes.
+
+## AppEmptyHeader
+
+Centered column grouping media + title + description. Use as the first child of `AppEmpty`.
+
+Accepts all `<div>` HTML attributes.
+
+## AppEmptyMedia
+
+Container for an illustration, icon, or image.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `"default"` \| `"icon"` | `"default"` | `"icon"` renders a `size-12` rounded muted circle — use with a Lucide icon. `"default"` is a bare container for custom illustrations. |
+
+## AppEmptyTitle
+
+Primary heading. Renders `<h3>` with `text-base font-semibold`.
+
+Accepts all `<h3>` HTML attributes.
+
+## AppEmptyDescription
+
+Supporting text below the title. Renders `<p>` with `text-sm text-muted-foreground`.
+
+Accepts all `<p>` HTML attributes.
+
+## AppEmptyContent
+
+Action area below the header. Use for buttons or links.
+
+Accepts all `<div>` HTML attributes.
+
+## Usage
+
+### Zero-data state with icon
+```tsx
+import { InboxIcon } from "lucide-react"
+
+<AppEmpty>
+  <AppEmptyHeader>
+    <AppEmptyMedia variant="icon">
+      <InboxIcon className="size-6" aria-hidden />
+    </AppEmptyMedia>
+    <AppEmptyTitle>No items</AppEmptyTitle>
+    <AppEmptyDescription>Get started by creating a new item.</AppEmptyDescription>
+  </AppEmptyHeader>
+  <AppEmptyContent>
+    <AppButton size="sm">Create item</AppButton>
+  </AppEmptyContent>
+</AppEmpty>
+```
+
+### No search results
+```tsx
+import { Search } from "lucide-react"
+
+<AppEmpty>
+  <AppEmptyHeader>
+    <AppEmptyMedia variant="icon">
+      <Search className="size-6" aria-hidden />
+    </AppEmptyMedia>
+    <AppEmptyTitle>No results</AppEmptyTitle>
+    <AppEmptyDescription>Try adjusting your search or filters.</AppEmptyDescription>
+  </AppEmptyHeader>
+</AppEmpty>
+```
+
+### With illustration
+```tsx
+<AppEmpty>
+  <AppEmptyHeader>
+    <AppEmptyMedia>
+      <img src="/empty-illustration.svg" alt="" className="size-24" />
+    </AppEmptyMedia>
+    <AppEmptyTitle>Nothing here yet</AppEmptyTitle>
+    <AppEmptyDescription>Add your first item to get started.</AppEmptyDescription>
+  </AppEmptyHeader>
+  <AppEmptyContent>
+    <AppButton>Get started</AppButton>
+  </AppEmptyContent>
+</AppEmpty>
+```
+
+## Rules
+- ✅ Use `AppEmpty` for all zero-data states — no results, first-time views, filtered-empty lists
+- ✅ Use `variant="icon"` on `AppEmptyMedia` when showing a Lucide icon
+- ✅ Always include `AppEmptyTitle` — it is the primary accessible label for the state
+- ❌ Do not nest `AppEmptyHeader` inside `AppEmptyContent` — they are siblings
+- ❌ If a prop you need is missing, stop and inform the design team

package/rules/field.md

@@ -0,0 +1,149 @@
+# AppField
+
+> Docs: https://ui-kit.vercel.app/docs/components/field
+
+```tsx
+import {
+  AppField,
+  AppFieldLabel,
+  AppFieldControl,
+  AppFieldDescription,
+  AppFieldError,
+  AppFieldContent,
+  AppFieldTitle,
+  AppFieldGroup,
+  AppFieldSet,
+  AppFieldLegend,
+  useAppField,
+} from "@skunkworksai/ui-kit"
+```
+
+## AppField
+
+Root provider. Generates a stable `id` and propagates `invalid` state to all child field components via context.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `orientation` | `"vertical"` \| `"horizontal"` \| `"responsive"` | `"vertical"` | Layout of label + input. `"responsive"` is vertical on mobile, horizontal on `md+`. |
+| `invalid` | `boolean` | `false` | Marks field invalid. Turns label red and wires `aria-invalid` on the control. |
+| `className` | `string` | — | Additional Tailwind classes. |
+
+## AppFieldLabel
+
+Label bound to the control via FieldContext id. Do not set `htmlFor` manually.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `required` | `boolean` | `false` | Appends a red asterisk after the label text. |
+
+## AppFieldControl
+
+Slot wrapper. Injects `id`, `aria-describedby`, and `aria-invalid` from FieldContext onto the wrapped input. Wrap every input with this.
+
+Accepts all Radix `Slot` props.
+
+## AppFieldDescription
+
+Helper text below the input. Always rendered (not conditional) so `aria-describedby` stays stable.
+
+Accepts all `<p>` HTML attributes.
+
+## AppFieldError
+
+Validation error text. Renders nothing when `children` is empty or falsy.
+
+Accepts all `<p>` HTML attributes.
+
+## AppFieldContent
+
+Vertical stack (`gap-1`) wrapper for `AppFieldDescription` and `AppFieldError`.
+
+Accepts all `<div>` HTML attributes.
+
+## AppFieldTitle
+
+Small semibold label above a group of fields. Not bound to any control — use `AppFieldLabel` for per-input labels.
+
+Accepts all `<p>` HTML attributes.
+
+## AppFieldGroup
+
+Vertical stack (`gap-4`) of multiple `AppField` rows.
+
+Accepts all `<div>` HTML attributes.
+
+## AppFieldSet
+
+Semantic `<fieldset>` with browser defaults stripped (`m-0 border-0 p-0`).
+
+Accepts all `<fieldset>` HTML attributes.
+
+## AppFieldLegend
+
+Legend for `AppFieldSet`.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `"legend"` \| `"label"` | `"legend"` | `"legend"` is visually hidden (`sr-only`). `"label"` renders visible like `AppFieldLabel`. |
+
+## Usage
+
+### Default field
+```tsx
+<AppField>
+  <AppFieldLabel required>Email address</AppFieldLabel>
+  <AppFieldControl>
+    <AppInput type="email" placeholder="you@example.com" />
+  </AppFieldControl>
+  <AppFieldDescription>We will never share your email.</AppFieldDescription>
+</AppField>
+```
+
+### Field with validation error
+```tsx
+<AppField invalid>
+  <AppFieldLabel>Username</AppFieldLabel>
+  <AppFieldControl>
+    <AppInput placeholder="johndoe" defaultValue="jo" />
+  </AppFieldControl>
+  <AppFieldContent>
+    <AppFieldDescription>Must be at least 3 characters.</AppFieldDescription>
+    <AppFieldError>Username is too short.</AppFieldError>
+  </AppFieldContent>
+</AppField>
+```
+
+### Horizontal layout
+```tsx
+<AppField orientation="horizontal">
+  <AppFieldLabel>Notifications</AppFieldLabel>
+  <AppFieldControl>
+    <AppSwitch />
+  </AppFieldControl>
+</AppField>
+```
+
+### Grouped fields inside a fieldset
+```tsx
+<AppFieldSet>
+  <AppFieldLegend variant="label">Billing address</AppFieldLegend>
+  <AppFieldGroup>
+    <AppField>
+      <AppFieldLabel required>Street</AppFieldLabel>
+      <AppFieldControl><AppInput placeholder="123 Main St" /></AppFieldControl>
+    </AppField>
+    <AppField>
+      <AppFieldLabel required>City</AppFieldLabel>
+      <AppFieldControl><AppInput placeholder="San Francisco" /></AppFieldControl>
+    </AppField>
+  </AppFieldGroup>
+</AppFieldSet>
+```
+
+## Rules
+- ✅ Always wrap inputs with `AppFieldControl` — it injects id and aria attributes automatically
+- ✅ Use `invalid` prop on `AppField` for validation state — do not set `aria-invalid` manually
+- ✅ Use `AppFieldContent` to stack description + error below the input
+- ❌ Never set `htmlFor` on `AppFieldLabel` manually — FieldContext handles it
+- ❌ Never set `id` on the input manually — `AppFieldControl` injects it
+- ❌ If a prop you need is missing, stop and inform the design team

package/rules/form.md

@@ -0,0 +1,60 @@
+# AppForm
+
+> Docs: https://ui-kit.vercel.app/docs/components/form
+
+```tsx
+import {
+  AppForm,
+  AppFormItem,
+  AppFormLabel,
+  AppFormControl,
+  AppFormDescription,
+  AppFormMessage,
+  AppFormField,
+  useAppFormField,
+} from "@/components/primitives/AppForm"
+```
+
+## AppFormField
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `control` | `Control<any>` | - | The control object from `useForm`. |
+| `name` | `string` | - | The name of the field in the form data. |
+| `render` | `(props: { field: any }) => React.ReactNode` | - | A function that returns the component to render. |
+
+## Usage
+
+### Basic Form with Validation
+```tsx
+const form = useForm<FormValues>({
+  defaultValues: { username: "" },
+})
+
+<AppForm {...form}>
+  <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-6">
+    <AppFormField
+      control={form.control}
+      name="username"
+      render={({ field }) => (
+        <AppFormItem>
+          <AppFormLabel>Username</AppFormLabel>
+          <AppFormControl>
+            <AppInput placeholder="Enter your username" {...field} />
+          </AppFormControl>
+          <AppFormDescription>Your public name.</AppFormDescription>
+          <AppFormMessage />
+        </AppFormItem>
+      )}
+    />
+    <AppButton type="submit">Submit</AppButton>
+  </form>
+</AppForm>
+```
+
+## Rules
+
+- **Do** use `AppForm` and `AppFormField` for all complex forms requiring validation.
+- **Do** leverage `react-hook-form` for form management.
+- **Don't** use raw `<form>` without `AppForm` if validation is needed.
+- If a prop you need is missing, stop and inform the design team.