Developing for Accessibility

Introduction

Please use semantic HTML everywhere possible to allow assistive technologies and autonomous automation scripts to accurately navigate and execute functions within our application layouts.

Markup is a structural core requirement, not an afterthought. Every element should accurately describe the functional context of the content it wraps.

• List of available HTML tags
• List of ARIA attributes

Checklist Use Cases

This tracking list incorporates guidelines from the a11yproject and explicit findings from internal Claromentis product audits.

Team Process Standard: Developers should copy the relevant criteria sections from this checklist directly into their Merge Requests (MR) or JIRA task tickets to verify feature-level accessibility alignment before code review.

Implementation Criteria Sections

Content & Language

• Use simple, straightforward language and avoid idioms, metaphors, or complex formatting where direct phrasing works.
• Ensure that button, a, and label text identifiers are descriptive and unique within the context of the page.
• Use left-aligned layouts for LTR languages, and right-aligned layouts for RTL languages (Note: Claromentis currently does not support RTL layouts natively).

Global Code Architecture

• Validate raw HTML markup structures.
• Declare a valid lang token variable on the root html element.
• Provide a completely unique, dynamic title tag string for each independent page view or workspace state.
• Use explicit landmark elements (<main>, <nav>, <header>, <footer>) to identify page architecture.
• Ensure a linear, logical code flow order that perfectly matches the visual scanning sequence.
• Avoid using the autofocus attribute on form fields, as it breaks positional tracking paths on page initialization.
• Ensure user sessions provide visible alerts allowing workers to extend inactivity timeouts before automatic sign-outs occur.
• Deprecate and remove custom HTML title tooltips, as they are unmapped on mobile layouts and keyboard tracking loops.

Keyboard Navigation & Focus Properties

• Interactive elements navigated via keyboard input must provide a visible, high-contrast outline focus style.
• Ensure the tab-index focus sequence matches the logical visual layout reading order exactly.
• Purge and remove hidden focusable elements from the active tab map (elements styled with display: none; or visibility: hidden; must have their tabindex disabled).
• Focus Visibility Preservation (WCAG 2.4.11): Focused elements must never be obscured or covered by sticky layout headers, absolute application banners, or scrolling side panels. Use CSS scroll-padding overrides to maintain focus clearance.

Images & Asset Handling

• All img components must carry a declared alt attribute.
• Decorative Graphics & Icons: Visual assets that serve as pure decoration, or replicate adjacent label strings, must define a null alternative property (alt="").
• Visual Icon Handling: Framework icons, embedded SVGs, or custom IonIcons must use the aria-hidden="true" variable to cleanly exclude visual noise from screen readers: <ion-icon name="add-outline" aria-hidden="true"></ion-icon>.
• Provide explicit fallback text descriptions or analytical tables for complex layout elements like charts, graphs, data visualization patterns, and maps.
• If graphical visual assets contain embedded text strings, ensure those strings are typed out fully inside the alternative text attribute.

Heading Structure

• Heading elements (<h1>-<h6>) must present structural meaning, breaking content into nested information clusters.
• Enforce a strict limit of exactly one <h1> node element per distinct views page.
• Sequential Heading Levels: Heading structures must follow a sequential hierarchy (<h1> → <h2> → <h3>). [cite_start]Do not skip semantic heading levels for styling convenience[cite: 32].

Controls, Links & Buttons

• Utilize the anchor tag (<a>) strictly for navigation paths targeting valid URL addresses or distinct local view anchors.
• Ensure text links within layout descriptions remain highly distinct from plain text blocks using underlines or explicit structural borders.
• Dynamic Layout Action Items (WCAG 2.5.7 Alternative): Elements that execute dynamic client-side scripting commands, parameter changes, data sorting filters, or popup overlays must use true semantic elements: <button type="button">.
• Never bind dynamic UI code scripts or panel parameters to empty anchor links using invalid execution patterns like <a href="javascript:void(0);">. Custom user agents and automation scripts fail when dynamic triggers use fallback navigation wrappers.
• Target Areas (WCAG 2.5.8): All interactive tap targets (buttons, checkable nodes, clickable list triggers) must scale to a minimum physical sizing layout blueprint of 24x24 CSS pixels (including structural element padding space).
• Surfaced actions must map an explicit :focus outline state.
• Provide an institutional "Skip to Main Content" utility block at the absolute top of the DOM structure that appears instantly when the keyboard focus initiates.
• Explicitly append text alerts to link descriptions that route destination endpoints into separate browser windows or background tabs.

Modals & Real-Time Layout Streams (Bootstrap v4.6 Specifications)

• Live UI Updates: Application components presenting real-time generative responses, text streams, or asynchronous layout changes must define an active live property (aria-live="polite"). This ensures incoming updates are read without hijacking or breaking active focus actions.
• Dynamic Triggers: Framework controls firing a modular popup window must specify the relationship directly using the aria-controls selector attribute: <button type="button" aria-controls="deptModal" data-toggle="modal" data-target="#deptModal">.
• Structural Overlay Identification: The primary visibility header inside an active modal window must map an explicit id selector string: <h5 class="modal-title" id="deptModalLabel">...</h5>.
• Parent Container Alignment: The absolute outer modal layout framework container wrapper must link directly back to the inner heading element using a label assignment string: <div class="modal fade" id="deptModal" role="dialog" aria-labelledby="deptModalLabel">.

Forms & Input Assistance

• Every independent input layout component must bind directly to an explicit visual <label> tag using matching for and id markup assignments.
• Off-Screen Form Naming: When interface restrictions prevent the use of visual text strings for input controls, developers must define the label string programmatically using an explicit aria-label or aria-labelledby assignment.
• Group collections of closely related checkbox inputs or nested choices using separate semantic <fieldset> and <legend> container blocks.
• Configure standard browser fields with contextual autocomplete properties to support data auto-fill and prevent repetitive entries (WCAG 3.3.7).
• Error Handling: When dynamic validation tasks trigger errors upon submission, compile error summaries clearly within a structural element at the top of the interface block.
• Programmatically anchor text validation descriptions directly to the invalid form component using an aria-describedby="[error-container-id]" layout property.
• Never represent system errors, warnings, or action successes using changes to text color alone.

Tables & Analytics Formatting

• Use the native HTML structural tag framework (<table>, <thead>, <tbody>, <tr>) strictly for presenting matching sets of related numerical data. Do not build interface grids with standard table syntax.
• Explicitly map table header blocks utilizing the proper <th> component wrapper combined with a literal relationship layout attribute choice (scope="col" or scope="row").
• Deploy the <caption> node to render an explicit, clear identifier title describing the underlying table data collection.

Media & Video Elements

• Standard video and audio files must never launch using automatic play sequences.
• Ensure custom media wrapper elements provide fully focusable interactive control actions.
• All production video segments require visible subtitle streams.
• All standalone audio segments require descriptive transcripts.
• Review tracking sequences to guarantee animations do not trigger seizure patterns (elements must never flash more than 3 times within a single second).
• All moving assets must honor the user's system preferences using strict media query boundaries: @media (prefers-reduced-motion: reduce).