13 KiB

Raw Blame History Unescape Escape

WCAG 2.1 AA Accessibility Audit Report — DocuSeal

Date: 2026-02-25 Standard: WCAG 2.1 Level AA Scope: ERB views, Vue components, custom JS elements, color contrast Status: FAIL — multiple violations identified

Executive Summary

Four specialized audit agents reviewed the full codebase across four domains. A total of ~80 issues were identified: 20 critical, ~30 major, ~30 minor. The most impactful failures cluster around six themes:

Viewport zoom disabled (users with low vision cannot zoom)
Focus indicators removed on many inputs (keyboard users cannot see focus position)
Modal focus not managed (keyboard users get trapped or lose focus)
alert() / prompt() used for errors (screen readers cannot process these)
Form controls lack proper labels (screen readers cannot describe fields)
Validation errors not announced via live regions

The recent PDF/Text tab switcher implementation is noted as correctly implemented (proper ARIA tablist/tab/tabpanel, roving tabindex, keyboard navigation). The sr-only page text pattern is also correctly implemented.

Priority 1 — Critical (Fix Immediately)

C1. Viewport Zoom Disabled

WCAG: 1.4.4 Resize Text (AA) File: app/views/layouts/application.html.erb:8 Issue: maximum-scale=1.0, user-scalable=no prevents users from zooming to 200%. Fix: Change to <meta name="viewport" content="width=device-width, initial-scale=1.0">

C2. Focus Indicators Removed Without Alternative

WCAG: 2.4.7 Focus Visible (AA) Files:

app/views/templates/_file_form.html.erb:11 — outline-none focus:ring-0
app/views/templates_preferences/_recipients.html.erb:15 — same
app/views/templates_clone/_form.html.erb:17 — same
app/javascript/submission_form/phone_step.vue:105 — !outline-none
app/javascript/template_builder/font_modal.vue:172 — outline-none
app/javascript/template_builder/area.vue:67 — outline-none on contenteditable
app/javascript/template_builder/document.vue:9-30 — focus:outline-none on tab buttons (no alternative) Fix: Replace outline-none focus:ring-0 with focus:ring-2 focus:ring-base-content focus:ring-offset-1 on each.

WCAG: 2.4.3 Focus Order (A), 2.1.2 No Keyboard Trap (A) File: app/javascript/elements/turbo_modal.js (entire file) Issues:

No focus trap within modal (Tab escapes the modal)
No focus moved into modal on open
No focus restoration to trigger element on close
No role="dialog" or aria-modal="true" Fix: On open, store trigger reference, move focus to first focusable element, trap Tab/Shift+Tab; on close, restore focus to trigger. Add role="dialog" aria-modal="true" aria-labelledby="<title-id>".

C4. alert() / prompt() Used for All Errors

WCAG: 3.3.1 Error Identification (A), 4.1.3 Status Messages (AA) Files:

app/javascript/elements/fetch_form.js:24
app/javascript/elements/download_button.js:48
app/javascript/elements/clipboard_copy.js:20
app/javascript/elements/prompt_password.js:7
app/javascript/submission_form/signature_step.vue:765-773 Fix: Replace every alert() / prompt() with ARIA live region announcements (role="alert" or aria-live="assertive"). For prompt_password.js, replace browser prompt with a custom role="dialog" modal containing a labelled input.

C5. Form Controls Lack Associated Labels

WCAG: 1.3.1 Info and Relationships (A), 4.1.2 Name Role Value (A) Files:

app/javascript/submission_form/signature_step.vue:209-216 — signature text input has no <label>
app/javascript/submission_form/signature_step.vue:218-262 — signing reason <select> has no <label>
app/javascript/submission_form/area.vue:133-141 — checkbox has no label
app/javascript/submission_form/area.vue:153-161 — radio buttons have no labels Fix: Add <label for="..."> or aria-label to each unlabelled control. For radio/checkbox groups, wrap in <fieldset>/<legend> or role="group" aria-labelledby.

C6. Validation Errors Not Announced to Screen Readers

WCAG: 3.3.1 Error Identification (A), 4.1.3 Status Messages (AA) Files:

app/javascript/submission_form/form.vue:35-44 — disabled submit button tooltip not announced
app/javascript/submission_form/signature_step.vue:765-773 — signature too small uses alert() Fix: Add role="alert" aria-live="polite" region that updates when form state changes. Remove alert() calls. For the "fill all required fields" message, render it in a live region when the button is disabled.

C7. text-gray-100 on Dark Background — Invisible Text

WCAG: 1.4.3 Contrast Minimum (AA) — contrast ~0.4:1 File: app/views/templates/_embedding.html.erb:58, 63, 91, 103, 138, 156, 196, 214 Fix: Replace text-gray-100 with text-white on dark code block backgrounds.

Priority 2 — High (Fix This Sprint)

H1. Missing H1 Heading on Signing Form

WCAG: 2.4.6 Headings and Labels (AA) File: app/views/submit_form/show.html.erb:19-20 Issue: Submission name displayed in a plain <div>, not an <h1>. Fix: Change or wrap the submission name div with <h1 class="...">.

H2. Form Layout Missing lang Attribute

WCAG: 3.1.1 Language of Page (A) File: app/views/layouts/form.html.erb:2 Issue: <html data-theme="docuseal"> — no lang attribute. Fix: <html data-theme="docuseal" lang="<%= I18n.locale %>">

WCAG: 2.4.1 Bypass Blocks (A) File: app/views/layouts/form.html.erb Issue: Public signing form has no skip navigation link (application layout has one). Fix: Add skip link before the nav:

<a href="#main-content" class="absolute left-0 top-0 -translate-y-full focus:translate-y-0 z-50 p-4 bg-base-100 text-base-content border-2 border-neutral">
  <%= t('skip_to_main_content') %>
</a>

H4. text-gray-300/400 on White/Light Backgrounds — Fails 4.5:1

WCAG: 1.4.3 Contrast Minimum (AA) Files:

app/javascript/submission_form/signature_step.vue:221,230 — text-gray-300 select placeholder (~2.2:1)
app/javascript/submission_form/area.vue:211 — text-gray-400 (~2.1:1)
app/javascript/submission_form/form.vue:207,215 — text-gray-300 (~2.2:1)
app/javascript/template_builder/conditions_modal.vue:64,106,133 — text-gray-300 (~2.2:1)
app/javascript/template_builder/import_list.vue:53,80 — !text-gray-300 (~2.2:1)
app/views/submissions/_send_sms_button.html.erb:3 — text-gray-400 (~2.1:1) Fix: Replace with text-gray-600 (minimum) or text-base-content/70 on these elements.

H5. Modal Close Buttons Use `<a>` Instead of `<button>`

WCAG: 4.1.2 Name Role Value (A) Files:

app/views/shared/_turbo_modal.html.erb:10
app/views/shared/_turbo_modal_large.html.erb:10 Fix: <button type="button" data-action="click:turbo-modal#close" aria-label="<%= t('close') %>">×</button>

H6. Duplicate IDs — decline_button

WCAG: 4.1.1 Parsing (A) File: app/views/submit_form/show.html.erb:24,42 Fix: Use id="decline_button_header" and id="decline_button_scroll".

WCAG: 2.1.1 Keyboard (A) File: app/views/shared/_navbar.html.erb:26-80 Issue: DaisyUI dropdown with <label tabindex="0"> has no Enter/Space/Escape/Arrow key handling; aria-expanded never updates. Fix: Add JavaScript keyboard event handling following ARIA APG menu button pattern.

H8. Canvas Elements Lack Text Alternatives

WCAG: 1.1.1 Non-text Content (A) File: app/javascript/submission_form/signature_step.vue:171-176 Fix: Add fallback text inside <canvas>: "Signature drawing pad. Use the tools above to draw or type your signature."

Priority 3 — Medium (Address in Next Sprint)

M1. Color-Only Submitter Indicators (Colored Dots)

WCAG: 1.3.3 Sensory Characteristics (A) File: app/views/submissions/show.html.erb:193,202 Fix: Add aria-hidden="true" to the colored dot; add adjacent text labels like "Party 1", "Party 2".

M2. Color-Only Field Type Indicators (Template Builder)

WCAG: 1.4.1 Use of Color (A) File: app/javascript/template_builder/area.vue:646-672 Fix: Add text label or icon in addition to the color-coded border/background.

M3. Contenteditable Field Name Lacks ARIA

WCAG: 4.1.2 Name Role Value (A) File: app/javascript/template_builder/area.vue:65-73 Fix: Add role="textbox" aria-multiline="false" aria-label="Field name" to the contenteditable <span>.

M4. toggle_visible / field_condition Don't Set aria-expanded / aria-hidden

WCAG: 4.1.2 Name Role Value (A) Files: app/javascript/elements/toggle_visible.js, app/javascript/elements/field_condition.js Fix: Set aria-expanded on trigger; set aria-hidden="true" on hidden targets.

M5. Password Visibility Toggle Lacks aria-label / aria-pressed

WCAG: 4.1.2 Name Role Value (A) File: app/javascript/elements/password_input.js:11-18 Fix: Add aria-label="Show password" / "Hide password" toggled on state change. Add aria-pressed.

M6. Dynamic List (add/remove items) No Focus Management

WCAG: 2.4.3 Focus Order (A) File: app/javascript/elements/dynamic_list.js:11-26 Fix: Move focus to new item's first input when added; announce removal via live region.

M7. Clipboard Copy No Confirmation Feedback

WCAG: 4.1.3 Status Messages (AA) File: app/javascript/elements/clipboard_copy.js Fix: Add aria-live="polite" region announcing "Copied to clipboard" for 2-3 seconds after copy.

M8. Form Profile — No Inline Validation Error Messages

WCAG: 3.3.1 Error Identification (A) File: app/views/profile/index.html.erb:65-82 Fix: Display per-field error messages with aria-describedby linking field to error span; wrap in role="alert".

M9. Placeholder Colors at Very Low Opacity (area.vue contenteditable)