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.

About this page

Accessibility documentation is scattered on different projet documentation, blog posts, etc. it's hard to find your way when you start from scratch. This wiki page, hosted by freedesktop for stability, collects links and documentation, to act as a central place for documentation.

If something is missing on these pages, don't hesitate to mail ; or better : get a freedesktop wiki account by mailing wiki-requests to do additions yourself. You can send the "Generation" part result to Samuel Thibault for him to create your account.


A few important principles are to be kept in mind

  • We want to make existing software accessible, and avoid dedicated software, both to avoid having to maintain them, and to make accessibility mainstream so that users don't get ghettoed
  • 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-list for Wayland

This is collected on Wayland

Revamping GTK accessibility stack?

This is collected on GTK-a11y-revamp

It is maintained on the gnome gitlab pages:


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) (description)

The reason why ATK and atk-bridge are separate is because previously the at-spi stack could be running either on top of dbus or corba. There used to be an atk-adaptor for CORBA, while the current atk-bridge is only for dbus.

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.

MakingWidgetAccessible documents a brief summary how to add accessibility support

A glimpse into atspi using python is available.

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 and its Accessibility wiki

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

To check the content exposed by application, use accerciser

LinuxJournal proposes a HOW-TO

Screen reader side

For the screen reader side, one can read the libatspi documentation or the pyatspi2 documentation available with pydoc3 pyatspi, there is also a small pyatspi2 example available

The main screen reader used on the desktop is Orca, there is also an initial project called Odilia

Screen magnification is provided by gnome-shell or compiz' ezoom plugin.


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: