| name | usability-accessibility |
| description | Usability and WCAG 2.1 AA accessibility for AiScan modal UI. ARIA attributes, keyboard navigation, focus management, color contrast, screen reader support, form validation feedback. |
Usability & Accessibility — AiScan UI Guidelines
Target Standard
WCAG 2.1 Level AA — all new and modified UI must meet this baseline.
Modal Accessibility
The AiScan scanning modal is the primary UI surface. Requirements:
ARIA Attributes
<div class="modal" role="dialog" aria-modal="true" aria-labelledby="aiscan-modal-title">
<h5 id="aiscan-modal-title">Escanear Factura</h5>
...
</div>
Focus Management
- On modal open: move focus to the first interactive element (file input or close button)
- Focus trap: Tab key cycles within modal — never escapes to background content
- On modal close: return focus to the button that opened it
- Use
tabindex="-1" on non-interactive containers that receive programmatic focus
Keyboard Navigation
| Key | Action |
|---|
Escape | Close modal |
Enter | Activate primary action button |
Tab / Shift+Tab | Navigate between interactive elements |
| Arrow keys | Navigate within radio groups, select menus |
Wizard Steps
- Mark current step with
aria-current="step"
- Announce step changes with
aria-live="polite" region
- Previous/Next buttons clearly labeled (not just arrows)
- Disabled nav buttons use
aria-disabled="true" + tabindex="-1"
Async Status Feedback
AI analysis takes seconds — user must know what's happening:
<div aria-live="polite" aria-atomic="true" class="aiscan-status">
Analizando documento...
</div>
- Use
aria-live="polite" for non-urgent updates (analysis progress)
- Use
aria-live="assertive" for errors only
- Include a visible spinner/progress indicator (not just text)
Confidence Indicators
Extracted data includes confidence scores. Display rules:
- Never use color alone — always pair with text or icon
- Good: green checkmark + "Alta confianza"
- Bad: just a green dot
- Minimum contrast: text on colored background must meet 4.5:1 ratio
- Provide tooltip/title with numeric confidence value
Forms & Validation
Labels
- Every
<input>, <select>, <textarea> must have an associated <label>
- Use
for="id" attribute — not wrapping <label> (FS convention)
- Placeholder text is NOT a substitute for a label
Error Messages
<input id="invoice-number" aria-describedby="invoice-number-error" aria-invalid="true">
<div id="invoice-number-error" class="text-danger" role="alert">
Numero de factura requerido
</div>
- Link errors to inputs via
aria-describedby
- Set
aria-invalid="true" on invalid fields
- Error messages must be visible (not just color change on border)
File Upload
- Drag-and-drop area must have a keyboard-accessible alternative (upload button)
- Drop area:
role="button" with tabindex="0" and keydown handler for Enter/Space
- Announce successful upload: "Archivo subido: factura.pdf"
- File type restrictions shown visually AND in
accept attribute
Split-Pane Layout
The modal uses a 55/45 split (preview left, data right):
- Tab order: left pane (document preview) → right pane (extracted data) — logical reading order
- Draggable divider must be keyboard-accessible (
role="separator", arrow keys resize)
- On mobile (<768px): stack vertically, preview on top
Tables (Line Items)
<table class="table" aria-label="Lineas de factura">
<thead>
<tr><th scope="col">Descripcion</th><th scope="col">Cantidad</th>...</tr>
</thead>
...
</table>
- Use
<th scope="col"> for column headers
- Editable cells: use
<input> inside <td>, each with label (visible or aria-label)
- Add/remove row buttons: descriptive labels ("Eliminar linea 3")
Color & Contrast
- Text on background: minimum 4.5:1 contrast ratio
- UI components (buttons, inputs, icons): minimum 3:1
- Do not convey information by color alone — always pair with shape, text, or pattern
- Test with browser DevTools accessibility audit
Reference Files
Assets/JS/aiscan.js — UI event handling and DOM manipulationAssets/CSS/aiscan.css — Modal, split-pane, and form styling
