mobile-principles

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha 7196f765fc11 · 28 Oct 2026Report an issue or request a re-scan

• Publisherathevon GitHub userOwner of the repository this skill is read from
• Source folderathevon/genjutsu/skills/_jutsu/mobile-principlesThe exact folder we audited
• LicenceNOASSERTIONAs the repository states it
• Commit pinned for this verdict7196f765fc11A new audit runs when the source changes
• Repository statusNot archivedLast push 22 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

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

---
name: mobile-principles
description: "Mobile-specific UX principles - touch targets, hover-less doctrine, thumb zones, safe areas, gestures, mobile perf budgets. Cross-platform (web mobile, iOS, Android)."
metadata:
  internal: true
---

> **Version-sensitive.** Every API name, SDK gate and browser-support claim below was
> verified on **2026-09-08** against primary sources. What against, and when, is in
> `_jutsu/VERSIONS.md`. If that date is old, re-verify before acting on a version number.

# Mobile Principles

> Touch-first UX context. Loaded when mobile is detected (web mobile, iOS, Android).
> Concise rules here. Deep-dive in `references/`.

---

## Touch Targets

| Platform | Recommended (design to this) | Hard floor | Spacing | Spec |
|---|---|---|---|---|
| Apple iOS / iPadOS | 44x44 pt | 28x28 pt | ~12 pt padding around bezeled controls, ~24 pt around unbezeled ones | Apple HIG, Accessibility > Mobility |
| Apple watchOS | 44x44 pt | 28x28 pt | as above | Apple HIG |
| Android | 48x48 dp | 48x48 dp | 8 dp between targets | Material Design 3 |
| Web mobile | 44x44 CSS px | 24x24 CSS px | 24 px un-overlapped spacing satisfies the AA exception | WCAG 2.5.5 Target Size (Enhanced), **AAA** = 44x44; WCAG 2.5.8 Target Size (Minimum), **AA** = 24x24 |

**Rule of thumb:** any tap target smaller than the platform minimum is a usability bug, period.
The hit area can extend beyond the visible glyph (use padding, `hitSlop`, or a transparent inner spacer), but the *interactive* surface must reach the minimum. Spacing matters as much as size: two 44pt buttons touching edges are still mistappable.

---

## No-Hover Doctrine

`:hover` does not exist on touch. Treating it as a primary trigger means hidden affordances on every phone. Anything reachable only by hover is, on mobile, simply gone. Visible-by-default is the rule; hover styles are a desktop *enhancement*, never a load-bearing interaction.

**CSS - gate hover styles behind a media query:**
```css
.card { opacity: 1; transform: translateY(0); }

@media (hover: hover) and (pointer: fine) {
  .card { opacity: 0.85; }
  .card:hover { opacity: 1; transform: translateY(-2px); }
}
```

**SwiftUI - tap and long-press, no pseudo-hover:**
```swift
Image(systemName: "heart")
  .onTapGesture { toggleLike() }
  .contextMenu {
    Button("Share", systemImage: "square.and.arrow.up", action: share)
    Button("Report", systemImage: "flag", role: .destructive, action: report)
  }
```

**Compose - combinedClickable for tap + long-press:**
```kotlin
Box(
  modifier = Modifier
    .combinedClickable(
      onClick = { toggleLike() },
      onLongClick = { showContextMenu() },
    )
) {
  Icon(Icons.Default.Favorite, contentDescription = "Like")
}
```

---

## Thumb Zones (Hoober)

Steven Hoober's research shows portrait phone use is overwhelmingly one-handed or cradled, with the thumb pivoting from the bottom corner. The screen splits into reachable zones:

```
+------+----+------+
| HARD | OK | HARD |   <- top: stretch, two-handed only
+------+----+------+
|  OK  | OK |  OK  |   <- middle: comfortable
+------+----+------+
| EASY |EASY| EASY |   <- bottom: natural thumb arc
+------+----+------+
```

- **Bottom third (EASY):** primary CTA, send, confirm, FAB, tab bar.
- **Middle (OK):** content, secondary actions.
- **Top (HARD):** back, close, search, profile - things the user expects to reach for, not hit by reflex.

**Rule:** primary CTA goes in the bottom half. Secondary, less-frequent or destructive actions go in the top. Never put a "Pay" button in the top-right corner of a phone screen.

---

## Safe Areas

| Platform | API | Insets respected |
|---|---|---|
| Web | `env(safe-area-inset-top|right|bottom|left)` + `viewport-fit=cover` | notch, home indicator |
| SwiftUI | `.safeAreaInset(edge: ...)`, `safeAreaInsets` env | nav bar, tab bar, notch, home |
| Compose | `Modifier.windowInsetsPadding(WindowInsets.safeDrawing)` | system bars, IME, cutouts |

**Web:**
```html
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
```
```css
.fab {
  position: fixed;
  bottom: calc(env(safe-area-inset-bottom) + 16px);
  right: calc(env(safe-area-inset-right) + 16px);
}
```

**SwiftUI:**
```swift
ScrollView { content }
  .safeAreaInset(edge: .bottom) {
    PrimaryCTA().padding()
  }
```

**Compose:**
```kotlin
Column(
  modifier = Modifier
    .fillMaxSize()
    .windowInsetsPadding(WindowInsets.safeDrawing)
) { /* content */ }
```

---

## Reduced Motion (cross-platform unified)

| Platform | API |
|---|---|
| Web CSS | `@media (prefers-reduced-motion: reduce)` |
| Web JS | `window.matchMedia('(prefers-reduced-motion: reduce)')` |
| SwiftUI | `@Environment(\.accessibilityReduceMotion) var reduceMotion` |
| UIKit | `UIAccessibility.isReduceMotionEnabled` |
| Compose | Custom helper using `Settings.Global.ANIMATOR_DURATION_SCALE` (see code below; deep-dive in `references/accessibility-mobile.md`) |

**SwiftUI:**
```swift
struct Hero: View {
  @Environment(\.accessibilityReduceMotion) var reduceMotion
  @State private var shown = false

  var body: some View {
    Text("Welcome")
      .opacity(shown ? 1 : 0)
      .offset(y: shown ? 0 : (reduceMotion ? 0 : 20))
      .animation(reduceMotion ? .none : .easeOut(duration: 0.3), value: shown)
      .onAppear { shown = true }
  }
}
```

**UIKit:**
```swift
let duration = UIAccessibility.isReduceMotionEnabled ? 0 : 0.3
UIView.animate(withDuration: duration) {
  view.alpha = 1
  view.transform = .identity
}
```

**Compose (helper pattern):**
```kotlin
@Composable
fun rememberReduceMotion(): Boolean {
  val context = LocalContext.current
  return remember {
    Settings.Global.getFloat(
      context.contentResolver,
      Settings.Global.ANIMATOR_DURATION_SCALE,
      1f,
    ) == 0f
  }
}

val reduceMotion = rememberReduceMotion()
val spec = if (reduceMotion) snap() else tween<Float>(durationMillis = 300)
```

> Note: prefer `ValueAnimator.areAnimatorsEnabled()` (API 26+) - it ret

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/athevon/genjutsu
git -C genjutsu checkout 7196f765fc11

Works in

1. 2026-10-28
   ✓SAFE B 89 / 100

   first audit · source 7196f765fc11

Questions about mobile-principles

• github.com/athevon/genjutsu/tree/main/skills/_jutsu/mobile-princ — the audited source at commit 7196f765fc11 and every finding aboveObserved · 28 Oct 2026

Spotted something wrong? Report a correction · Methodology