Please document correct usage of accessibilityRole "link" #3215

Description

Here's the current documentation for accessibilityRole="link":

link Used when the element should be treated as a link.

This... could be more helpful. It's arguably a tautology: it says the link role should be used in those cases where the link role should be used.

There are many examples (some given below) of inconsistent and sometimes contradictory ways this has been interpreted.

What is the problem?

This is a problem because people fill in their own common-sense opinion on how link roles should be used (possibly influenced by non-equivalent experience of links on websites).

For example, I've encountered three different interpretations on how the link role should be used, all from seemingly authoritative sources:

1. Navigation between screens: The widely used react-navigation project has utilities like useLinkProps that apply accessiblityRole="link" to any element that navigates between screens - every element using these utilities that would do internal routing in a web context will get the "link" role in Android and iOS.
2. All interactive inline text: The react-native-accessibility-engine project has a test "link-role-required" that requires any Text element with an onPress handler to have the role "link", regardless of what the press does. This appears to be interpreting "link" by presentation (interactive inline text) rather than the nature of the action.
3. Opening URLs in device browser: App accessibility consultants I've worked with in the past have advised that "link" should be used specifically for interactive elements that cause the app open and focus a web browser, and that "button" should be used for in-app navigation (regardless of element type). Here's an example of an accessibility consultancy giving this advice in the context of iOS:

Links open a URL in an external browser. This the important distinction between buttons. Only apply the trait of link when the users interaction with the control will take them out of your application and into Safari.

How can we address it?

There is one right answer as to how React Native's link accessibilityRole is intended to be used, based on the appropriate iOS and Android guidance for the underlying properties and traits that React Native applies internally to the native Android and iOS elements it controls.

The React Native accessibility docs should state it clearly. For example (assuming this one is correct):

link Interactive elements that load a web page in a device browser, switching focus away from this app

Why is it important?

There's clearly already diverging interpretations of how this role should be used, and it's a very commonly used role, so there is almost certainly already a lot of inconsistency on when elements are described as a "Link" in React Native apps in production.

Who needs this?

Ideally all React Native developers should be applying this accessibilityRole consistently and correctly.

When should this happen (use version numbers if needed)?

As soon as there's a clear consensus on what the correct usage is.