Skip to main content

Building an accessible platform with custom code

  • Last updated:
  • Administrators
  • Instructors
  • Power Users

Introduction

Customizing your platform with CSS, HTML, and external code can help create a more personalized and engaging experience for your users. 

This article outlines best practices for ensuring that these customizations remain accessible to everyone, providing guidelines for different customization options.

For more information about accessibility at Docebo, including a list of the available resources, refer to the article Accessibility at Docebo.

General rules

Here is a list of general guidelines, valid for all customization methods:

  • Visibility of structural elements: Do not hide the structural elements of the platform (such as the title, the bar, breadcrumbs, and the header) not to compromise the user experience for those using assistive technologies. If you need to hide elements, make sure that your customization provides an equivalent alternative.
  • Use semantic HTML elements: Structure your content with proper HTML elements. This ensures content is understood by assistive technologies and helps users navigate more easily.
  • Provide alternative text: Always include descriptive alternative text for images and icons. For decorative images, leave the alt attribute empty. For images used as buttons or interactive elements, ensure an accessible name is provided.
  • Ensure keyboard navigation: All interactive elements (buttons, links, form fields) must be navigable using the keyboard alone. Ensure that there is a visible focus indicator to assist keyboard navigation.
    Use ARIA roles: For custom widgets or dynamic content, use ARIA roles and properties to enhance accessibility.
  • Provide consistent navigation: Ensure a consistent layout and navigation structure across the platform to help users find content more easily.
  • Ensure proper content hierarchy: Structure your content with proper heading tags to ensure it is logically organized. Only one <h1> should be used per page.
  • Maintain color contrast: Ensure enough contrast between text and background colors for readability, particularly for users with low vision or color blindness.
  • Avoid auto-playing content: Auto-play media can be disruptive. If necessary, allow users to pause, stop, or control the volume of the media.
  • Test accessibility: Regularly test your customizations for accessibility. Use tools like Lighthouse, Axe, or WAVE to identify potential issues. Also, perform manual testing, including keyboard-only navigation and screen reader testing.

The following chapters provide ad-hoc best practices for different types of customization sources.

Custom CSS for platform design

When customizing the platform design through CSS, ensure that visual changes do not hinder accessibility. For example:

  • Maintain a good contrast ratio between text and background to enhance readability for users with visual impairments (minimum 4.5:1 contrast).
  • Avoid color as the sole indicator of meaning; use text labels or other visual cues.
  • Ensure that CSS modifications do not interfere with keyboard navigation or the visibility of focus indicators.
  • Always provide focus indicators for operable elements in your custom content.

Custom HTML widgets

When using custom HTML widgets to add specific elements to pages, remember the following:

  • Use proper semantic HTML tags (for example, <section>, <article>, <group>) to convey the meaning and structure of the content.
  • Ensure headings are used correctly to establish content hierarchy.
  • Ensure all interactive elements (buttons, links) are clearly described and navigable by keyboard.
  • Avoid images of text since this can be inaccessible for screen readers. Instead, use proper HTML text elements that are fully readable and resizable.

Custom HTML in text areas

When adding custom HTML content to text areas, such as descriptions: 

  • Use accessible HTML elements such as lists, headings, and links to structure the content logically.
  • Ensure any non-text content, like images or icons, has descriptive alt text or aria-labels for screen readers.
  • Avoid using images of text. If you must include images, provide appropriate alternative text and use HTML text for critical content.

For more best practices on writing accessible content, refer to the article Writing accessible and effective content.

Custom links

Avoid opening links in new tabs or windows, unless it is strictly necessary, as this can disrupt the user's browsing experience. If you have to, indicate if a link opens in a new window or tab, and ensure it is clearly stated:

  • If you use the platform editor, use the target="_blank" attribute for links.
  • If you provide custom HTML content, include the target="_blank" attribute directly in the code, and ensure the link includes a clear indication that it opens in a new tab or window. This can be done by using visible text or by referencing a visually hidden element with aria-describedby.

External content

When embedding external content via iframes or linking to external pages, make sure that:

  • The embedded content is also accessible. Verify that it complies with the Web Content Accessibility Guidelines (WCAG) standards.
  • When embedding content that may require interaction (like forms or media), ensure keyboard and screen reader accessibility is fully supported.
  • Always add a title attribute. This provides a clear, concise label for the iframe's content, crucial for screen reader users to understand its purpose. Example: <iframe src="..." title="Interactive Map"></iframe>
  • Add a lang attribute if the content's language differs. If the iframe content is in a different language than the main page, include a lang attribute to ensure correct pronunciation by assistive technologies. Example: <iframe src="..." title="French Article" lang="fr"></iframe>;
  • Ensure external links have clear, descriptive link text that indicates the destination or purpose of the link.

External code

When you are injecting external code, such as JavaScript or custom HTML, into the platform, ensure it is accessible. Here's what you need to focus on:

  • Dynamic content updates: If your code updates content without a full page reload, make sure those changes are perceivable to screen reader users. In specific cases, you may use ARIA live regions to announce important updates, but apply them cautiously to avoid overwhelming users with too many interruptions.
  • Keyboard accessibility: All interactive elements within your injected code must be fully accessible and operable using only a keyboard. Users who cannot use a mouse rely entirely on keyboard navigation.
  • Regular testing: Always test your injected code regularly to confirm compatibility and ensure a seamless experience for all users.