From ac90dcaf84184363f6debdd35e3b49ec9a6b5eb8 Mon Sep 17 00:00:00 2001
From: Daniil Perkin <danetschka4pertschik@gmail.com>
Date: Mon, 28 Sep 2026 13:27:07 +0200
Subject: [PATCH 1/6] feat(ui): teach Field the optional marker and required
 propagation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Issue #242: forms marked their optional fields with hand-written label
copies ("Title (optional)", "Optional link." hints) and required fields
got only an asterisk, which is aria-hidden and therefore told a screen
reader nothing. Both are part of the Field contract that the primitive
could not express, so every caller got them slightly wrong in its own
way.

- `Field` grows an `optional` prop that appends "(optional)" inside the
  `<label>`, where it is part of both the visible text and the
  accessible name — the convention screen readers announce with the
  field ("Title (optional)"), rather than a second element beside it
  that nothing reliably connects to the control.
- `fieldContext` now carries `required`, so the asterisk's meaning
  reaches the actual control: `Input`, `Textarea` and `Select` render
  `aria-required="true"` when the enclosing `Field` is required. The
  asterisk itself stays `aria-hidden` — it is decoration; the attribute
  is the announcement.
- Precedence is explicit and pinned by tests: `aria-required` on the
  control wins, then the HTML `required` attribute, then the wrapper.
  The value is emitted only when true, so existing plain inputs do not
  grow a stray `aria-required="false"`.
- The space before "(optional)" is its own text node rather than the
  first character of the span: dom-accessibility-api trims each element
  child's contribution, so a leading space inside the span disappeared
  from the accessible name while surviving in `textContent` — the two
  disagreed ("Nickname (optional)" vs "Nickname(optional)"). The
  separate node keeps both computations identical.

Tests cover the optional label (visible text and accessible name),
required winning over optional, the absent mark on optional controls,
propagation to all three controls, the HTML-required mirror, and the
explicit aria-required override.
---
 src/components/ui/Field.tsx             | 23 +++++++-
 src/components/ui/Input.tsx             |  6 +++
 src/components/ui/Select.tsx            |  6 +++
 src/components/ui/Textarea.tsx          |  6 +++
 src/components/ui/fieldContext.ts       |  6 +++
 tests/unit/components/ui/Field.test.tsx | 71 +++++++++++++++++++++++++
 6 files changed, 116 insertions(+), 2 deletions(-)

diff --git a/src/components/ui/Field.tsx b/src/components/ui/Field.tsx
index 88d6c74a9..b55e64730 100644
--- a/src/components/ui/Field.tsx
+++ b/src/components/ui/Field.tsx
@@ -16,8 +16,19 @@ export type FieldProps = {
    * or an empty string when the field is fine.
    */
   error?: ReactNode;
-  /** Appends the conventional asterisk and sets `required` semantics visually. */
+  /**
+   * Appends the conventional asterisk and carries the semantics through
+   * context, so the wrapped control also gets `aria-required` — the asterisk
+   * itself is `aria-hidden` and invisible to a screen reader.
+   */
   required?: boolean;
+  /**
+   * Appends a visible "(optional)" to the label, the counterpart for fields the
+   * form genuinely does not need. Rendered inside the `<label>` so it lands in
+   * the control's accessible name and announces with the field; ignored when
+   * `required` is also set, since the two are mutually exclusive in practice.
+   */
+  optional?: boolean;
   /**
    * Fixed id for the control, when something outside the field has to point at
    * it (`aria-controls`, a `ref`-free `focus()` by id, an existing E2E
@@ -60,6 +71,7 @@ export function Field({
   hint,
   error,
   required = false,
+  optional = false,
   controlId: providedControlId,
   disabled = false,
   className = "",
@@ -83,8 +95,9 @@ export function Field({
       describedBy: described || undefined,
       invalid: hasError,
       disabled,
+      required,
     };
-  }, [controlId, hintId, errorId, hasHint, hasError, disabled]);
+  }, [controlId, hintId, errorId, hasHint, hasError, disabled, required]);
 
   return (
     <div className={`flex flex-col gap-1.5 ${className}`.trim()}>
@@ -96,6 +109,12 @@ export function Field({
               *
             </span>
           )}
+          {optional && !required && (
+            <>
+              {" "}
+              <span className="ml-1 text-xs font-normal text-app-text-subtle">(optional)</span>
+            </>
+          )}
         </label>
       )}
 
diff --git a/src/components/ui/Input.tsx b/src/components/ui/Input.tsx
index b66ad8d81..f1c9f0f5a 100644
--- a/src/components/ui/Input.tsx
+++ b/src/components/ui/Input.tsx
@@ -64,6 +64,7 @@ export const Input = forwardRef<HTMLInputElement, InputProps>(function Input(
     id,
     disabled,
     "aria-describedby": ariaDescribedBy,
+    "aria-required": ariaRequired,
     ...rest
   },
   ref,
@@ -74,6 +75,10 @@ export const Input = forwardRef<HTMLInputElement, InputProps>(function Input(
   const resolvedId = id ?? field?.controlId;
   const resolvedDescribedBy = ariaDescribedBy ?? field?.describedBy;
   const isDisabled = disabled ?? field?.disabled ?? false;
+  // An explicit `aria-required` or HTML `required` on the control wins; only
+  // when neither is given does the enclosing `Field` supply it. Emitted only
+  // when true, so a plain input does not grow a stray `aria-required="false"`.
+  const isRequired = ariaRequired ?? rest.required ?? field?.required;
 
   const control = (
     <input
@@ -82,6 +87,7 @@ export const Input = forwardRef<HTMLInputElement, InputProps>(function Input(
       disabled={isDisabled}
       aria-invalid={isInvalid || undefined}
       aria-describedby={resolvedDescribedBy}
+      aria-required={isRequired || undefined}
       className={fieldClasses({
         size,
         invalid: isInvalid,
diff --git a/src/components/ui/Select.tsx b/src/components/ui/Select.tsx
index 5e94172de..774ed3da2 100644
--- a/src/components/ui/Select.tsx
+++ b/src/components/ui/Select.tsx
@@ -29,6 +29,7 @@ export const Select = forwardRef<HTMLSelectElement, SelectProps>(function Select
     id,
     disabled,
     "aria-describedby": ariaDescribedBy,
+    "aria-required": ariaRequired,
     children,
     ...rest
   },
@@ -36,6 +37,10 @@ export const Select = forwardRef<HTMLSelectElement, SelectProps>(function Select
 ) {
   const field = useContext(FieldContext);
   const isInvalid = invalid ?? field?.invalid ?? false;
+  // An explicit `aria-required` or HTML `required` on the control wins; only
+  // when neither is given does the enclosing `Field` supply it. Emitted only
+  // when true, so a plain select does not grow a stray `aria-required="false"`.
+  const isRequired = ariaRequired ?? rest.required ?? field?.required;
 
   return (
     <select
@@ -44,6 +49,7 @@ export const Select = forwardRef<HTMLSelectElement, SelectProps>(function Select
       disabled={disabled ?? field?.disabled ?? false}
       aria-invalid={isInvalid || undefined}
       aria-describedby={ariaDescribedBy ?? field?.describedBy}
+      aria-required={isRequired || undefined}
       className={fieldClasses({
         size,
         invalid: isInvalid,
diff --git a/src/components/ui/Textarea.tsx b/src/components/ui/Textarea.tsx
index f8a044104..12b4d6676 100644
--- a/src/components/ui/Textarea.tsx
+++ b/src/components/ui/Textarea.tsx
@@ -66,12 +66,17 @@ export const Textarea = forwardRef<HTMLTextAreaElement, TextareaProps>(function
     disabled,
     value,
     "aria-describedby": ariaDescribedBy,
+    "aria-required": ariaRequired,
     ...rest
   },
   forwardedRef,
 ) {
   const field = useContext(FieldContext);
   const isInvalid = invalid ?? field?.invalid ?? false;
+  // An explicit `aria-required` or HTML `required` on the control wins; only
+  // when neither is given does the enclosing `Field` supply it. Emitted only
+  // when true, so a plain textarea does not grow a stray `aria-required="false"`.
+  const isRequired = ariaRequired ?? rest.required ?? field?.required;
 
   const innerRef = useRef<HTMLTextAreaElement | null>(null);
 
@@ -107,6 +112,7 @@ export const Textarea = forwardRef<HTMLTextAreaElement, TextareaProps>(function
       disabled={disabled ?? field?.disabled ?? false}
       aria-invalid={isInvalid || undefined}
       aria-describedby={ariaDescribedBy ?? field?.describedBy}
+      aria-required={isRequired || undefined}
       className={textareaClasses({
         invalid: isInvalid,
         className: `${autoResize ? "resize-none overflow-hidden" : "resize-y"} ${className}`.trim(),
diff --git a/src/components/ui/fieldContext.ts b/src/components/ui/fieldContext.ts
index 7d5c82178..707c25486 100644
--- a/src/components/ui/fieldContext.ts
+++ b/src/components/ui/fieldContext.ts
@@ -12,6 +12,12 @@ export type FieldContextValue = {
   invalid: boolean;
   /** Mirrors `Field`'s `disabled`, so the control does not need it passed twice. */
   disabled: boolean;
+  /**
+   * Mirrors `Field`'s `required`, so the control can put `aria-required` on the
+   * real element — the asterisk in the label is `aria-hidden` decoration and
+   * tells assistive tech nothing on its own.
+   */
+  required: boolean;
 };
 
 /**
diff --git a/tests/unit/components/ui/Field.test.tsx b/tests/unit/components/ui/Field.test.tsx
index 4c2a31b97..c7c5e1c18 100644
--- a/tests/unit/components/ui/Field.test.tsx
+++ b/tests/unit/components/ui/Field.test.tsx
@@ -92,6 +92,77 @@ describe("Field", () => {
     );
     expect(screen.getByLabelText("Manager")).toHaveAttribute("aria-invalid", "true");
   });
+
+  it("marks the label optional when the field is not required", () => {
+    render(
+      <Field label="Nickname" optional>
+        <Input />
+      </Field>,
+    );
+    const control = screen.getByLabelText("Nickname (optional)");
+    expect(control).toBeInTheDocument();
+    expect(control).toHaveAccessibleName("Nickname (optional)");
+  });
+
+  it("prefers the required mark when both props are set", () => {
+    render(
+      <Field label="Email" required optional>
+        <Input />
+      </Field>,
+    );
+    expect(screen.getByLabelText(/^Email/)).toBeInTheDocument();
+    expect(screen.queryByText("(optional)")).not.toBeInTheDocument();
+  });
+
+  it("does not mark an optional control as required", () => {
+    render(
+      <Field label="Nickname" optional>
+        <Input />
+      </Field>,
+    );
+    expect(screen.getByLabelText("Nickname (optional)")).not.toHaveAttribute("aria-required");
+  });
+
+  it("carries the field's required flag to the control as aria-required", () => {
+    const { unmount: unmountInput } = render(
+      <Field label="Name" required>
+        <Input />
+      </Field>,
+    );
+    expect(screen.getByLabelText(/^Name/)).toHaveAttribute("aria-required", "true");
+    unmountInput();
+
+    const { unmount: unmountTextarea } = render(
+      <Field label="Bio" required>
+        <Textarea />
+      </Field>,
+    );
+    expect(screen.getByLabelText(/^Bio/)).toHaveAttribute("aria-required", "true");
+    unmountTextarea();
+
+    render(
+      <Field label="Role" required>
+        <Select>
+          <option value="">None</option>
+        </Select>
+      </Field>,
+    );
+    expect(screen.getByLabelText(/^Role/)).toHaveAttribute("aria-required", "true");
+  });
+
+  it("keeps the HTML required attribute mirrored in aria-required", () => {
+    render(<Input aria-label="Search" required />);
+    expect(screen.getByLabelText("Search")).toHaveAttribute("aria-required", "true");
+  });
+
+  it("lets an explicit aria-required on the control override the field", () => {
+    render(
+      <Field label="Name" required>
+        <Input aria-required={false} />
+      </Field>,
+    );
+    expect(screen.getByLabelText(/^Name/)).not.toHaveAttribute("aria-required");
+  });
 });
 
 describe("Textarea", () => {

From 863e2a5d782f998e8ac26950d69d5802808d8d0f Mon Sep 17 00:00:00 2001
From: Daniil Perkin <danetschka4pertschik@gmail.com>
Date: Mon, 28 Sep 2026 13:27:07 +0200
Subject: [PATCH 2/6] refactor(forms): standardize the required and optional
 marks on Field
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Every form that hand-marked optional fields, or left required controls
unmarked, now speaks the shared convention — the boundary between "the
form needs this" and "this is a plus" reads the same on every screen,
and assistive tech is told either way.

Removed in favour of the prop (visible text deliberately unchanged):
- AddCardForm + NoteCard: the "Title (optional)" / "What to call it
  (optional)" label copies.
- WizardDetailsStep: Industry's "Optional. " hint prefix (the hint
  keeps the actual guidance); Description now marks itself optional.
- AddArrivalStepModal: the same for "How to do it" and "Where to do it"
  ("Optional link." -> "Link to tool or docs."). "What needs to be
  done" now declares the required-ness its submit guard
  (`canSubmitCustom`) already enforced.

Migrated outright:
- NewStarterTaskModal bypassed Field entirely — raw `<label>`/`<input>`
  pairs, a local inputClasses string and a span-based "(optional)". It
  is now four Fields around Input/Textarea, and the competency-keys
  guidance moved into Field's hint slot so it gets aria-describedby.

Marked, because the code already enforces it:
- TokenAddForm, AtlassianCredentialAddForm, TokenRotateForm — the
  credential fields are already gated by `required` inputs / submit
  guards; the asterisk and aria-required now say so.
- ProjectDetailsDrawer: Name required, Description optional, matching
  the wizard's semantics for the same fields.
- AccountForm (first/last/email carry `required`), NewAreaForm (submit
  disabled while empty), ConfluenceConnectStep (base URL and Space ID
  inputs carry `required`).

Left deliberately unchanged: ArrivalStepAuthoring's editor tolerates a
blank title in its save path (there is no guard to mirror), so it gets
no required mark in this PR.

The appended marks change each label's text, so tests that pinned the
old exact strings now match the leading part they intended — /^Name/,
/^Description/, /^Title/, /^Industry/, /^Space ID/, /^Confluence base
URL/, /^Token name/ — same assertions, relaxed where the mark made the
full string ambiguous.
---
 .../admin/components/ProjectDetailsDrawer.tsx |  9 ++-
 .../wizard/steps/WizardDetailsStep.tsx        |  5 +-
 .../components/AddArrivalStepModal.tsx        |  7 +-
 src/features/board/components/AddCardForm.tsx |  4 +-
 src/features/board/components/NewAreaForm.tsx |  1 +
 src/features/board/components/NoteCard.tsx    |  2 +-
 .../components/ConfluenceConnectStep.tsx      |  3 +-
 .../profile/components/AccountForm.tsx        |  6 +-
 .../settings/components/TokenAddForm.tsx      |  3 +-
 .../settings/components/TokenRotateForm.tsx   |  1 +
 .../atlassian/AtlassianCredentialAddForm.tsx  |  9 ++-
 .../components/NewStarterTaskModal.tsx        | 69 ++++++-------------
 .../a11y/AccessManagementView.a11y.test.tsx   |  2 +-
 .../components/CreateProjectWizard.test.tsx   | 12 ++--
 .../components/ProjectDetailsDrawer.test.tsx  | 44 ++++++------
 .../starter-work/NewStarterTaskModal.test.tsx |  8 +--
 .../starter-work/StarterWorkSection.test.tsx  |  2 +-
 17 files changed, 88 insertions(+), 99 deletions(-)

diff --git a/src/features/admin/components/ProjectDetailsDrawer.tsx b/src/features/admin/components/ProjectDetailsDrawer.tsx
index a53dd3278..2db0da718 100644
--- a/src/features/admin/components/ProjectDetailsDrawer.tsx
+++ b/src/features/admin/components/ProjectDetailsDrawer.tsx
@@ -331,14 +331,19 @@ export function ProjectDetailsDrawer({
               )}
 
               <div className="space-y-4">
-                <Field label="Name" controlId={nameInputId} disabled={isSaving}>
+                <Field label="Name" controlId={nameInputId} required disabled={isSaving}>
                   <Input
                     value={draftProject.name}
                     onChange={(event) => updateDraftField("name", event.target.value)}
                   />
                 </Field>
 
-                <Field label="Description" controlId={descriptionInputId} disabled={isSaving}>
+                <Field
+                  label="Description"
+                  controlId={descriptionInputId}
+                  optional
+                  disabled={isSaving}
+                >
                   <Textarea
                     value={draftProject.description}
                     onChange={(event) => updateDraftField("description", event.target.value)}
diff --git a/src/features/admin/components/wizard/steps/WizardDetailsStep.tsx b/src/features/admin/components/wizard/steps/WizardDetailsStep.tsx
index e7e63b834..10f505b58 100644
--- a/src/features/admin/components/wizard/steps/WizardDetailsStep.tsx
+++ b/src/features/admin/components/wizard/steps/WizardDetailsStep.tsx
@@ -89,7 +89,7 @@ export function WizardDetailsStep({
         />
       </Field>
 
-      <Field label="Description" controlId={descriptionInputId}>
+      <Field label="Description" controlId={descriptionInputId} optional>
         <Textarea
           value={description}
           onChange={(event) => onDescriptionChange(event.target.value)}
@@ -102,7 +102,8 @@ export function WizardDetailsStep({
       <Field
         label="Industry"
         controlId={industryInputId}
-        hint="Optional. Leave empty and set or evaluate it later from the project's admin drawer."
+        optional
+        hint="Leave empty and set or evaluate it later from the project's admin drawer."
       >
         <Input
           value={industry}
diff --git a/src/features/arrival/components/AddArrivalStepModal.tsx b/src/features/arrival/components/AddArrivalStepModal.tsx
index b078d465b..a9931f5bc 100644
--- a/src/features/arrival/components/AddArrivalStepModal.tsx
+++ b/src/features/arrival/components/AddArrivalStepModal.tsx
@@ -267,7 +267,7 @@ export function AddArrivalStepModal({
 
           {phase === "details" && kind === "custom" && (
             <div className="space-y-3">
-              <Field label="What needs to be done">
+              <Field label="What needs to be done" required>
                 <Input
                   value={title}
                   onChange={(event) => setTitle(event.target.value)}
@@ -277,7 +277,8 @@ export function AddArrivalStepModal({
 
               <Field
                 label="How to do it"
-                hint="Optional. Anything they need to know before starting."
+                optional
+                hint="Anything they need to know before starting."
               >
                 <Textarea
                   value={description}
@@ -287,7 +288,7 @@ export function AddArrivalStepModal({
                 />
               </Field>
 
-              <Field label="Where to do it" hint="Optional link.">
+              <Field label="Where to do it" optional hint="Link to tool or docs.">
                 <Input
                   value={href}
                   onChange={(event) => setHref(event.target.value)}
diff --git a/src/features/board/components/AddCardForm.tsx b/src/features/board/components/AddCardForm.tsx
index 4fcfb8d89..202b3f147 100644
--- a/src/features/board/components/AddCardForm.tsx
+++ b/src/features/board/components/AddCardForm.tsx
@@ -117,7 +117,7 @@ export function AddCardForm({ kind, onAdd, onClose }: AddCardFormProps) {
       <div className="flex items-start justify-between gap-2">
         <div className="min-w-0 flex-1 space-y-3">
           {kind === "NOTE" && (
-            <Field label="Title (optional)" controlId={`${fieldId}-title`}>
+            <Field label="Title" optional controlId={`${fieldId}-title`}>
               <Input
                 value={noteTitle}
                 onChange={(event) => setNoteTitle(event.target.value)}
@@ -155,7 +155,7 @@ export function AddCardForm({ kind, onAdd, onClose }: AddCardFormProps) {
       </div>
 
       {kind === "LINK" && (
-        <Field label="What to call it (optional)" controlId={`${fieldId}-label`}>
+        <Field label="What to call it" optional controlId={`${fieldId}-label`}>
           <Input value={label} onChange={(event) => setLabel(event.target.value)} />
         </Field>
       )}
diff --git a/src/features/board/components/NewAreaForm.tsx b/src/features/board/components/NewAreaForm.tsx
index 0e678fa6d..d48dc8eaf 100644
--- a/src/features/board/components/NewAreaForm.tsx
+++ b/src/features/board/components/NewAreaForm.tsx
@@ -50,6 +50,7 @@ export function NewAreaForm({ onCreate, onClose }: NewAreaFormProps) {
           <Field
             label="Name this area"
             controlId="new-area-name"
+            required
             hint="A part of the board you can open on its own — Paperwork, Week two, Before my first release."
           >
             <Input
diff --git a/src/features/board/components/NoteCard.tsx b/src/features/board/components/NoteCard.tsx
index 09646b046..83cb05358 100644
--- a/src/features/board/components/NoteCard.tsx
+++ b/src/features/board/components/NoteCard.tsx
@@ -128,7 +128,7 @@ export function NoteCard({ content, card, onDismiss, dismissing, onEdit, origin
     >
       {editing ? (
         <div className="space-y-3">
-          <Field label="Title (optional)" controlId={`note-title-${card.id}`}>
+          <Field label="Title" optional controlId={`note-title-${card.id}`}>
             <Input
               value={titleDraft}
               onChange={(event) => setTitleDraft(event.target.value)}
diff --git a/src/features/data-ingestion/components/ConfluenceConnectStep.tsx b/src/features/data-ingestion/components/ConfluenceConnectStep.tsx
index 2ac10f3ba..cf3b2254d 100644
--- a/src/features/data-ingestion/components/ConfluenceConnectStep.tsx
+++ b/src/features/data-ingestion/components/ConfluenceConnectStep.tsx
@@ -76,7 +76,7 @@ export function ConfluenceConnectStep({
         </div>
       )}
 
-      <Field label="Confluence base URL" controlId="confluence-base-url" disabled={isBusy}>
+      <Field label="Confluence base URL" controlId="confluence-base-url" required disabled={isBusy}>
         <Input
           data-testid="confluence-base-url"
           type="url"
@@ -90,6 +90,7 @@ export function ConfluenceConnectStep({
       <Field
         label="Space ID"
         controlId="confluence-space-id"
+        required
         disabled={isBusy}
         hint="Numeric ID of the space in Confluence Cloud."
       >
diff --git a/src/features/profile/components/AccountForm.tsx b/src/features/profile/components/AccountForm.tsx
index 9c4a4d7c3..d35170cc8 100644
--- a/src/features/profile/components/AccountForm.tsx
+++ b/src/features/profile/components/AccountForm.tsx
@@ -122,7 +122,7 @@ export function AccountForm({ profile, onUpdate }: AccountFormProps) {
         className="space-y-4"
       >
         <div className="grid grid-cols-1 gap-4 md:grid-cols-2">
-          <Field label="First Name" controlId="firstName">
+          <Field label="First Name" controlId="firstName" required>
             <Input
               type="text"
               value={firstName}
@@ -130,7 +130,7 @@ export function AccountForm({ profile, onUpdate }: AccountFormProps) {
               required
             />
           </Field>
-          <Field label="Last Name" controlId="lastName">
+          <Field label="Last Name" controlId="lastName" required>
             <Input
               type="text"
               value={lastName}
@@ -140,7 +140,7 @@ export function AccountForm({ profile, onUpdate }: AccountFormProps) {
           </Field>
         </div>
 
-        <Field label="Email Address" controlId="email">
+        <Field label="Email Address" controlId="email" required>
           <Input type="email" value={email} onChange={(e) => setEmail(e.target.value)} required />
         </Field>
 
diff --git a/src/features/settings/components/TokenAddForm.tsx b/src/features/settings/components/TokenAddForm.tsx
index 0987f8af8..85c9aaf33 100644
--- a/src/features/settings/components/TokenAddForm.tsx
+++ b/src/features/settings/components/TokenAddForm.tsx
@@ -110,7 +110,7 @@ export function TokenAddForm({ onClose, onSaved, embedded = false }: TokenAddFor
       )}
 
       <div className="space-y-3">
-        <Field label="Token name" controlId="settings-add-token-name" disabled={isSaving}>
+        <Field label="Token name" controlId="settings-add-token-name" required disabled={isSaving}>
           <Input
             ref={nameInputRef}
             data-testid="settings-add-token-name"
@@ -125,6 +125,7 @@ export function TokenAddForm({ onClose, onSaved, embedded = false }: TokenAddFor
         <Field
           label="Token (ghp_...)"
           controlId="settings-add-token-value"
+          required
           hint="The token value is stored encrypted and cannot be retrieved after saving."
           disabled={isSaving}
         >
diff --git a/src/features/settings/components/TokenRotateForm.tsx b/src/features/settings/components/TokenRotateForm.tsx
index 0b05b1105..af6d74618 100644
--- a/src/features/settings/components/TokenRotateForm.tsx
+++ b/src/features/settings/components/TokenRotateForm.tsx
@@ -84,6 +84,7 @@ export function TokenRotateForm({ name, onClose, onSaved }: TokenRotateFormProps
         <Field
           label="New GitHub PAT"
           controlId="settings-rotate-token-value"
+          required
           disabled={isSaving}
           className="min-w-0 flex-1"
         >
diff --git a/src/features/settings/components/atlassian/AtlassianCredentialAddForm.tsx b/src/features/settings/components/atlassian/AtlassianCredentialAddForm.tsx
index 1052a4889..40d9ac02e 100644
--- a/src/features/settings/components/atlassian/AtlassianCredentialAddForm.tsx
+++ b/src/features/settings/components/atlassian/AtlassianCredentialAddForm.tsx
@@ -126,6 +126,7 @@ export function AtlassianCredentialAddForm({
         <Field
           label="Atlassian account email"
           controlId="settings-atlassian-add-email"
+          required
           disabled={isSaving}
         >
           <Input
@@ -140,7 +141,12 @@ export function AtlassianCredentialAddForm({
           />
         </Field>
 
-        <Field label="Credential name" controlId="settings-atlassian-add-name" disabled={isSaving}>
+        <Field
+          label="Credential name"
+          controlId="settings-atlassian-add-name"
+          required
+          disabled={isSaving}
+        >
           <Input
             ref={nameInputRef}
             data-testid="settings-atlassian-add-name"
@@ -155,6 +161,7 @@ export function AtlassianCredentialAddForm({
         <Field
           label="API token"
           controlId="settings-atlassian-add-token"
+          required
           disabled={isSaving}
           hint="The token is stored encrypted and cannot be retrieved after saving."
         >
diff --git a/src/features/starter-work/components/NewStarterTaskModal.tsx b/src/features/starter-work/components/NewStarterTaskModal.tsx
index 7a52086f9..5a060681f 100644
--- a/src/features/starter-work/components/NewStarterTaskModal.tsx
+++ b/src/features/starter-work/components/NewStarterTaskModal.tsx
@@ -1,7 +1,10 @@
 import { useState } from "react";
 import { Plus } from "lucide-react";
 import { Button } from "../../../components/ui/Button";
+import { Field } from "../../../components/ui/Field";
+import { Input } from "../../../components/ui/Input";
 import { Modal } from "../../../components/ui/Modal";
+import { Textarea } from "../../../components/ui/Textarea";
 import type { CreateStarterWorkTaskInput } from "../types";
 import { capturePoolFlightRect, type PoolFlightRect } from "./poolFlight";
 
@@ -11,9 +14,6 @@ type NewStarterTaskModalProps = {
   onClose: () => void;
 };
 
-const inputClasses =
-  "w-full rounded-lg border border-app-border bg-app-surface px-3 py-2 text-sm text-app-text focus-visible:ring-2 focus-visible:ring-app-focus focus-visible:outline-none";
-
 /**
  * A PM hand-authoring a starter task, with no AI mining.
  *
@@ -87,70 +87,41 @@ export function NewStarterTaskModal({ isSaving, onCreate, onClose }: NewStarterT
         onSubmit={(event) => void handleSubmit(event)}
         className="space-y-4"
       >
-        <div>
-          <label htmlFor="new-task-title" className="mb-1 block text-xs font-medium text-app-text">
-            Title
-          </label>
-          <input
-            id="new-task-title"
+        <Field label="Title" required>
+          <Input
             value={title}
             onChange={(event) => setTitle(event.target.value)}
             placeholder="e.g. Add a dark-mode toggle to the settings page"
-            className={inputClasses}
           />
-        </div>
+        </Field>
 
-        <div>
-          <label
-            htmlFor="new-task-summary"
-            className="mb-1 block text-xs font-medium text-app-text"
-          >
-            What it involves
-          </label>
-          <textarea
-            id="new-task-summary"
-            rows={3}
+        <Field label="What it involves" optional>
+          <Textarea
             value={summary}
             onChange={(event) => setSummary(event.target.value)}
-            className={inputClasses}
+            minRows={3}
           />
-        </div>
+        </Field>
 
-        <div>
-          <label
-            htmlFor="new-task-source-url"
-            className="mb-1 block text-xs font-medium text-app-text"
-          >
-            Link <span className="text-app-text-subtle">(optional)</span>
-          </label>
-          <input
-            id="new-task-source-url"
+        <Field label="Link" optional>
+          <Input
             value={sourceUrl}
             onChange={(event) => setSourceUrl(event.target.value)}
             placeholder="https://github.com/org/repo/issues/123"
-            className={inputClasses}
           />
-        </div>
+        </Field>
 
-        <div>
-          <label
-            htmlFor="new-task-competency-keys"
-            className="mb-1 block text-xs font-medium text-app-text"
-          >
-            Prerequisite competencies <span className="text-app-text-subtle">(optional)</span>
-          </label>
-          <input
-            id="new-task-competency-keys"
+        <Field
+          label="Prerequisite competencies"
+          optional
+          hint="Competency identifiers, comma-separated. Each becomes a prerequisite edge into the task; any that isn't in the graph is quietly skipped."
+        >
+          <Input
             value={competencyKeysRaw}
             onChange={(event) => setCompetencyKeysRaw(event.target.value)}
             placeholder="react, typescript"
-            className={inputClasses}
           />
-          <p className="mt-1 text-xs text-app-text-subtle">
-            Competency identifiers, comma-separated. Each becomes a prerequisite edge into the task;
-            any that isn&apos;t in the graph is quietly skipped.
-          </p>
-        </div>
+        </Field>
       </form>
     </Modal>
   );
diff --git a/tests/unit/a11y/AccessManagementView.a11y.test.tsx b/tests/unit/a11y/AccessManagementView.a11y.test.tsx
index be018fba3..9e1de8923 100644
--- a/tests/unit/a11y/AccessManagementView.a11y.test.tsx
+++ b/tests/unit/a11y/AccessManagementView.a11y.test.tsx
@@ -98,7 +98,7 @@ describe("AccessManagementView Accessibility", () => {
     expect(await axe(baseElement)).toHaveNoViolations();
 
     await user.click(screen.getByTestId("access-add-source-github"));
-    expect(await screen.findByLabelText("Token name")).toBeInTheDocument();
+    expect(await screen.findByLabelText(/^Token name/)).toBeInTheDocument();
     expect(await axe(baseElement)).toHaveNoViolations();
   });
 
diff --git a/tests/unit/features/admin/components/CreateProjectWizard.test.tsx b/tests/unit/features/admin/components/CreateProjectWizard.test.tsx
index b61287eb0..eed93ab8e 100644
--- a/tests/unit/features/admin/components/CreateProjectWizard.test.tsx
+++ b/tests/unit/features/admin/components/CreateProjectWizard.test.tsx
@@ -254,10 +254,10 @@ describe("CreateProjectWizard", () => {
     await screen.findByText(/Team token - me@example.com/i);
 
     await user.type(
-      screen.getByLabelText("Confluence base URL"),
+      screen.getByLabelText(/^Confluence base URL/),
       "https://acme.atlassian.net/wiki",
     );
-    await user.type(screen.getByLabelText("Space ID"), "123456");
+    await user.type(screen.getByLabelText(/^Space ID/), "123456");
     await user.click(screen.getByRole("button", { name: /add to list/i }));
   }
 
@@ -384,7 +384,7 @@ describe("CreateProjectWizard", () => {
     await settleModalFocus();
 
     await user.type(screen.getByLabelText(/^Name/), "Apollo");
-    await user.type(screen.getByLabelText("Industry"), "Fintech");
+    await user.type(screen.getByLabelText(/^Industry/), "Fintech");
 
     await user.click(screen.getByRole("button", { name: /continue/i }));
     await user.click(screen.getByRole("button", { name: /continue/i }));
@@ -424,7 +424,7 @@ describe("CreateProjectWizard", () => {
     expect(await screen.findByText("Not set")).toBeInTheDocument();
 
     await user.click(screen.getByRole("button", { name: "Go to Details" }));
-    await user.type(screen.getByLabelText("Industry"), "Fintech");
+    await user.type(screen.getByLabelText(/^Industry/), "Fintech");
     await user.click(screen.getByRole("button", { name: /continue/i }));
     await user.click(screen.getByRole("button", { name: /continue/i }));
     await user.click(screen.getByRole("button", { name: /continue/i }));
@@ -675,12 +675,12 @@ describe("CreateProjectWizard", () => {
     await screen.findByText(/Team token - me@example.com/i);
 
     await user.type(
-      screen.getByLabelText("Confluence base URL"),
+      screen.getByLabelText(/^Confluence base URL/),
       "https://acme.atlassian.net/wiki",
     );
     // "DOCS" is what Confluence's own UI shows, so it is the obvious thing to
     // paste — and the backend would only reject it at provisioning time.
-    await user.type(screen.getByLabelText("Space ID"), "DOCS");
+    await user.type(screen.getByLabelText(/^Space ID/), "DOCS");
 
     expect(screen.getByRole("button", { name: /add to list/i })).toBeDisabled();
   });
diff --git a/tests/unit/features/admin/components/ProjectDetailsDrawer.test.tsx b/tests/unit/features/admin/components/ProjectDetailsDrawer.test.tsx
index a4196efb8..26d6cd4ce 100644
--- a/tests/unit/features/admin/components/ProjectDetailsDrawer.test.tsx
+++ b/tests/unit/features/admin/components/ProjectDetailsDrawer.test.tsx
@@ -218,14 +218,14 @@ describe("ProjectDetailsDrawer", () => {
       const user = userEvent.setup();
       render(<ProjectDetailsDrawer project={projectOverview} isOpen={true} onClose={vi.fn()} />);
 
-      await waitFor(() => expect(screen.getByLabelText("Name")).toHaveValue("Alpha"));
+      await waitFor(() => expect(screen.getByLabelText(/^Name/)).toHaveValue("Alpha"));
 
       // There is no edit mode to enter first.
       expect(screen.queryByRole("button", { name: /Edit Project/i })).not.toBeInTheDocument();
-      expect(screen.getByLabelText("Description")).toBeEnabled();
+      expect(screen.getByLabelText(/^Description/)).toBeEnabled();
 
-      await user.clear(screen.getByLabelText("Name"));
-      await user.type(screen.getByLabelText("Name"), "Beta");
+      await user.clear(screen.getByLabelText(/^Name/));
+      await user.type(screen.getByLabelText(/^Name/), "Beta");
 
       expect(screen.getByText("1 unsaved change")).toBeInTheDocument();
     });
@@ -241,9 +241,9 @@ describe("ProjectDetailsDrawer", () => {
         />,
       );
 
-      await waitFor(() => expect(screen.getByLabelText("Name")).toHaveValue("Alpha"));
+      await waitFor(() => expect(screen.getByLabelText(/^Name/)).toHaveValue("Alpha"));
 
-      await user.type(screen.getByLabelText("Description"), "!");
+      await user.type(screen.getByLabelText(/^Description/), "!");
       await user.click(screen.getByRole("button", { name: /Remove Jane Doe from project/ }));
 
       expect(screen.getByText("2 unsaved changes")).toBeInTheDocument();
@@ -256,10 +256,10 @@ describe("ProjectDetailsDrawer", () => {
 
       render(<ProjectDetailsDrawer project={projectOverview} isOpen={true} onClose={vi.fn()} />);
 
-      await waitFor(() => expect(screen.getByLabelText("Name")).toHaveValue("Alpha"));
+      await waitFor(() => expect(screen.getByLabelText(/^Name/)).toHaveValue("Alpha"));
 
-      await user.clear(screen.getByLabelText("Name"));
-      await user.type(screen.getByLabelText("Name"), "Beta");
+      await user.clear(screen.getByLabelText(/^Name/));
+      await user.type(screen.getByLabelText(/^Name/), "Beta");
       await user.click(screen.getByRole("button", { name: /Remove Jane Doe from project/ }));
       await user.click(screen.getByRole("button", { name: "Save changes" }));
 
@@ -276,9 +276,9 @@ describe("ProjectDetailsDrawer", () => {
       const user = userEvent.setup();
       render(<ProjectDetailsDrawer project={projectOverview} isOpen={true} onClose={vi.fn()} />);
 
-      await waitFor(() => expect(screen.getByLabelText("Name")).toHaveValue("Alpha"));
+      await waitFor(() => expect(screen.getByLabelText(/^Name/)).toHaveValue("Alpha"));
 
-      await user.clear(screen.getByLabelText("Name"));
+      await user.clear(screen.getByLabelText(/^Name/));
       await user.click(screen.getByRole("button", { name: "Save changes" }));
 
       expect(screen.getByText("Project name is required.")).toBeInTheDocument();
@@ -289,21 +289,21 @@ describe("ProjectDetailsDrawer", () => {
       const user = userEvent.setup();
       render(<ProjectDetailsDrawer project={projectOverview} isOpen={true} onClose={vi.fn()} />);
 
-      await waitFor(() => expect(screen.getByLabelText("Name")).toHaveValue("Alpha"));
+      await waitFor(() => expect(screen.getByLabelText(/^Name/)).toHaveValue("Alpha"));
 
-      await user.clear(screen.getByLabelText("Name"));
-      await user.type(screen.getByLabelText("Name"), "Beta");
+      await user.clear(screen.getByLabelText(/^Name/));
+      await user.type(screen.getByLabelText(/^Name/), "Beta");
       await user.click(screen.getByRole("button", { name: /Remove Jane Doe from project/ }));
       await user.click(screen.getByRole("button", { name: "Discard" }));
 
-      expect(screen.getByLabelText("Name")).toHaveValue("Alpha");
+      expect(screen.getByLabelText(/^Name/)).toHaveValue("Alpha");
       expect(screen.queryByText(/unsaved change/)).not.toBeInTheDocument();
     });
 
     it("shows no footer while nothing is staged", async () => {
       render(<ProjectDetailsDrawer project={projectOverview} isOpen={true} onClose={vi.fn()} />);
 
-      await waitFor(() => expect(screen.getByLabelText("Name")).toHaveValue("Alpha"));
+      await waitFor(() => expect(screen.getByLabelText(/^Name/)).toHaveValue("Alpha"));
 
       expect(screen.queryByRole("button", { name: "Save changes" })).not.toBeInTheDocument();
     });
@@ -351,7 +351,7 @@ describe("ProjectDetailsDrawer", () => {
         />,
       );
 
-      await waitFor(() => expect(screen.getByLabelText("Name")).toHaveValue("Alpha"));
+      await waitFor(() => expect(screen.getByLabelText(/^Name/)).toHaveValue("Alpha"));
       expect(screen.queryByTestId("edit-industry-button")).not.toBeInTheDocument();
       expect(screen.queryByTestId("reevaluate-industry-button")).not.toBeInTheDocument();
     });
@@ -422,7 +422,7 @@ describe("ProjectDetailsDrawer", () => {
         />,
       );
 
-      await waitFor(() => expect(screen.getByLabelText("Name")).toHaveValue("Alpha"));
+      await waitFor(() => expect(screen.getByLabelText(/^Name/)).toHaveValue("Alpha"));
 
       await user.click(screen.getByTestId("reevaluate-industry-button"));
 
@@ -457,16 +457,16 @@ describe("ProjectDetailsDrawer", () => {
         />,
       );
 
-      await waitFor(() => expect(screen.getByLabelText("Name")).toHaveValue("Alpha"));
-      await user.clear(screen.getByLabelText("Name"));
-      await user.type(screen.getByLabelText("Name"), "Renamed draft");
+      await waitFor(() => expect(screen.getByLabelText(/^Name/)).toHaveValue("Alpha"));
+      await user.clear(screen.getByLabelText(/^Name/));
+      await user.type(screen.getByLabelText(/^Name/), "Renamed draft");
 
       await user.click(screen.getByTestId("reevaluate-industry-button"));
 
       await waitFor(() =>
         expect(screen.getByTestId("project-industry-value")).toHaveTextContent("Fintech"),
       );
-      expect(screen.getByLabelText("Name")).toHaveValue("Renamed draft");
+      expect(screen.getByLabelText(/^Name/)).toHaveValue("Renamed draft");
     });
   });
 
diff --git a/tests/unit/features/starter-work/NewStarterTaskModal.test.tsx b/tests/unit/features/starter-work/NewStarterTaskModal.test.tsx
index 07841c6dd..d1d7e62a6 100644
--- a/tests/unit/features/starter-work/NewStarterTaskModal.test.tsx
+++ b/tests/unit/features/starter-work/NewStarterTaskModal.test.tsx
@@ -22,7 +22,7 @@ describe("NewStarterTaskModal", () => {
     const user = userEvent.setup();
     const { onCreate } = renderModal();
 
-    await user.type(screen.getByLabelText("Title"), "Add dark mode");
+    await user.type(screen.getByLabelText(/^Title/), "Add dark mode");
     await user.click(screen.getByTestId("create-starter-task"));
 
     expect(onCreate).toHaveBeenCalledWith(
@@ -41,7 +41,7 @@ describe("NewStarterTaskModal", () => {
     const user = userEvent.setup();
     const { onCreate } = renderModal();
 
-    await user.type(screen.getByLabelText("Title"), "Add dark mode");
+    await user.type(screen.getByLabelText(/^Title/), "Add dark mode");
     await user.type(screen.getByLabelText(/Prerequisite competencies/i), "react,  typescript  css");
     await user.click(screen.getByTestId("create-starter-task"));
 
@@ -55,7 +55,7 @@ describe("NewStarterTaskModal", () => {
     const user = userEvent.setup();
     const { onClose } = renderModal({ onCreate: vi.fn().mockResolvedValue(true) });
 
-    await user.type(screen.getByLabelText("Title"), "Add dark mode");
+    await user.type(screen.getByLabelText(/^Title/), "Add dark mode");
     await user.click(screen.getByTestId("create-starter-task"));
 
     expect(onClose).toHaveBeenCalled();
@@ -65,7 +65,7 @@ describe("NewStarterTaskModal", () => {
     const user = userEvent.setup();
     const { onClose } = renderModal({ onCreate: vi.fn().mockResolvedValue(false) });
 
-    await user.type(screen.getByLabelText("Title"), "Add dark mode");
+    await user.type(screen.getByLabelText(/^Title/), "Add dark mode");
     await user.click(screen.getByTestId("create-starter-task"));
 
     expect(onClose).not.toHaveBeenCalled();
diff --git a/tests/unit/features/starter-work/StarterWorkSection.test.tsx b/tests/unit/features/starter-work/StarterWorkSection.test.tsx
index 5413ecad9..e9e7d6130 100644
--- a/tests/unit/features/starter-work/StarterWorkSection.test.tsx
+++ b/tests/unit/features/starter-work/StarterWorkSection.test.tsx
@@ -301,7 +301,7 @@ describe("StarterWorkSection", () => {
 
     await openAddMenu(user);
     await user.click(await screen.findByTestId("add-starter-task"));
-    await user.type(screen.getByLabelText("Title"), "Add a dark-mode toggle");
+    await user.type(screen.getByLabelText(/^Title/), "Add a dark-mode toggle");
     await user.click(screen.getByTestId("create-starter-task"));
 
     await waitFor(() =>

From b807180f3be0707eb8c05884e24fbbc2a06a246f Mon Sep 17 00:00:00 2001
From: Daniil Perkin <danetschka4pertschik@gmail.com>
Date: Mon, 28 Sep 2026 13:27:07 +0200
Subject: [PATCH 3/6] test(a11y): cover the sources step and the GitHub token
 flows
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Issue #242 asks for axe coverage of the wizard beyond the details step,
including both shapes of the "Add GitHub token" form: inline on a
narrow viewport, and as the portalled desktop companion where a second
dialog lives outside the wizard's own subtree.

- The walkthrough mirrors the main suite's helpers (details -> members
  -> sources, then into the GitHub detail) so the a11y tests exercise
  the real navigation instead of a shallow render.
- One test asserts the semantics end to end: Name announces
  aria-required, while Description and Industry are labelled
  "(optional)".
- The inline flow runs on the suite's default narrowest viewport; the
  companion test flips `mockViewport(true)` so `(min-width: 1280px)`
  matches and the form renders in CompanionModal. `baseElement` is the
  whole body, so axe sees both dialogs.

The keyboard-focus half of the issue is PR #268's fix
(hotfix/token-companion-keyboard-focus) and intentionally stays out of
this branch — this PR closes the label and semantics scope only.
---
 .../a11y/CreateProjectWizard.a11y.test.tsx    | 128 ++++++++++++++++--
 1 file changed, 115 insertions(+), 13 deletions(-)

diff --git a/tests/unit/a11y/CreateProjectWizard.a11y.test.tsx b/tests/unit/a11y/CreateProjectWizard.a11y.test.tsx
index bf84996e8..f1d1c52ce 100644
--- a/tests/unit/a11y/CreateProjectWizard.a11y.test.tsx
+++ b/tests/unit/a11y/CreateProjectWizard.a11y.test.tsx
@@ -1,8 +1,10 @@
-import { render, screen, waitFor } from "@testing-library/react";
-import { describe, it, expect, vi } from "vitest";
+import { act, render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeEach, describe, it, expect, vi } from "vitest";
 import { axe } from "vitest-axe";
 import { MemoryRouter } from "react-router-dom";
 import { CreateProjectWizard } from "../../../src/features/admin/components/CreateProjectWizard";
+import { mockViewport } from "../setup/matchMedia";
 
 vi.mock("../../../src/services/projectService", () => ({
   projectService: {
@@ -21,23 +23,123 @@ vi.mock("../../../src/services/sources/githubService", () => ({
   addGithubPat: vi.fn(),
 }));
 
+vi.mock("../../../src/services/ingestionService", () => ({
+  getIngestionSourceStatuses: vi.fn().mockResolvedValue([]),
+}));
+
+function renderWizard() {
+  return render(
+    <MemoryRouter>
+      <CreateProjectWizard
+        isOpen
+        tokenNames={["team-pat"]}
+        users={[]}
+        onClose={vi.fn()}
+        onProjectCreated={vi.fn()}
+      />
+    </MemoryRouter>,
+  );
+}
+
+/**
+ * Lets the modal's mount-time autofocus run before typing: `Modal` grabs focus
+ * inside a `requestAnimationFrame`, and a frame firing midway through typing
+ * would pull the caret off the field and drop the remaining keystrokes.
+ */
+async function settleModalFocus() {
+  await act(async () => {
+    await new Promise((resolve) => requestAnimationFrame(resolve));
+  });
+}
+
+/** Details → members → sources. */
+async function goToSources(user: ReturnType<typeof userEvent.setup>) {
+  await settleModalFocus();
+  await user.type(screen.getByLabelText(/^Name/), "Apollo");
+  await user.click(screen.getByRole("button", { name: /continue/i }));
+  await user.click(screen.getByRole("button", { name: /continue/i }));
+}
+
+/** From the sources step, open the add-source flow and pick the GitHub type. */
+async function openGithubDetail(user: ReturnType<typeof userEvent.setup>) {
+  await user.click(screen.getByRole("button", { name: /add source/i }));
+  await user.click(screen.getByRole("button", { name: /indexes repositories/i }));
+}
+
 describe("CreateProjectWizard Accessibility", () => {
+  beforeEach(() => {
+    // Narrowest layout by default — the credential form opens inline. The
+    // companion test flips this to a desktop viewport for itself.
+    mockViewport(false);
+  });
+
   it("has no axe violations on the details step", async () => {
-    const { baseElement } = render(
-      <MemoryRouter>
-        <CreateProjectWizard
-          isOpen
-          tokenNames={["team-pat"]}
-          users={[]}
-          onClose={vi.fn()}
-          onProjectCreated={vi.fn()}
-        />
-      </MemoryRouter>,
-    );
+    const { baseElement } = renderWizard();
+
+    await screen.findByRole("dialog", { name: "New Project" });
+    await waitFor(() => expect(screen.getByLabelText(/^Name/)).toBeInTheDocument());
+
+    expect(await axe(baseElement)).toHaveNoViolations();
+  });
+
+  it("carries required and optional semantics into the fields", async () => {
+    const { baseElement } = renderWizard();
+
+    await screen.findByRole("dialog", { name: "New Project" });
+    await waitFor(() => expect(screen.getByLabelText(/^Name/)).toBeInTheDocument());
+
+    // Required: announced on the control itself, since the asterisk is
+    // aria-hidden decoration. Optional: printed into the label everyone reads.
+    expect(screen.getByLabelText(/^Name/)).toHaveAttribute("aria-required", "true");
+    expect(screen.getByLabelText("Description (optional)")).toBeInTheDocument();
+    expect(screen.getByLabelText("Industry (optional)")).toBeInTheDocument();
+
+    expect(await axe(baseElement)).toHaveNoViolations();
+  });
+
+  it("has no axe violations on the sources step", async () => {
+    const user = userEvent.setup();
+    const { baseElement } = renderWizard();
+
+    await screen.findByRole("dialog", { name: "New Project" });
+    await waitFor(() => expect(screen.getByLabelText(/^Name/)).toBeInTheDocument());
+    await goToSources(user);
+
+    expect(screen.getByRole("button", { name: /add source/i })).toBeInTheDocument();
+    expect(await axe(baseElement)).toHaveNoViolations();
+  });
+
+  it("has no axe violations with the inline GitHub token form open", async () => {
+    const user = userEvent.setup();
+    const { baseElement } = renderWizard();
+
+    await screen.findByRole("dialog", { name: "New Project" });
+    await waitFor(() => expect(screen.getByLabelText(/^Name/)).toBeInTheDocument());
+    await goToSources(user);
+    await openGithubDetail(user);
+
+    await user.click(screen.getByRole("button", { name: /add github token/i }));
+
+    expect(await screen.findByLabelText(/^Token name/)).toHaveAttribute("aria-required", "true");
+    expect(screen.getByLabelText(/^Token \(ghp_/)).toHaveAttribute("aria-required", "true");
+    expect(await axe(baseElement)).toHaveNoViolations();
+  });
+
+  it("has no axe violations with the desktop token companion open", async () => {
+    mockViewport(true);
+    const user = userEvent.setup();
+    const { baseElement } = renderWizard();
 
     await screen.findByRole("dialog", { name: "New Project" });
     await waitFor(() => expect(screen.getByLabelText(/^Name/)).toBeInTheDocument());
+    await goToSources(user);
+    await openGithubDetail(user);
+
+    await user.click(screen.getByRole("button", { name: /add github token/i }));
 
+    // At or above 1280px the form slides in beside the wizard, portalled to
+    // <body> — `baseElement` is the whole body, so axe sees it too.
+    expect(await screen.findByRole("dialog", { name: "New GitHub token" })).toBeInTheDocument();
     expect(await axe(baseElement)).toHaveNoViolations();
   });
 });

From 276a0d905861596cacb55140b7c6052092f2a28a Mon Sep 17 00:00:00 2001
From: Daniil Perkin <danetschka4pertschik@gmail.com>
Date: Mon, 28 Sep 2026 14:08:50 +0200
Subject: [PATCH 4/6] fix(settings): mark the Atlassian row's credential forms
 as required
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review round on #275 found the sweep had a hole: the inline Rename and
Rotate panels in AtlassianCredentialRow wrapped `<Input required>` in a
`Field` that never declared `required`. The control still announced
itself (`aria-required` comes from the input itself), but the label
carried no asterisk — the one place in the tree where the visual mark
and the semantics disagreed.

- Both Fields ("New name", "New API token") now say `required`, which is
  exactly what the panels already enforce: the inputs carry the HTML
  `required` attribute and the row's mutations are submit-driven.
- The fix is verified mechanically, not just by eye: a JSX-block sweep
  over `src/` for "control declares required, enclosing Field does not"
  now returns zero hits (the regex runs against `=>`-normalised source,
  since arrow props otherwise truncate the tag match).
- A regression test opens both panels and pins the mark plus
  `aria-required` on the field, so this class of omission cannot return
  silently for the row.
---
 .../atlassian/AtlassianCredentialRow.tsx      |  2 ++
 .../atlassian/AtlassianCredentialRow.test.tsx | 30 +++++++++++++++++++
 2 files changed, 32 insertions(+)
 create mode 100644 tests/unit/features/settings/components/atlassian/AtlassianCredentialRow.test.tsx

diff --git a/src/features/settings/components/atlassian/AtlassianCredentialRow.tsx b/src/features/settings/components/atlassian/AtlassianCredentialRow.tsx
index 2f10e064a..58d8cd520 100644
--- a/src/features/settings/components/atlassian/AtlassianCredentialRow.tsx
+++ b/src/features/settings/components/atlassian/AtlassianCredentialRow.tsx
@@ -199,6 +199,7 @@ export function AtlassianCredentialRow({ credential, onSaved }: AtlassianCredent
               <Field
                 label="New name"
                 controlId={`settings-atlassian-rename-${displayName}`}
+                required
                 disabled={isBusy}
                 className="min-w-0 flex-1"
               >
@@ -248,6 +249,7 @@ export function AtlassianCredentialRow({ credential, onSaved }: AtlassianCredent
               <Field
                 label="New API token"
                 controlId={`settings-atlassian-rotate-${displayName}`}
+                required
                 disabled={isBusy}
                 className="min-w-0 flex-1"
               >
diff --git a/tests/unit/features/settings/components/atlassian/AtlassianCredentialRow.test.tsx b/tests/unit/features/settings/components/atlassian/AtlassianCredentialRow.test.tsx
new file mode 100644
index 000000000..a54a6bd3d
--- /dev/null
+++ b/tests/unit/features/settings/components/atlassian/AtlassianCredentialRow.test.tsx
@@ -0,0 +1,30 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, it, expect, vi } from "vitest";
+import { AtlassianCredentialRow } from "../../../../../../src/features/settings/components/atlassian/AtlassianCredentialRow.tsx";
+
+const credential = { userEmail: "ada@example.com", displayName: "work" };
+
+describe("AtlassianCredentialRow field marks", () => {
+  it("marks the rename field as required", async () => {
+    const user = userEvent.setup();
+    render(<AtlassianCredentialRow credential={credential} onSaved={vi.fn(async () => {})} />);
+
+    await user.click(screen.getByRole("button", { name: /rename credential/i }));
+
+    expect(screen.getByLabelText(/^New name/)).toHaveAttribute("aria-required", "true");
+    // The visual half of the same fact: both credential forms are gated by a
+    // `required` input, so their labels have to say so too.
+    expect(screen.getByText("*")).toBeInTheDocument();
+  });
+
+  it("marks the rotate field as required", async () => {
+    const user = userEvent.setup();
+    render(<AtlassianCredentialRow credential={credential} onSaved={vi.fn(async () => {})} />);
+
+    await user.click(screen.getByRole("button", { name: /rotate token/i }));
+
+    expect(screen.getByLabelText(/^New API token/)).toHaveAttribute("aria-required", "true");
+    expect(screen.getByText("*")).toBeInTheDocument();
+  });
+});

From 0599d48c73db6bb6baa5323f6676fdc36e4b393a Mon Sep 17 00:00:00 2001
From: Daniil Perkin <danetschka4pertschik@gmail.com>
Date: Mon, 28 Sep 2026 14:08:50 +0200
Subject: [PATCH 5/6] test(a11y): put the viewport mock back after the
 companion check
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`mockViewport` swaps the global `matchMedia` out and never restores it —
unlike `mockResizableViewport`, which ships a `restore()` for exactly
this reason. The wizard a11y suite flips to a desktop viewport for its
last test, so without a reset any test appended after it would silently
inherit `min-width: true`.

Cross-file pollution was never possible (Vitest isolates each test file
in a fresh environment; the repo leaves `isolate` at its default), so
this is about the file staying order-independent as it grows, not about
a bug in the gate. The reset puts the suite default (narrowest) back.
---
 tests/unit/a11y/CreateProjectWizard.a11y.test.tsx | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/tests/unit/a11y/CreateProjectWizard.a11y.test.tsx b/tests/unit/a11y/CreateProjectWizard.a11y.test.tsx
index f1d1c52ce..bcc385432 100644
--- a/tests/unit/a11y/CreateProjectWizard.a11y.test.tsx
+++ b/tests/unit/a11y/CreateProjectWizard.a11y.test.tsx
@@ -1,6 +1,6 @@
 import { act, render, screen, waitFor } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
-import { beforeEach, describe, it, expect, vi } from "vitest";
+import { afterEach, beforeEach, describe, it, expect, vi } from "vitest";
 import { axe } from "vitest-axe";
 import { MemoryRouter } from "react-router-dom";
 import { CreateProjectWizard } from "../../../src/features/admin/components/CreateProjectWizard";
@@ -73,6 +73,13 @@ describe("CreateProjectWizard Accessibility", () => {
     mockViewport(false);
   });
 
+  afterEach(() => {
+    // `mockViewport` swaps the global `matchMedia` out without restoring it.
+    // Put the suite default (narrowest) back, so a test added after the
+    // desktop-flipping one cannot inherit the wide viewport by accident.
+    mockViewport(false);
+  });
+
   it("has no axe violations on the details step", async () => {
     const { baseElement } = renderWizard();
 

From 7ac15cc0ba793ec3c366fb3ab9519b2daaa9c002 Mon Sep 17 00:00:00 2001
From: Daniil Perkin <danetschka4pertschik@gmail.com>
Date: Mon, 28 Sep 2026 16:07:22 +0200
Subject: [PATCH 6/6] docs(ui): spell out that Field's required is ARIA, not
 native validation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

kiranfin's review flagged the one thing the new prop does not do: a
`Field`-only `required` never reaches the browser's constraint
validation, so the wrapped control gets `aria-required` but no native
`required` attribute — no `:required` styling, no "fill out this field"
popup. That is deliberate (the app's forms gate their own submits and
show inline errors; flipping native validation on from a label-level
flag would replace those messages with browser chrome behind the form's
back), but nothing in the code said so, which makes it a trap for the
next caller who wants the browser to do the validating.

- `Field`'s `required` doc now states the boundary and points at the
  escape hatch: pass `required` to the control itself when the native
  attribute is wanted.
- `fieldContext`'s `required` carries the matching note, since that is
  where a control author reads it.
- A unit test pins the contract rather than trusting the comment: a
  Field-only mark leaves `input.required === false` (and the attribute
  off), while a control-level `required` still lands on the element.

No behaviour changes — this is the documentation/hardening option from
the review, not the flow-through alternative, which would have changed
runtime validation semantics across ten forms.
---
 src/components/ui/Field.tsx             |  8 ++++++++
 src/components/ui/fieldContext.ts       |  4 +++-
 tests/unit/components/ui/Field.test.tsx | 25 +++++++++++++++++++++++++
 3 files changed, 36 insertions(+), 1 deletion(-)

diff --git a/src/components/ui/Field.tsx b/src/components/ui/Field.tsx
index b55e64730..32e2a900a 100644
--- a/src/components/ui/Field.tsx
+++ b/src/components/ui/Field.tsx
@@ -20,6 +20,14 @@ export type FieldProps = {
    * Appends the conventional asterisk and carries the semantics through
    * context, so the wrapped control also gets `aria-required` — the asterisk
    * itself is `aria-hidden` and invisible to a screen reader.
+   *
+   * Presentation and ARIA, not constraint validation: this does **not** put the
+   * native `required` attribute on the wrapped control, so no `:required`
+   * styling and no browser "fill out this field" popup appear. The forms in
+   * this app validate themselves — guarded submit buttons, inline errors — and
+   * a label-level flag should not switch browser validation on behind their
+   * backs. Pass `required` to the control itself when the native attribute is
+   * wanted; the two stay separate on purpose.
    */
   required?: boolean;
   /**
diff --git a/src/components/ui/fieldContext.ts b/src/components/ui/fieldContext.ts
index 707c25486..8d4396a1a 100644
--- a/src/components/ui/fieldContext.ts
+++ b/src/components/ui/fieldContext.ts
@@ -15,7 +15,9 @@ export type FieldContextValue = {
   /**
    * Mirrors `Field`'s `required`, so the control can put `aria-required` on the
    * real element — the asterisk in the label is `aria-hidden` decoration and
-   * tells assistive tech nothing on its own.
+   * tells assistive tech nothing on its own. The native `required` attribute is
+   * deliberately left to the caller: this flag is ARIA, not constraint
+   * validation.
    */
   required: boolean;
 };
diff --git a/tests/unit/components/ui/Field.test.tsx b/tests/unit/components/ui/Field.test.tsx
index c7c5e1c18..90182219b 100644
--- a/tests/unit/components/ui/Field.test.tsx
+++ b/tests/unit/components/ui/Field.test.tsx
@@ -155,6 +155,31 @@ describe("Field", () => {
     expect(screen.getByLabelText("Search")).toHaveAttribute("aria-required", "true");
   });
 
+  it("keeps the browser's own constraint validation off unless the control asks for it", () => {
+    const { rerender } = render(
+      <Field label="Name" required>
+        <Input />
+      </Field>,
+    );
+
+    // The field mark is presentation and ARIA: no native attribute, so no
+    // `:required` styling and no browser "fill out this field" popup — these
+    // forms gate their own submits with guards and inline errors.
+    const fieldOnly = screen.getByLabelText(/^Name/);
+    expect(fieldOnly).not.toHaveAttribute("required");
+    expect((fieldOnly as HTMLInputElement).required).toBe(false);
+
+    rerender(
+      <Field label="Name" required>
+        <Input required />
+      </Field>,
+    );
+
+    const controlLevel = screen.getByLabelText(/^Name/);
+    expect(controlLevel).toHaveAttribute("required");
+    expect((controlLevel as HTMLInputElement).required).toBe(true);
+  });
+
   it("lets an explicit aria-required on the control override the field", () => {
     render(
       <Field label="Name" required>