@aurodesignsystem-dev/auro-formkit 0.0.0-pr1611.0 → 0.0.0-pr1613.0

package/components/checkbox/demo/accessibility.md

@@ -8,12 +8,13 @@ For keyboard interaction details, see the <auro-hyperlink href="keyboard-behavio
 
 <auro-header level="2" id="ariaRolesAndAttributes">ARIA Roles and Attributes</auro-header>
 <auro-header level="3" id="checkboxGroup">Checkbox Group</auro-header>
-The `<auro-checkbox-group>` element uses a `<fieldset>` with a `<legend>` internally, providing native grouping semantics:
+The `<auro-checkbox-group>` element uses a `<fieldset>` with a `<legend>` internally, providing native grouping semantics. These attributes are applied to that shadow-DOM `<fieldset>`, **not** to the `<auro-checkbox-group>` host element:
 
 | Attribute | Value | Description |
 |---|---|---|
-| `role` | `group` (implicit via `fieldset`) | Groups related checkboxes together. |
-| `aria-invalid` | `true` / `false` | Reflects whether the group is currently in an invalid state. |
+| `role` | `group` (implicit via `fieldset`) | Groups related checkboxes together. There is no ARIA `checkboxgroup` role, so the `<fieldset>`'s implicit `group` role is used as-is. |
+| `aria-invalid` | `true` | Present only while the group is in an invalid state. The attribute is **omitted entirely** when the group is valid — it is never set to `false`. |
+| `aria-describedby` | id reference | Points at the `id` of the group's help-text/error element, so assistive technology can associate the message with the group on demand rather than relying only on the one-time live-region announcement. |
 
 <auro-header level="3" id="checkboxElement">Checkbox</auro-header>
 Each `<auro-checkbox>` renders a native `<input type="checkbox">` inside its shadow DOM:
@@ -23,12 +24,22 @@ Each `<auro-checkbox>` renders a native `<input type="checkbox">` inside its sha
 | `type` | `checkbox` | Native checkbox input type. |
 | `aria-checked` | `true` / `false` | Reflects the checked state of the checkbox. |
 | `aria-disabled` | `true` / `false` | Indicates whether the checkbox is disabled. |
+| `aria-invalid` | `true` | Mirrored onto each checkbox from the group while the group is invalid, and removed when it becomes valid. Omitted rather than set to `false`. |
+
+<auro-header level="4" id="invalidStatePlacement">Why the invalid state appears twice</auro-header>
+While the group is invalid, `aria-invalid` is set on both the `<fieldset>` and every individual `<auro-checkbox>`. This is intentional: some assistive-technology and browser combinations announce a container's invalid state only when focus first enters the group, so mirroring the state onto each checkbox keeps it conveyed as focus moves through the options.
+
+The `checkbox` role is in `aria-invalid`'s supported-role list in every ARIA version, so the per-checkbox placement is unambiguous. The group-level placement is worth one note: `aria-invalid` is a global attribute in ARIA 1.1, applicable to any role including `group`, but ARIA 1.2 deprecates that global use in favor of a supported-role list that does not include `group`. Keeping it on the `<fieldset>` is a deliberate choice — it is not a *prohibited* attribute for `group`, current axe-core resolves it as global and reports no violation, and it gives the group a real invalid signal that would otherwise be lost. This is covered by an automated axe assertion in the component's test suite so that a future change in tooling surfaces here rather than in a consumer's audit.
+
+<auro-header level="4" id="attributePlacementNote">Attribute placement</auro-header>
+`aria-invalid` is applied to the internal `<fieldset>`, not to the `<auro-checkbox-group>` host element. Do not write CSS selectors or test assertions against `auro-checkbox-group[aria-invalid]`; target the `part="checkbox-group"` fieldset or read the `validity` property instead.
 
 <auro-header level="2" id="screenReaderAnnouncements">Screen Reader Announcements</auro-header>
 - **Focus** — When focus moves to a checkbox, the screen reader announces the checkbox label, its checked/unchecked state, and role ("checkbox").
 - **State change** — Toggling the checkbox announces the new state ("checked" or "unchecked").
 - **Group context** — The legend text provides group context when navigating between groups.
-- **Error** — When validation fails, the error message is announced to screen reader users.
+- **Error** — When validation fails, the error message is announced immediately via the help text's `role="alert"` live region, and stays discoverable afterward through the group's `aria-describedby` association.
+- **Invalid state** — While the group is invalid, entering it or moving between its checkboxes conveys the invalid state.
 
 <auro-header level="2" id="accessibleLabels">Accessible Labels</auro-header>
 - The `legend` slot content provides the accessible group label via the native `<legend>` element.

package/components/checkbox/demo/api.md

@@ -46,9 +46,10 @@ The `auro-checkbox-group` element is a wrapper for `auro-checkbox` elements..
 
 ## CSS Shadow Parts
 
-| Part       | Description                                      |
-|------------|--------------------------------------------------|
-| `helpText` | Apply css to the help text element that displays helper or error messages. |
+| Part             | Description                                      |
+|------------------|--------------------------------------------------|
+| `checkbox-group` | Apply css to the fieldset element in the shadow DOM |
+| `helpText`       | Apply css to the help text element that displays helper or error messages. |
 
 # auro-checkbox
 

package/components/checkbox/demo/customize.md

@@ -160,7 +160,7 @@
 <auro-header level="3" id="cssParts">CSS Shadow Parts</auro-header>
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/customize/css-parts.md) -->
 <!-- The below content is automatically added from ./../docs/partials/customize/css-parts.md -->
-<p>CSS Shadow Parts allow you to style elements inside a web component's shadow DOM using the <code>::part()</code> pseudo-element. The following parts are exposed by <code>&lt;auro-checkbox&gt;</code>.</p>
+<p>CSS Shadow Parts allow you to style elements inside a web component's shadow DOM using the <code>::part()</code> pseudo-element. The following parts are exposed by <code>&lt;auro-checkbox-group&gt;</code> and <code>&lt;auro-checkbox&gt;</code>.</p>
 <table class="auro_table">
 <thead>
 <tr>
@@ -169,6 +169,7 @@
 </tr>
 </thead>
 <tbody>
+<tr><td><code>checkbox-group</code></td><td>The fieldset element in the <code>&lt;auro-checkbox-group&gt;</code> shadow DOM. Use this to style the group container, and to query the element that carries the group's <code>aria-invalid</code> state.</td></tr>
 <tr><td><code>checkbox</code></td><td>The checkbox container element.</td></tr>
 <tr><td><code>checkbox-input</code></td><td>The checkbox input element.</td></tr>
 <tr><td><code>checkbox-label</code></td><td>The checkbox label element.</td></tr>

package/components/checkbox/demo/customize.min.js

@@ -1046,6 +1046,48 @@ class AuroDependencyVersioning {
   }
 }
 
+/**
+ * Generates a v4 UUID with a three-tier fallback for insecure contexts.
+ *
+ * Tier 1 (secure contexts): crypto.randomUUID() — native, fully random.
+ * Tier 2 (insecure contexts): crypto.getRandomValues() — available on all
+ *   modern browsers regardless of secure-context status.
+ * Tier 3 (last resort, no crypto API): new Date().getTime() — lower entropy,
+ *   but sufficient for element IDs where collision risk is negligible.
+ *
+ * See: https://w3c.github.io/webcrypto/#dom-crypto-randomuuid (secure-context restriction)
+ */
+function generateUUID() {
+  let uuid;
+
+  if (
+    typeof crypto !== "undefined" &&
+    typeof crypto.randomUUID === "function"
+  ) {
+    uuid = crypto.randomUUID();
+  } else if (
+    typeof crypto !== "undefined" &&
+    typeof crypto.getRandomValues === "function"
+  ) {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = Array.from(bytes).map((b) => b.toString(16).padStart(2, "0"));
+    uuid = `${hex.slice(0, 4).join("")}-${hex.slice(4, 6).join("")}-${hex.slice(6, 8).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10).join("")}`;
+  } else {
+    let d = new Date().getTime();
+    uuid = "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+      const r = (d % 16) | 0;
+      d = (d - r) / 16 || new Date().getTime();
+      return (c === "x" ? r : (r & 0x3) | 0x8).toString(16);
+    });
+  }
+
+  // CSS selectors require IDs starting with a letter; replace a leading digit with 'a'.
+  return /^[0-9]/.test(uuid) ? `a${uuid.slice(1)}` : uuid;
+}
+
 var styleCss$1 = i$5`:host{display:block;padding-bottom:var(--ds-size-150, 0.75rem)}.displayFlex legend+slot{display:flex;white-space:nowrap}fieldset{all:unset}legend{margin-bottom:var(--ds-size-150, 0.75rem)}[auro-helptext]{margin-top:var(--ds-size-150, 0.75rem)}`;
 
 var colorCss$1 = i$5`:host{color:var(--ds-auro-checkbox-group-text-color)}:host([disabled]){--ds-auro-checkbox-group-text-color: var(--ds-basic-color-texticon-disabled, #d0d0d0)}:host([onDark]),:host([appearance=inverse]){--ds-auro-checkbox-group-text-color: var(--ds-basic-color-texticon-inverse, #ffffff)}:host([onDark][disabled]),:host([appearance=inverse][disabled]){--ds-auro-checkbox-group-text-color: var(--ds-basic-color-texticon-inverse-disabled, #7e8894)}`;
@@ -1284,7 +1326,7 @@ class AuroHelpText extends i$2 {
   }
 }
 
-var formkitVersion = '202609050113';
+var formkitVersion = '202609082147';
 
 // Copyright (c) 2026 Alaska Airlines. All rights reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.
@@ -1294,6 +1336,7 @@ var formkitVersion = '202609050113';
  * The `auro-checkbox-group` element is a wrapper for `auro-checkbox` elements.
  * @customElement auro-checkbox-group
  *
+ * @csspart checkbox-group - Apply css to the fieldset element in the shadow DOM
  * @csspart helpText - Apply css to the help text element that displays helper or error messages.
  *
  * @slot legend - Allows for the legend to be overridden.
@@ -1361,6 +1404,11 @@ class AuroCheckboxGroup extends i$2 {
      * @private
      */
     this.helpTextTag = versioning.generateTag('auro-formkit-checkbox-helptext', formkitVersion, AuroHelpText);
+
+    /**
+     * @private
+     */
+    this.uniqueId = generateUUID();
   }
 
   static get styles() {
@@ -1612,6 +1660,47 @@ class AuroCheckboxGroup extends i$2 {
     this.handlePreselectedItems();
 
     this.validate();
+    this.syncCheckboxValidity();
+  }
+
+  /**
+   * Whether the group is currently in an invalid state.
+   * `validity` — not `error` — is the authoritative source: `validate()` resolves the
+   * `error` attribute to `validity = 'customError'`, so `error` is already covered here.
+   * Single definition of "invalid" for the whole component, consumed by `render()` and
+   * `syncCheckboxValidity()` so the fieldset and its children can never disagree.
+   * @private
+   * @returns {boolean}
+   */
+  get isInvalid() {
+    return Boolean(this.validity && this.validity !== 'valid');
+  }
+
+  /**
+   * Method for mirroring the group's invalid state onto each checkbox.
+   * Has to be re-applied from `handleItems()` as well, because a slot change can happen
+   * without `validity` itself changing — a checkbox slotted into an already-invalid
+   * group would otherwise be missed.
+   * @private
+   * @returns {void}
+   */
+  syncCheckboxValidity() {
+    const invalid = this.isInvalid;
+
+    this.checkboxes.forEach((el) => {
+      if (invalid) {
+        el.setAttribute('error', true);
+        el.setAttribute('aria-invalid', 'true');
+      } else {
+        // Group state is authoritative: an `error` set directly on an individual
+        // checkbox by a consumer is cleared here, and because this method also runs
+        // from `handleItems()` that now happens on every slot change, not just on a
+        // validity change. Matches auro-radio-group. See docs/post-mortem/1636704.md,
+        // "Breaking Change Assessment", for why this is not treated as a breaker.
+        el.removeAttribute('error');
+        el.removeAttribute('aria-invalid');
+      }
+    });
   }
 
   /**
@@ -1643,13 +1732,7 @@ class AuroCheckboxGroup extends i$2 {
     }
 
     if (changedProperties.has('validity')) {
-      this.checkboxes.forEach((el) => {
-        if (this.validity && this.validity !== 'valid') {
-          el.setAttribute('error', true);
-        } else {
-          el.removeAttribute('error');
-        }
-      });
+      this.syncCheckboxValidity();
     }
 
     if (changedProperties.has('required')) {
@@ -1673,12 +1756,6 @@ class AuroCheckboxGroup extends i$2 {
     }
 
     if (changedProperties.has('error')) {
-      if (this.error) {
-        this.setAttribute('aria-invalid', true);
-      } else {
-        this.removeAttribute('aria-invalid');
-      }
-
       this.validate(true);
     }
   }
@@ -1697,7 +1774,12 @@ class AuroCheckboxGroup extends i$2 {
     };
 
     return u`
-      <fieldset class="${e(groupClasses)}">
+      <fieldset
+        class="${e(groupClasses)}"
+        part="checkbox-group"
+        aria-invalid="${o$1(this.isInvalid ? 'true' : undefined)}"
+        aria-describedby="${this.uniqueId}"
+      >
         <legend>
           <slot name="legend"></slot>
           ${this.required ? undefined : u`<slot name="optionalLabel"> (optional)</slot>`}
@@ -1705,13 +1787,13 @@ class AuroCheckboxGroup extends i$2 {
         <slot @slotchange=${this.handleItems}></slot>
       </fieldset>
 
-      ${!this.validity || this.validity === undefined || this.validity === 'valid'
+      ${!this.isInvalid
         ? u`
-          <${this.helpTextTag} part="helpText" appearance="${this.onDark ? 'inverse' : this.appearance}">
+          <${this.helpTextTag} id="${this.uniqueId}" part="helpText" appearance="${this.onDark ? 'inverse' : this.appearance}">
             <slot name="helpText"></slot>
           </${this.helpTextTag}>`
         : u`
-          <${this.helpTextTag} error appearance="${this.onDark ? 'inverse' : this.appearance}"" role="alert" aria-live="assertive" part="helpText">
+          <${this.helpTextTag} id="${this.uniqueId}" error appearance="${this.onDark ? 'inverse' : this.appearance}" role="alert" aria-live="assertive" part="helpText">
             ${this.errorMessage}
           </${this.helpTextTag}>`
       }

package/components/checkbox/demo/getting-started.min.js

@@ -1046,6 +1046,48 @@ class AuroDependencyVersioning {
   }
 }
 
+/**
+ * Generates a v4 UUID with a three-tier fallback for insecure contexts.
+ *
+ * Tier 1 (secure contexts): crypto.randomUUID() — native, fully random.
+ * Tier 2 (insecure contexts): crypto.getRandomValues() — available on all
+ *   modern browsers regardless of secure-context status.
+ * Tier 3 (last resort, no crypto API): new Date().getTime() — lower entropy,
+ *   but sufficient for element IDs where collision risk is negligible.
+ *
+ * See: https://w3c.github.io/webcrypto/#dom-crypto-randomuuid (secure-context restriction)
+ */
+function generateUUID() {
+  let uuid;
+
+  if (
+    typeof crypto !== "undefined" &&
+    typeof crypto.randomUUID === "function"
+  ) {
+    uuid = crypto.randomUUID();
+  } else if (
+    typeof crypto !== "undefined" &&
+    typeof crypto.getRandomValues === "function"
+  ) {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = Array.from(bytes).map((b) => b.toString(16).padStart(2, "0"));
+    uuid = `${hex.slice(0, 4).join("")}-${hex.slice(4, 6).join("")}-${hex.slice(6, 8).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10).join("")}`;
+  } else {
+    let d = new Date().getTime();
+    uuid = "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+      const r = (d % 16) | 0;
+      d = (d - r) / 16 || new Date().getTime();
+      return (c === "x" ? r : (r & 0x3) | 0x8).toString(16);
+    });
+  }
+
+  // CSS selectors require IDs starting with a letter; replace a leading digit with 'a'.
+  return /^[0-9]/.test(uuid) ? `a${uuid.slice(1)}` : uuid;
+}
+
 var styleCss$1 = i$5`:host{display:block;padding-bottom:var(--ds-size-150, 0.75rem)}.displayFlex legend+slot{display:flex;white-space:nowrap}fieldset{all:unset}legend{margin-bottom:var(--ds-size-150, 0.75rem)}[auro-helptext]{margin-top:var(--ds-size-150, 0.75rem)}`;
 
 var colorCss$1 = i$5`:host{color:var(--ds-auro-checkbox-group-text-color)}:host([disabled]){--ds-auro-checkbox-group-text-color: var(--ds-basic-color-texticon-disabled, #d0d0d0)}:host([onDark]),:host([appearance=inverse]){--ds-auro-checkbox-group-text-color: var(--ds-basic-color-texticon-inverse, #ffffff)}:host([onDark][disabled]),:host([appearance=inverse][disabled]){--ds-auro-checkbox-group-text-color: var(--ds-basic-color-texticon-inverse-disabled, #7e8894)}`;
@@ -1284,7 +1326,7 @@ class AuroHelpText extends i$2 {
   }
 }
 
-var formkitVersion = '202609050113';
+var formkitVersion = '202609082147';
 
 // Copyright (c) 2026 Alaska Airlines. All rights reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.
@@ -1294,6 +1336,7 @@ var formkitVersion = '202609050113';
  * The `auro-checkbox-group` element is a wrapper for `auro-checkbox` elements.
  * @customElement auro-checkbox-group
  *
+ * @csspart checkbox-group - Apply css to the fieldset element in the shadow DOM
  * @csspart helpText - Apply css to the help text element that displays helper or error messages.
  *
  * @slot legend - Allows for the legend to be overridden.
@@ -1361,6 +1404,11 @@ class AuroCheckboxGroup extends i$2 {
      * @private
      */
     this.helpTextTag = versioning.generateTag('auro-formkit-checkbox-helptext', formkitVersion, AuroHelpText);
+
+    /**
+     * @private
+     */
+    this.uniqueId = generateUUID();
   }
 
   static get styles() {
@@ -1612,6 +1660,47 @@ class AuroCheckboxGroup extends i$2 {
     this.handlePreselectedItems();
 
     this.validate();
+    this.syncCheckboxValidity();
+  }
+
+  /**
+   * Whether the group is currently in an invalid state.
+   * `validity` — not `error` — is the authoritative source: `validate()` resolves the
+   * `error` attribute to `validity = 'customError'`, so `error` is already covered here.
+   * Single definition of "invalid" for the whole component, consumed by `render()` and
+   * `syncCheckboxValidity()` so the fieldset and its children can never disagree.
+   * @private
+   * @returns {boolean}
+   */
+  get isInvalid() {
+    return Boolean(this.validity && this.validity !== 'valid');
+  }
+
+  /**
+   * Method for mirroring the group's invalid state onto each checkbox.
+   * Has to be re-applied from `handleItems()` as well, because a slot change can happen
+   * without `validity` itself changing — a checkbox slotted into an already-invalid
+   * group would otherwise be missed.
+   * @private
+   * @returns {void}
+   */
+  syncCheckboxValidity() {
+    const invalid = this.isInvalid;
+
+    this.checkboxes.forEach((el) => {
+      if (invalid) {
+        el.setAttribute('error', true);
+        el.setAttribute('aria-invalid', 'true');
+      } else {
+        // Group state is authoritative: an `error` set directly on an individual
+        // checkbox by a consumer is cleared here, and because this method also runs
+        // from `handleItems()` that now happens on every slot change, not just on a
+        // validity change. Matches auro-radio-group. See docs/post-mortem/1636704.md,
+        // "Breaking Change Assessment", for why this is not treated as a breaker.
+        el.removeAttribute('error');
+        el.removeAttribute('aria-invalid');
+      }
+    });
   }
 
   /**
@@ -1643,13 +1732,7 @@ class AuroCheckboxGroup extends i$2 {
     }
 
     if (changedProperties.has('validity')) {
-      this.checkboxes.forEach((el) => {
-        if (this.validity && this.validity !== 'valid') {
-          el.setAttribute('error', true);
-        } else {
-          el.removeAttribute('error');
-        }
-      });
+      this.syncCheckboxValidity();
     }
 
     if (changedProperties.has('required')) {
@@ -1673,12 +1756,6 @@ class AuroCheckboxGroup extends i$2 {
     }
 
     if (changedProperties.has('error')) {
-      if (this.error) {
-        this.setAttribute('aria-invalid', true);
-      } else {
-        this.removeAttribute('aria-invalid');
-      }
-
       this.validate(true);
     }
   }
@@ -1697,7 +1774,12 @@ class AuroCheckboxGroup extends i$2 {
     };
 
     return u`
-      <fieldset class="${e(groupClasses)}">
+      <fieldset
+        class="${e(groupClasses)}"
+        part="checkbox-group"
+        aria-invalid="${o$1(this.isInvalid ? 'true' : undefined)}"
+        aria-describedby="${this.uniqueId}"
+      >
         <legend>
           <slot name="legend"></slot>
           ${this.required ? undefined : u`<slot name="optionalLabel"> (optional)</slot>`}
@@ -1705,13 +1787,13 @@ class AuroCheckboxGroup extends i$2 {
         <slot @slotchange=${this.handleItems}></slot>
       </fieldset>
 
-      ${!this.validity || this.validity === undefined || this.validity === 'valid'
+      ${!this.isInvalid
         ? u`
-          <${this.helpTextTag} part="helpText" appearance="${this.onDark ? 'inverse' : this.appearance}">
+          <${this.helpTextTag} id="${this.uniqueId}" part="helpText" appearance="${this.onDark ? 'inverse' : this.appearance}">
             <slot name="helpText"></slot>
           </${this.helpTextTag}>`
         : u`
-          <${this.helpTextTag} error appearance="${this.onDark ? 'inverse' : this.appearance}"" role="alert" aria-live="assertive" part="helpText">
+          <${this.helpTextTag} id="${this.uniqueId}" error appearance="${this.onDark ? 'inverse' : this.appearance}" role="alert" aria-live="assertive" part="helpText">
             ${this.errorMessage}
           </${this.helpTextTag}>`
       }

package/components/checkbox/demo/index.min.js

@@ -1046,6 +1046,48 @@ class AuroDependencyVersioning {
   }
 }
 
+/**
+ * Generates a v4 UUID with a three-tier fallback for insecure contexts.
+ *
+ * Tier 1 (secure contexts): crypto.randomUUID() — native, fully random.
+ * Tier 2 (insecure contexts): crypto.getRandomValues() — available on all
+ *   modern browsers regardless of secure-context status.
+ * Tier 3 (last resort, no crypto API): new Date().getTime() — lower entropy,
+ *   but sufficient for element IDs where collision risk is negligible.
+ *
+ * See: https://w3c.github.io/webcrypto/#dom-crypto-randomuuid (secure-context restriction)
+ */
+function generateUUID() {
+  let uuid;
+
+  if (
+    typeof crypto !== "undefined" &&
+    typeof crypto.randomUUID === "function"
+  ) {
+    uuid = crypto.randomUUID();
+  } else if (
+    typeof crypto !== "undefined" &&
+    typeof crypto.getRandomValues === "function"
+  ) {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = Array.from(bytes).map((b) => b.toString(16).padStart(2, "0"));
+    uuid = `${hex.slice(0, 4).join("")}-${hex.slice(4, 6).join("")}-${hex.slice(6, 8).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10).join("")}`;
+  } else {
+    let d = new Date().getTime();
+    uuid = "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+      const r = (d % 16) | 0;
+      d = (d - r) / 16 || new Date().getTime();
+      return (c === "x" ? r : (r & 0x3) | 0x8).toString(16);
+    });
+  }
+
+  // CSS selectors require IDs starting with a letter; replace a leading digit with 'a'.
+  return /^[0-9]/.test(uuid) ? `a${uuid.slice(1)}` : uuid;
+}
+
 var styleCss$1 = i$5`:host{display:block;padding-bottom:var(--ds-size-150, 0.75rem)}.displayFlex legend+slot{display:flex;white-space:nowrap}fieldset{all:unset}legend{margin-bottom:var(--ds-size-150, 0.75rem)}[auro-helptext]{margin-top:var(--ds-size-150, 0.75rem)}`;
 
 var colorCss$1 = i$5`:host{color:var(--ds-auro-checkbox-group-text-color)}:host([disabled]){--ds-auro-checkbox-group-text-color: var(--ds-basic-color-texticon-disabled, #d0d0d0)}:host([onDark]),:host([appearance=inverse]){--ds-auro-checkbox-group-text-color: var(--ds-basic-color-texticon-inverse, #ffffff)}:host([onDark][disabled]),:host([appearance=inverse][disabled]){--ds-auro-checkbox-group-text-color: var(--ds-basic-color-texticon-inverse-disabled, #7e8894)}`;
@@ -1284,7 +1326,7 @@ class AuroHelpText extends i$2 {
   }
 }
 
-var formkitVersion = '202609050113';
+var formkitVersion = '202609082147';
 
 // Copyright (c) 2026 Alaska Airlines. All rights reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.
@@ -1294,6 +1336,7 @@ var formkitVersion = '202609050113';
  * The `auro-checkbox-group` element is a wrapper for `auro-checkbox` elements.
  * @customElement auro-checkbox-group
  *
+ * @csspart checkbox-group - Apply css to the fieldset element in the shadow DOM
  * @csspart helpText - Apply css to the help text element that displays helper or error messages.
  *
  * @slot legend - Allows for the legend to be overridden.
@@ -1361,6 +1404,11 @@ class AuroCheckboxGroup extends i$2 {
      * @private
      */
     this.helpTextTag = versioning.generateTag('auro-formkit-checkbox-helptext', formkitVersion, AuroHelpText);
+
+    /**
+     * @private
+     */
+    this.uniqueId = generateUUID();
   }
 
   static get styles() {
@@ -1612,6 +1660,47 @@ class AuroCheckboxGroup extends i$2 {
     this.handlePreselectedItems();
 
     this.validate();
+    this.syncCheckboxValidity();
+  }
+
+  /**
+   * Whether the group is currently in an invalid state.
+   * `validity` — not `error` — is the authoritative source: `validate()` resolves the
+   * `error` attribute to `validity = 'customError'`, so `error` is already covered here.
+   * Single definition of "invalid" for the whole component, consumed by `render()` and
+   * `syncCheckboxValidity()` so the fieldset and its children can never disagree.
+   * @private
+   * @returns {boolean}
+   */
+  get isInvalid() {
+    return Boolean(this.validity && this.validity !== 'valid');
+  }
+
+  /**
+   * Method for mirroring the group's invalid state onto each checkbox.
+   * Has to be re-applied from `handleItems()` as well, because a slot change can happen
+   * without `validity` itself changing — a checkbox slotted into an already-invalid
+   * group would otherwise be missed.
+   * @private
+   * @returns {void}
+   */
+  syncCheckboxValidity() {
+    const invalid = this.isInvalid;
+
+    this.checkboxes.forEach((el) => {
+      if (invalid) {
+        el.setAttribute('error', true);
+        el.setAttribute('aria-invalid', 'true');
+      } else {
+        // Group state is authoritative: an `error` set directly on an individual
+        // checkbox by a consumer is cleared here, and because this method also runs
+        // from `handleItems()` that now happens on every slot change, not just on a
+        // validity change. Matches auro-radio-group. See docs/post-mortem/1636704.md,
+        // "Breaking Change Assessment", for why this is not treated as a breaker.
+        el.removeAttribute('error');
+        el.removeAttribute('aria-invalid');
+      }
+    });
   }
 
   /**
@@ -1643,13 +1732,7 @@ class AuroCheckboxGroup extends i$2 {
     }
 
     if (changedProperties.has('validity')) {
-      this.checkboxes.forEach((el) => {
-        if (this.validity && this.validity !== 'valid') {
-          el.setAttribute('error', true);
-        } else {
-          el.removeAttribute('error');
-        }
-      });
+      this.syncCheckboxValidity();
     }
 
     if (changedProperties.has('required')) {
@@ -1673,12 +1756,6 @@ class AuroCheckboxGroup extends i$2 {
     }
 
     if (changedProperties.has('error')) {
-      if (this.error) {
-        this.setAttribute('aria-invalid', true);
-      } else {
-        this.removeAttribute('aria-invalid');
-      }
-
       this.validate(true);
     }
   }
@@ -1697,7 +1774,12 @@ class AuroCheckboxGroup extends i$2 {
     };
 
     return u`
-      <fieldset class="${e(groupClasses)}">
+      <fieldset
+        class="${e(groupClasses)}"
+        part="checkbox-group"
+        aria-invalid="${o$1(this.isInvalid ? 'true' : undefined)}"
+        aria-describedby="${this.uniqueId}"
+      >
         <legend>
           <slot name="legend"></slot>
           ${this.required ? undefined : u`<slot name="optionalLabel"> (optional)</slot>`}
@@ -1705,13 +1787,13 @@ class AuroCheckboxGroup extends i$2 {
         <slot @slotchange=${this.handleItems}></slot>
       </fieldset>
 
-      ${!this.validity || this.validity === undefined || this.validity === 'valid'
+      ${!this.isInvalid
         ? u`
-          <${this.helpTextTag} part="helpText" appearance="${this.onDark ? 'inverse' : this.appearance}">
+          <${this.helpTextTag} id="${this.uniqueId}" part="helpText" appearance="${this.onDark ? 'inverse' : this.appearance}">
             <slot name="helpText"></slot>
           </${this.helpTextTag}>`
         : u`
-          <${this.helpTextTag} error appearance="${this.onDark ? 'inverse' : this.appearance}"" role="alert" aria-live="assertive" part="helpText">
+          <${this.helpTextTag} id="${this.uniqueId}" error appearance="${this.onDark ? 'inverse' : this.appearance}" role="alert" aria-live="assertive" part="helpText">
             ${this.errorMessage}
           </${this.helpTextTag}>`
       }

package/components/checkbox/dist/auro-checkbox-group.d.ts

@@ -2,6 +2,7 @@
  * The `auro-checkbox-group` element is a wrapper for `auro-checkbox` elements.
  * @customElement auro-checkbox-group
  *
+ * @csspart checkbox-group - Apply css to the fieldset element in the shadow DOM
  * @csspart helpText - Apply css to the help text element that displays helper or error messages.
  *
  * @slot legend - Allows for the legend to be overridden.
@@ -141,6 +142,10 @@ export class AuroCheckboxGroup extends LitElement {
      * @private
      */
     private helpTextTag;
+    /**
+     * @private
+     */
+    private uniqueId;
     /**
      * Helper method to handle checkbox value changing.
      * @private
@@ -164,6 +169,25 @@ export class AuroCheckboxGroup extends LitElement {
      */
     private handleItems;
     checkboxes: Element[] | undefined;
+    /**
+     * Whether the group is currently in an invalid state.
+     * `validity` — not `error` — is the authoritative source: `validate()` resolves the
+     * `error` attribute to `validity = 'customError'`, so `error` is already covered here.
+     * Single definition of "invalid" for the whole component, consumed by `render()` and
+     * `syncCheckboxValidity()` so the fieldset and its children can never disagree.
+     * @private
+     * @returns {boolean}
+     */
+    private get isInvalid();
+    /**
+     * Method for mirroring the group's invalid state onto each checkbox.
+     * Has to be re-applied from `handleItems()` as well, because a slot change can happen
+     * without `validity` itself changing — a checkbox slotted into an already-invalid
+     * group would otherwise be missed.
+     * @private
+     * @returns {void}
+     */
+    private syncCheckboxValidity;
     /**
      * Resets component to initial state.
      * @returns {void}