Skip to content

AThevon/genjutsu / skills/_jutsu/mobile-principles

mobile-principles

Verified

Mobile-specific UX principles - touch targets, hover-less doctrine, thumb zones, safe areas, gestures, mobile perf budgets. Cross-platform (web mobile, iOS, Android).

FileKindSize
SKILL.mdskill md11.8 KB
references/accessibility-mobile.mdmarkdown5.7 KB
references/gestures-deep.mdmarkdown8.6 KB

references/accessibility-mobile.md

View on GitHub
# Mobile Accessibility (deep-dive)

Mobile accessibility patterns. Screen readers, dynamic type, contrast, motor accommodations.
Cross-platform reference for SwiftUI, Compose, and the mobile web. Backs up the parent SKILL.md's reduced-motion section with the Android 14+ nuance.

---

## Screen readers

### VoiceOver (iOS / macOS)

VoiceOver reads `accessibilityLabel`, then `accessibilityValue`, then `accessibilityHint`. Traits (`accessibilityAddTraits`) tell it the element's role.

```swift
struct VolumeSlider: View {
  @Binding var value: Double // 0...1

  var body: some View {
    CustomTrack(value: value)
      .accessibilityElement()
      .accessibilityLabel("Volume")
      .accessibilityValue("\(Int(value * 100)) percent")
      .accessibilityHint("Swipe up or down to adjust")
      .accessibilityAddTraits(.isAdjustable)
      .accessibilityAdjustableAction { direction in
        switch direction {
        case .increment: value = min(1, value + 0.1)
        case .decrement: value = max(0, value - 0.1)
        @unknown default: break
        }
      }
  }
}
```

### TalkBack (Android Compose)

Compose builds a semantics tree from modifiers. `clearAndSetSemantics` replaces children's semantics (use it when a custom composable should be announced as one element). `traversalIndex` controls reading order.

```kotlin
Box(
  modifier = Modifier
    .size(48.dp)
    .clickable(onClick = onToggle)
    .clearAndSetSemantics {
      contentDescription = if (liked) "Liked, double tap to unlike" else "Not liked, double tap to like"
      role = Role.Button
      stateDescription = if (liked) "On" else "Off"
    },
) {
  Icon(if (liked) Icons.Filled.Favorite else Icons.Outlined.FavoriteBorder, contentDescription = null)
}
```

### Web (mobile)

ARIA on mobile is the same API as desktop, just delivered to VoiceOver/TalkBack instead of NVDA/JAWS. No major divergence.

```html
<div role="slider" aria-label="Volume"
  aria-valuemin="0" aria-valuemax="100" aria-valuenow="60"
  aria-describedby="vol-help" tabindex="0"></div>
<p id="vol-help" class="visually-hidden">Swipe up or down to adjust</p>
```

---

## Dynamic type / font scaling

**SwiftUI** - system styles scale. Custom fonts opt in via `UIFontMetrics` or `dynamicTypeSize`.

```swift
Text("Hello").font(.body) // scales

Text("Custom").font(.custom("Inter-Regular", size: 17, relativeTo: .body))
  .dynamicTypeSize(.xSmall ... .accessibility3)
```

**Compose** - use Material typography; read `LocalDensity.current.fontScale` for extreme sizes.

```kotlin
val fontScale = LocalDensity.current.fontScale
Text(
  text = "Headline",
  style = MaterialTheme.typography.headlineSmall,
  maxLines = if (fontScale > 1.3f) 3 else 2,
)
```

**Web** - relative units, cap with `clamp()`.

```css
:root { font-size: 100%; }
h1 { font-size: clamp(1.5rem, 4vw + 1rem, 2.5rem); }
p  { font-size: 1rem; line-height: 1.5; }
```

---

## Contrast (WCAG 2.2 AA)

| Element | Ratio |
|---|---|
| Normal text (<18pt or <14pt bold) | 4.5:1 |
| Large text (>=18pt or >=14pt bold) | 3:1 |
| Non-text UI components, icons, focus rings | 3:1 |

Tools: Stark plugin (Figma), Xcode Accessibility Inspector (Audit tab), Android Accessibility Scanner. Never rely on color alone (WCAG 1.4.1): pair it with an icon, label, or pattern.

---

## Motor accommodations

**iOS** - detect alternative input methods:

```swift
if UIAccessibility.isAssistiveTouchRunning {
  // increase tap targets, slow auto-dismiss, avoid time-limited gestures
}
// also: isSwitchControlRunning, isVoiceOverRunning
```

**Android - reduce motion (the nuance).** The reliable system-wide signal is `ValueAnimator.areAnimatorsEnabled()` (API 26+): it returns `false` when the animator duration scale is 0, which the developer-options "Animation off" toggle, Battery Saver, and the user-facing Settings -> Accessibility -> Remove animations toggle all set. `Settings.Global.ANIMATOR_DURATION_SCALE == 0f` reads the same value directly (use it as the pre-API-26 fallback).

```kotlin
@Composable
fun rememberReduceMotion(): Boolean {
  val context = LocalContext.current
  return remember {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
      !ValueAnimator.areAnimatorsEnabled() // API 26+: reflects animator duration scale == 0
    } else {
      Settings.Global.getFloat( // fallback for API < 26
        context.contentResolver,
        Settings.Global.ANIMATOR_DURATION_SCALE,
        1f,
      ) == 0f
    }
  }
}
```

Switch Access works if you respect standard focusable semantics (`Modifier.focusable()`, proper traversal order). Avoid time-limited gestures; provide a button alternative.

**Web:**

```css
@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.001ms !important;
    transition-duration: 0.001ms !important;
  }
}
```

Large click targets (WCAG 2.5.8 Target Size (Minimum) is the **AA** bar at 24x24 CSS px, with a spacing exception; WCAG 2.5.5 Target Size (Enhanced) is the **AAA** bar at 44x44 CSS px - design to 44, audit against 24), no hover-only affordances, no drag-only interactions without a button fallback.

---

## Testing checklist

- [ ] VoiceOver and TalkBack pass: every interactive element announced with a clear label and role.
- [ ] Dynamic Type at 200% (iOS xxxLarge / Android fontScale 2.0): no truncation, no overlap.
- [ ] Contrast pass: 4.5:1 normal text, 3:1 large text and non-text components.
- [ ] All interactive elements have labels (no unlabeled icon button).
- [ ] No information conveyed by color alone.
- [ ] All gestures have a non-gesture alternative (button, menu, keyboard equivalent).

---

## Sources

- Apple Accessibility: https://developer.apple.com/accessibility/
- Android Accessibility: https://developer.android.com/guide/topics/ui/accessibility
- WCAG 2.2: https://www.w3.org/TR/WCAG22/
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall