AThevon/genjutsu / skills/_jutsu/mobile-principles
mobile-principles
VerifiedMobile-specific UX principles - touch targets, hover-less doctrine, thumb zones, safe areas, gestures, mobile perf budgets. Cross-platform (web mobile, iOS, Android).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.8 KB |
| references/accessibility-mobile.md | markdown | 5.7 KB |
| references/gestures-deep.md | markdown | 8.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/
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |