Accessibility

Inclusive experiences are a core requirement at Shoptet. This guide gives our React engineers clear accessibility criteria for design-system components and app features, ensuring they work for all users, including people with disabilities. Our baseline is the Web Content Accessibility Guidelines (WCAG) 2.2.

Level A: Foundational Accessibility

Meeting these criteria is crucial for basic accessibility and ensures that core functionalities are available to all users.

Keyboard Operability

Users must be able to complete all flows and control all components entirely using only the keyboard.

• Principle: Functionality must be operable via keyboard.
• Guidance:
  • Reach & activate everything: every interactive element is reachable with Tab / Shift+Tab and activatable with Enter/Space as appropriate.
    • Buttons: Enter or Space activates.
    • Links: Enter activates.
    • Checkbox: Space toggles; RadioGroup: Arrow keys move selection within the group (use the roving tabindex pattern so only the selected radio is tabbable).
    • Menus, tabs, comboboxes, lists: use the APG keyboard model (arrows/home/end) rather than repurposing Tab for in-widget navigation.
  • Logical focus order: the tab sequence follows the reading/visual order and preserves meaning. If a primary action (e.g., “Save”) appears early visually but is used at the end of a long form, ensure it’s also reachable logically (placement or programmatic order—not excessive Shift+Tab).
  • No keyboard traps (2.1.2): users can always move focus away. Don’t capture focus without a way out.
  • Overlays & dialogs: when opening a modal/dialog:
    • Move focus to the dialog (or its first focusable control),
    • Trap focus within while open,
    • Provide Esc to close,
    • On close, return focus to the trigger element.
  • Make it visible: the focused element must have a clear focus indicator with sufficient contrast
• WCAG Reference: 2.1.1 Keyboard

Valid HTML

Invalid HTML can break semantics and the ability for assistive technology to consume the content of the webpage.

• Principle: Content must be parseable and free of syntax errors that can disrupt assistive technologies.
• Guidance: Always write well-formed and valid HTML. This includes proper nesting of elements, correctly closed tags, and adherence to HTML specifications.
• WCAG Reference: 4.1.1 Parsing

Semantic HTML Usage

Whenever possible, use semantic HTML elements that inherently convey meaning.

• Principle: Structure content using semantic elements to communicate meaning and relationships to assistive technologies.
• Guidance:
  • Use proper heading elements (<h1> through <h6>) to structure content hierarchy.
  • Utilize semantic elements for lists (<ul>, <ol>), navigation (<nav>), side content (<aside>), forms (<form>), and tables (<table>).
  • Always use native <button> and <a> elements for interactive controls.
• WCAG Reference: 1.3.1 Info and Relationships, 4.1.2 Name, Role, Value

Interactive Elements: Buttons and Links

All interactive (clickable) elements should semantically be either buttons or links.

• Principle: Use appropriate HTML elements for interactive controls to convey their purpose and behavior.
• Guidance:
  • If an action changes the URL or navigates to a new resource, it should be an <a> element (link).
  • If an action performs an operation on the current page or within the application without changing the URL, it should be a <button> element.
  • Avoid using <div> or other non-interactive elements with onClick events unless robust accessibility alternatives (like a visible, focusable native button that triggers the same action) are provided. Buttons inherently handle keyboard interactions, focus management, and semantic roles crucial for assistive technologies.
• WCAG Reference: 2.1.1 Keyboard

Labeled Interactive Elements

All interactive elements must have an accessible label.

• Principle: Ensure all interactive elements have labels to describe their purpose.
• Guidance:
  • This includes buttons, inputs, selects, checkboxes, text areas, toggles, links, etc.
  • Labels should preferably be visually present. If a visual label is not feasible (e.g., for some icon buttons), use invisible labels (e.g., aria-label, aria-labelledby) that are perceivable by assistive technologies.
  • When an input requires specific information to be successfully filled, provide clear instructions or contextual information alongside the label.
• WCAG Reference: 1.3.1 Info and Relationships, 3.3.2 Labels or Instructions

Labeled Landmarks

Important landmark regions on the page should be clearly labeled.

• Principle: Provide meaningful names for regions of content to aid navigation for users of assistive technologies.
• Guidance:
  • Prefer native landmarks first: use <header> (page banner), <nav> (navigation), <main> (primary content), <aside> (complementary), and <footer> (content info). Avoid role="main" / role="navigation" unless you truly can’t use the native element.
  • Use exactly one <main> per page and don’t nest it.
  • Typically one page-level banner (<header> at the document root) and one page-level contentinfo (<footer> at the document root). Headers/footers inside articles/sections are fine, but they are not page landmarks.
  • Name duplicate landmarks: if you have multiple <nav> or <aside> regions, give each an accessible name via aria-label or aria-labelledby (e.g., “Primary navigation”, “Footer navigation”, “Secondary sidebar”) so screen-reader users can tell them apart.
  • Use region sparingly: only turn a <section> into a landmark with role="region" if it has an accessible name and truly represents a distinct area users may want to jump to. Otherwise, keep it semantic but not landmarked.
  • Don’t landmark lists directly: <ul>/<ol> are lists, not landmarks. If a list represents a region, wrap it in an appropriate landmark (e.g., a <nav> for a menu).
• Suggested Reading: My Priority of Methods for Labeling a Control
• WCAG Reference: 1.3.1 Info and Relationships

Meaningful Link Labels

Links should have a label that is understandable on its own or easily determinable from its context.

• Principle: Ensure that the purpose of a link is clear to users, even out of context.
• Guidance:
  • Level A: The link purpose can be easily determined from the context (e.g., the sentence in which the link appears).
  • Level AAA (Strongly Recommended): The link's label itself has a clear and meaningful purpose on its own.
• Examples:
  • ✅ Import catalog item to ONE Data vs. ❌ Import
  • ✅ Go to customers detail vs. ❌ Go to detail
• WCAG Reference: 2.4.4 Link Purpose (In Context)

Text Alternatives for Non-Text Content

All non-text content must have a text alternative that serves the equivalent purpose.

• Principle: Provide text equivalents for non-text content so it can be understood by assistive technologies.
• Guidance:
  • This applies to elements like charts, graphs, and indicators of state.
  • The text alternative can be provided directly (e.g., an accessible label for a chart showing "Number of valid results") or be available at a different part of the page.
  • Exception: Content that is purely decorative (e.g., a background pattern) can be hidden from assistive technologies.
• WCAG Reference: 1.1.1 Non-text Content

Images Have alt Attributes

All <img> elements must have an alt attribute.

• Principle: Provide text alternatives for images to convey their meaning.
• Guidance:
  • If an image is part of the content and conveys meaning, its alt attribute must contain a concise, meaningful description of the image.
  • If an image is purely decorative (e.g., most icons), it should have an empty alt attribute (alt="") to hide it from screen readers.
  • Important: A missing alt attribute is not the same as an empty alt attribute. A missing alt attribute often causes screen readers to announce the image file name, which is unhelpful.
• WCAG Reference: 1.1.1 Non-text Content

Don't Use Only Color to Convey Information

Information should not rely solely on color to be understood.

• Principle: Provide multiple visual cues in addition to color to convey information.
• Guidance:
  • For example, when indicating valid/invalid states, don't just use red and green. Supplement with icons (e.g., a checkmark or an "X"), text labels ("Valid," "Invalid"), or distinct patterns (e.g., for bars in a chart).
  • More broadly, ensure information necessary for understanding and operating content does not rely solely on sensory characteristics like shape, size, visual location, orientation, or sound.
• WCAG Reference: 1.3.3 Sensory Characteristics, 1.4.1 Use of Color

Keyboard Shortcuts

When adding keyboard shortcuts, those shortcuts must not be a single letter (e.g., "F") unless they are only active when a component has focus or the user can turn them off or remap them.

• Principle: Ensure that character key shortcuts do not interfere with assistive technology or standard keyboard use.
• Guidance: Avoid single-character shortcuts that could conflict with browser or screen reader commands. Use modifier keys (e.g., Ctrl+F, Alt+S).
• WCAG Reference: 2.1.4 Character Key Shortcuts

Page Title

Every webpage must have a title that describes the purpose of the page.

• Principle: Provide clear and descriptive titles for web pages.
• Guidance:
  • Ensure the <title> element in the <head> of your HTML accurately reflects the page's content or purpose (visible in browser tabs).
  • The main heading on the page (<h1>) should also clearly describe the page's purpose and ideally match or be very similar to the page title.
• WCAG Reference: 2.4.2 Page Titled

Logical Focus Order

Components on the page must be focusable in an order that preserves meaning and operability.

• Principle: Ensure that the focus order follows a logical sequence consistent with the meaning and relationships presented in the content.
• Guidance:
  • Design the tab order (Tab, Shift+Tab) to be intuitive for keyboard users.
  • Avoid illogical jumps in focus. For example, if a "Save" button is positioned visually early but logically applies after filling a long form, reconsider its placement or ensure the tab order is adjusted to make it easily accessible at the end of the form.
• WCAG Reference: 2.4.3 Focus Order

Input Error Identification

All input errors must be announced and clearly shown to users.

• Principle: Users must be able to identify input errors and understand how to correct them.
• Guidance:
  • When an input field has an error, it must be clearly identified (e.g., using a visual cue like a red border and an aria-invalid="true" attribute).
  • The error message should be placed close to the input field or clearly reference the input by name.
  • The error message text should explicitly state what the problem is and, ideally, provide guidance on how to fix it.
• WCAG Reference: 3.3.1 Error Identification

Bypass Blocks

A mechanism must be available to bypass content that is repeated on multiple pages.

• Principle: Provide methods to skip repetitive content and navigate directly to the main content area.
• Guidance:
  • The most common implementation is a "Skip to main content" link, which is visually hidden but becomes visible and focusable when a keyboard user tabs to it.
  • More skip regions can be implemented as needed (e.g., "Skip to navigation").
• WCAG Reference: 2.4.1 Bypass Blocks

Level AA: Enhanced Accessibility (Our Target)

These criteria aim for a higher level of accessibility, addressing common barriers for a wider range of users. Achieving Level AA is our primary target.

Headings for Structure

Headings must be used to provide structure to the content, and a proper level of heading must be used. Headings and labels should describe the topic or purpose of the section.

• Principle: Organize content with a clear and consistent heading hierarchy.
• Guidance:
  • Use <h1> through <h6> elements to create a logical document outline.
  • Do not skip heading levels (e.g., an <h3> should not directly follow an <h1>; an <h2> should be in between).
  • The visual style of a heading (e.g., font size) does not dictate its semantic level. An <h1> doesn't have to be the largest text on the page; its primary role is semantic.
• WCAG Reference: 1.3.1 Info and Relationships, 2.4.6 Headings and Labels

Visible Focus Outline

When using a keyboard, the focus outline must always be clearly visible so users know their current position on the page.

• Principle: Provide a clear visual indicator of the keyboard focus.
• Guidance:
  • A visible focus outline is often the only way for keyboard users to track their position. Do not hide or remove default browser focus outlines (e.g., using outline: none; in CSS).
  • Design custom focus outlines to be clearly visible and have good contrast against various backgrounds.
• WCAG Reference: 2.4.7 Focus Visible

Minimum Contrast Ratio (Text)

Ensure there is at least a 4.5:1 contrast ratio between text and its background.

• Principle: Ensure sufficient contrast between text and its background for readability.
• Guidance:
  • This is primarily a design responsibility, but developers should be aware and flag any issues.
  • Normal text size (typically 16px / 1rem): Minimum contrast ratio of 4.5:1.
  • Larger text (at least 18pt / 24px, or 14pt / 18.66px and bold): Minimum contrast ratio of 3:1.
  • For text smaller than 16px, consider increasing the contrast ratio above 4.5:1.
  • Exception: Disabled elements are exempt from this contrast requirement.
  • Note: WCAG Level AAA requires 7:1 and 4.5:1 respectively.
• WCAG Reference: 1.4.3 Contrast (Minimum), 1.4.6 Contrast (Enhanced)

Non-Text Contrast

Contrast between non-text elements (e.g., buttons, icons) and their background is at least 3:1.

• Principle: Ensure sufficient contrast for graphical objects and user interface components.
• Guidance:
  • This also applies to design, but developers should verify.
  • UI components (like the boundaries of an input field, or an icon) should have a contrast of at least 3:1 against adjacent colors so that users can clearly perceive them.
  • Exception: Disabled elements are exempt from this contrast requirement.
• WCAG Reference: 1.4.11 Non-text Contrast

Content on Hover or Focus

Avoid hiding critical content behind hover or focus states. If content must be revealed on hover/focus, ensure specific conditions are met.

• Principle: Ensure content revealed on hover or focus is perceivable and operable by all users.
• Guidance:
  • Avoid where possible: It's best not to hide essential information or interactive controls solely behind hover/focus states.
  • If unavoidable, ensure:
    • Revealed on both hover and focus: Content must appear for both mouse hover and keyboard focus.
    • Dismissable: A mechanism must be available to dismiss the additional content without moving the pointer or keyboard focus (unless it's an input error or doesn't obscure other content).
    • Hoverable: If triggered by hover, the pointer can be moved over the additional content without it disappearing.
    • Persistent: The content remains visible until the trigger is removed, the user dismisses it, or its information becomes invalid.
  • Text-based content like tooltips is generally acceptable, but it should not contain crucial information or interactive elements if not meeting the above criteria.
• WCAG Reference: 1.4.13 Content on Hover or Focus

Consistent UI

The user interface must be consistent across various screens and components.

• Principle: Promote predictability and ease of use through consistent design and functionality.
• Guidance:
  • When an action or UI element is reused across different pages or contexts, it should maintain the same visual appearance and labels.
  • Examples:
    • If "Save" is used for one creation flow, don't use "Confirm" for the same action in another.
    • Navigation elements should look and function identically across all pages.
• WCAG Reference: 3.2.3 Consistent Navigation, 3.2.4 Consistent Identification

Text Resizing

Text can be resized up to 200% without loss of content readability or functionality.

• Principle: Ensure content remains usable when text is magnified.
• Guidance:
  • Avoid using px based font-sizes that prevent text resizing. Prefer relative units like em or rem.
  • Test layouts by zooming the browser text (or the entire page) to 200% to ensure no broken layouts or loss of readability.
• More Info: Responsive Type and Zoom
• WCAG Reference: 1.4.4 Resize Text

Reflow (Responsiveness)

Content can be presented without loss of information or functionality, and without requiring two-dimensional scrolling for certain widths/heights. This essentially means the application must be responsive.

• Principle: Content should adapt to different screen sizes and zoom levels without requiring horizontal scrolling for typical content.
• Guidance:
  • Vertical scrolling content: Should not require horizontal scrolling at a width equivalent to 320 CSS pixels.
  • Horizontal scrolling content: Should not require vertical scrolling at a height equivalent to 256 CSS pixels.
  • This allows users to zoom up to 400% on a 1280px wide screen (1280px / 4 = 320px) and still use the application effectively.
  • Exception: Parts of content that inherently require a two-dimensional layout for usage or meaning (e.g., large data tables) are exempt.
• WCAG Reference: 1.4.10 Reflow

Text Spacing

Ensure content and functionality are not lost when text spacing properties are adjusted.

• Principle: Provide flexibility for users to adjust text spacing without adverse effects.
• Guidance: Ensure that setting the following CSS properties (and changing no other style property) does not lead to loss of content or functionality:
  • Line height (line spacing) to at least 1.5 times the font size.
  • Spacing following paragraphs to at least 2 times the font size.
  • Letter spacing (tracking) to at least 0.12 times the font size.
  • Word spacing to at least 0.16 times the font size.
• WCAG Reference: 1.4.12 Text Spacing

Pointer & Touch Input

Touch and pointer interactions must be operable without fine motor precision or complex gestures, and actions must be cancellable. Targets should be large enough (or well-spaced) to avoid accidental activation.

• Principle: Provide single-pointer alternatives, allow cancellation, and ensure comfortable target sizes so people can operate controls with mouse, touch, pen, or alternative pointers.
• Guidance:
  • Pointer gestures: If a feature uses multipoint or path-based gestures (e.g., pinch, drag-to-draw), also provide a single-pointer alternative such as buttons, tap, or a slider. (SC 2.5.1 Pointer Gestures)
  • Pointer cancellation: Prefer activating on pointer up (release), and let users cancel by moving off the target before release. Avoid irreversible actions on pointer down unless essential. (SC 2.5.2 Pointer Cancellation)
  • Target size (WCAG 2.2): Make interactive targets at least 24×24 CSS px. If a target is smaller, meet the spacing exception (a 24px-diameter circle around the target must not intersect any adjacent target). Document defaults for buttons, icon buttons, chips, and touch controls in the design system. (SC 2.5.8 Target Size — Minimum)
  • Dragging movements (WCAG 2.2): For any drag interaction (e.g., reordering, map panning), provide a non-drag alternative such as “Move up/down” buttons or arrow controls. (SC 2.5.7 Dragging Movements)
• Examples:
  • Reorder list items via drag and via “Move up/down” buttons.
  • Map can be panned by drag and by arrow controls or “Pan left/right/up/down” buttons.
  • Icon buttons meet 24×24 minimum or have sufficient spacing so adjacent targets don’t overlap the 24px circle.
• WCAG Reference: 2.5.1 Pointer Gestures (Level A), 2.5.2 Pointer Cancellation (Level A), 2.5.8 Target Size — Minimum (Level AA), 2.5.7 Dragging Movements (Level A)