content-grouping

When elements form a single logical unit, they should be exposed to assistive technologies as such

Description

Elements and text nodes that make up a single logical unit (i.e., should be read in a flow to preserve the context and meaning) should be grouped in a way that assistive technologies such as screen readers will read them correctly.

Quick Fixes

Set the accessibility label for every interactable element

Android (.xml), pass:

1<LinearLayout
2    android:id="@+id/message_container"
3    android:layout_width="match_parent"
4    android:layout_height="wrap_content"
5    android:orientation="vertical"
6    android:screenReaderFocusable="true">
7
8    <TextView
9        android:id="@+id/message_title"
10        android:layout_width="wrap_content"
11        android:layout_height="wrap_content"
12        android:text="@string/message_title"
13        android:focusable="false" />
14
15    <TextView
16        android:id="@+id/message_body"
17        android:layout_width="wrap_content"
18        android:layout_height="wrap_content"
19        android:text="@string/message_body"
20        android:focusable="false" />
21</LinearLayout>

Android (.xml), fail:

1<LinearLayout
2    android:id="@+id/message_container"
3    android:layout_width="match_parent"
4    android:layout_height="wrap_content"
5    android:orientation="vertical"
6    android:screenReaderFocusable="true">
7
8    <TextView
9        android:id="@+id/message_title"
10        android:layout_width="wrap_content"
11        android:layout_height="wrap_content"
12        android:text="@string/message_title"
13        android:focusable="true" />
14
15    <TextView
16        android:id="@+id/message_body"
17        android:layout_width="wrap_content"
18        android:layout_height="wrap_content"
19        android:text="@string/message_body"
20        android:focusable="false" />
21</LinearLayout>

Android (Java), pass:

1LinearLayout messageContainer = new LinearLayout(this);
2messageContainer.setId(R.id.message_container);
3messageContainer.setLayoutParams(new LinearLayout.LayoutParams(
4    LinearLayout.LayoutParams.MATCH_PARENT,
5    LinearLayout.LayoutParams.WRAP_CONTENT
6));
7messageContainer.setOrientation(LinearLayout.VERTICAL);
8messageContainer.setImportantForAccessibility(View.IMPORTANT_FOR_ACCESSIBILITY_YES);
9
10TextView messageTitle = new TextView(this);
11messageTitle.setId(R.id.message_title);
12messageTitle.setLayoutParams(new LinearLayout.LayoutParams(
13    LinearLayout.LayoutParams.WRAP_CONTENT,
14    LinearLayout.LayoutParams.WRAP_CONTENT
15));
16messageTitle.setText(R.string.message_title);
17messageTitle.setFocusable(false);
18
19TextView messageBody = new TextView(this);
20messageBody.setId(R.id.message_body);
21messageBody.setLayoutParams(new LinearLayout.LayoutParams(
22    LinearLayout.LayoutParams.WRAP_CONTENT,
23    LinearLayout.LayoutParams.WRAP_CONTENT
24));
25messageBody.setText(R.string.message_body);
26messageBody.setFocusable(false);
27
28messageContainer.addView(messageTitle);
29messageContainer.addView(messageBody);
30

Android (Java), fail:

1val messageContainer = LinearLayout(this).apply {
2    id = R.id.message_container
3    layoutParams = LinearLayout.LayoutParams(
4        LinearLayout.LayoutParams.MATCH_PARENT,
5        LinearLayout.LayoutParams.WRAP_CONTENT
6    )
7    orientation = LinearLayout.VERTICAL
8    importantForAccessibility = View.IMPORTANT_FOR_ACCESSIBILITY_YES
9}
10
11val messageTitle = TextView(this).apply {
12    id = R.id.message_title
13    layoutParams = LinearLayout.LayoutParams(
14        LinearLayout.LayoutParams.WRAP_CONTENT,
15        LinearLayout.LayoutParams.WRAP_CONTENT
16    )
17    setText(R.string.message_title)
18    isFocusable = false
19}
20
21val messageBody = TextView(this).apply {
22    id = R.id.message_body
23    layoutParams = LinearLayout.LayoutParams(
24        LinearLayout.LayoutParams.WRAP_CONTENT,
25        LinearLayout.LayoutParams.WRAP_CONTENT
26    )
27    setText(R.string.message_body)
28    isFocusable = false
29}
30
31messageContainer.addView(messageTitle)
32messageContainer.addView(messageBody)
33

How Users Are Affected

Screen reader users will receive the content in a fragmented and unclear way, which may hurt understanding the meaning and purpose of the element.

WCAG Success criteria

This issue might cause elements to fail one or more of the following Success criteria:
1.3.2 Meaningful Sequence (A) | Apple Human User Interface Guidelines, Accessibility, Navigation