Add accessibility to /learn section of Lichess#20552
Conversation
|
I went through the whole first stage (the rook). In the visual interface, you have 2 options:
Let me know if you need some assistance |
|
In my tests, the buttons for next and back to menu appear at the bottom of the DOM after a stage has passed. I will try to reproduce and implement a fix if necessary. |
|
Looks like something fell over when implementing latest master at some point. I've fixed it, the branch as it is currently properly renders the stage complete screen for me |
Adds a parallel `learn.nvui` bundle gated on `site.blindMode`, mirroring the puzzle/round/analyse pattern. First cut covers stage map, goal, text board, move form, status, last move, settings and basic board commands. Apple announcements, scenario chaining and promotion input are not yet wired up.
Adds an aria-live polite "Apples" section listing remaining apple squares on apple levels — the diff is announced as squares are collected. For promotion moves, parses the role from the 5-char UCI returned by inputToMove and resolves the parked promotion via promotionCtrl.finish, skipping the visual-only piece picker.
Wraps the rendered board in a hooked div and attaches the standard nvui handlers: arrow-key navigation, piece-jump letters, rank-jump digits, click-to-select, 'o' to announce the current square, 'm' to list possible moves from the focused square, and 'i' to focus the move input. Adds the .boardstatus aria-live region the handlers write into.
- Pass orig/dest to setFen on player moves so ground.state.lastMove is preserved and the last-move aria-live region updates correctly - Replace shared boardCommands() (which requires i18n.keyboardMove and includes a clock command irrelevant to learn) with an inline list of the commands that actually apply - Add renderStageComplete: when stageCompleted() is true, replace the board view with an assertive aria-live announcement, completion text, and Next/Back to menu navigation buttons
- Use hl() from lib/view instead of h() from snabbdom, matching the codebase convention used in puzzle.nvui - Import VNode from lib/view; drop the snabbdom import - Use Api directly instead of aliasing it as CgApi - Remove role="status" from assertive aria-live regions; role="status" implies polite and contradicts aria-live="assertive"
Blueprint shapes (arrows/circles drawn on the board to guide the player) are invisible to screen reader users. Translate them to a Hints section: green arrows become "a1 to c1", red arrows "Threat: e5 to a1", blue arrows (stalemate escape squares) "Cover: e3 to a7", circles just the square name. Section is omitted when a level has no shapes.
zersiax
force-pushed
the
learn-nvui
branch
2 times, most recently
from
1638166 to
99ec8ac
Compare
|
@zersiax is a prominent developer whose work has significantly benefited the blind community across a number of important projects, so I think this is a great initiative.
That said, I’m curious about how the Learn feature is intended to work from an accessibility perspective. How does the feature currently guide sighted beginners? Does it mainly teach piece movement, board coordinates, and the basic rules of chess, or does it go beyond that?
For blind users, it may also be worth considering whether some lessons should include guidance on interacting with the board itself. For example:
How to navigate the board using the keyboard.
How to identify squares and piece locations non-visually.
How to use the available accessibility commands and shortcuts.
How to review moves and follow lesson instructions without relying on visual cues.
In other words, should accessibility-related interaction skills be integrated into the lessons, or would the goal be to keep Learn focused purely on chess concepts and rules?
I’d be interested to hear your thoughts on the intended scope of the feature and how accessibility content might fit into it.
|
|
@yafred Would you like me to make these visible for non-screen reader users? I wasn't sure if this way would be best, or if we should somehow reuse the visual on screen instead. Either way I think it works. @ikrami1 Right now, the Learn section essentially teaches users chess moves and manoeuvers by having the player collect stars off the chessboard with a single type of piece, to teach how the piece moves, or by resolving a preset situation, e.g., your king is in check, get him to safety in x moves. It doesn't really teach anything else to my knowledge, and adding more content the way you're describing would be an overall Learn effort, not so much an accessibility fix. So I'd say this PR isn't the best last-off point for that, an issue or discussion topic might be better? |
|
@zersiax thanks so much for the clarification. I have no idea how the feature actually works, so your explanation is what I needed. No need to add or modify anything. Keep up the excellent work. @yafred <https://github.com/yafred> will help me test the feature soon.
|
|
@zersiax don't bother about the visibility of the buttons ... ikrami1 will certainly give his feedback himself but there is something we should fix before we go online and start improving the details. |
|
That's a good idea. I think hints should probably be good to read out with a command as well. I will attach those to g and h both in the command input and the board, and i noticed we're auto-skipping the initial stage intros in NVUI while they do show up on the visual side. Fixing that as well, will commit when properly tested |
|
And done. Let me know if you find any other gaps @yafred |
|
That looks perfect .... A few minor comments:
I was also thinking that, may be, we should just say black pawns instead of stars. But It just occurred to me that this is inherited from the visual interface texts. |
|
how about one more command / shortcut to read the remaining stars and there positions? so: g reads the goal, v reads the hint, s reads the stars.
This looks amazing and a great value for people to actually learn chess. I have been playing for quite sometime and i really enjoyed going through the stages to learn the pieces.
|
|
@yafred I'm using stars because that is what is used in the tutorials and goal texts, e.g. "collect all the stars". I figured keeping it that way might be more uniform. |
|
ئِre stars: i agree, in the educational and training context, stars sounds cool.
re s key: it is not used with any other command as far as i am aware.
With these simple improvements, the feature will be very mature and ready to appear on the site in my opinion.
Keep up the great job.
|
|
@zersiax thanks for your effort, i will be adding the below text to the blind mode tutorial, i hope you can review it and see if it needs any modifications or improvements as the author of the feature. 7. Learn: Accessible Chess TutorialsLichess includes a comprehensive /learn section — a series of interactive tutorials designed to teach chess basics, piece movement, and fundamental tactics to new players. This section has become fully accessible to blind and visually impaired users, closing a long-standing gap in the platform's accessibility. The tutorials are ideal for:
For many blind users, learning chess online has been challenging because most tutorials rely on visual diagrams, arrows, and highlighted squares. The accessible Learn section changes this by:
Whether you are completely new to chess or an experienced player who wants to explore variants or practice specific piece movements, the Learn section is now a fully accessible gateway to the game. The Learn section is organized into several categories and stages, each teaching a specific chess concept through interactive exercises:
Each stage presents a chessboard with a specific goal — usually to collect all stars by moving a designated piece to each starred square, or to resolve a situation in a limited number of moves (e.g., get your king out of check). 7.1. Accessing the Learn Section
7.2. Tutorial Interface and NavigationWhen you open a tutorial stage, the interface will feel familiar — it closely resembles the puzzle and analysis screens, with some important differences:
7.3. Tutorial-Specific Features and CommandsWhen you are focused on the chessboard, make sure your screen reader is in Focus Mode (e.g., The Learn section introduces several new concepts and keyboard commands tailored to the tutorial experience: Collecting Stars
You can also type any of these commands into the command input field (the edit box labeled "Your move" or "Command input"). Just type the letter ( Stage CompletionWhen you successfully complete a stage:
Important Notes for Learn Mode
|
|
@ikrami1 for the documentation, we can proceed as usual. When you hare happy with the content, you can send the markdown to me so that we compare it to https://github.com/yafred/lichess-blind-mode/tree/master/docs/_pages before I update the Lichess page |
|
LGTM @ikrami1 , feel free to proceed |
|
Just quickly checking in, are we waiting on me currently? The docs were written by @ikrami1 and the code is all done, just making sure there's no miscommunication happening :) |
|
As I understand it, the next step is for a Lichess maintainer to review the pull request and merge it when they have time. I’m not sure how long that usually takes, but in my experience Lichess tends to review and merge contributions fairly quickly. Your work is important, necessary, and genuinely valuable for both blind learners and the people who teach and support them. From my testing, the feature works flawlessly and is ready to be used. Perhaps @ornicar is simply busy with other priorities at the moment and hasn’t had a chance to review it yet. Hopefully it will get the attention it deserves soon. |
4 participants
The problem
Lichess is one of the most accessible chess websites for people using a screen reader, leaving competitors far behind where the screen reader-specific experience is concerned.
There has, historically, been one big gap particularly for new players, and that is the tutorials at /learn.
While I feel these would be a great way for new players to develop board orientation, spatial awareness around the pieces etc., they were never included in the accessibility offerings that cover live play, analysis and puzzle screens so far, and haven't been for a number of years.
My attempt
I'll be the first to admit my Scala is very rusty, so I tried to touch that side of things as little as possible. I'd be happy to make changes if required.
I essentially used the accessibility work on the puzzle screen as my example, copied it as far as I was able and then added tutorial-specific fixes within the actual UI. I tried to stick to code conventions I saw used in other parts of the codebase to keep the codebase consistent.
Basically, this adds:
testing
I spun up lila-docker on a macbook pro and tested the changes live as I was making them, using a Windows browser with NVDA (screen reader) running. I can confirm these changes work as intended in that sense (see caveats below). If a testing video if required I can do that.
Caveats
I myself am a blind screen reader user, and I based how the tutorials work on what I could glean from the code. If there are other visual inicators that would be useful to add I didn't find them, but would be happy to add them if someone can point them out.
Similarly, I have tested the screen reader experience thoroughly, but may have missed unintended visual changes. I'm open to feedback on getting this experience merged so others can benefit from them.