# Instruction In Name (Mobile)

> In mobile apps, accessible names must not include instructions, gestures, or usage hints.

Source: https://knowledge.evinced.com/mobile/mobile-validations/instruction-in-name

Accessible names must not include instructions, gestures, or usage hints.

Use the accessible name to state the control's purpose. Don't include gestures, input methods, or other instructions, such as “*double tap*”, “*tap*”, “*long press*”, “*swipe up*”, or “*use the rotor*”. Assistive technologies already tell users how to operate a control, based on its role and state. When the name also contains instructions, screen readers announce them twice, once from the name and once from the control itself, and the two may even contradict each other. Users can also change the gestures their assistive technology uses, so instructions in the name may simply be wrong for them.

**Note:** If users need extra guidance, put it in the platform's hint instead of the name, for example `accessibilityHint` on iOS and in React Native, `hint` in Flutter's `Semantics`, or `onClickLabel` in Jetpack Compose.

## Pass Patterns

### Android

**XML Views**

The button's name comes from its text, “*Mute*”, with no instructions.

```xml
<Button
    android:id="@+id/muteButton"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="Mute" />
```

**Jetpack Compose**

The button's name comes from its text, “*Mute*”, with no instructions.

```kotlin
Button(onClick = { toggleMute() }) {
    Text("Mute")
}
```

### iOS

**UIKit**

The button's name comes from its title, “*Mute*”, with no instructions.

```swift
let muteButton = UIButton(type: .system)
muteButton.setTitle("Mute", for: .normal)
```

**SwiftUI**

The button's name comes from its title, “*Mute*”, with no instructions.

```swift
Button("Mute") {
    toggleMute()
}
```

### Cross Platform

React Native

The button's name comes from its text, “*Mute*”, with no instructions.

```tsx
<Pressable accessibilityRole="button" onPress={toggleMute}>
  <Text>Mute</Text>
</Pressable>
```

## Fail Patterns

### Android

**XML Views**

The `contentDescription` adds the instruction “*double tap to toggle*” to the name.

```xml
<Button
    android:id="@+id/muteButton"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="Mute"
    android:contentDescription="Mute, double tap to toggle" />
```

**Jetpack Compose**

The `contentDescription` adds the instruction “*double tap*” to the name.

```kotlin
Button(
    onClick = { toggleMute() },
    modifier = Modifier.semantics {
        contentDescription = "Mute, double tap"
    },
) {
    Text("Mute")
}
```

### iOS

**UIKit**

The `accessibilityLabel` adds the instruction “*double tap to toggle*” to the name.

```swift
let muteButton = UIButton(type: .system)
muteButton.setTitle("Mute", for: .normal)
muteButton.accessibilityLabel = "Mute, double tap to toggle"
```

**SwiftUI**

The `accessibilityLabel` adds the instruction “*double tap to toggle*” to the name.

```swift
Button("Mute") {
    toggleMute()
}
.accessibilityLabel("Mute, double tap to toggle")
```

### Cross Platform

React Native

The `accessibilityLabel` adds the instruction “*double tap to toggle*” to the name.

```tsx
<Pressable
  accessibilityRole="button"
  accessibilityLabel="Mute, double tap to toggle"
  onPress={toggleMute}
>
  <Text>Mute</Text>
</Pressable>
```

## Try It Yourself

### Using a screen reader

**New to screen reader testing, or need a refresher?**  
Review this article first: [Practical guides for using screen readers](https://knowledge.evinced.com/a11y-essentials/practical-guides-for-using-screen-readers)

1.  Turn on VoiceOver on iOS, or TalkBack on Android.
2.  Swipe right or left to move to the control.
3.  Listen to the control's name, before its role and the screen reader's own usage hint.

**Expected results:** The name states only the control's purpose, for example “*Mute, button*”.

**Actual results:** The name includes instructions, and the screen reader repeats them in its own hint, for example “*Mute, double tap to toggle, button, double tap to activate*”.

### Using developer tools

1.  **iOS:** In Xcode, open **Xcode > Open Developer Tool > Accessibility Inspector**, select the simulator or device, and point at the control. Check its **Label**.
2.  **Android:** In Android Studio, open the **Layout Inspector** and select the control. Check its `contentDescription`, for Views, or its semantics, for Jetpack Compose.

**Expected results:** The name contains no gestures or instructions.

**Actual results:** The name contains gestures or instructions, such as “*double tap*” or “*swipe up*”.

## FAQ

**Why is this issue marked as Best Practice?**

The control can still be found and operated, so users are not blocked. However, the repeated or contradicting instructions make announcements longer and can confuse users, especially when they have customized their gestures, so it is rated best practice.

## Standards and Regulations

This issue is classified as "**Best Practice**," meaning it isn't tied to a specific WCAG success criterion or any other regulation or standard; however it still affects the experience of some users. These issues fall outside formal compliance requirements, yet addressing them improves usability and accessibility in practice.

## Personas impacted by this issue

-   [Voice Input](https://knowledge.evinced.com/a11y-essentials/personas#voice-input)
-   [Screen Reader](https://knowledge.evinced.com/a11y-essentials/personas#screen-reader)

## Related Issues

-   [accessible-name](https://knowledge.evinced.com/mobile/mobile-validations/accessible-name)
-   [alternative-text](https://knowledge.evinced.com/mobile/mobile-validations/alternative-text)
-   [conflicting-state-in-name](https://knowledge.evinced.com/mobile/mobile-validations/conflicting-state-in-name)
-   [conflicting-type-in-label](https://knowledge.evinced.com/mobile/mobile-validations/conflicting-type-in-label)
-   [meaningful-alternative-text](https://knowledge.evinced.com/mobile/mobile-validations/meaningful-alternative-text)
-   [state-in-name](https://knowledge.evinced.com/mobile/mobile-validations/state-in-name)
-   [type-in-label](https://knowledge.evinced.com/mobile/mobile-validations/type-in-label)
