From d690ef895a4513ca6bd348d3c2ac29a171047ad3 Mon Sep 17 00:00:00 2001
From: Hirotaka Mizutani <52546+hirotaka@users.noreply.github.com>
Date: Tue, 30 Jun 2026 16:41:31 +0900
Subject: [PATCH] feat(registry): Add form components

---
 AGENTS.md                                    |   2 +-
 app/components/demo/FormDemo.vue             | 118 ++++++++++++++++++
 app/components/demo/FormFieldDemo.vue        |  32 +++++
 app/components/ui/field/Field.vue            |  25 ++++
 app/components/ui/field/FieldContent.vue     |  15 +++
 app/components/ui/field/FieldDescription.vue |  15 +++
 app/components/ui/field/FieldError.vue       |  47 +++++++
 app/components/ui/field/FieldGroup.vue       |  15 +++
 app/components/ui/field/FieldLabel.vue       |  20 +++
 app/components/ui/field/FieldLegend.vue      |  21 ++++
 app/components/ui/field/FieldSeparator.vue   |  15 +++
 app/components/ui/field/FieldSet.vue         |  15 +++
 app/components/ui/field/FieldTitle.vue       |  15 +++
 app/components/ui/field/index.ts             |  10 ++
 app/components/ui/select/Select.vue          |  18 +++
 app/components/ui/select/SelectContent.vue   |  33 +++++
 app/components/ui/select/SelectGroup.vue     |  15 +++
 app/components/ui/select/SelectItem.vue      |  32 +++++
 app/components/ui/select/SelectItemText.vue  |  12 ++
 app/components/ui/select/SelectLabel.vue     |  18 +++
 app/components/ui/select/SelectSeparator.vue |  16 +++
 app/components/ui/select/SelectTrigger.vue   |  28 +++++
 app/components/ui/select/SelectValue.vue     |  15 +++
 app/components/ui/select/index.ts            |   9 ++
 app/components/ui/textarea/Textarea.vue      |  31 +++++
 app/components/ui/textarea/index.ts          |   1 +
 app/composables/useNavigation.ts             |   2 +-
 app/registry/blocks/form-field/FormField.vue | 124 +++++++++++++++++++
 app/registry/blocks/form-field/index.ts      |   1 +
 app/registry/blocks/form/Form.vue            | 100 +++++++++++++++
 app/registry/blocks/form/form-types.ts       |  31 +++++
 app/registry/blocks/form/form-utils.ts       | 121 ++++++++++++++++++
 app/registry/blocks/form/index.ts            |   3 +
 content.config.ts                            |   2 +-
 content/docs/2.components/18.form.md         | 120 ++++++++++++++++++
 content/docs/2.components/19.form-field.md   |  90 ++++++++++++++
 scripts/registry-verify.ts                   |   8 ++
 37 files changed, 1192 insertions(+), 3 deletions(-)
 create mode 100644 app/components/demo/FormDemo.vue
 create mode 100644 app/components/demo/FormFieldDemo.vue
 create mode 100644 app/components/ui/field/Field.vue
 create mode 100644 app/components/ui/field/FieldContent.vue
 create mode 100644 app/components/ui/field/FieldDescription.vue
 create mode 100644 app/components/ui/field/FieldError.vue
 create mode 100644 app/components/ui/field/FieldGroup.vue
 create mode 100644 app/components/ui/field/FieldLabel.vue
 create mode 100644 app/components/ui/field/FieldLegend.vue
 create mode 100644 app/components/ui/field/FieldSeparator.vue
 create mode 100644 app/components/ui/field/FieldSet.vue
 create mode 100644 app/components/ui/field/FieldTitle.vue
 create mode 100644 app/components/ui/field/index.ts
 create mode 100644 app/components/ui/select/Select.vue
 create mode 100644 app/components/ui/select/SelectContent.vue
 create mode 100644 app/components/ui/select/SelectGroup.vue
 create mode 100644 app/components/ui/select/SelectItem.vue
 create mode 100644 app/components/ui/select/SelectItemText.vue
 create mode 100644 app/components/ui/select/SelectLabel.vue
 create mode 100644 app/components/ui/select/SelectSeparator.vue
 create mode 100644 app/components/ui/select/SelectTrigger.vue
 create mode 100644 app/components/ui/select/SelectValue.vue
 create mode 100644 app/components/ui/select/index.ts
 create mode 100644 app/components/ui/textarea/Textarea.vue
 create mode 100644 app/components/ui/textarea/index.ts
 create mode 100644 app/registry/blocks/form-field/FormField.vue
 create mode 100644 app/registry/blocks/form-field/index.ts
 create mode 100644 app/registry/blocks/form/Form.vue
 create mode 100644 app/registry/blocks/form/form-types.ts
 create mode 100644 app/registry/blocks/form/form-utils.ts
 create mode 100644 app/registry/blocks/form/index.ts
 create mode 100644 content/docs/2.components/18.form.md
 create mode 100644 content/docs/2.components/19.form-field.md

diff --git a/AGENTS.md b/AGENTS.md
index 67f6860..c196138 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -52,7 +52,7 @@ Config: `registry.config.ts` and `components.json` `registries` field.
 
 ## Content
 
-- `content.config.ts` defines the docs collection with `category` field: `element | content | marketing | chat | overview`
+- `content.config.ts` defines the docs collection with `category` field: `form | content | marketing | chat | overview`
 - `@nuxt/content` v3 with D1 database (`content.database.type: "d1"`)
 - Markdown highlight disabled; `nuxt-shiki` module handles syntax highlighting instead
 
diff --git a/app/components/demo/FormDemo.vue b/app/components/demo/FormDemo.vue
new file mode 100644
index 0000000..17f8303
--- /dev/null
+++ b/app/components/demo/FormDemo.vue
@@ -0,0 +1,118 @@
+<script setup lang="ts">
+import { reactive, ref } from "vue";
+import { Button } from "~/components/ui/button";
+import { Input } from "~/components/ui/input";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "~/components/ui/select";
+import { Textarea } from "~/components/ui/textarea";
+import { Form, type FormError } from "~/registry/blocks/form";
+import { FormField } from "~/registry/blocks/form-field";
+
+const state = reactive({
+  email: "",
+  message: "",
+  role: "",
+});
+const submitted = ref(false);
+
+function validate(values: typeof state): FormError[] {
+  const errors: FormError[] = [];
+
+  if (!values.email.includes("@")) {
+    errors.push({ name: "email", message: "Enter a valid email address." });
+  }
+  if (values.message.trim().length < 10) {
+    errors.push({ name: "message", message: "Message must be at least 10 characters." });
+  }
+  if (!values.role) {
+    errors.push({ name: "role", message: "Select a role." });
+  }
+
+  return errors;
+}
+
+function onSubmit() {
+  submitted.value = true;
+}
+</script>
+
+<template>
+  <Form
+    :state="state"
+    :validate="validate"
+    class="w-full max-w-md space-y-4"
+    @submit="onSubmit"
+  >
+    <FormField
+      v-slot="field"
+      label="Email"
+      name="email"
+      description="Use your work email."
+      required
+    >
+      <Input
+        v-model="state.email"
+        v-bind="field"
+        type="email"
+        placeholder="you@example.com"
+      />
+    </FormField>
+
+    <FormField
+      v-slot="field"
+      label="Message"
+      name="message"
+      help="Tell us what you are building."
+    >
+      <Textarea
+        v-model="state.message"
+        v-bind="field"
+        placeholder="I am building..."
+        rows="3"
+      />
+    </FormField>
+
+    <FormField
+      v-slot="field"
+      label="Role"
+      name="role"
+    >
+      <Select v-model="state.role">
+        <SelectTrigger
+          class="w-full"
+          v-bind="field"
+        >
+          <SelectValue placeholder="Select role" />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="admin">
+            Admin
+          </SelectItem>
+          <SelectItem value="editor">
+            Editor
+          </SelectItem>
+          <SelectItem value="viewer">
+            Viewer
+          </SelectItem>
+        </SelectContent>
+      </Select>
+    </FormField>
+
+    <div class="flex items-center gap-3">
+      <Button type="submit">
+        Submit
+      </Button>
+      <p
+        v-if="submitted"
+        class="text-sm text-muted-foreground"
+      >
+        Submitted locally. Your app owns the API call.
+      </p>
+    </div>
+  </Form>
+</template>
diff --git a/app/components/demo/FormFieldDemo.vue b/app/components/demo/FormFieldDemo.vue
new file mode 100644
index 0000000..5a57f64
--- /dev/null
+++ b/app/components/demo/FormFieldDemo.vue
@@ -0,0 +1,32 @@
+<script setup lang="ts">
+import { Input } from "~/components/ui/input";
+import { FormField } from "~/registry/blocks/form-field";
+</script>
+
+<template>
+  <div class="w-full max-w-md space-y-4">
+    <FormField
+      v-slot="field"
+      label="Project name"
+      description="This appears in your workspace switcher."
+      hint="Required"
+      required
+    >
+      <Input
+        v-bind="field"
+        placeholder="Acme dashboard"
+      />
+    </FormField>
+
+    <FormField
+      v-slot="field"
+      label="Slug"
+      error="Use lowercase letters, numbers, and dashes only."
+    >
+      <Input
+        v-bind="field"
+        model-value="Acme Dashboard"
+      />
+    </FormField>
+  </div>
+</template>
diff --git a/app/components/ui/field/Field.vue b/app/components/ui/field/Field.vue
new file mode 100644
index 0000000..1f1f058
--- /dev/null
+++ b/app/components/ui/field/Field.vue
@@ -0,0 +1,25 @@
+<script setup lang="ts">
+import type { HTMLAttributes } from "vue";
+import { cn } from "@/lib/utils";
+
+const props = withDefaults(defineProps<{
+  orientation?: "vertical" | "horizontal" | "responsive";
+  class?: HTMLAttributes["class"];
+}>(), {
+  orientation: "vertical",
+});
+</script>
+
+<template>
+  <div
+    data-slot="field"
+    :data-orientation="orientation"
+    :class="cn(
+      'grid gap-2 data-[orientation=horizontal]:grid-cols-[auto_1fr] data-[orientation=horizontal]:items-center data-[orientation=responsive]:gap-3 @md/field-group:data-[orientation=responsive]:grid-cols-[auto_1fr] @md/field-group:data-[orientation=responsive]:items-center',
+      props.class,
+    )"
+    role="group"
+  >
+    <slot />
+  </div>
+</template>
diff --git a/app/components/ui/field/FieldContent.vue b/app/components/ui/field/FieldContent.vue
new file mode 100644
index 0000000..70d5d7e
--- /dev/null
+++ b/app/components/ui/field/FieldContent.vue
@@ -0,0 +1,15 @@
+<script setup lang="ts">
+import type { HTMLAttributes } from "vue";
+import { cn } from "@/lib/utils";
+
+const props = defineProps<{ class?: HTMLAttributes["class"] }>();
+</script>
+
+<template>
+  <div
+    data-slot="field-content"
+    :class="cn('grid gap-1.5 leading-none', props.class)"
+  >
+    <slot />
+  </div>
+</template>
diff --git a/app/components/ui/field/FieldDescription.vue b/app/components/ui/field/FieldDescription.vue
new file mode 100644
index 0000000..b46304f
--- /dev/null
+++ b/app/components/ui/field/FieldDescription.vue
@@ -0,0 +1,15 @@
+<script setup lang="ts">
+import type { HTMLAttributes } from "vue";
+import { cn } from "@/lib/utils";
+
+const props = defineProps<{ class?: HTMLAttributes["class"] }>();
+</script>
+
+<template>
+  <p
+    data-slot="field-description"
+    :class="cn('text-muted-foreground text-sm', props.class)"
+  >
+    <slot />
+  </p>
+</template>
diff --git a/app/components/ui/field/FieldError.vue b/app/components/ui/field/FieldError.vue
new file mode 100644
index 0000000..6d918cb
--- /dev/null
+++ b/app/components/ui/field/FieldError.vue
@@ -0,0 +1,47 @@
+<script setup lang="ts">
+import type { HTMLAttributes } from "vue";
+import { computed } from "vue";
+import { cn } from "@/lib/utils";
+
+export interface FieldErrorItem {
+  message?: string;
+}
+
+const props = defineProps<{
+  error?: string | boolean | null;
+  errors?: Array<string | FieldErrorItem | undefined> | null;
+  class?: HTMLAttributes["class"];
+}>();
+
+const messages = computed(() => {
+  if (typeof props.error === "string") return [props.error];
+  return (props.errors ?? [])
+    .map(error => typeof error === "string" ? error : error?.message)
+    .filter((message): message is string => Boolean(message));
+});
+</script>
+
+<template>
+  <div
+    v-if="messages.length || $slots.default"
+    data-slot="field-error"
+    :class="cn('text-destructive text-sm font-medium', props.class)"
+  >
+    <slot>
+      <p v-if="messages.length === 1">
+        {{ messages[0] }}
+      </p>
+      <ul
+        v-else
+        class="list-disc ps-5"
+      >
+        <li
+          v-for="message in messages"
+          :key="message"
+        >
+          {{ message }}
+        </li>
+      </ul>
+    </slot>
+  </div>
+</template>
diff --git a/app/components/ui/field/FieldGroup.vue b/app/components/ui/field/FieldGroup.vue
new file mode 100644
index 0000000..1e25ab1
--- /dev/null
+++ b/app/components/ui/field/FieldGroup.vue
@@ -0,0 +1,15 @@
+<script setup lang="ts">
+import type { HTMLAttributes } from "vue";
+import { cn } from "@/lib/utils";
+
+const props = defineProps<{ class?: HTMLAttributes["class"] }>();
+</script>
+
+<template>
+  <div
+    data-slot="field-group"
+    :class="cn('@container/field-group grid gap-6', props.class)"
+  >
+    <slot />
+  </div>
+</template>
diff --git a/app/components/ui/field/FieldLabel.vue b/app/components/ui/field/FieldLabel.vue
new file mode 100644
index 0000000..6f37231
--- /dev/null
+++ b/app/components/ui/field/FieldLabel.vue
@@ -0,0 +1,20 @@
+<script setup lang="ts">
+import type { LabelProps } from "reka-ui";
+import type { HTMLAttributes } from "vue";
+import { reactiveOmit } from "@vueuse/core";
+import { Label } from "reka-ui";
+import { cn } from "@/lib/utils";
+
+const props = defineProps<LabelProps & { class?: HTMLAttributes["class"] }>();
+const delegatedProps = reactiveOmit(props, "class");
+</script>
+
+<template>
+  <Label
+    data-slot="field-label"
+    v-bind="delegatedProps"
+    :class="cn('flex items-center gap-2 text-sm leading-none font-medium select-none group-data-[disabled=true]:pointer-events-none group-data-[disabled=true]:opacity-50 peer-disabled:cursor-not-allowed peer-disabled:opacity-50', props.class)"
+  >
+    <slot />
+  </Label>
+</template>
diff --git a/app/components/ui/field/FieldLegend.vue b/app/components/ui/field/FieldLegend.vue
new file mode 100644
index 0000000..11a1fad
--- /dev/null
+++ b/app/components/ui/field/FieldLegend.vue
@@ -0,0 +1,21 @@
+<script setup lang="ts">
+import type { HTMLAttributes } from "vue";
+import { cn } from "@/lib/utils";
+
+const props = withDefaults(defineProps<{
+  variant?: "legend" | "label";
+  class?: HTMLAttributes["class"];
+}>(), {
+  variant: "legend",
+});
+</script>
+
+<template>
+  <legend
+    data-slot="field-legend"
+    :data-variant="variant"
+    :class="cn('mb-3 font-medium data-[variant=legend]:text-base data-[variant=label]:text-sm', props.class)"
+  >
+    <slot />
+  </legend>
+</template>
diff --git a/app/components/ui/field/FieldSeparator.vue b/app/components/ui/field/FieldSeparator.vue
new file mode 100644
index 0000000..5524e1f
--- /dev/null
+++ b/app/components/ui/field/FieldSeparator.vue
@@ -0,0 +1,15 @@
+<script setup lang="ts">
+import type { HTMLAttributes } from "vue";
+import { cn } from "@/lib/utils";
+
+const props = defineProps<{ class?: HTMLAttributes["class"] }>();
+</script>
+
+<template>
+  <div
+    data-slot="field-separator"
+    :class="cn('bg-border h-px w-full', props.class)"
+  >
+    <slot />
+  </div>
+</template>
diff --git a/app/components/ui/field/FieldSet.vue b/app/components/ui/field/FieldSet.vue
new file mode 100644
index 0000000..52bfee5
--- /dev/null
+++ b/app/components/ui/field/FieldSet.vue
@@ -0,0 +1,15 @@
+<script setup lang="ts">
+import type { HTMLAttributes } from "vue";
+import { cn } from "@/lib/utils";
+
+const props = defineProps<{ class?: HTMLAttributes["class"] }>();
+</script>
+
+<template>
+  <fieldset
+    data-slot="field-set"
+    :class="cn('grid gap-6', props.class)"
+  >
+    <slot />
+  </fieldset>
+</template>
diff --git a/app/components/ui/field/FieldTitle.vue b/app/components/ui/field/FieldTitle.vue
new file mode 100644
index 0000000..ce620fa
--- /dev/null
+++ b/app/components/ui/field/FieldTitle.vue
@@ -0,0 +1,15 @@
+<script setup lang="ts">
+import type { HTMLAttributes } from "vue";
+import { cn } from "@/lib/utils";
+
+const props = defineProps<{ class?: HTMLAttributes["class"] }>();
+</script>
+
+<template>
+  <div
+    data-slot="field-title"
+    :class="cn('text-sm leading-none font-medium', props.class)"
+  >
+    <slot />
+  </div>
+</template>
diff --git a/app/components/ui/field/index.ts b/app/components/ui/field/index.ts
new file mode 100644
index 0000000..cf2450a
--- /dev/null
+++ b/app/components/ui/field/index.ts
@@ -0,0 +1,10 @@
+export { default as Field } from "./Field.vue";
+export { default as FieldContent } from "./FieldContent.vue";
+export { default as FieldDescription } from "./FieldDescription.vue";
+export { default as FieldError, type FieldErrorItem } from "./FieldError.vue";
+export { default as FieldGroup } from "./FieldGroup.vue";
+export { default as FieldLabel } from "./FieldLabel.vue";
+export { default as FieldLegend } from "./FieldLegend.vue";
+export { default as FieldSeparator } from "./FieldSeparator.vue";
+export { default as FieldSet } from "./FieldSet.vue";
+export { default as FieldTitle } from "./FieldTitle.vue";
diff --git a/app/components/ui/select/Select.vue b/app/components/ui/select/Select.vue
new file mode 100644
index 0000000..9048de9
--- /dev/null
+++ b/app/components/ui/select/Select.vue
@@ -0,0 +1,18 @@
+<script setup lang="ts">
+import type { SelectRootEmits, SelectRootProps } from "reka-ui";
+import { SelectRoot, useForwardPropsEmits } from "reka-ui";
+
+const props = defineProps<SelectRootProps>();
+const emits = defineEmits<SelectRootEmits>();
+
+const forwarded = useForwardPropsEmits(props, emits);
+</script>
+
+<template>
+  <SelectRoot
+    data-slot="select"
+    v-bind="forwarded"
+  >
+    <slot />
+  </SelectRoot>
+</template>
diff --git a/app/components/ui/select/SelectContent.vue b/app/components/ui/select/SelectContent.vue
new file mode 100644
index 0000000..742267b
--- /dev/null
+++ b/app/components/ui/select/SelectContent.vue
@@ -0,0 +1,33 @@
+<script setup lang="ts">
+import type { SelectContentEmits, SelectContentProps } from "reka-ui";
+import type { HTMLAttributes } from "vue";
+import { SelectContent, SelectPortal, SelectViewport, useForwardPropsEmits } from "reka-ui";
+import { cn } from "@/lib/utils";
+
+const props = withDefaults(defineProps<SelectContentProps & { class?: HTMLAttributes["class"] }>(), {
+  position: "popper",
+});
+const emits = defineEmits<SelectContentEmits>();
+
+const forwarded = useForwardPropsEmits(props, emits);
+</script>
+
+<template>
+  <SelectPortal>
+    <SelectContent
+      data-slot="select-content"
+      v-bind="forwarded"
+      :class="cn(
+        'bg-popover text-popover-foreground data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 relative z-50 max-h-96 min-w-32 overflow-hidden rounded-md border shadow-md',
+        position === 'popper' && 'data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1',
+        props.class,
+      )"
+    >
+      <SelectViewport
+        :class="cn('p-1', position === 'popper' && 'h-[var(--reka-select-trigger-height)] w-full min-w-[var(--reka-select-trigger-width)] scroll-my-1')"
+      >
+        <slot />
+      </SelectViewport>
+    </SelectContent>
+  </SelectPortal>
+</template>
diff --git a/app/components/ui/select/SelectGroup.vue b/app/components/ui/select/SelectGroup.vue
new file mode 100644
index 0000000..fa57ee9
--- /dev/null
+++ b/app/components/ui/select/SelectGroup.vue
@@ -0,0 +1,15 @@
+<script setup lang="ts">
+import type { SelectGroupProps } from "reka-ui";
+import { SelectGroup } from "reka-ui";
+
+const props = defineProps<SelectGroupProps>();
+</script>
+
+<template>
+  <SelectGroup
+    data-slot="select-group"
+    v-bind="props"
+  >
+    <slot />
+  </SelectGroup>
+</template>
diff --git a/app/components/ui/select/SelectItem.vue b/app/components/ui/select/SelectItem.vue
new file mode 100644
index 0000000..2a453fe
--- /dev/null
+++ b/app/components/ui/select/SelectItem.vue
@@ -0,0 +1,32 @@
+<script setup lang="ts">
+import type { SelectItemProps } from "reka-ui";
+import type { HTMLAttributes } from "vue";
+import { Check } from "lucide-vue-next";
+import { SelectItem, SelectItemIndicator, SelectItemText } from "reka-ui";
+import { cn } from "@/lib/utils";
+
+const props = defineProps<SelectItemProps & { class?: HTMLAttributes["class"] }>();
+</script>
+
+<template>
+  <SelectItem
+    data-slot="select-item"
+    v-bind="props"
+    :class="cn(
+      'focus:bg-accent focus:text-accent-foreground [&_svg:not([class*=text-])]:text-muted-foreground relative flex w-full cursor-default items-center gap-2 rounded-sm py-1.5 pr-8 pl-2 text-sm outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0',
+      props.class,
+    )"
+  >
+    <span class="absolute right-2 flex size-3.5 items-center justify-center">
+      <SelectItemIndicator>
+        <Check
+          class="size-4"
+          aria-hidden="true"
+        />
+      </SelectItemIndicator>
+    </span>
+    <SelectItemText>
+      <slot />
+    </SelectItemText>
+  </SelectItem>
+</template>
diff --git a/app/components/ui/select/SelectItemText.vue b/app/components/ui/select/SelectItemText.vue
new file mode 100644
index 0000000..ab193b1
--- /dev/null
+++ b/app/components/ui/select/SelectItemText.vue
@@ -0,0 +1,12 @@
+<script setup lang="ts">
+import type { SelectItemTextProps } from "reka-ui";
+import { SelectItemText } from "reka-ui";
+
+const props = defineProps<SelectItemTextProps>();
+</script>
+
+<template>
+  <SelectItemText v-bind="props">
+    <slot />
+  </SelectItemText>
+</template>
diff --git a/app/components/ui/select/SelectLabel.vue b/app/components/ui/select/SelectLabel.vue
new file mode 100644
index 0000000..1e55542
--- /dev/null
+++ b/app/components/ui/select/SelectLabel.vue
@@ -0,0 +1,18 @@
+<script setup lang="ts">
+import type { SelectLabelProps } from "reka-ui";
+import type { HTMLAttributes } from "vue";
+import { SelectLabel } from "reka-ui";
+import { cn } from "@/lib/utils";
+
+const props = defineProps<SelectLabelProps & { class?: HTMLAttributes["class"] }>();
+</script>
+
+<template>
+  <SelectLabel
+    data-slot="select-label"
+    v-bind="props"
+    :class="cn('text-muted-foreground px-2 py-1.5 text-xs', props.class)"
+  >
+    <slot />
+  </SelectLabel>
+</template>
diff --git a/app/components/ui/select/SelectSeparator.vue b/app/components/ui/select/SelectSeparator.vue
new file mode 100644
index 0000000..5f7c269
--- /dev/null
+++ b/app/components/ui/select/SelectSeparator.vue
@@ -0,0 +1,16 @@
+<script setup lang="ts">
+import type { SelectSeparatorProps } from "reka-ui";
+import type { HTMLAttributes } from "vue";
+import { SelectSeparator } from "reka-ui";
+import { cn } from "@/lib/utils";
+
+const props = defineProps<SelectSeparatorProps & { class?: HTMLAttributes["class"] }>();
+</script>
+
+<template>
+  <SelectSeparator
+    data-slot="select-separator"
+    v-bind="props"
+    :class="cn('bg-border pointer-events-none -mx-1 my-1 h-px', props.class)"
+  />
+</template>
diff --git a/app/components/ui/select/SelectTrigger.vue b/app/components/ui/select/SelectTrigger.vue
new file mode 100644
index 0000000..d840d7f
--- /dev/null
+++ b/app/components/ui/select/SelectTrigger.vue
@@ -0,0 +1,28 @@
+<script setup lang="ts">
+import type { SelectTriggerProps } from "reka-ui";
+import type { HTMLAttributes } from "vue";
+import { ChevronDown } from "lucide-vue-next";
+import { SelectIcon, SelectTrigger } from "reka-ui";
+import { cn } from "@/lib/utils";
+
+const props = defineProps<SelectTriggerProps & { class?: HTMLAttributes["class"] }>();
+</script>
+
+<template>
+  <SelectTrigger
+    data-slot="select-trigger"
+    v-bind="props"
+    :class="cn(
+      'border-input data-[placeholder]:text-muted-foreground [&_svg:not([class*=text-])]:text-muted-foreground focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive dark:bg-input/30 flex h-9 w-fit items-center justify-between gap-2 rounded-md border bg-transparent px-3 py-2 text-sm whitespace-nowrap shadow-xs transition-[color,box-shadow] outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50 data-[size=default]:h-9 data-[size=sm]:h-8 *:data-[slot=select-value]:line-clamp-1 *:data-[slot=select-value]:flex *:data-[slot=select-value]:items-center *:data-[slot=select-value]:gap-2 [&_svg]:pointer-events-none [&_svg]:shrink-0',
+      props.class,
+    )"
+  >
+    <slot />
+    <SelectIcon as-child>
+      <ChevronDown
+        class="size-4 opacity-50"
+        aria-hidden="true"
+      />
+    </SelectIcon>
+  </SelectTrigger>
+</template>
diff --git a/app/components/ui/select/SelectValue.vue b/app/components/ui/select/SelectValue.vue
new file mode 100644
index 0000000..98c0d67
--- /dev/null
+++ b/app/components/ui/select/SelectValue.vue
@@ -0,0 +1,15 @@
+<script setup lang="ts">
+import type { SelectValueProps } from "reka-ui";
+import { SelectValue } from "reka-ui";
+
+const props = defineProps<SelectValueProps>();
+</script>
+
+<template>
+  <SelectValue
+    data-slot="select-value"
+    v-bind="props"
+  >
+    <slot />
+  </SelectValue>
+</template>
diff --git a/app/components/ui/select/index.ts b/app/components/ui/select/index.ts
new file mode 100644
index 0000000..8e6b873
--- /dev/null
+++ b/app/components/ui/select/index.ts
@@ -0,0 +1,9 @@
+export { default as Select } from "./Select.vue";
+export { default as SelectContent } from "./SelectContent.vue";
+export { default as SelectGroup } from "./SelectGroup.vue";
+export { default as SelectItem } from "./SelectItem.vue";
+export { default as SelectItemText } from "./SelectItemText.vue";
+export { default as SelectLabel } from "./SelectLabel.vue";
+export { default as SelectSeparator } from "./SelectSeparator.vue";
+export { default as SelectTrigger } from "./SelectTrigger.vue";
+export { default as SelectValue } from "./SelectValue.vue";
diff --git a/app/components/ui/textarea/Textarea.vue b/app/components/ui/textarea/Textarea.vue
new file mode 100644
index 0000000..ec2f156
--- /dev/null
+++ b/app/components/ui/textarea/Textarea.vue
@@ -0,0 +1,31 @@
+<script setup lang="ts">
+import type { HTMLAttributes } from "vue";
+import { useVModel } from "@vueuse/core";
+import { cn } from "@/lib/utils";
+
+const props = defineProps<{
+  defaultValue?: string | number;
+  modelValue?: string | number;
+  class?: HTMLAttributes["class"];
+}>();
+
+const emits = defineEmits<{
+  (e: "update:modelValue", payload: string | number): void;
+}>();
+
+const modelValue = useVModel(props, "modelValue", emits, {
+  passive: true,
+  defaultValue: props.defaultValue,
+});
+</script>
+
+<template>
+  <textarea
+    v-model="modelValue"
+    data-slot="textarea"
+    :class="cn(
+      'border-input placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive dark:bg-input/30 flex field-sizing-content min-h-16 w-full rounded-md border bg-transparent px-3 py-2 text-base shadow-xs transition-[color,box-shadow] outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50 md:text-sm',
+      props.class,
+    )"
+  />
+</template>
diff --git a/app/components/ui/textarea/index.ts b/app/components/ui/textarea/index.ts
new file mode 100644
index 0000000..178d08c
--- /dev/null
+++ b/app/components/ui/textarea/index.ts
@@ -0,0 +1 @@
+export { default as Textarea } from "./Textarea.vue";
diff --git a/app/composables/useNavigation.ts b/app/composables/useNavigation.ts
index d030f1e..c67acff 100644
--- a/app/composables/useNavigation.ts
+++ b/app/composables/useNavigation.ts
@@ -8,7 +8,7 @@ export const sectionCategories: Record<string, { id: string; title: string }[]>
     { id: "overview", title: "Overview" },
     { id: "content", title: "Content" },
     { id: "marketing", title: "Marketing" },
-    { id: "element", title: "Element" },
+    { id: "form", title: "Form" },
     { id: "chat", title: "AI Chat" },
   ],
 };
diff --git a/app/registry/blocks/form-field/FormField.vue b/app/registry/blocks/form-field/FormField.vue
new file mode 100644
index 0000000..6034afc
--- /dev/null
+++ b/app/registry/blocks/form-field/FormField.vue
@@ -0,0 +1,124 @@
+<script setup lang="ts">
+import type { HTMLAttributes } from "vue";
+import { computed, inject, useId } from "vue";
+import { cn } from "@/lib/utils";
+import {
+  Field,
+  FieldDescription,
+  FieldError,
+  FieldLabel,
+} from "@/components/ui/field";
+import { FORM_CONTEXT_KEY } from "../form";
+
+export interface FormFieldProps {
+  name?: string;
+  errorPattern?: RegExp;
+  label?: string;
+  description?: string;
+  help?: string;
+  hint?: string;
+  error?: string | boolean;
+  required?: boolean;
+  orientation?: "vertical" | "horizontal" | "responsive";
+  class?: HTMLAttributes["class"];
+}
+
+const props = withDefaults(defineProps<FormFieldProps>(), {
+  orientation: "vertical",
+});
+
+const form = inject(FORM_CONTEXT_KEY, null);
+const baseId = useId();
+
+const controlId = computed(() => props.name ? `${props.name.replace(/[^a-zA-Z0-9_-]/g, "-")}-${baseId}` : `field-${baseId}`);
+const descriptionId = computed(() => `${controlId.value}-description`);
+const helpId = computed(() => `${controlId.value}-help`);
+const errorId = computed(() => `${controlId.value}-error`);
+
+const contextErrors = computed(() => form?.getFieldErrors(props.name, props.errorPattern) ?? []);
+const errorMessage = computed(() => {
+  if (typeof props.error === "string") return props.error;
+  if (props.error === true) return "Invalid value.";
+  return contextErrors.value[0]?.message;
+});
+const invalid = computed(() => Boolean(errorMessage.value));
+const describedBy = computed(() => [
+  props.description ? descriptionId.value : undefined,
+  props.help && !invalid.value ? helpId.value : undefined,
+  invalid.value ? errorId.value : undefined,
+].filter(Boolean).join(" ") || undefined);
+const slotProps = computed(() => ({
+  "id": controlId.value,
+  "name": props.name,
+  "disabled": form?.disabled.value ?? false,
+  "aria-invalid": invalid.value ? "true" : undefined,
+  "aria-describedby": describedBy.value,
+}));
+</script>
+
+<template>
+  <Field
+    data-slot="form-field"
+    :data-invalid="invalid ? '' : undefined"
+    :data-disabled="form?.disabled.value ? '' : undefined"
+    :orientation="orientation"
+    :class="cn(props.class)"
+  >
+    <div class="flex items-center justify-between gap-2">
+      <FieldLabel
+        v-if="label || $slots.label"
+        :for="controlId"
+        :class="required && 'after:text-destructive after:ms-0.5 after:content-[\'*\']'"
+      >
+        <slot name="label">
+          {{ label }}
+        </slot>
+      </FieldLabel>
+
+      <span
+        v-if="hint || $slots.hint"
+        data-slot="form-field-hint"
+        class="text-muted-foreground text-sm"
+      >
+        <slot name="hint">
+          {{ hint }}
+        </slot>
+      </span>
+    </div>
+
+    <FieldDescription
+      v-if="description || $slots.description"
+      :id="descriptionId"
+    >
+      <slot name="description">
+        {{ description }}
+      </slot>
+    </FieldDescription>
+
+    <div data-slot="form-field-control">
+      <slot
+        v-bind="slotProps"
+      />
+    </div>
+
+    <FieldError
+      v-if="invalid || $slots.error"
+      :id="errorId"
+      :error="errorMessage"
+    >
+      <slot name="error">
+        {{ errorMessage }}
+      </slot>
+    </FieldError>
+
+    <FieldDescription
+      v-else-if="help || $slots.help"
+      :id="helpId"
+      data-slot="form-field-help"
+    >
+      <slot name="help">
+        {{ help }}
+      </slot>
+    </FieldDescription>
+  </Field>
+</template>
diff --git a/app/registry/blocks/form-field/index.ts b/app/registry/blocks/form-field/index.ts
new file mode 100644
index 0000000..9d2150d
--- /dev/null
+++ b/app/registry/blocks/form-field/index.ts
@@ -0,0 +1 @@
+export { default as FormField, type FormFieldProps } from "./FormField.vue";
diff --git a/app/registry/blocks/form/Form.vue b/app/registry/blocks/form/Form.vue
new file mode 100644
index 0000000..f0b02c7
--- /dev/null
+++ b/app/registry/blocks/form/Form.vue
@@ -0,0 +1,100 @@
+<script setup lang="ts" generic="TState = unknown">
+import type { HTMLAttributes } from "vue";
+import type { FormErrorEvent, FormInputEvent, FormSubmitEvent, FormValidate } from "./form-types";
+import { computed, provide, ref, toRef } from "vue";
+import { cn } from "@/lib/utils";
+import { findFormErrors, FORM_CONTEXT_KEY, validateWithSchema } from "./form-utils";
+
+export interface FormProps<TState = unknown> {
+  state?: TState;
+  schema?: unknown;
+  validate?: FormValidate<TState>;
+  validateOn?: FormInputEvent[];
+  disabled?: boolean;
+  class?: HTMLAttributes["class"];
+}
+
+const props = withDefaults(defineProps<FormProps<TState>>(), {
+  validateOn: () => ["blur"],
+  disabled: false,
+});
+
+defineOptions({
+  name: "StackhackerForm",
+});
+
+const emit = defineEmits<{
+  submit: [event: FormSubmitEvent<TState | undefined>];
+  error: [event: FormErrorEvent<TState | undefined>];
+}>();
+
+const errors = ref<FormErrorEvent["errors"]>([]);
+const state = toRef(props, "state");
+const disabled = computed(() => props.disabled);
+
+async function validateForm(event?: Event) {
+  const nextErrors = props.validate
+    ? await props.validate(props.state as TState)
+    : await validateWithSchema(props.schema, props.state);
+
+  errors.value = nextErrors;
+  if (event && nextErrors.length) {
+    emit("error", {
+      originalEvent: event,
+      errors: nextErrors,
+      data: props.state,
+    });
+  }
+  return nextErrors;
+}
+
+async function onSubmit(event: SubmitEvent) {
+  event.preventDefault();
+
+  const nextErrors = await validateForm(event);
+  if (nextErrors.length) return;
+
+  emit("submit", {
+    originalEvent: event,
+    data: props.state,
+  });
+}
+
+function shouldValidateOn(type: FormInputEvent) {
+  return props.validateOn.includes(type);
+}
+
+async function onInput(event: Event) {
+  if (shouldValidateOn("input")) await validateForm(event);
+}
+
+async function onChange(event: Event) {
+  if (shouldValidateOn("change")) await validateForm(event);
+}
+
+async function onBlur(event: Event) {
+  if (shouldValidateOn("blur")) await validateForm(event);
+}
+
+provide(FORM_CONTEXT_KEY, {
+  errors,
+  disabled,
+  state,
+  validate: validateForm,
+  getFieldErrors: (name, errorPattern) => findFormErrors(errors.value, name, errorPattern),
+});
+</script>
+
+<template>
+  <form
+    data-slot="form"
+    :data-disabled="disabled ? '' : undefined"
+    :class="cn(props.class)"
+    @submit="onSubmit"
+    @input.capture="onInput"
+    @change.capture="onChange"
+    @blur.capture="onBlur"
+  >
+    <slot />
+  </form>
+</template>
diff --git a/app/registry/blocks/form/form-types.ts b/app/registry/blocks/form/form-types.ts
new file mode 100644
index 0000000..f9795a4
--- /dev/null
+++ b/app/registry/blocks/form/form-types.ts
@@ -0,0 +1,31 @@
+import type { Ref } from "vue";
+
+export interface FormError {
+  name: string;
+  message: string;
+  id?: string;
+  [key: string]: unknown;
+}
+
+export interface FormSubmitEvent<TState = unknown> {
+  originalEvent: SubmitEvent;
+  data: TState;
+}
+
+export interface FormErrorEvent<TState = unknown> {
+  originalEvent?: Event;
+  errors: FormError[];
+  data: TState;
+}
+
+export type FormInputEvent = "input" | "change" | "blur";
+
+export type FormValidate<TState = unknown> = (state: TState) => FormError[] | Promise<FormError[]>;
+
+export interface FormContextValue<TState = unknown> {
+  errors: Ref<FormError[]>;
+  disabled: Ref<boolean>;
+  getFieldErrors: (name?: string, errorPattern?: RegExp) => FormError[];
+  validate: (event?: Event) => Promise<FormError[]>;
+  state: Ref<TState | undefined>;
+}
diff --git a/app/registry/blocks/form/form-utils.ts b/app/registry/blocks/form/form-utils.ts
new file mode 100644
index 0000000..196a8d3
--- /dev/null
+++ b/app/registry/blocks/form/form-utils.ts
@@ -0,0 +1,121 @@
+import type { InjectionKey } from "vue";
+import type { FormContextValue, FormError } from "./form-types";
+
+export const FORM_CONTEXT_KEY: InjectionKey<FormContextValue> = Symbol("stackhacker-ui-form-context");
+
+interface MessageLike {
+  message?: unknown;
+  $message?: unknown;
+  name?: unknown;
+  path?: unknown;
+  id?: unknown;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function pathToName(path: unknown) {
+  if (Array.isArray(path)) return path.join(".");
+  return typeof path === "string" ? path : undefined;
+}
+
+function messageFrom(value: unknown) {
+  if (typeof value === "string") return value;
+  if (!isRecord(value)) return undefined;
+
+  const item = value as MessageLike;
+  if (typeof item.message === "string") return item.message;
+  if (typeof item.$message === "string") return item.$message;
+  return undefined;
+}
+
+function nameFrom(value: unknown, fallback?: string) {
+  if (!isRecord(value)) return fallback;
+
+  const item = value as MessageLike;
+  if (typeof item.name === "string") return item.name;
+  return pathToName(item.path) ?? fallback;
+}
+
+function normalizeErrorItem(value: unknown, fallbackName?: string): FormError | null {
+  const message = messageFrom(value);
+  const name = nameFrom(value, fallbackName);
+  if (!message || !name) return null;
+
+  const id = isRecord(value) && typeof value.id === "string" ? value.id : undefined;
+  return { name, message, ...(id ? { id } : {}) };
+}
+
+function collectErrorTree(value: unknown, prefix = ""): FormError[] {
+  if (!value) return [];
+
+  if (Array.isArray(value)) {
+    return value
+      .map(error => normalizeErrorItem(error, prefix))
+      .filter((error): error is FormError => Boolean(error));
+  }
+
+  const direct = normalizeErrorItem(value, prefix || undefined);
+  if (direct) return [direct];
+
+  if (!isRecord(value)) return [];
+
+  return Object.entries(value).flatMap(([key, child]) => {
+    const path = prefix ? `${prefix}.${key}` : key;
+    return collectErrorTree(child, path);
+  });
+}
+
+export function normalizeFormErrors(value: unknown): FormError[] {
+  return collectErrorTree(value);
+}
+
+export function findFormErrors(errors: FormError[], name?: string, errorPattern?: RegExp) {
+  if (!name && !errorPattern) return [];
+
+  return errors.filter((error) => {
+    if (name && error.name === name) return true;
+    return errorPattern ? errorPattern.test(error.name) : false;
+  });
+}
+
+export async function validateWithSchema(schema: unknown, state: unknown): Promise<FormError[]> {
+  if (!schema) return [];
+
+  if (isRecord(schema) && typeof schema.$validate === "function") {
+    await schema.$validate();
+    return normalizeFormErrors(schema.$errors);
+  }
+
+  if (isRecord(schema) && isRecord(schema["~standard"])) {
+    const standard = schema["~standard"];
+    if (typeof standard.validate === "function") {
+      const result = await standard.validate(state);
+      if (isRecord(result) && Array.isArray(result.issues)) {
+        return normalizeFormErrors(result.issues);
+      }
+      return [];
+    }
+  }
+
+  if (isRecord(schema) && typeof schema.safeParse === "function") {
+    const result = await schema.safeParse(state);
+    if (isRecord(result) && result.success === false && isRecord(result.error)) {
+      return normalizeFormErrors(result.error.issues);
+    }
+    return [];
+  }
+
+  if (isRecord(schema) && typeof schema.parse === "function") {
+    try {
+      await schema.parse(state);
+      return [];
+    }
+    catch (error) {
+      return normalizeFormErrors(isRecord(error) ? error.issues : error);
+    }
+  }
+
+  return [];
+}
diff --git a/app/registry/blocks/form/index.ts b/app/registry/blocks/form/index.ts
new file mode 100644
index 0000000..af1039e
--- /dev/null
+++ b/app/registry/blocks/form/index.ts
@@ -0,0 +1,3 @@
+export { default as Form, type FormProps } from "./Form.vue";
+export type { FormError, FormErrorEvent, FormInputEvent, FormSubmitEvent, FormValidate } from "./form-types";
+export { findFormErrors, FORM_CONTEXT_KEY, normalizeFormErrors, validateWithSchema } from "./form-utils";
diff --git a/content.config.ts b/content.config.ts
index 6b69213..94e8516 100644
--- a/content.config.ts
+++ b/content.config.ts
@@ -9,7 +9,7 @@ export default defineContentConfig({
       },
       schema: z.object({
         category: z
-          .enum(["element", "content", "marketing", "chat", "overview"])
+          .enum(["form", "content", "marketing", "chat", "overview"])
           .optional(),
       }),
     }),
diff --git a/content/docs/2.components/18.form.md b/content/docs/2.components/18.form.md
new file mode 100644
index 0000000..6d6f15a
--- /dev/null
+++ b/content/docs/2.components/18.form.md
@@ -0,0 +1,120 @@
+---
+title: Form
+description: Validate app-owned form state and distribute errors to named fields.
+category: form
+---
+
+::component-preview
+---
+
+name: FormDemo
+---
+
+::
+
+## Installation
+
+Add the shadcn-vue controls you want to compose, then add Stackhacker UI's form layer.
+
+```bash
+npx shadcn-vue@latest add field input textarea select
+npx shadcn-vue@latest add "https://ui.stackhacker.io/r/form.json"
+npx shadcn-vue@latest add "https://ui.stackhacker.io/r/form-field.json"
+```
+
+## Usage
+
+```vue
+<script setup lang="ts">
+import { reactive } from 'vue'
+import { Form, type FormError } from '@/components/form'
+import { FormField } from '@/components/form-field'
+import { Input } from '@/components/ui/input'
+
+const state = reactive({ email: '' })
+
+function validate(values: typeof state): FormError[] {
+  if (!values.email.includes('@')) {
+    return [{ name: 'email', message: 'Enter a valid email address.' }]
+  }
+  return []
+}
+
+async function onSubmit(event) {
+  await saveProfile(event.data)
+}
+</script>
+
+<template>
+  <Form :state="state" :validate="validate" @submit="onSubmit">
+    <FormField v-slot="field" label="Email" name="email">
+      <Input v-model="state.email" v-bind="field" type="email" />
+    </FormField>
+  </Form>
+</template>
+```
+
+## Responsibilities
+
+`Form` owns the UI protocol: form event handling, validation triggering, error collection, field-level error distribution, and `submit` / `error` events.
+
+Your app owns API submission, mutation, persistence, toast, redirect, server error interpretation, auth flows, and business rules.
+
+## Regle Integration
+
+Regle remains an app dependency. Stackhacker UI does not import Regle.
+
+```vue
+<script setup lang="ts">
+import { useRegle } from '@regle/core'
+import { email, required, withMessage } from '@regle/rules'
+import { Form } from '@/components/form'
+import { FormField } from '@/components/form-field'
+import { Input } from '@/components/ui/input'
+
+const { r$ } = useRegle({ email: '' }, {
+  email: {
+    required,
+    email: withMessage(email, 'Enter a valid email address.')
+  }
+})
+</script>
+
+<template>
+  <Form :schema="r$" :state="r$.$value">
+    <FormField v-slot="field" label="Email" name="email">
+      <Input v-model="r$.$value.email" v-bind="field" type="email" />
+    </FormField>
+  </Form>
+</template>
+```
+
+## API Reference
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `state` | `unknown` | — | App-owned reactive form state. |
+| `schema` | `unknown` | — | Optional schema-like validator such as Regle or Standard Schema. |
+| `validate` | `(state) => FormError[] \| Promise<FormError[]>` | — | Custom validation function. |
+| `validateOn` | `('input' \| 'change' \| 'blur')[]` | `['blur']` | Input events that trigger validation. |
+| `disabled` | `boolean` | `false` | Marks the form context disabled for fields. |
+| `class` | `string` | — | Additional CSS classes. |
+
+### Events
+
+| Event | Payload | Description |
+|------|---------|-------------|
+| `submit` | `{ originalEvent, data }` | Emitted after validation succeeds. |
+| `error` | `{ originalEvent, errors, data }` | Emitted after validation fails. |
+
+### Types
+
+```ts
+interface FormError {
+  name: string
+  message: string
+  id?: string
+}
+```
diff --git a/content/docs/2.components/19.form-field.md b/content/docs/2.components/19.form-field.md
new file mode 100644
index 0000000..110ffe8
--- /dev/null
+++ b/content/docs/2.components/19.form-field.md
@@ -0,0 +1,90 @@
+---
+title: FormField
+description: Wrap form controls with labels, descriptions, help text, and validation errors.
+category: form
+---
+
+::component-preview
+---
+name: FormFieldDemo
+---
+::
+
+## Installation
+
+```bash
+npx shadcn-vue@latest add field input
+npx shadcn-vue@latest add "https://ui.stackhacker.io/r/form-field.json"
+```
+
+## Usage
+
+```vue
+<script setup lang="ts">
+import { FormField } from '@/components/form-field'
+import { Input } from '@/components/ui/input'
+</script>
+
+<template>
+  <FormField
+    v-slot="field"
+    label="Email"
+    description="Use your work email."
+    error="Enter a valid email address."
+  >
+    <Input v-bind="field" type="email" />
+  </FormField>
+</template>
+```
+
+## With Form
+
+When used inside `Form`, the `name` prop matches the current form errors.
+
+```vue
+<Form :state="state" :validate="validate">
+  <FormField v-slot="field" label="Email" name="email">
+    <Input v-model="state.email" v-bind="field" />
+  </FormField>
+</Form>
+```
+
+## Slot Props
+
+`FormField` passes accessibility props to the default slot so the slotted control can receive a stable `id`, invalid state, and description/error references.
+
+| Prop | Description |
+|------|-------------|
+| `id` | Generated control id. |
+| `name` | Field name. |
+| `disabled` | Whether the parent form is disabled. |
+| `aria-invalid` | ARIA invalid state for the control. |
+| `aria-describedby` | Description, help, or error ids for the control. |
+
+## API Reference
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `string` | — | Field name used to match form errors. |
+| `errorPattern` | `RegExp` | — | Optional pattern for matching related error names. |
+| `label` | `string` | — | Field label. |
+| `description` | `string` | — | Supporting copy below the label. |
+| `help` | `string` | — | Help text shown when no error is present. |
+| `hint` | `string` | — | Text shown next to the label. |
+| `error` | `string \| boolean` | — | Explicit error. Overrides form context errors. |
+| `required` | `boolean` | `false` | Shows a required marker. |
+| `orientation` | `'vertical' \| 'horizontal' \| 'responsive'` | `'vertical'` | Field layout orientation. |
+| `class` | `string` | — | Additional CSS classes. |
+
+### Slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | Form control. Receives accessibility slot props. |
+| `label` | Custom label content. |
+| `description` | Custom description content. |
+| `help` | Custom help content. |
+| `hint` | Custom hint content. |
+| `error` | Custom error content. |
diff --git a/scripts/registry-verify.ts b/scripts/registry-verify.ts
index 69804de..08ffc6d 100644
--- a/scripts/registry-verify.ts
+++ b/scripts/registry-verify.ts
@@ -163,6 +163,14 @@ const expectedItems: Record<string, ExpectedRegistryItem> = {
     dependencies: [],
     registryDependencies: [],
   },
+  "form": {
+    dependencies: [],
+    registryDependencies: [],
+  },
+  "form-field": {
+    dependencies: [],
+    registryDependencies: ["field", stackhackerDependency("form")],
+  },
 };
 
 if (registryIndex) {