Improve accessibility of Tutorial code samples
还没有人认领这个 Issue。
- 主要语言
- JavaScript
- 星标
- 11.8k
- 派生
- 7.9k
- 平均合并
- 1 天 11 小时
- 30 天内合并 PR
- 11
描述
This issue is being split out of #78 so that its specific action items can be discussed and tracked without cluttering the more general site-wide accessibility discussion.
Huge shout-out to @frastlin for raising this issue, and to @roblevintennis and others for stepping up to prototype and thoroughly discuss this. I'm really just here to polish and integrate their work into the live site!
Currently, the Tic-Tac-Toe example that readers are guided through on the Tutorial page is difficult or impossible to use by people using screen readers and other assistive technologies.
In previous discussions, some low-impact, high-value accessibility improvements have been identified that would not only provide value for the impacted end-users, but would also start readers (who may also be new developers) off on the right foot by promoting semantic, native markup and simple accessibility best practices as a normal part of the development process.
These changes wouldn't require significant (if any) rewriting of the existing narrative content, and may not even require explicit explanation at all (similar to the current markup). At a high level, there are really only three changes that need to be made:
- Implement a native
<table>instead of<div>s to organize Squares - Turn the next player status
<div>into an ARIA live region by addingaria-live="polite"andaria-atomic="true". - Insert the word "empty" as screen-reader-only inner text to buttons that have not been selected yet.
These changes can be seen in this prototype "Final Result" CodePen here: https://codepen.io/jasonwebb/pen/eYNdbpp?editors=0101
The <table> structure should be pretty self-explanatory, but for the player status live region I wonder if it might be nice to have a very short "tip" box saying something like, "ARIA live regions have their content read out by screen readers whenever it changes so that people using screen readers know whose turn is next!"
To implement these changes, a few adjustments need to be made to some of the step-by-step code samples, which are either on the page directly or hosted externally on CodePen.
I feel like its fine to prototype these new code samples using anybody's CodePen account, but when it comes time for a PR they should probably be handed off to an official ReactJS (or maintainer) account for posterity.
Here are each of the instances I could find throughout the page:
On-page code samples
- Update on-page code samples to use
<table>instead of<div>s.- Replace screenshot under Developer Tools section to reflect updated
<table>structure - Update on-page code sample at the very end of the Lifting State Up section to use
<table>structure. - Update on-page code sample at the very end of the Taking Turns section to use
<table>structure. - Update on-page code sample in the Lifting State Up, Again section to use
<table>structure.
- Replace screenshot under Developer Tools section to reflect updated
- Update on-page code samples for the
<button>markup to include rendering an sr-only "empty" string when no state is set.- Four code samples under Making an Interactive Component
- Update the second-to-last sample under Lifting State Up
- Update code sample under Function Components
- Update the "status" div to be an ARIA live region
- Large code sample at the end of Lifting State Up
- Large code sample at the end of Taking Turns
- Second code sample under Lifting State Up, Again
External code samples
- Update Final Result code sample on CodePen
- Update link in What Are We Building? section, or integrate updated code to the existing CodePen.
- Update the Starter Code code sample on CodePen
- Update link in the Setup Option #1 section, or integrate updated code to the existing CodePen.
- Updates links in steps 4 and 5 of the [Setup Option #2], or integrate updated code to the existing CodePen.(https://reactjs.org/tutorial/tutorial.html#setup-option-2-local-development-environment) section
- Update link in the [Inspecting the Starter Code], or integrate updated code to the existing CodePen.(https://reactjs.org/tutorial/tutorial.html#inspecting-the-starter-code) section.
- Update the intermediate code sample under the Passing Data Through Props section.
- Create updated CodePen
- Update the link to the CodePen, or integrate updated code to the existing CodePen.
- Update the intermediate code sample under the Making an Interactive Component section.
- Update the two intermediate code samples under the Lifting State Up section.
- Create updated CodePen for the first code sample.
- Update the link to the CodePen for the first code sample, or integrate updated code to the existing CodePen.
- Create updated CodePen for the second code sample.
- Update the link to the CodePen for the second code sample, or integrate updated code to the existing CodePen.
- Update the intermediate code sample under the Function Components section.
- Create updated CodePen
- Update the link to the CodePen, or integrate updated code to the existing CodePen.
Next steps
- I'll create a fork of the repo on my Github account (done) to try to unify the work to a common location.
- Open to other ideas! IIRC, we can't work directly on the master repo without permissions, so a forked repo is (I think) the way to go. Happy to be wrong though!
- As tasks are actioned by contributors, I can add their username next to the list items above so we all know what is already being worked on.
- Just drop a comment on this thread to let me know which task(s) you'd like to "own" and I'll add your name.
- When the tasks above are completed and accounted for in a unified branch somewhere, a PR will be opened on the master repo to propose integration.
If you see anything that I've missed, please let me know and I'll try to respond ASAP!
贡献指南
从这里开始
- 先读完整个 Issue,再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库,在一个分支上完成修改。
- 提交 Pull Request,并在描述里引用这个 Issue 编号。
调研方向
先从 Tutorial 页面和页面内及外部 CodePen 示例的检查清单开始,然后将所请求的表格、live-region 和仅供屏幕阅读器使用的文本更改与链接的 Final Result 原型进行比较。完成的标准是更新列出的示例、CodePen 链接和 Developer Tools 截图,使无障碍更改在整个教程中保持一致。
由索引模型根据 Issue 内容生成。
评估
- 技术栈
- javascript, react
- 领域
- accessibility, documentation
- Issue 类型
- 文档
- 难度
- 4/5
- 预计耗时
- 3-5 天
- 活跃度
- 停滞
- 描述清晰度
- 基本清楚
- 新手友好度
- 35/100