From 06bfdd55caaa42e441c93b14b5c34abbdfc84e6e Mon Sep 17 00:00:00 2001
From: Guido X Jansen <x@gui.do>
Date: Wed, 04 Mar 2026 18:23:46 +0000
Subject: [PATCH] feat(a11y): add required/optional indicators to all form fields (#169)

* feat(a11y): add required/optional indicators to all form fields

Create shared FormLabel component with aria-hidden asterisks for required
fields and "(optional)" text for optional fields. Replaces 13 raw <label>
elements across all forms. Adds HTML required attribute to required inputs.
Fixes accessibility bug in onboarding-field-input.tsx where asterisk
lacked aria-hidden. Updates test queries to use getByRole (which respects
aria-hidden) instead of getByLabelText.

* style: format with prettier
---
 src/components/community-profile-form-fields.tsx | 12 +++++-------
 src/components/markdown-editor.tsx | 10 ++++++++--
 src/components/onboarding-field-input.tsx | 108 +++++++++++++++++++++++++++++++++++++++++++-----------------------------------------------------------------
 src/components/report-form-content.tsx | 14 ++++++++++----
 src/components/topic-content-editor.tsx | 9 ++++++++-
 src/components/topic-form.test.tsx | 20 ++++++++++----------
 src/components/topic-form.tsx | 2 +-
 src/components/topic-meta-fields.tsx | 15 +++++++++------
 src/app/login/page.tsx | 6 ++++--
 src/app/new/page.test.tsx | 4 ++--
 src/components/settings/report-appeal-form.tsx | 13 +++++++------
 src/components/ui/form-label.tsx | 33 +++++++++++++++++++++++++++++++++
 src/app/admin/onboarding/page.test.tsx | 37 +++++++++++++++++++++++--------------
 src/components/admin/categories/category-form.tsx | 20 ++++++++++++--------
 src/components/admin/onboarding/onboarding-field-form.tsx | 23 +++++++++++++----------
 src/components/admin/pages/page-form.tsx | 29 +++++++++++++++--------------
 src/components/admin/settings/community-settings-form.tsx | 26 +++++++++++++-------------
 src/components/admin/settings/pds-override-dialog.tsx | 9 +++++----
 src/components/admin/trust-seeds/add-seed-dialog.tsx | 11 ++++++-----
 19 file(s) changed, 227 insertion(s)(+), 174 deletion(s)(-)

diff --git a/src/components/community-profile-form-fields.tsx b/src/components/community-profile-form-fields.tsx
--- a/src/components/community-profile-form-fields.tsx
+++ b/src/components/community-profile-form-fields.tsx
@@ -4,6 +4,7 @@
  */
 
 import { cn } from '@/lib/utils'
+import { FormLabel } from '@/components/ui/form-label'
 
 const DISPLAY_NAME_MAX = 256
 const BIO_MAX = 2048
@@ -28,12 +29,9 @@
   return (
     <>
       <div className="space-y-1">
-        <label
-          htmlFor="community-display-name"
-          className="block text-sm font-medium text-foreground"
-        >
+        <FormLabel htmlFor="community-display-name" optional>
           Display name
-        </label>
+        </FormLabel>
         <input
           id="community-display-name"
           type="text"
@@ -53,9 +51,9 @@
       </div>
 
       <div className="space-y-1">
-        <label htmlFor="community-bio" className="block text-sm font-medium text-foreground">
+        <FormLabel htmlFor="community-bio" optional>
           Bio
-        </label>
+        </FormLabel>
         <textarea
           id="community-bio"
           value={bio}
diff --git a/src/components/markdown-editor.tsx b/src/components/markdown-editor.tsx
--- a/src/components/markdown-editor.tsx
+++ b/src/components/markdown-editor.tsx
@@ -9,6 +9,7 @@
 
 import { useRef, useState, useCallback } from 'react'
 import { cn } from '@/lib/utils'
+import { FormLabel } from '@/components/ui/form-label'
 import { TOOLBAR_ACTIONS } from '@/components/markdown-toolbar-actions'
 import type { ToolbarAction } from '@/components/markdown-toolbar-actions'
 
@@ -17,6 +18,8 @@
   onChange: (value: string) => void
   id: string
   label: string
+  required?: boolean
+  optional?: boolean
   error?: string
   className?: string
   placeholder?: string
@@ -27,6 +30,8 @@
   onChange,
   id,
   label,
+  required,
+  optional,
   error,
   className,
   placeholder,
@@ -87,9 +92,9 @@
 
   return (
     <div className={cn('space-y-1', className)}>
-      <label htmlFor={id} className="block text-sm font-medium text-foreground">
+      <FormLabel htmlFor={id} required={required} optional={optional}>
         {label}
-      </label>
+      </FormLabel>
 
       <div
         ref={toolbarRef}
@@ -123,6 +128,7 @@
         value={value}
         onChange={(e) => onChange(e.target.value)}
         placeholder={placeholder ?? 'Write your content using Markdown...'}
+        required={required}
         aria-invalid={error ? 'true' : undefined}
         aria-describedby={errorId}
         className={cn(
diff --git a/src/components/onboarding-field-input.tsx b/src/components/onboarding-field-input.tsx
--- a/src/components/onboarding-field-input.tsx
+++ b/src/components/onboarding-field-input.tsx
@@ -5,36 +5,10 @@
 
 import type { OnboardingField } from '@/lib/api/types'
 import { AGE_OPTIONS } from '@/lib/constants'
+import { FormLabel } from '@/components/ui/form-label'
 
 const INPUT_CLASS =
   'mt-1 w-full rounded-md border border-border bg-background px-3 py-2 text-sm text-foreground'
-
-function FieldLabel({
-  htmlFor,
-  label,
-  required,
-  description,
-  block = true,
-}: {
-  htmlFor: string
-  label: string
-  required: boolean
-  description?: string | null
-  block?: boolean
-}) {
-  return (
-    <>
-      <label
-        htmlFor={htmlFor}
-        className={`${block ? 'block ' : ''}text-sm font-medium text-foreground`}
-      >
-        {label}
-        {required && <span className="ml-1 text-destructive">*</span>}
-      </label>
-      {description && <p className="mt-0.5 text-xs text-muted-foreground">{description}</p>}
-    </>
-  )
-}
 
 interface OnboardingFieldInputProps {
   field: OnboardingField
@@ -50,16 +24,17 @@
     case 'age_confirmation':
       return (
         <div>
-          <FieldLabel
-            htmlFor={labelId}
-            label={field.label}
-            required={required}
-            description={field.description}
-          />
+          <FormLabel htmlFor={labelId} required={required} optional={!required}>
+            {field.label}
+          </FormLabel>
+          {field.description && (
+            <p className="mt-0.5 text-xs text-muted-foreground">{field.description}</p>
+          )}
           <select
             id={labelId}
             value={value !== undefined ? String(value) : ''}
             onChange={(e) => onChange(e.target.value === '' ? undefined : Number(e.target.value))}
+            required={required}
             className={INPUT_CLASS}
           >
             <option value="">Select age bracket...</option>
@@ -81,16 +56,16 @@
             type="checkbox"
             checked={value === true}
             onChange={(e) => onChange(e.target.checked)}
+            required={required}
             className="mt-1 h-4 w-4 rounded border-border"
           />
           <div>
-            <FieldLabel
-              htmlFor={labelId}
-              label={field.label}
-              required={required}
-              description={field.description}
-              block={false}
-            />
+            <FormLabel htmlFor={labelId} required={required} optional={!required} block={false}>
+              {field.label}
+            </FormLabel>
+            {field.description && (
+              <p className="mt-0.5 text-xs text-muted-foreground">{field.description}</p>
+            )}
             {tosUrl && (
               <a
                 href={tosUrl}
@@ -114,16 +89,16 @@
             type="checkbox"
             checked={value === true}
             onChange={(e) => onChange(e.target.checked)}
+            required={required}
             className="mt-1 h-4 w-4 rounded border-border"
           />
           <div>
-            <FieldLabel
-              htmlFor={labelId}
-              label={field.label}
-              required={required}
-              description={field.description}
-              block={false}
-            />
+            <FormLabel htmlFor={labelId} required={required} optional={!required} block={false}>
+              {field.label}
+            </FormLabel>
+            {field.description && (
+              <p className="mt-0.5 text-xs text-muted-foreground">{field.description}</p>
+            )}
           </div>
         </div>
       )
@@ -131,18 +106,19 @@
     case 'newsletter_email':
       return (
         <div>
-          <FieldLabel
-            htmlFor={labelId}
-            label={field.label}
-            required={required}
-            description={field.description}
-          />
+          <FormLabel htmlFor={labelId} required={required} optional={!required}>
+            {field.label}
+          </FormLabel>
+          {field.description && (
+            <p className="mt-0.5 text-xs text-muted-foreground">{field.description}</p>
+          )}
           <input
             id={labelId}
             type="email"
             value={typeof value === 'string' ? value : ''}
             onChange={(e) => onChange(e.target.value || undefined)}
             placeholder="your@email.com"
+            required={required}
             className={INPUT_CLASS}
           />
         </div>
@@ -151,17 +127,18 @@
     case 'custom_text':
       return (
         <div>
-          <FieldLabel
-            htmlFor={labelId}
-            label={field.label}
-            required={required}
-            description={field.description}
-          />
+          <FormLabel htmlFor={labelId} required={required} optional={!required}>
+            {field.label}
+          </FormLabel>
+          {field.description && (
+            <p className="mt-0.5 text-xs text-muted-foreground">{field.description}</p>
+          )}
           <textarea
             id={labelId}
             value={typeof value === 'string' ? value : ''}
             onChange={(e) => onChange(e.target.value || undefined)}
             rows={3}
+            required={required}
             className={INPUT_CLASS}
           />
         </div>
@@ -171,16 +148,17 @@
       const options = (field.config?.options ?? []) as string[]
       return (
         <div>
-          <FieldLabel
-            htmlFor={labelId}
-            label={field.label}
-            required={required}
-            description={field.description}
-          />
+          <FormLabel htmlFor={labelId} required={required} optional={!required}>
+            {field.label}
+          </FormLabel>
+          {field.description && (
+            <p className="mt-0.5 text-xs text-muted-foreground">{field.description}</p>
+          )}
           <select
             id={labelId}
             value={typeof value === 'string' ? value : ''}
             onChange={(e) => onChange(e.target.value || undefined)}
+            required={required}
             className={INPUT_CLASS}
           >
             <option value="">Select...</option>
diff --git a/src/components/report-form-content.tsx b/src/components/report-form-content.tsx
--- a/src/components/report-form-content.tsx
+++ b/src/components/report-form-content.tsx
@@ -4,6 +4,7 @@
  */
 
 import { cn } from '@/lib/utils'
+import { FormLabel } from '@/components/ui/form-label'
 
 const REPORT_REASONS = [
   { value: 'spam', label: 'Spam' },
@@ -45,7 +46,12 @@
 
       <form onSubmit={onSubmit} className="mt-4 space-y-4" noValidate>
         <fieldset disabled={submitting}>
-          <legend className="text-sm font-medium text-foreground">Reason</legend>
+          <legend className="text-sm font-medium text-foreground">
+            Reason
+            <span aria-hidden="true" className="ml-1 text-destructive">
+              *
+            </span>
+          </legend>
           <div className="mt-2 space-y-2">
             {REPORT_REASONS.map((r) => (
               <label key={r.value} className="flex items-center gap-2">
@@ -72,14 +78,14 @@
         </fieldset>
 
         <div className="space-y-1">
-          <label htmlFor="report-details" className="block text-sm font-medium text-foreground">
+          <FormLabel htmlFor="report-details" optional>
             Additional details
-          </label>
+          </FormLabel>
           <textarea
             id="report-details"
             value={details}
             onChange={(e) => onDetailsChange(e.target.value)}
-            placeholder="Optional: provide more context"
+            placeholder="Provide more context"
             rows={3}
             disabled={submitting}
             className={cn(
diff --git a/src/components/topic-content-editor.tsx b/src/components/topic-content-editor.tsx
--- a/src/components/topic-content-editor.tsx
+++ b/src/components/topic-content-editor.tsx
@@ -14,9 +14,15 @@
   content: string
   onChange: (content: string) => void
   error?: string
+  required?: boolean
 }
 
-export function TopicContentEditor({ content, onChange, error }: TopicContentEditorProps) {
+export function TopicContentEditor({
+  content,
+  onChange,
+  error,
+  required,
+}: TopicContentEditorProps) {
   const [activeTab, setActiveTab] = useState<'write' | 'preview'>('write')
 
   return (
@@ -67,6 +73,7 @@
           onChange={onChange}
           id="topic-content"
           label="Content"
+          required={required}
           error={error}
         />
       </div>
diff --git a/src/components/topic-form.test.tsx b/src/components/topic-form.test.tsx
--- a/src/components/topic-form.test.tsx
+++ b/src/components/topic-form.test.tsx
@@ -26,22 +26,22 @@
 describe('TopicForm', () => {
   it('renders title input', () => {
     render(<TopicForm onSubmit={vi.fn()} />)
-    expect(screen.getByLabelText('Title')).toBeInTheDocument()
+    expect(screen.getByRole('textbox', { name: 'Title' })).toBeInTheDocument()
   })
 
   it('renders category select', () => {
     render(<TopicForm onSubmit={vi.fn()} />)
-    expect(screen.getByLabelText('Category')).toBeInTheDocument()
+    expect(screen.getByRole('combobox', { name: 'Category' })).toBeInTheDocument()
   })
 
   it('renders tag input', () => {
     render(<TopicForm onSubmit={vi.fn()} />)
-    expect(screen.getByLabelText('Tags')).toBeInTheDocument()
+    expect(screen.getByRole('textbox', { name: /Tags/ })).toBeInTheDocument()
   })
 
   it('renders content editor', () => {
     render(<TopicForm onSubmit={vi.fn()} />)
-    expect(screen.getByLabelText('Content')).toBeInTheDocument()
+    expect(screen.getByRole('textbox', { name: 'Content' })).toBeInTheDocument()
   })
 
   it('renders cross-post checkboxes', () => {
@@ -95,7 +95,7 @@
     const onSubmit = vi.fn()
     render(<TopicForm onSubmit={onSubmit} />)
 
-    await user.type(screen.getByLabelText('Title'), 'Test Title')
+    await user.type(screen.getByRole('textbox', { name: 'Title' }), 'Test Title')
     await user.click(screen.getByRole('button', { name: 'Create Topic' }))
     expect(screen.getByText('Content is required')).toBeInTheDocument()
     expect(onSubmit).not.toHaveBeenCalled()
@@ -106,8 +106,8 @@
     const onSubmit = vi.fn()
     render(<TopicForm onSubmit={onSubmit} />)
 
-    await user.type(screen.getByLabelText('Title'), 'Test Title')
-    await user.type(screen.getByLabelText('Content'), 'Test content')
+    await user.type(screen.getByRole('textbox', { name: 'Title' }), 'Test Title')
+    await user.type(screen.getByRole('textbox', { name: 'Content' }), 'Test content')
     await user.click(screen.getByRole('button', { name: 'Create Topic' }))
     expect(screen.getByText('Category is required')).toBeInTheDocument()
     expect(onSubmit).not.toHaveBeenCalled()
@@ -118,7 +118,7 @@
     const onSubmit = vi.fn()
     render(<TopicForm onSubmit={onSubmit} />)
 
-    await user.type(screen.getByLabelText('Title'), 'AB')
+    await user.type(screen.getByRole('textbox', { name: 'Title' }), 'AB')
     await user.click(screen.getByRole('button', { name: 'Create Topic' }))
     expect(screen.getByText('Title must be at least 3 characters')).toBeInTheDocument()
     expect(onSubmit).not.toHaveBeenCalled()
@@ -148,8 +148,8 @@
         mode="edit"
       />
     )
-    expect(screen.getByLabelText('Title')).toHaveValue('Existing Topic')
-    expect(screen.getByLabelText('Content')).toHaveValue('Existing content')
+    expect(screen.getByRole('textbox', { name: 'Title' })).toHaveValue('Existing Topic')
+    expect(screen.getByRole('textbox', { name: 'Content' })).toHaveValue('Existing content')
   })
 
   it('passes axe accessibility check', async () => {
diff --git a/src/components/topic-form.tsx b/src/components/topic-form.tsx
--- a/src/components/topic-form.tsx
+++ b/src/components/topic-form.tsx
@@ -103,7 +103,7 @@
         onTagInputChange={setTagInput}
       />
 
-      <TopicContentEditor content={content} onChange={setContent} error={errors.content} />
+      <TopicContentEditor content={content} onChange={setContent} error={errors.content} required />
 
       {mode === 'create' && (
         <TopicCrossPostSection
diff --git a/src/components/topic-meta-fields.tsx b/src/components/topic-meta-fields.tsx
--- a/src/components/topic-meta-fields.tsx
+++ b/src/components/topic-meta-fields.tsx
@@ -4,6 +4,7 @@
  */
 
 import { cn } from '@/lib/utils'
+import { FormLabel } from '@/components/ui/form-label'
 
 interface TopicMetaFieldsProps {
   title: string
@@ -29,15 +30,16 @@
   return (
     <>
       <div className="space-y-1">
-        <label htmlFor="topic-title" className="block text-sm font-medium text-foreground">
+        <FormLabel htmlFor="topic-title" required>
           Title
-        </label>
+        </FormLabel>
         <input
           id="topic-title"
           type="text"
           value={title}
           onChange={(e) => onTitleChange(e.target.value)}
           placeholder="Enter a descriptive title"
+          required
           aria-invalid={errors.title ? 'true' : undefined}
           aria-describedby={errors.title ? 'topic-title-error' : undefined}
           className={cn(
@@ -54,13 +56,14 @@
       </div>
 
       <div className="space-y-1">
-        <label htmlFor="topic-category" className="block text-sm font-medium text-foreground">
+        <FormLabel htmlFor="topic-category" required>
           Category
-        </label>
+        </FormLabel>
         <select
           id="topic-category"
           value={category}
           onChange={(e) => onCategoryChange(e.target.value)}
+          required
           aria-invalid={errors.category ? 'true' : undefined}
           aria-describedby={errors.category ? 'topic-category-error' : undefined}
           className={cn(
@@ -84,9 +87,9 @@
       </div>
 
       <div className="space-y-1">
-        <label htmlFor="topic-tags" className="block text-sm font-medium text-foreground">
+        <FormLabel htmlFor="topic-tags" optional>
           Tags
-        </label>
+        </FormLabel>
         <input
           id="topic-tags"
           type="text"
diff --git a/src/app/login/page.tsx b/src/app/login/page.tsx
--- a/src/app/login/page.tsx
+++ b/src/app/login/page.tsx
@@ -14,6 +14,7 @@
 import { useAuth } from '@/hooks/use-auth'
 import { ApiError } from '@/lib/api/client'
 import { cn } from '@/lib/utils'
+import { FormLabel } from '@/components/ui/form-label'
 
 function LoginContent() {
   const { login, isAuthenticated, isLoading } = useAuth()
@@ -110,9 +111,9 @@
           )}
 
           <div className="space-y-1">
-            <label htmlFor="handle" className="block text-sm font-medium text-foreground">
+            <FormLabel htmlFor="handle" required>
               Handle
-            </label>
+            </FormLabel>
             <input
               id="handle"
               name="handle"
@@ -121,6 +122,7 @@
               onChange={(e) => setHandle(e.target.value)}
               placeholder="jay.bsky.team"
               autoComplete="username"
+              required
               disabled={submitting}
               className={cn(
                 'block w-full rounded-md border border-border bg-background px-3 py-2 text-sm text-foreground placeholder:text-muted-foreground',
diff --git a/src/app/new/page.test.tsx b/src/app/new/page.test.tsx
--- a/src/app/new/page.test.tsx
+++ b/src/app/new/page.test.tsx
@@ -76,8 +76,8 @@
 
   it('renders topic form', () => {
     render(<NewTopicPage />)
-    expect(screen.getByLabelText('Title')).toBeInTheDocument()
-    expect(screen.getByLabelText('Content')).toBeInTheDocument()
+    expect(screen.getByRole('textbox', { name: 'Title' })).toBeInTheDocument()
+    expect(screen.getByRole('textbox', { name: 'Content' })).toBeInTheDocument()
     expect(screen.getByRole('button', { name: 'Create Topic' })).toBeInTheDocument()
   })
 
diff --git a/src/components/settings/report-appeal-form.tsx b/src/components/settings/report-appeal-form.tsx
--- a/src/components/settings/report-appeal-form.tsx
+++ b/src/components/settings/report-appeal-form.tsx
@@ -4,6 +4,7 @@
  */
 
 import { cn } from '@/lib/utils'
+import { FormLabel } from '@/components/ui/form-label'
 
 interface ReportAppealFormProps {
   reportId: number
@@ -27,19 +28,19 @@
   return (
     <form onSubmit={onAppealSubmit} className="space-y-3" noValidate>
       <div className="space-y-1">
-        <label
-          htmlFor={`appeal-reason-${reportId}`}
-          className="block text-sm font-medium text-foreground"
-        >
+        <FormLabel htmlFor={`appeal-reason-${reportId}`} required>
           Reason for appeal
-        </label>
+        </FormLabel>
         <textarea
           id={`appeal-reason-${reportId}`}
           value={appealReason}
           onChange={(e) => onAppealReasonChange(e.target.value)}
           placeholder="Explain why you believe this report should be reconsidered"
           rows={3}
+          required
           disabled={appealSubmitting}
+          aria-invalid={appealError ? 'true' : undefined}
+          aria-describedby={appealError ? `appeal-error-${reportId}` : undefined}
           className={cn(
             'block w-full rounded-md border border-border bg-background px-3 py-2 text-sm text-foreground placeholder:text-muted-foreground',
             'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
@@ -47,7 +48,7 @@
           )}
         />
         {appealError && (
-          <p className="text-sm text-destructive" role="alert">
+          <p id={`appeal-error-${reportId}`} className="text-sm text-destructive" role="alert">
             {appealError}
           </p>
         )}
diff --git a/src/components/ui/form-label.tsx b/src/components/ui/form-label.tsx
new file mode 100644
--- /dev/null
+++ b/src/components/ui/form-label.tsx
@@ -0,0 +1,33 @@
+import { cn } from '@/lib/utils'
+
+interface FormLabelProps extends React.LabelHTMLAttributes<HTMLLabelElement> {
+  required?: boolean
+  optional?: boolean
+  block?: boolean
+}
+
+export function FormLabel({
+  required,
+  optional,
+  block = true,
+  children,
+  className,
+  ...props
+}: FormLabelProps) {
+  return (
+    <label
+      className={cn(block && 'block', 'text-sm font-medium text-foreground', className)}
+      {...props}
+    >
+      {children}
+      {required && (
+        <span aria-hidden="true" className="ml-1 text-destructive">
+          *
+        </span>
+      )}
+      {optional && (
+        <span className="ml-1.5 text-xs font-normal text-muted-foreground">(optional)</span>
+      )}
+    </label>
+  )
+}
diff --git a/src/app/admin/onboarding/page.test.tsx b/src/app/admin/onboarding/page.test.tsx
--- a/src/app/admin/onboarding/page.test.tsx
+++ b/src/app/admin/onboarding/page.test.tsx
@@ -100,8 +100,8 @@
     const user = userEvent.setup()
     render(<AdminOnboardingPage />)
     await user.click(screen.getByRole('button', { name: /add field/i }))
-    expect(screen.getByLabelText(/field type/i)).toBeInTheDocument()
-    expect(screen.getByLabelText(/^label$/i)).toBeInTheDocument()
+    expect(screen.getByRole('combobox', { name: /field type/i })).toBeInTheDocument()
+    expect(screen.getByRole('textbox', { name: /^label$/i })).toBeInTheDocument()
   })
 
   it('shows edit form when edit button is clicked', async () => {
@@ -112,7 +112,7 @@
     })
     const editButtons = screen.getAllByRole('button', { name: /edit/i })
     await user.click(editButtons[0]!)
-    expect(screen.getByLabelText(/^label$/i)).toBeInTheDocument()
+    expect(screen.getByRole('textbox', { name: /^label$/i })).toBeInTheDocument()
   })
 
   it('hides field type selector when editing existing field', async () => {
@@ -123,7 +123,7 @@
     })
     const editButtons = screen.getAllByRole('button', { name: /edit/i })
     await user.click(editButtons[0]!)
-    expect(screen.queryByLabelText(/field type/i)).not.toBeInTheDocument()
+    expect(screen.queryByRole('combobox', { name: /field type/i })).not.toBeInTheDocument()
   })
 
   it('shows validation error when saving with empty label', async () => {
@@ -138,9 +138,9 @@
     const user = userEvent.setup()
     render(<AdminOnboardingPage />)
     await user.click(screen.getByRole('button', { name: /add field/i }))
-    expect(screen.getByLabelText(/^label$/i)).toBeInTheDocument()
+    expect(screen.getByRole('textbox', { name: /^label$/i })).toBeInTheDocument()
     await user.click(screen.getByRole('button', { name: /cancel/i }))
-    expect(screen.queryByLabelText(/^label$/i)).not.toBeInTheDocument()
+    expect(screen.queryByRole('textbox', { name: /^label$/i })).not.toBeInTheDocument()
   })
 
   it('renders reorder buttons for each field', async () => {
@@ -234,18 +234,21 @@
     render(<AdminOnboardingPage />)
     await user.click(screen.getByRole('button', { name: /add field/i }))
     // Default type is custom_text -- no ToS URL input yet
-    expect(screen.queryByLabelText(/terms of service url/i)).not.toBeInTheDocument()
+    expect(screen.queryByRole('textbox', { name: /terms of service url/i })).not.toBeInTheDocument()
     // Switch to tos_acceptance
-    await user.selectOptions(screen.getByLabelText(/field type/i), 'tos_acceptance')
-    expect(screen.getByLabelText(/terms of service url/i)).toBeInTheDocument()
+    await user.selectOptions(
+      screen.getByRole('combobox', { name: /field type/i }),
+      'tos_acceptance'
+    )
+    expect(screen.getByRole('textbox', { name: /terms of service url/i })).toBeInTheDocument()
   })
 
   it('hides ToS URL input for other field types', async () => {
     const user = userEvent.setup()
     render(<AdminOnboardingPage />)
     await user.click(screen.getByRole('button', { name: /add field/i }))
-    await user.selectOptions(screen.getByLabelText(/field type/i), 'custom_text')
-    expect(screen.queryByLabelText(/terms of service url/i)).not.toBeInTheDocument()
+    await user.selectOptions(screen.getByRole('combobox', { name: /field type/i }), 'custom_text')
+    expect(screen.queryByRole('textbox', { name: /terms of service url/i })).not.toBeInTheDocument()
   })
 
   it('saves tosUrl in config when provided', async () => {
@@ -274,9 +277,15 @@
     const user = userEvent.setup()
     render(<AdminOnboardingPage />)
     await user.click(screen.getByRole('button', { name: /add field/i }))
-    await user.selectOptions(screen.getByLabelText(/field type/i), 'tos_acceptance')
-    await user.type(screen.getByLabelText(/^label$/i), 'Accept ToS')
-    await user.type(screen.getByLabelText(/terms of service url/i), 'https://example.com/tos')
+    await user.selectOptions(
+      screen.getByRole('combobox', { name: /field type/i }),
+      'tos_acceptance'
+    )
+    await user.type(screen.getByRole('textbox', { name: /^label$/i }), 'Accept ToS')
+    await user.type(
+      screen.getByRole('textbox', { name: /terms of service url/i }),
+      'https://example.com/tos'
+    )
     await user.click(screen.getByRole('button', { name: /^save$/i }))
     await waitFor(() => {
       expect(capturedBody).not.toBeNull()
diff --git a/src/components/admin/categories/category-form.tsx b/src/components/admin/categories/category-form.tsx
--- a/src/components/admin/categories/category-form.tsx
+++ b/src/components/admin/categories/category-form.tsx
@@ -4,6 +4,7 @@
  */
 
 import type { MaturityRating } from '@/lib/api/types'
+import { FormLabel } from '@/components/ui/form-label'
 
 export interface EditingCategory {
   id: string | null
@@ -29,33 +30,35 @@
       </h2>
       <div className="space-y-4">
         <div>
-          <label htmlFor="cat-name" className="block text-sm font-medium text-foreground">
+          <FormLabel htmlFor="cat-name" required>
             Category Name
-          </label>
+          </FormLabel>
           <input
             id="cat-name"
             type="text"
             value={editing.name}
             onChange={(e) => onChange({ ...editing, name: e.target.value })}
+            required
             className="mt-1 w-full rounded-md border border-border bg-background px-3 py-2 text-sm text-foreground"
           />
         </div>
         <div>
-          <label htmlFor="cat-slug" className="block text-sm font-medium text-foreground">
+          <FormLabel htmlFor="cat-slug" required>
             Slug
-          </label>
+          </FormLabel>
           <input
             id="cat-slug"
             type="text"
             value={editing.slug}
             onChange={(e) => onChange({ ...editing, slug: e.target.value })}
+            required
             className="mt-1 w-full rounded-md border border-border bg-background px-3 py-2 text-sm text-foreground"
           />
         </div>
         <div>
-          <label htmlFor="cat-desc" className="block text-sm font-medium text-foreground">
+          <FormLabel htmlFor="cat-desc" optional>
             Description
-          </label>
+          </FormLabel>
           <textarea
             id="cat-desc"
             value={editing.description}
@@ -65,15 +68,16 @@
           />
         </div>
         <div>
-          <label htmlFor="cat-maturity" className="block text-sm font-medium text-foreground">
+          <FormLabel htmlFor="cat-maturity" required>
             Maturity Rating
-          </label>
+          </FormLabel>
           <select
             id="cat-maturity"
             value={editing.maturityRating}
             onChange={(e) =>
               onChange({ ...editing, maturityRating: e.target.value as MaturityRating })
             }
+            required
             className="mt-1 w-full rounded-md border border-border bg-background px-3 py-2 text-sm text-foreground"
           >
             <option value="safe">Safe</option>
diff --git a/src/components/admin/onboarding/onboarding-field-form.tsx b/src/components/admin/onboarding/onboarding-field-form.tsx
--- a/src/components/admin/onboarding/onboarding-field-form.tsx
+++ b/src/components/admin/onboarding/onboarding-field-form.tsx
@@ -4,6 +4,7 @@
  */
 
 import type { OnboardingFieldType } from '@/lib/api/types'
+import { FormLabel } from '@/components/ui/form-label'
 
 const FIELD_TYPE_LABELS: Record<OnboardingFieldType, string> = {
   age_confirmation: 'Age Confirmation',
@@ -57,15 +58,16 @@
       <div className="space-y-4">
         {!editing.id && (
           <div>
-            <label htmlFor="field-type" className="block text-sm font-medium text-foreground">
+            <FormLabel htmlFor="field-type" required>
               Field Type
-            </label>
+            </FormLabel>
             <select
               id="field-type"
               value={editing.fieldType}
               onChange={(e) =>
                 onChange({ ...editing, fieldType: e.target.value as OnboardingFieldType })
               }
+              required
               className="mt-1 w-full rounded-md border border-border bg-background px-3 py-2 text-sm text-foreground"
             >
               {Object.entries(FIELD_TYPE_LABELS).map(([value, label]) => (
@@ -77,22 +79,23 @@
           </div>
         )}
         <div>
-          <label htmlFor="field-label" className="block text-sm font-medium text-foreground">
+          <FormLabel htmlFor="field-label" required>
             Label
-          </label>
+          </FormLabel>
           <input
             id="field-label"
             type="text"
             value={editing.label}
             onChange={(e) => onChange({ ...editing, label: e.target.value })}
+            required
             className="mt-1 w-full rounded-md border border-border bg-background px-3 py-2 text-sm text-foreground"
             placeholder="e.g., Accept our community rules"
           />
         </div>
         <div>
-          <label htmlFor="field-description" className="block text-sm font-medium text-foreground">
-            Description (optional)
-          </label>
+          <FormLabel htmlFor="field-description" optional>
+            Description
+          </FormLabel>
           <textarea
             id="field-description"
             value={editing.description}
@@ -104,9 +107,9 @@
         </div>
         {editing.fieldType === 'tos_acceptance' && (
           <div>
-            <label htmlFor="field-tos-url" className="block text-sm font-medium text-foreground">
-              Terms of Service URL (optional)
-            </label>
+            <FormLabel htmlFor="field-tos-url" optional>
+              Terms of Service URL
+            </FormLabel>
             <input
               id="field-tos-url"
               type="url"
diff --git a/src/components/admin/pages/page-form.tsx b/src/components/admin/pages/page-form.tsx
--- a/src/components/admin/pages/page-form.tsx
+++ b/src/components/admin/pages/page-form.tsx
@@ -5,6 +5,7 @@
  */
 
 import { TopicContentEditor } from '@/components/topic-content-editor'
+import { FormLabel } from '@/components/ui/form-label'
 import type { PageStatus, PageTreeNode } from '@/lib/api/types'
 
 export interface PageFormProps {
@@ -52,41 +53,44 @@
     <>
       <div className="space-y-4">
         <div>
-          <label htmlFor="page-title" className="block text-sm font-medium text-foreground">
+          <FormLabel htmlFor="page-title" required>
             Title
-          </label>
+          </FormLabel>
           <input
             id="page-title"
             type="text"
             value={title}
             onChange={(e) => onTitleChange(e.target.value)}
+            required
             className="mt-1 block w-full rounded-md border border-border bg-background px-3 py-2 text-sm text-foreground placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
             placeholder="Page title"
           />
         </div>
 
         <div>
-          <label htmlFor="page-slug" className="block text-sm font-medium text-foreground">
+          <FormLabel htmlFor="page-slug" required>
             Slug
-          </label>
+          </FormLabel>
           <input
             id="page-slug"
             type="text"
             value={slug}
             onChange={(e) => onSlugChange(e.target.value)}
+            required
             className="mt-1 block w-full rounded-md border border-border bg-background px-3 py-2 text-sm text-foreground placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
             placeholder="url-slug"
           />
         </div>
 
         <div>
-          <label htmlFor="page-status" className="block text-sm font-medium text-foreground">
+          <FormLabel htmlFor="page-status" required>
             Status
-          </label>
+          </FormLabel>
           <select
             id="page-status"
             value={status}
             onChange={(e) => onStatusChange(e.target.value as PageStatus)}
+            required
             className="mt-1 block w-full rounded-md border border-border bg-background px-3 py-2 text-sm text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
           >
             <option value="draft">Draft</option>
@@ -95,9 +99,9 @@
         </div>
 
         <div>
-          <label htmlFor="page-parent" className="block text-sm font-medium text-foreground">
+          <FormLabel htmlFor="page-parent" optional>
             Parent Page
-          </label>
+          </FormLabel>
           <select
             id="page-parent"
             value={parentId ?? ''}
@@ -114,12 +118,9 @@
         </div>
 
         <div>
-          <label
-            htmlFor="page-meta-description"
-            className="block text-sm font-medium text-foreground"
-          >
+          <FormLabel htmlFor="page-meta-description" optional>
             Meta Description
-          </label>
+          </FormLabel>
           <textarea
             id="page-meta-description"
             value={metaDescription}
@@ -132,7 +133,7 @@
           <p className="mt-1 text-xs text-muted-foreground">{metaDescription.length}/320</p>
         </div>
 
-        <TopicContentEditor content={content} onChange={onContentChange} />
+        <TopicContentEditor content={content} onChange={onContentChange} required />
       </div>
 
       <div className="flex items-center gap-3">
diff --git a/src/components/admin/settings/community-settings-form.tsx b/src/components/admin/settings/community-settings-form.tsx
--- a/src/components/admin/settings/community-settings-form.tsx
+++ b/src/components/admin/settings/community-settings-form.tsx
@@ -6,6 +6,7 @@
 'use client'
 
 import { ErrorAlert } from '@/components/error-alert'
+import { FormLabel } from '@/components/ui/form-label'
 import type { CommunitySettings, MaturityRating } from '@/lib/api/types'
 
 interface CommunitySettingsFormProps {
@@ -28,22 +29,23 @@
   return (
     <div className="max-w-lg space-y-6">
       <div>
-        <label htmlFor="settings-name" className="block text-sm font-medium text-foreground">
+        <FormLabel htmlFor="settings-name" required>
           Community Name
-        </label>
+        </FormLabel>
         <input
           id="settings-name"
           type="text"
           value={settings.communityName}
           onChange={(e) => onChange({ ...settings, communityName: e.target.value })}
+          required
           className="mt-1 w-full rounded-md border border-border bg-background px-3 py-2 text-sm text-foreground"
         />
       </div>
 
       <div>
-        <label htmlFor="settings-desc" className="block text-sm font-medium text-foreground">
+        <FormLabel htmlFor="settings-desc" optional>
           Description
-        </label>
+        </FormLabel>
         <textarea
           id="settings-desc"
           value={settings.communityDescription ?? ''}
@@ -54,15 +56,16 @@
       </div>
 
       <div>
-        <label htmlFor="settings-maturity" className="block text-sm font-medium text-foreground">
+        <FormLabel htmlFor="settings-maturity" required>
           Community Maturity Rating
-        </label>
+        </FormLabel>
         <select
           id="settings-maturity"
           value={settings.maturityRating}
           onChange={(e) =>
             onChange({ ...settings, maturityRating: e.target.value as MaturityRating })
           }
+          required
           className="mt-1 w-full rounded-md border border-border bg-background px-3 py-2 text-sm text-foreground"
         >
           <option value="safe">Safe (default)</option>
@@ -75,9 +78,9 @@
       </div>
 
       <div>
-        <label htmlFor="settings-reactions" className="block text-sm font-medium text-foreground">
+        <FormLabel htmlFor="settings-reactions" optional>
           Reaction Set
-        </label>
+        </FormLabel>
         <input
           id="settings-reactions"
           type="text"
@@ -99,12 +102,9 @@
       </div>
 
       <div>
-        <label
-          htmlFor="settings-max-reply-depth"
-          className="block text-sm font-medium text-foreground"
-        >
+        <FormLabel htmlFor="settings-max-reply-depth" optional>
           Max Reply Depth
-        </label>
+        </FormLabel>
         <input
           id="settings-max-reply-depth"
           type="number"
diff --git a/src/components/admin/settings/pds-override-dialog.tsx b/src/components/admin/settings/pds-override-dialog.tsx
--- a/src/components/admin/settings/pds-override-dialog.tsx
+++ b/src/components/admin/settings/pds-override-dialog.tsx
@@ -7,6 +7,7 @@
 
 import { useState, useEffect, useRef } from 'react'
 import { cn } from '@/lib/utils'
+import { FormLabel } from '@/components/ui/form-label'
 
 interface PdsOverrideDialogProps {
   open: boolean
@@ -65,9 +66,9 @@
         </h3>
         <form onSubmit={handleSubmit} className="mt-4 space-y-4">
           <div>
-            <label htmlFor="pds-hostname" className="block text-sm font-medium text-foreground">
+            <FormLabel htmlFor="pds-hostname" required>
               PDS Hostname
-            </label>
+            </FormLabel>
             <input
               ref={hostnameRef}
               id="pds-hostname"
@@ -84,9 +85,9 @@
             />
           </div>
           <div>
-            <label htmlFor="pds-trust-factor" className="block text-sm font-medium text-foreground">
+            <FormLabel htmlFor="pds-trust-factor" required>
               Trust Factor: {trustFactor.toFixed(1)}
-            </label>
+            </FormLabel>
             <input
               id="pds-trust-factor"
               type="range"
diff --git a/src/components/admin/trust-seeds/add-seed-dialog.tsx b/src/components/admin/trust-seeds/add-seed-dialog.tsx
--- a/src/components/admin/trust-seeds/add-seed-dialog.tsx
+++ b/src/components/admin/trust-seeds/add-seed-dialog.tsx
@@ -6,6 +6,7 @@
 'use client'
 
 import { useState, useEffect, useRef } from 'react'
+import { FormLabel } from '@/components/ui/form-label'
 
 interface AddSeedDialogProps {
   open: boolean
@@ -55,9 +56,9 @@
         <h3 className="text-lg font-semibold text-foreground">Add trust seed</h3>
         <form onSubmit={handleSubmit} className="mt-4 space-y-4">
           <div>
-            <label htmlFor="seed-handle" className="block text-sm font-medium text-foreground">
+            <FormLabel htmlFor="seed-handle" required>
               Handle
-            </label>
+            </FormLabel>
             <input
               ref={handleRef}
               id="seed-handle"
@@ -70,15 +71,15 @@
             />
           </div>
           <div>
-            <label htmlFor="seed-reason" className="block text-sm font-medium text-foreground">
+            <FormLabel htmlFor="seed-reason" optional>
               Reason
-            </label>
+            </FormLabel>
             <input
               id="seed-reason"
               type="text"
               value={reason}
               onChange={(e) => setReason(e.target.value)}
-              placeholder="Optional: why this account is trusted"
+              placeholder="Why this account is trusted"
               className="mt-1 w-full rounded-md border border-border bg-background px-3 py-2 text-sm text-foreground placeholder:text-muted-foreground"
             />
           </div>

--
tangled.sh