chore: add documentation on accessibility of custom fields#9807
chore: add documentation on accessibility of custom fields#9807rachel-fenichel wants to merge 3 commits intoRaspberryPiFoundation:v13from
Conversation
|
|
||
| In general, the on-block display for a clickable field should have the ARIA | ||
| role `button` to indicate that an action will take place when it is clicked or | ||
| activated. |
There was a problem hiding this comment.
Is this the only example because it's known to the most common?
There was a problem hiding this comment.
Yes. Are there other roles that you think are worth including? Checkbox is the only other one that came to mind.
| must ensure that the result is meaningful when read with a screen reader. To | ||
| this end, if getAriaValue returns an invalid representation (i.e. `null` or | ||
| empty string) then it should be instead represented using a localization of the | ||
| text empty string to convey this to the user. |
There was a problem hiding this comment.
Nit: Add quotes around "empty string" for clarity?
There was a problem hiding this comment.
Updated to match the phrasing you suggested for extending a field.
|
|
||
| When extending a built-in field you will inherit its ARIA type and value logic. | ||
| You can override the inherited ARIA logic by overriding any of `getAriaTypeName`, | ||
| `getAriaValue`, and `computeAriaLabel`. |
There was a problem hiding this comment.
In general, do expect people to need to override computeAriaLabel? It's really just building the <ARIA type>: <ARIA value> string (or just <ARIA value> when type info is excluded). While it's possible to change how this works, I would think most developers would only need to override the other two.
There was a problem hiding this comment.
I also wonder if it would be overkill to include an example here of when you might want to override, such as making things more specific... Example: 'Angle' instead of 'Number' for type or n + ' degrees' for clarifying the meaning of the value.
There was a problem hiding this comment.
Do we have any built-in fields that do anything interesting for type or value that I could link to?
| that the result is meaningful when read with a screen reader. To this end, if | ||
| `getAriaValue` returns an invalid representation (i.e. `null` or empty string) | ||
| then it should be instead represented using a localization of the text | ||
| `empty string` to convey this to the user. |
There was a problem hiding this comment.
This is all factual, but I feel like we could make it a bit clearer. The word "it" on line 94 is particularly ambiguous, but I think we could generally tighten the responsibility here too:
getAriaValuemust return a human-readable, screen reader–appropriate representation of the field’s current value. By default, it returns the result ofgetText, which is not guaranteed to be informative for assistive technologies.
You must overridegetAriaValuewhengetTextmight not produce a meaningful spoken representation (for example, when possible values includes symbols, abbreviations, or non-textual representations such as icons or colors).
IfgetAriaValuewould return an empty or non-informative value, it must instead return a localized string indicating that the value is empty.
rachel-fenichel
left a comment
rachel-fenichel
left a comment
There was a problem hiding this comment.
I updated the ARIA value phrasing. Please let me know if it's clearer this way.
|
|
||
| In general, the on-block display for a clickable field should have the ARIA | ||
| role `button` to indicate that an action will take place when it is clicked or | ||
| activated. |
There was a problem hiding this comment.
Yes. Are there other roles that you think are worth including? Checkbox is the only other one that came to mind.
|
|
||
| When extending a built-in field you will inherit its ARIA type and value logic. | ||
| You can override the inherited ARIA logic by overriding any of `getAriaTypeName`, | ||
| `getAriaValue`, and `computeAriaLabel`. |
There was a problem hiding this comment.
Do we have any built-in fields that do anything interesting for type or value that I could link to?
| must ensure that the result is meaningful when read with a screen reader. To | ||
| this end, if getAriaValue returns an invalid representation (i.e. `null` or | ||
| empty string) then it should be instead represented using a localization of the | ||
| text empty string to convey this to the user. |
There was a problem hiding this comment.
Updated to match the phrasing you suggested for extending a field.
| that the result is meaningful when read with a screen reader. To this end, if | ||
| `getAriaValue` returns an invalid representation (i.e. `null` or empty string) | ||
| then it should be instead represented using a localization of the text | ||
| `empty string` to convey this to the user. |
2 participants
The basics
The details
Resolves
Part of #9787
Proposed Changes
Add information about accessibility and ARIA to the pages on extending a built-in field and creating a custom field.
Reason for Changes
Documentation!