From bbda15a9b360f3c36f5d2ca6de4d0c01156f978b Mon Sep 17 00:00:00 2001
From: Philipp Reinking <philipp@deck9.co>
Date: Sat, 17 Oct 2026 19:30:36 +0200
Subject: [PATCH 1/4] fix(Label): readable help text with an id for
 aria-describedby (BITS-289)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 src/Label/Label.stories.ts | 14 ++++++++++++++
 src/Label/Label.vue        |  3 ++-
 tests/Label.spec.ts        | 39 ++++++++++++++++++++++++++++++++++++++
 3 files changed, 55 insertions(+), 1 deletion(-)
 create mode 100644 tests/Label.spec.ts

diff --git a/src/Label/Label.stories.ts b/src/Label/Label.stories.ts
index ee24fa1..d55e330 100644
--- a/src/Label/Label.stories.ts
+++ b/src/Label/Label.stories.ts
@@ -1,4 +1,5 @@
 import D9Label from "./Label.vue";
+import D9Input from "../Input/Input.vue";
 
 export default {
   title: "Forms/Label",
@@ -21,3 +22,16 @@ export const WithDescription = (args: Record<string, unknown>) => ({
   template:
     '<D9Label id="name" label="Your name" description="Please use your full name." />',
 });
+
+export const LinkedToField = (args: Record<string, unknown>) => ({
+  components: { D9Label, D9Input },
+  setup() {
+    return { args };
+  },
+  // The help text gets the id "<id>-help": point the field at it with aria-describedby.
+  template: `
+    <div>
+      <D9Label id="name" label="Your name" description="Please use your full name." />
+      <D9Input id="name" aria-describedby="name-help" />
+    </div>`,
+});
diff --git a/src/Label/Label.vue b/src/Label/Label.vue
index ebece5a..b03886e 100644
--- a/src/Label/Label.vue
+++ b/src/Label/Label.vue
@@ -11,7 +11,8 @@
   >
     <label :id="id ? `${id}-label` : undefined" :for="id">{{ label }}</label>
     <span
-      class="block text-xs text-grey-400 font-normal mono-0 casual-60"
+      :id="id ? `${id}-help` : undefined"
+      class="block text-xs text-grey-500 dark:text-grey-400 font-normal mono-0 casual-60"
       v-if="description"
       >{{ description }}</span
     >
diff --git a/tests/Label.spec.ts b/tests/Label.spec.ts
new file mode 100644
index 0000000..a0ae32d
--- /dev/null
+++ b/tests/Label.spec.ts
@@ -0,0 +1,39 @@
+import { mount } from "@vue/test-utils";
+import { describe, expect, it } from "vitest";
+import { D9Label } from "../src";
+
+describe("D9Label help text", () => {
+  it("gets the id <id>-help next to <id>-label", () => {
+    const wrapper = mount(D9Label, {
+      props: { id: "name", label: "Name", description: "Full name." },
+    });
+
+    expect(wrapper.find("label").attributes("id")).toBe("name-label");
+    expect(wrapper.find("#name-help").text()).toBe("Full name.");
+  });
+
+  it("has no help id without an id", () => {
+    const wrapper = mount(D9Label, {
+      props: { label: "Name", description: "Full name." },
+    });
+
+    expect(wrapper.find("[id]").exists()).toBe(false);
+  });
+
+  it("renders no help element without a description", () => {
+    const wrapper = mount(D9Label, { props: { id: "name", label: "Name" } });
+
+    expect(wrapper.find("#name-help").exists()).toBe(false);
+  });
+
+  it("uses a text color with at least 4.5:1 contrast on white and grey-50", () => {
+    const wrapper = mount(D9Label, {
+      props: { id: "name", label: "Name", description: "Full name." },
+    });
+    const classes = wrapper.find("#name-help").classes();
+
+    // grey is slate: 500 is 4.76:1 on white, 4.55:1 on grey-50; 400 is only 2.56 / 2.45
+    expect(classes).toContain("text-grey-500");
+    expect(classes).not.toContain("text-grey-400");
+  });
+});

From 10da847156fd10db9b95566200f7d562d9ac1c6c Mon Sep 17 00:00:00 2001
From: Philipp Reinking <philipp@deck9.co>
Date: Sat, 17 Oct 2026 19:32:37 +0200
Subject: [PATCH 2/4] fix(Select): put aria-describedby on the button
 (BITS-289)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 src/Select/Select.vue | 26 +++++++++++++++++++++++++-
 tests/Select.spec.ts  | 16 ++++++++++++++++
 2 files changed, 41 insertions(+), 1 deletion(-)

diff --git a/src/Select/Select.vue b/src/Select/Select.vue
index b2982c6..6b6b26f 100644
--- a/src/Select/Select.vue
+++ b/src/Select/Select.vue
@@ -5,11 +5,13 @@
     @update:model-value="onSelect"
     :by="by"
     :disabled="isDisabled"
+    v-bind="wrapperAttrs"
   >
     <div class="relative">
       <ListboxButton
         :id="id"
         :aria-labelledby="labelledBy"
+        :aria-describedby="describedBy"
         class="w-full mono-50 bg-white text-grey-800 placeholder-grey-600 border border-grey-300 dark:bg-grey-800 dark:text-grey-100 dark:placeholder-grey-400 dark:border-grey-700 focus:ring-2 focus:border-blue-400 focus:ring-blue-400 focus:outline-none dark:focus:border-blue-800 dark:focus:ring-blue-800 cursor-default rounded font-normal text-left"
         :class="[inputClasses, textSizeClasses, disabledClasses]"
       >
@@ -111,6 +113,12 @@
   </Listbox>
 </template>
 
+<script lang="ts">
+export default {
+  inheritAttrs: false,
+};
+</script>
+
 <script setup lang="ts">
 import D9Icon from "../Icon/Icon.vue";
 import {
@@ -120,7 +128,14 @@ import {
   ListboxOptions,
 } from "@headlessui/vue";
 import { Size } from "../types/types";
-import { computed, onMounted, ref, watch, withDefaults } from "vue";
+import {
+  computed,
+  onMounted,
+  ref,
+  useAttrs,
+  watch,
+  withDefaults,
+} from "vue";
 import { useFormClasses } from "../utils/useFormClasses";
 
 interface SelectOption {
@@ -152,6 +167,15 @@ const props = withDefaults(
 
 const selected = ref(props.modelValue ?? null);
 
+// aria-describedby belongs on the button the screen reader focuses; other attrs stay on the wrapper.
+const attrs = useAttrs();
+const describedBy = computed(() => attrs["aria-describedby"] as string);
+const wrapperAttrs = computed(() =>
+  Object.fromEntries(
+    Object.entries(attrs).filter(([name]) => name !== "aria-describedby")
+  )
+);
+
 const emit = defineEmits<{
   (e: "update:modelValue", value: SelectOption): void;
 }>();
diff --git a/tests/Select.spec.ts b/tests/Select.spec.ts
index b9c9df2..0fbf0e1 100644
--- a/tests/Select.spec.ts
+++ b/tests/Select.spec.ts
@@ -23,4 +23,20 @@ describe("D9Select", () => {
 
     expect(wrapper.emitted("update:modelValue")).toBeUndefined();
   });
+
+  it("puts aria-describedby on the button and other attrs on the wrapper", () => {
+    const wrapper = mount(D9Select, {
+      props: { options },
+      attrs: { "aria-describedby": "x-help", class: "mt-2", "data-a": "1" },
+    });
+
+    expect(wrapper.find("button").attributes("aria-describedby")).toBe(
+      "x-help"
+    );
+    // the wrapper's opening tag is the first line of the markup
+    const wrapperTag = wrapper.html().split("\n")[0];
+    expect(wrapperTag).toContain('class="mt-2"');
+    expect(wrapperTag).toContain('data-a="1"');
+    expect(wrapperTag).not.toContain("aria-describedby");
+  });
 });

From 1ed38aa23fa31df3965050c815240c7308e245eb Mon Sep 17 00:00:00 2001
From: Philipp Reinking <philipp@deck9.co>
Date: Sat, 17 Oct 2026 19:35:52 +0200
Subject: [PATCH 3/4] fix(Select): use defineOptions so dist types still build
 (BITS-289)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 src/Select/Select.vue | 8 ++------
 1 file changed, 2 insertions(+), 6 deletions(-)

diff --git a/src/Select/Select.vue b/src/Select/Select.vue
index 6b6b26f..0e8e690 100644
--- a/src/Select/Select.vue
+++ b/src/Select/Select.vue
@@ -113,12 +113,6 @@
   </Listbox>
 </template>
 
-<script lang="ts">
-export default {
-  inheritAttrs: false,
-};
-</script>
-
 <script setup lang="ts">
 import D9Icon from "../Icon/Icon.vue";
 import {
@@ -165,6 +159,8 @@ const props = withDefaults(
   }
 );
 
+defineOptions({ inheritAttrs: false });
+
 const selected = ref(props.modelValue ?? null);
 
 // aria-describedby belongs on the button the screen reader focuses; other attrs stay on the wrapper.

From fe3015b2c0ad71933b1d2231c8dab70eeb1c49bf Mon Sep 17 00:00:00 2001
From: Philipp Reinking <philipp@deck9.co>
Date: Sat, 17 Oct 2026 19:49:48 +0200
Subject: [PATCH 4/4] fix(Select): read attrs on every render so a later class
 shows (BITS-289)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 src/Select/Select.vue | 11 +++++------
 tests/Select.spec.ts  |  8 ++++++++
 2 files changed, 13 insertions(+), 6 deletions(-)

diff --git a/src/Select/Select.vue b/src/Select/Select.vue
index 0e8e690..27b2a6a 100644
--- a/src/Select/Select.vue
+++ b/src/Select/Select.vue
@@ -5,13 +5,13 @@
     @update:model-value="onSelect"
     :by="by"
     :disabled="isDisabled"
-    v-bind="wrapperAttrs"
+    v-bind="wrapperAttrs()"
   >
     <div class="relative">
       <ListboxButton
         :id="id"
         :aria-labelledby="labelledBy"
-        :aria-describedby="describedBy"
+        :aria-describedby="attrs['aria-describedby'] as string"
         class="w-full mono-50 bg-white text-grey-800 placeholder-grey-600 border border-grey-300 dark:bg-grey-800 dark:text-grey-100 dark:placeholder-grey-400 dark:border-grey-700 focus:ring-2 focus:border-blue-400 focus:ring-blue-400 focus:outline-none dark:focus:border-blue-800 dark:focus:ring-blue-800 cursor-default rounded font-normal text-left"
         :class="[inputClasses, textSizeClasses, disabledClasses]"
       >
@@ -165,12 +165,11 @@ const selected = ref(props.modelValue ?? null);
 
 // aria-describedby belongs on the button the screen reader focuses; other attrs stay on the wrapper.
 const attrs = useAttrs();
-const describedBy = computed(() => attrs["aria-describedby"] as string);
-const wrapperAttrs = computed(() =>
+// a function, not a computed: attrs isn't reactive, so a computed would miss attrs set later
+const wrapperAttrs = () =>
   Object.fromEntries(
     Object.entries(attrs).filter(([name]) => name !== "aria-describedby")
-  )
-);
+  );
 
 const emit = defineEmits<{
   (e: "update:modelValue", value: SelectOption): void;
diff --git a/tests/Select.spec.ts b/tests/Select.spec.ts
index 0fbf0e1..d085856 100644
--- a/tests/Select.spec.ts
+++ b/tests/Select.spec.ts
@@ -39,4 +39,12 @@ describe("D9Select", () => {
     expect(wrapperTag).toContain('data-a="1"');
     expect(wrapperTag).not.toContain("aria-describedby");
   });
+
+  it("shows a class set after the first render on the wrapper", async () => {
+    const wrapper = mount(D9Select, { props: { options } });
+
+    await wrapper.setProps({ class: "mt-2" });
+
+    expect(wrapper.html().split("\n")[0]).toContain('class="mt-2"');
+  });
 });