mobile-viewport-craft

name

mobile-viewport-craft

description

Design the mobile and responsive viewport craft for a web UI — a content-driven breakpoint strategy (mobile-first; breakpoints where the layout breaks), touch-target sizing and spacing, safe-area/notch handling, the dynamic-viewport-unit fix for the URL-bar resize (the 100vh trap → svh/lvh/dvh), input behavior (right types, no focus-zoom, keyboard occlusion), hover-absence (no hover-only affordances) and gestures, and responsive layout patterns (reflow, wide tables, orientation). Produces a per-surface viewport/touch craft spec. Owns layout/touch/viewport CORRECTNESS on small screens; mobile page WEIGHT and network cost are frontend-perf-engineer's. Use when designing responsive layout, breakpoints, or touch interactions, or when a UI overflows, mis-sizes taps, or hides content behind browser chrome. Do NOT use for mobile performance/bundle weight (frontend-perf-engineer), non-happy-path states (edge-state-ux-designer), or accessibility VERIFICATION (accessibility-test-harness).

Mobile Viewport Craft

Purpose

The desktop layout "works on mobile" until a real thumb hits it: taps land on the wrong control because targets are 24px and crammed together, a full-height panel is cut off because 100vh includes the space the browser's URL bar will later reclaim, the bottom action button sits under the home indicator, and a hover-only menu simply never opens because touch has no hover. This skill produces the viewport craft for a web surface — a content-driven breakpoint strategy, touch-target sizing, safe-area and dynamic-viewport-unit handling, input/keyboard behavior, hover-absence and gesture design, and the responsive layout patterns for reflowing real content (including wide tables) onto small screens. It owns layout, touch, and viewport CORRECTNESS; the page's WEIGHT and network performance on mobile are frontend-perf-engineer's.

Use When

• Use when: designing responsive layout or a mobile breakpoint strategy, or making a desktop-first UI work on phones/tablets.
• Use when: designing touch interactions — target sizing, thumb reach, gestures — or replacing hover-only affordances for touch.
• Use when: a UI overflows horizontally, mis-sizes tap targets, or hides content behind the mobile browser chrome / notch / home indicator (the 100vh trap).
• Use when: designing form input behavior on mobile — keyboard types, focus-zoom, the focused field hidden behind the on-screen keyboard.
• Use when: reflowing wide content (tables, dashboards) onto small screens, or supporting orientation and OS text-scaling.
• Do NOT use when: the task is mobile PERFORMANCE — bundle weight, image payload, JS execution cost on low-end devices — that is frontend-perf-engineer; this skill owns layout/touch, not kilobytes.
• Do NOT use when: the task is the view's empty/loading/error STATES — that is edge-state-ux-designer; those states still need mobile craft, but the state design itself is separate.
• Do NOT use when: the task is VERIFYING accessibility (screen-reader, contrast, keyboard) as a test pass — that is accessibility-test-harness; this skill designs touch/viewport craft and notes a11y intent (target size, zoom-safety) that the harness then checks.

Inputs to Inspect

1. The real device/context mix for this product (from usage data if available): which viewport widths, OS/browsers, and input modes actually matter, and the minimum supported width.
2. The surfaces in scope and their content: navigation, forms, data tables/dashboards, media — each has different reflow needs.
3. The existing layout system: CSS approach (fl/grid, framework), current breakpoints, use of viewport units, and any known mobile breakage (horizontal scroll, clipped panels, tiny taps).
4. Interaction inventory: anything currently hover-dependent (tooltips, dropdowns, row actions), custom gestures, and fixed/sticky elements that interact with the keyboard.
5. Constraints from siblings: frontend-perf-engineer's device/network class (so the craft targets the same baseline), and any a11y obligations (target size, 200% zoom) that accessibility-test-harness will verify.

Workflow

1. Set the target context and go mobile-first. State the minimum supported width, the device/input classes that matter, and design up from the smallest — progressive enhancement, not desktop shrunk down.
2. Choose breakpoints by content, not devices. Add a breakpoint where THIS layout starts to break (line length too long, columns too cramped), not at a list of named phone widths that dates instantly. Fluid between breakpoints; reach for container queries when a component's layout depends on its own space, not the viewport's.
3. Design touch targets. Minimum hit area (~44×44px guideline) with adequate spacing so adjacent targets aren't mis-hit; put primary actions in the thumb-reachable zone; ensure the tappable area matches the visual (padding, not just the icon glyph).
4. Handle the viewport chrome honestly. Replace 100vh with dynamic viewport units (dvh/svh/lvh) so full-height layouts account for the collapsing URL bar; apply safe-area-inset-* for notches and the home indicator; verify fixed headers/footers don't cover content or collide with the keyboard.
5. Design input and keyboard behavior. Correct input types and inputmode for the right on-screen keyboard; input font-size that avoids iOS focus-zoom (≥16px); ensure the focused field scrolls above the keyboard rather than hiding behind it; sensible autofill/ autocomplete.
6. Eliminate hover dependence and design gestures. Every hover-only affordance (tooltip, menu, row action) needs a touch-reachable equivalent (tap, disclosure, long-press with a visible alternative). Custom gestures must be discoverable and must not fight the browser's own (back-swipe, pull-to-refresh, scroll).
7. Reflow real content. Choose reflow (stack columns) vs hide (progressive disclosure — never hide a critical action). For wide tables pick a pattern deliberately: stack-to-cards, horizontal scroll with a frozen key column, or priority-column collapse — and state the tradeoff. Long forms, nav (bottom-bar vs hamburger), and responsive media all get an explicit pattern.
8. Support orientation and OS text-scaling. Rotation doesn't break layout or lose state; respect OS text-size / browser zoom (don't clip or overlap at 200%) — record this as a11y intent for accessibility-test-harness to verify.
9. Name boundaries and deliver the per-surface craft spec: weight/ network → frontend-perf-engineer; states → edge-state-ux-designer; a11y verification → accessibility-test-harness.

Breakpoint patterns, the touch-target and safe-area reference, the viewport-unit cheat sheet, and wide-table reflow options: references/mobile-viewport-sheet.md.

Output Format

MOBILE VIEWPORT CRAFT — <surface(s)>
Targets:      min-width=<n>; device/input classes; mobile-first stated
Breakpoints:  <content-driven list + rationale>; container queries where component-scoped
Touch:        min target ~44px + spacing; thumb-zone for primaries; hit-area = visual
Viewport:     100vh → dvh/svh/lvh; safe-area-inset applied; fixed elements vs keyboard checked
Input:        input types/inputmode; font-size ≥16px (no focus-zoom); focused field above keyboard
Hover/gesture: hover-only affordances → touch equivalents; custom gestures discoverable, no browser conflict
Layout:       reflow-vs-hide per region; wide-table pattern chosen (cards|scroll+frozen|priority) w/ tradeoff;
              nav pattern; responsive media
Orientation:  rotation-safe; OS text-scale/200% zoom respected (a11y intent)
Boundaries:   weight/network → frontend-perf-engineer; states → edge-state-ux-designer;
              a11y verify → accessibility-test-harness

Validation Checklist

• Design is mobile-first with a stated minimum width; breakpoints are content-driven, not a list of device widths.
• Touch targets meet a minimum size with spacing, and the tappable area matches the visual; primaries are thumb-reachable.
• Full-height layouts use dynamic viewport units, not 100vh; safe- area insets are applied for notch/home-indicator.
• Inputs use correct types, avoid focus-zoom (≥16px), and the focused field is not hidden behind the on-screen keyboard.
• No affordance is hover-only; each has a touch equivalent, and custom gestures don't conflict with browser gestures.
• Wide content has a deliberate reflow pattern with its tradeoff stated; nothing critical is hidden to "fit".
• Orientation change is safe and OS text-scaling/200% zoom doesn't clip or overlap (recorded for a11y verification).
• Weight/performance, state design, and a11y verification are handed to their owning skills, not solved here.

Gotchas

• 100vh on mobile is taller than the visible viewport because it includes the space the URL bar will reclaim — the bottom of a full-height layout gets cut off or sits under browser chrome. dvh/ svh/lvh exist precisely for this; 100vh is the single most common mobile layout bug.
• A 44px visual button with a 44px tap area is fine; a 44px icon with only the 16px glyph tappable is a miss-fest. Size the hit area, not just the picture.
• Inputs with font-size below 16px trigger auto-zoom on iOS, jarring the whole layout on focus. 16px is a functional floor, not a style choice.
• Hover-only menus and tooltips are invisible on touch — there is no hover event. Every hover affordance needs a tap path, or it doesn't exist for half your users.
• Breakpoints named after last year's flagship phone are obsolete on arrival and miss foldables, tablets, and split-screen. Break where the content breaks.
• The on-screen keyboard covers the bottom ~40% of the screen; a focused input or a fixed "Save" bar down there disappears behind it unless you scroll it into view or adjust for the keyboard.
• Hiding "secondary" content to fit mobile often hides the thing the user came for. Progressive disclosure is fine; hiding the primary action to win space is not.
• Custom left-swipe gestures fight the browser's back-swipe and pull-to- refresh; design gestures that coexist with the platform, not against it.

Stop Conditions

• The request is about mobile PERFORMANCE — bundle size, image weight, JS cost on low-end devices, metric budgets → route to frontend-perf-engineer; this skill owns layout/touch/viewport, not payload.
• The request is the view's empty/loading/error STATE design → route to edge-state-ux-designer (those states still need mobile craft, but the state model is separate).
• The request is to VERIFY accessibility (screen-reader announcements, contrast ratios, keyboard traversal) as a test pass → route to accessibility-test-harness; this skill records a11y intent, it does not run the checks.
• Meeting a touch-target or zoom-safety minimum would require dropping a feature or an a11y obligation the product must keep → surface the tradeoff to a human rather than silently shrinking targets below the usable/accessible floor.

Supporting Files

• references/mobile-viewport-sheet.md — content-driven breakpoint patterns, the touch-target and safe-area reference, the viewport-unit cheat sheet, input-type/keyboard table, and wide-table reflow options.
• evals/evals.json — behavior cases including the 100vh trap fix, the hover-only-to-touch conversion, and the wide-table reflow.
• evals/trigger-evals.json — discrimination against frontend-perf-engineer (weight vs craft), edge-state-ux-designer, and accessibility-test-harness.