diff --git a/website/src/content/pages/components/field.mdx b/website/src/content/pages/components/field.mdx index cc8747cb50..45075f3998 100644 --- a/website/src/content/pages/components/field.mdx +++ b/website/src/content/pages/components/field.mdx @@ -27,6 +27,11 @@ The `Field` component provides contexts such as `invalid`, `disabled`, `required While most Ark UI components natively support these contexts, you can also use the `Field` component with standard HTML form elements. +> **Important:** Always render a `Field.Label` when using form controls inside a `Field`. The form control's +> `aria-labelledby` references the label's DOM element—omitting it creates a broken ARIA reference (WCAG 4.1.2 failure). +> If you don't want a visible label, visually hide it while keeping it in the DOM. Using `aria-label` alone is not +> sufficient because the Field integration overrides labelling via `aria-labelledby`. + ### Input This example shows how to use the `Field` component with a standard input field.