Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Accessibility][Keyboard support] Add access keys & arrow keys docs and add clarify guidance #1271

Merged
merged 25 commits into from
Apr 28, 2023

Conversation

citelao
Copy link
Contributor

@citelao citelao commented Apr 18, 2023

Today, our Keyboard support section does not include information about access keys or arrow keys, and doesn't have much documentation about default behavior or reference documents. This change adds guidance for access keys, arrow keys, and more, and documents the expected and default behavior for many of them.

Fixes #1229
Fixes #1225
Fixes #1226

Description

  • Tab order
    • Added example of default behavior.
    • Clarified guidance & added documentation links.
    • Updated manual tab order example to differ from default behavior.
  • Arrow keys
    • Added arrow keys section, with default example and custom example using XYFocusKeyboardNavigation.
    • Documented common expectations for arrow keys, like Home/End, PgUp/PgDn, and PosInSet/SizeOfSet.
  • Accelerators
    • Demonstrate the default tooltip for keyboard accelerators.
    • Add an example with a custom tooltip.
  • Access keys
    • Added an example of access keys, plus documentation.
  • Landmarks & headings
    • Moved to Screen reader section, since it has no effect on Keyboard.
    • Added references for understanding headings & landmarks.
    • Added example with custom landmarks.
    • Documented "Narrator contexts", or how Narrator will read controls within named accessible groups.

Motivation and Context

This addresses documentation gaps in our keyboard examples. Hopefully it will lead folks to design more keyboard-accessible UI.

How Has This Been Tested?

Deployed locally.

  • Narrator correctly narrates new content.
  • Keyboard examples work as described.
  • Links work
  • Why aren't accelerator keys correctly setting the UIA AcceleratorKey property?

Screenshots (if appropriate):

Keyboard page

pg 1 of keyboard

pg 2 of keyboard

pg 3 of keyboard

Screen reader page

pg 1 of screen reader
pg 2 of screen reader

Types of changes

  • New feature (non-breaking change which adds functionality)

@citelao
Copy link
Contributor Author

citelao commented Apr 19, 2023

We should probably add examples of access keys to the menubar pages!

@citelao citelao requested a review from marcelwgn April 25, 2023 18:41
Comment on lines +234 to +236
<Hyperlink
NavigateUri="https://learn.microsoft.com/windows/apps/design/input/keyboard-interactions#navigation">
Keyboard interactions#Navigation
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did you mean to include the # inside the displayed text of the link? Maybe we use - instead if we want to indicate that we are only linking to sections of the same page?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I did deliberately chooose # as the separator. It's a bit dev-y, but my reasoning was that # represents an anchor link---it's the literal character used to denote anchors in a URL. I worried - would be too ambiguous (is this a subpage of a section? A long title? etc).

I'm open to changing it, though, if it's confusing.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The only thing I'm afraid is people thinking this is by mistake though I think this is a risk we can take here. After all, our audience is mostly devs.

Comment on lines +340 to +351
Text="Potatoes?" />
<!--
XYFocusKeyboardNavigation enables arrow keys between the buttons.

Note that:

- The buttons are still tabbable by default
- Home/End and PgUp/PgDn do not work
- Screen readers do not read PositionInSet/SizeOfSet ("1 of 3")

All of that would require custom work.
-->
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was thinking having it be present in the XAML sample code would be fine but I guess having it twice doesn't hurt and is also closer to reality when reading the sample code in app.

@marcelwgn
Copy link
Collaborator

PR looks good to me, thank you so much for working on all of this @citelao!

@marcelwgn
Copy link
Collaborator

@karkarl If you wanna take a look, otherwise I would merge this

@karkarl karkarl merged commit 491fc72 into microsoft:main Apr 28, 2023
@citelao citelao deleted the user/besto/keyboard_support branch May 1, 2023 20:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
3 participants