From cb5e7a486fa8f4ba119edee72f63527ebea37adb Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 19 Mar 2026 20:06:08 +0000 Subject: [PATCH 1/6] Initial plan From 39cf4c3d5e47bf68517fed6f3ccc0d0505ae0edf Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 19 Mar 2026 20:09:28 +0000 Subject: [PATCH 2/6] docs: document that Field.Label is required for accessible labelling with Checkbox and Switch Co-authored-by: anubra266 <30869823+anubra266@users.noreply.github.com> --- website/src/content/pages/components/checkbox.mdx | 5 +++++ website/src/content/pages/components/field.mdx | 5 +++++ website/src/content/pages/components/switch.mdx | 5 +++++ 3 files changed, 15 insertions(+) diff --git a/website/src/content/pages/components/checkbox.mdx b/website/src/content/pages/components/checkbox.mdx index 711c6d2c11..9099d6bce7 100644 --- a/website/src/content/pages/components/checkbox.mdx +++ b/website/src/content/pages/components/checkbox.mdx @@ -61,6 +61,11 @@ Use the `indeterminate` prop to create a checkbox in an indeterminate state (par The checkbox integrates smoothly with the `Field` component to handle form state, helper text, and error text for proper accessibility. +> **Important:** When using Checkbox inside a `Field`, always render a `Checkbox.Label` (or `Field.Label`). The hidden +> input's `aria-labelledby` references the label element, and omitting it creates a broken ARIA reference. If you don't +> want a visible label, apply a `sr-only` or `visually-hidden` class to keep it accessible but hidden. Using `aria-label` +> alone is not sufficient because the Field integration overrides labelling via `aria-labelledby`. + ### Form diff --git a/website/src/content/pages/components/field.mdx b/website/src/content/pages/components/field.mdx index cc8747cb50..f4ff2763dc 100644 --- a/website/src/content/pages/components/field.mdx +++ b/website/src/content/pages/components/field.mdx @@ -55,6 +55,11 @@ This example demonstrates how to integrate the `Field` component with a select d This example demonstrates how to integrate the `Field` and `Checkbox` components. +> **Important:** Always render a label element (e.g., `Checkbox.Label` or `Field.Label`) when using form controls inside +> a `Field`. The hidden input'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, apply a `sr-only` or `visually-hidden` class. Using +> `aria-label` alone is not sufficient because the Field integration overrides labelling via `aria-labelledby`. + ### Root Provider diff --git a/website/src/content/pages/components/switch.mdx b/website/src/content/pages/components/switch.mdx index bd5e71b64f..2ffd3c0bbf 100644 --- a/website/src/content/pages/components/switch.mdx +++ b/website/src/content/pages/components/switch.mdx @@ -43,6 +43,11 @@ can access the state and methods from outside the component. The `Field` component helps manage form-related state and accessibility attributes of a switch. It includes handling ARIA labels, helper text, and error text to ensure proper accessibility. +> **Important:** When using Switch inside a `Field`, always render a `Switch.Label` (or `Field.Label`). The hidden +> input's `aria-labelledby` references the label element, and omitting it creates a broken ARIA reference. If you don't +> want a visible label, apply a `sr-only` or `visually-hidden` class to keep it accessible but hidden. Using `aria-label` +> alone is not sufficient because the Field integration overrides labelling via `aria-labelledby`. + ### Context From 556f9f38eac9f01720980bcbdb29cfb24a6d7a32 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 19 Mar 2026 20:12:37 +0000 Subject: [PATCH 3/6] docs: fix Field label guidance to only recommend Field.Label Co-authored-by: anubra266 <30869823+anubra266@users.noreply.github.com> --- website/src/content/pages/components/checkbox.mdx | 8 ++++---- website/src/content/pages/components/field.mdx | 8 ++++---- website/src/content/pages/components/switch.mdx | 8 ++++---- 3 files changed, 12 insertions(+), 12 deletions(-) diff --git a/website/src/content/pages/components/checkbox.mdx b/website/src/content/pages/components/checkbox.mdx index 9099d6bce7..35c2b9daaa 100644 --- a/website/src/content/pages/components/checkbox.mdx +++ b/website/src/content/pages/components/checkbox.mdx @@ -61,10 +61,10 @@ Use the `indeterminate` prop to create a checkbox in an indeterminate state (par The checkbox integrates smoothly with the `Field` component to handle form state, helper text, and error text for proper accessibility. -> **Important:** When using Checkbox inside a `Field`, always render a `Checkbox.Label` (or `Field.Label`). The hidden -> input's `aria-labelledby` references the label element, and omitting it creates a broken ARIA reference. If you don't -> want a visible label, apply a `sr-only` or `visually-hidden` class to keep it accessible but hidden. Using `aria-label` -> alone is not sufficient because the Field integration overrides labelling via `aria-labelledby`. +> **Important:** When using Checkbox inside a `Field`, always render a `Field.Label`. The hidden input's +> `aria-labelledby` references the label element, and omitting it creates a broken ARIA reference. If you don't want a +> visible label, apply a `sr-only` or `visually-hidden` class to keep it accessible but hidden. Using `aria-label` alone +> is not sufficient because the Field integration overrides labelling via `aria-labelledby`. diff --git a/website/src/content/pages/components/field.mdx b/website/src/content/pages/components/field.mdx index f4ff2763dc..d0a1b0cc00 100644 --- a/website/src/content/pages/components/field.mdx +++ b/website/src/content/pages/components/field.mdx @@ -55,10 +55,10 @@ This example demonstrates how to integrate the `Field` component with a select d This example demonstrates how to integrate the `Field` and `Checkbox` components. -> **Important:** Always render a label element (e.g., `Checkbox.Label` or `Field.Label`) when using form controls inside -> a `Field`. The hidden input'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, apply a `sr-only` or `visually-hidden` class. Using -> `aria-label` alone is not sufficient because the Field integration overrides labelling via `aria-labelledby`. +> **Important:** Always render a `Field.Label` when using form controls inside a `Field`. The hidden input'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, apply a `sr-only` or `visually-hidden` class. Using `aria-label` alone is not +> sufficient because the Field integration overrides labelling via `aria-labelledby`. diff --git a/website/src/content/pages/components/switch.mdx b/website/src/content/pages/components/switch.mdx index 2ffd3c0bbf..8308440ecc 100644 --- a/website/src/content/pages/components/switch.mdx +++ b/website/src/content/pages/components/switch.mdx @@ -43,10 +43,10 @@ can access the state and methods from outside the component. The `Field` component helps manage form-related state and accessibility attributes of a switch. It includes handling ARIA labels, helper text, and error text to ensure proper accessibility. -> **Important:** When using Switch inside a `Field`, always render a `Switch.Label` (or `Field.Label`). The hidden -> input's `aria-labelledby` references the label element, and omitting it creates a broken ARIA reference. If you don't -> want a visible label, apply a `sr-only` or `visually-hidden` class to keep it accessible but hidden. Using `aria-label` -> alone is not sufficient because the Field integration overrides labelling via `aria-labelledby`. +> **Important:** When using Switch inside a `Field`, always render a `Field.Label`. The hidden input's +> `aria-labelledby` references the label element, and omitting it creates a broken ARIA reference. If you don't want a +> visible label, apply a `sr-only` or `visually-hidden` class to keep it accessible but hidden. Using `aria-label` alone +> is not sufficient because the Field integration overrides labelling via `aria-labelledby`. From 0fb3414e596fbdd86091546912e75a7c5e20e59a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 19 Mar 2026 20:35:47 +0000 Subject: [PATCH 4/6] docs: replace sr-only/visually-hidden with generic 'visually hide' wording Co-authored-by: anubra266 <30869823+anubra266@users.noreply.github.com> --- website/src/content/pages/components/checkbox.mdx | 2 +- website/src/content/pages/components/field.mdx | 2 +- website/src/content/pages/components/switch.mdx | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/website/src/content/pages/components/checkbox.mdx b/website/src/content/pages/components/checkbox.mdx index 35c2b9daaa..d1d42ad8c0 100644 --- a/website/src/content/pages/components/checkbox.mdx +++ b/website/src/content/pages/components/checkbox.mdx @@ -63,7 +63,7 @@ accessibility. > **Important:** When using Checkbox inside a `Field`, always render a `Field.Label`. The hidden input's > `aria-labelledby` references the label element, and omitting it creates a broken ARIA reference. If you don't want a -> visible label, apply a `sr-only` or `visually-hidden` class to keep it accessible but hidden. Using `aria-label` alone +> 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`. diff --git a/website/src/content/pages/components/field.mdx b/website/src/content/pages/components/field.mdx index d0a1b0cc00..20727d497d 100644 --- a/website/src/content/pages/components/field.mdx +++ b/website/src/content/pages/components/field.mdx @@ -57,7 +57,7 @@ This example demonstrates how to integrate the `Field` and `Checkbox` components > **Important:** Always render a `Field.Label` when using form controls inside a `Field`. The hidden input'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, apply a `sr-only` or `visually-hidden` class. Using `aria-label` alone is not +> 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`. diff --git a/website/src/content/pages/components/switch.mdx b/website/src/content/pages/components/switch.mdx index 8308440ecc..86e2d73091 100644 --- a/website/src/content/pages/components/switch.mdx +++ b/website/src/content/pages/components/switch.mdx @@ -45,7 +45,7 @@ ARIA labels, helper text, and error text to ensure proper accessibility. > **Important:** When using Switch inside a `Field`, always render a `Field.Label`. The hidden input's > `aria-labelledby` references the label element, and omitting it creates a broken ARIA reference. If you don't want a -> visible label, apply a `sr-only` or `visually-hidden` class to keep it accessible but hidden. Using `aria-label` alone +> 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`. From 6bb0f4c3ac2d32f06cb452a87886663c8fd83f8a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 19 Mar 2026 20:54:43 +0000 Subject: [PATCH 5/6] docs: move Field.Label callout to general Examples section in field.mdx Co-authored-by: anubra266 <30869823+anubra266@users.noreply.github.com> --- website/src/content/pages/components/field.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/website/src/content/pages/components/field.mdx b/website/src/content/pages/components/field.mdx index 20727d497d..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. @@ -55,11 +60,6 @@ This example demonstrates how to integrate the `Field` component with a select d This example demonstrates how to integrate the `Field` and `Checkbox` components. -> **Important:** Always render a `Field.Label` when using form controls inside a `Field`. The hidden input'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`. - ### Root Provider From bc1f97e65e43a68740fcdd95156e0da7af4cdc35 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 20 Mar 2026 20:56:03 +0000 Subject: [PATCH 6/6] docs: remove duplicate Field.Label callout from checkbox and switch docs Co-authored-by: anubra266 <30869823+anubra266@users.noreply.github.com> Agent-Logs-Url: https://github.com/chakra-ui/ark/sessions/863e8b0c-9f0c-4e59-88fc-d6865ae61fa3 --- website/src/content/pages/components/checkbox.mdx | 5 ----- website/src/content/pages/components/switch.mdx | 5 ----- 2 files changed, 10 deletions(-) diff --git a/website/src/content/pages/components/checkbox.mdx b/website/src/content/pages/components/checkbox.mdx index d1d42ad8c0..711c6d2c11 100644 --- a/website/src/content/pages/components/checkbox.mdx +++ b/website/src/content/pages/components/checkbox.mdx @@ -61,11 +61,6 @@ Use the `indeterminate` prop to create a checkbox in an indeterminate state (par The checkbox integrates smoothly with the `Field` component to handle form state, helper text, and error text for proper accessibility. -> **Important:** When using Checkbox inside a `Field`, always render a `Field.Label`. The hidden input's -> `aria-labelledby` references the label element, and omitting it creates a broken ARIA reference. 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`. - ### Form diff --git a/website/src/content/pages/components/switch.mdx b/website/src/content/pages/components/switch.mdx index 86e2d73091..bd5e71b64f 100644 --- a/website/src/content/pages/components/switch.mdx +++ b/website/src/content/pages/components/switch.mdx @@ -43,11 +43,6 @@ can access the state and methods from outside the component. The `Field` component helps manage form-related state and accessibility attributes of a switch. It includes handling ARIA labels, helper text, and error text to ensure proper accessibility. -> **Important:** When using Switch inside a `Field`, always render a `Field.Label`. The hidden input's -> `aria-labelledby` references the label element, and omitting it creates a broken ARIA reference. 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`. - ### Context