Accessibility is important for a lot of users, without it they just can not use their computer.

“15% of the world's population lives with some form of disability”

Laws require accessibility.


A few important principles are to be kept in mind

  • We want to make existing software accessible, and avoid dedicated software
  • We need synchronization: accessibility is just another way for input and output
  • It should be easily available, ready to be enabled.

See also Nonvisual Presentation of Graphical User Interfaces: Contrasting Two Approaches which discusses a lot of ground design principles.

TODO Wayland

This is collected on Wayland


Accessibility support is needed in Input


Accessibility support is needed in Output


Accessibility support is needed in applications, through AT-SPI2

at-spi stack overview (source)

Toolkits can either implement the at-spi dbus protocol themselves (as is done by qt5), or use Atk to do the at-spi marshalling for them.

In such a case, a tree of objects with base class AtkObject can either

  • be built along the toolkit widget tree (as is done externally and even lazily by java-atk-wrapper),
  • or within the toolkit widget tree itself: for instance gtk's base GtkWindow object contains an AtkObject *accessible field, subclass initialization functions specify with gtk_widget_class_set_accessible_type which precise accessible type should be used, and gtk will eventually create the right AtkObject subclass in gtk_widget_real_get_accessible. For instance, GtkLabel's gtk_label_class_init calls gtk_widget_class_set_accessible_type (widget_class, GTK_TYPE_LABEL_ACCESSIBLE); to specify that it will use the GtkLabelAccessible class to implement accessibility.

In both case, atk glib interfaces (AtkComponent, AtkText, AtkSelection, etc.) are added to the AtkObject subclasses, to specify which at-spi interfaces are implemented. See for instance GtkAccessibleLabel's G_DEFINE_TYPE_WITH_CODE call.

A Walkthrough documents the RPC and function calls details.

When an application is composed of several processes (e.g. applets, separate web rendering, etc.), one can use AtkPlug and AtkSocket to make the applet accessibility tree magically appear in the accessibility tree of the application. See an instance on

Gnome provides an Accessibility development guide

For ATK, there is a best ATK practices guide , and a minimal example of extending a base atk implementation is the GtkScaleAccessible class, based on GtkRangeAccessible, see gtk/gtk/a11y/gtkscaleaccessible.[ch]

For adding accessibility support to a custom-made widget, the evince implementation can be used as an example.

For Qt5, there is a guide for QWidget and a guide for Qt Quick

KDE provides an Accessibility development guide in the Human Interface Guidelines , a Plasma Accessibility documentation

Plans for wayland

LinuxJournal proposes a HOW-TO


There are so many accessibility mailing lists, notably for each distribution:

and for each toolkit or desktop:

and for each screen reader:

and cross-software lists:

If something is missing on these pages, don't hesitate to mail (or better, get a freedesktop wiki account to do additions yourself)