Discourse Accessibility Checklist 2026 | Forum WCAG 2.1 AA Guide
Last updated: 2026-07-30
Discourse runs a large share of the internet's product forums, open source project discussions, paid membership communities, and customer support hubs. It is unusually good software by forum standards, actively maintained, and its team has done real accessibility work, which makes it a better starting point than most community platforms. The problems that show up in audits come from three places instead. First, the platform's defining interface pattern is a challenge: the topic stream is a virtualized infinite scroll that mounts and unmounts posts as you move, which is genuinely hard to make keyboard and screen reader friendly, and heavy keyboard shortcut usage assumes a sighted mouse-and-keyboard user. Second, almost every real Discourse instance runs a custom theme, a custom color scheme, and a stack of theme components and plugins, and those are where contrast failures, removed focus outlines, and unlabeled controls enter. Third, and most persistently, the content is written by your members. Nobody on a forum writes alt text, screenshots carry the actual answer to the question, and pasted code and stack traces arrive as images. For a community that functions as documentation or support, that means the answer people need is frequently unreadable to part of the audience. Legally, communities attached to a commercial product are increasingly in scope: the European Accessibility Act has applied since June 2025 to e-commerce and a range of services, and a support forum that is the practical route to customer service is hard to argue is outside a company's service offering. US-facing companies face ADA Title III exposure on the same reasoning. This checklist covers the theme, composer, and content layers a community manager can actually control.
Common Accessibility Issues
Discourse renders long topics as a virtualized stream, mounting posts as they approach the viewport and unmounting them as they leave. For keyboard and screen reader users this creates specific failures: focus can be destroyed when the element holding it is unmounted, dumping the user back to the top of the document; newly loaded posts arrive with no announcement, so a screen reader user has no idea content appeared; and reaching the footer, category list, or anything below a long topic can be effectively impossible. Users with motor disabilities relying on keyboard navigation lose their place repeatedly in exactly the long threads where position matters most.
Provide and preserve reliable landmark and heading structure so users can jump between the header, topic content, reply composer, and sidebar without traversing the stream. Ensure a visible skip link lets keyboard users bypass the stream to reach the composer and site navigation. Announce newly loaded posts through a polite live region so screen reader users know the page changed, and verify that focus is never silently lost when posts unmount, moving it to a stable container if it must move. Keep the paginated topic and print views reachable and linked, since a static rendering of a long thread is often the most usable path for assistive technology, and test long threads specifically rather than short ones, because the problem only appears at scale.
Nearly every production Discourse instance uses a custom color scheme matching a company or project brand, and those schemes are chosen visually rather than validated. The recurring failures are low-contrast secondary text used for timestamps, view counts, post metadata, and category descriptions; brand-colored link and button text below threshold; muted or read-state indicators that become unreadable; and dark schemes where the palette was inverted without rechecking any pair. Because forum metadata carries genuinely useful information about recency and activity, unreadable metadata degrades the core navigation experience for low-vision members.
Validate every foreground and background pair in the custom color scheme against 4.5 to 1 for normal text and 3 to 1 for large text, and check control boundaries and focus indicators against 3 to 1, treating secondary and metadata text as real content rather than decoration. Test light and dark schemes independently, since a palette that passes in one direction routinely fails in the other. Verify the theme did not remove or weaken the focus outline, which custom Discourse themes frequently do while restyling buttons and links. Ensure states conveyed by color, such as unread, tracked, solved, or pinned, also carry text or an icon, because color alone excludes members with color vision deficiency.
The composer is where members actually participate, and it presents several barriers. Formatting toolbar controls are icon-only and depend on tooltips that assistive technology may not surface as accessible names, the side-by-side live preview creates a second copy of the content that can be announced redundantly, upload and drag-and-drop affordances often lack a keyboard-operable equivalent, and inline autocomplete for mentions, emoji, and categories updates without announcing that suggestions appeared or how to choose one. The net effect is that a screen reader user can read the forum but struggles to post to it, which excludes them from membership rather than merely from reading.
Ensure every composer toolbar control exposes a meaningful accessible name independent of its visual tooltip, and that all are reachable and operable by keyboard. Provide a standard file input alongside drag-and-drop upload so keyboard and screen reader users can attach images. Implement autocomplete for mentions and emoji as a properly announced combobox pattern, communicating that suggestions are available, how many, and which is active. Hide the live preview from assistive technology or clearly label it as a preview so its content is not read as a duplicate of the editor. Test the full post-a-reply flow by keyboard and screen reader after any composer-affecting theme component is installed.
Discourse interfaces lean heavily on icons and emoji: like and reaction buttons, bookmark, flag, share, solved markers, badge and trust level icons, and category glyphs. When these are rendered by a custom theme or a plugin, they frequently arrive as images or glyph elements with no text alternative, so a screen reader announces nothing or reads a raw shortcode. Members also use emoji inside posts as substantive content, including status indicators in tables and long emoji runs for emphasis, which screen readers read out in full and at length.
Give every icon-only control a clear accessible name describing its action rather than its appearance, so a control reads as its function instead of as a glyph, and verify reaction and voting buttons expose their pressed state so a member can tell whether they already reacted. Ensure emoji rendered as images carry the correct text alternative, which the platform normally handles but themes and plugins frequently break. Guide members away from using emoji as the only carrier of meaning in posts and category descriptions, and keep decorative emoji runs short, since a screen reader reads each one aloud and a row of them turns into noise that buries the actual message.
On a support or documentation forum, the answer is often a screenshot: a settings panel, an error dialog, a terminal output, a stack trace, or a snippet of code pasted as an image. Members essentially never write alt text, so for a blind or low-vision member the accepted solution to their problem is an unlabeled image. This is more damaging than a missing alt attribute on a marketing page, because the forum thread is frequently the only place that answer exists, having replaced official documentation in practice.
Set community expectations rather than trying to remediate retroactively: state in your posting guidelines that screenshots should be accompanied by a sentence describing what they show, and that code, error messages, and stack traces belong in code blocks as text rather than as images. Code as text is also searchable, copyable, and diffable, so this argument lands with technical members on grounds they already care about. Have moderators add a describing reply or edit in a description when a solution post depends on an image, prioritizing accepted-solution posts and pinned guides where traffic concentrates. Where staff post official screenshots, treat alt text as mandatory, since staff content sets the norm the community copies.
Discourse's extensibility is its strength and its main accessibility risk. Theme components and plugins add banners, custom headers, sidebars, category boxes, event calendars, polls, chat, and custom sign-up flows, and they routinely ship clickable divs, custom dropdowns with no keyboard behavior, modals that do not trap or restore focus, carousels without controls, and dynamic content that never announces itself. Because a single header or banner component renders on every page, one defective component becomes a site-wide failure, and community managers typically install several from mixed-quality sources.
Treat every theme component and plugin as untrusted until tested, and check the three things that catch most defects: can you reach and operate it with the keyboard alone, is there a visible focus indicator, and does every control announce a meaningful name. Test in a staging instance before installing to production, and prefer components that are actively maintained over abandoned ones, since accessibility fixes only arrive in maintained code. Re-test after upgrades, because component updates frequently change markup. Keep the installed set small and remove what you are not using, as every added component increases both the audit surface and the chance a future upgrade breaks navigation site-wide.
Discourse-Specific Tips
- Test long topics, not short ones, because the virtualized stream's keyboard and focus problems only appear once posts start unmounting.
- Validate light and dark color schemes separately, since an inverted palette almost always breaks pairs that passed in the other direction.
- Check that your custom theme did not remove the focus outline while restyling buttons and links.
- Test the whole post-a-reply flow by keyboard after installing anything that touches the composer.
- Put alt text and code-as-text expectations directly in your posting guidelines, since member content is the largest source of failures and cannot be fixed retroactively at scale.
- Prioritize accepted-solution and pinned posts for image descriptions, because forum traffic concentrates heavily there.
- Install theme components in a staging instance first and re-test after each upgrade, as one header component affects every page.
Recommended Tools
Discourse Meta
The official Discourse community, where accessibility issues, fixes, and theme component quality are discussed publicly and where you can check whether a component is actively maintained.
axe DevTools
A browser extension for auditing rendered forum pages, catching color scheme contrast failures, missing accessible names on icon-only controls, and non-semantic markup added by theme components and plugins.
NVDA
A free Windows screen reader for testing whether a long topic stream can be read and navigated, whether newly loaded posts are announced, and whether the composer can be used to post a reply.
WebAIM Contrast Checker
A quick check for the custom color scheme's text and background pairs, including the low-contrast metadata colors that forum themes most often get wrong.
Frequently Asked Questions
Our forum is just a community, not our product. Is it really in scope for accessibility law?
That distinction is weaker than it sounds, and it depends on what the forum actually does. If your Discourse instance is where customers get support, where your documentation effectively lives, where account or billing questions get answered, or where members who paid for access participate, then it is part of the service you provide rather than an optional extra. Under the European Accessibility Act, which has applied since June 2025 to e-commerce and a range of services, and under ADA Title III reasoning in the US, the argument that the only practical route to customer service is out of scope is not a strong one. There is also a non-legal version of the same point that usually moves faster internally: for many products the forum thread is the only place an answer exists, having quietly replaced official documentation. If that answer is a screenshot with no description, a paying customer cannot get help, and that is a support problem regardless of which statute applies.
We cannot control what members post. How do we handle missing alt text on thousands of screenshots?
You do not remediate the archive, you change the norm and fix the concentrated traffic. Put the expectation in your posting guidelines explicitly: describe what a screenshot shows in a sentence, and paste code, error messages, and stack traces as text in a code block rather than as images. The code-as-text argument sells itself to technical communities because text is searchable, copyable, and quotable, so you get compliance for reasons members already care about. Then use the traffic distribution: forum views concentrate overwhelmingly in accepted-solution posts, pinned guides, and a small set of popular threads, so having moderators add a describing reply or edit a description into those posts covers most real usage for a bounded amount of work. Make staff posts exemplary, since members copy the pattern they see from your team. Older low-traffic threads can be handled on request, which is a defensible position when the request path actually works.
Is the infinite-scrolling topic stream something we can fix ourselves?
Not the core behavior, no. The virtualized stream is fundamental to how Discourse renders long topics, and rewriting it is not a theme-level change. What you can control is everything around it, and that is where most of the practical improvement lives. Make sure landmark and heading structure is intact so users can jump to the header, the composer, and the sidebar without traversing the stream, and that a visible skip link works. Keep the paginated and print views of topics reachable, since a static rendering of a long thread is often the most usable path for assistive technology and costs you nothing to leave available. Verify your theme has not removed the focus indicator or broken the skip link, which is the most common self-inflicted version of this problem. Report concrete reproducible failures on Discourse Meta, because the platform team does act on specific accessibility reports and a fix upstream benefits every instance rather than just yours.
Further Reading
Other CMS Checklists
- Circle-so Accessibility Checklist
- Mighty-networks Accessibility Checklist
- Skool Accessibility Checklist
Get our free accessibility toolkit
We're building a simple accessibility checker for non-developers. Join the waitlist for early access and a free EAA compliance checklist.
No spam. Unsubscribe anytime.