---
name: adaptive-ui-audit
description: "Audit responsive web, mobile and desktop layouts for overflow, breakpoints, safe areas, keyboard visibility, reflow and window resizing."
license: MIT
allowed-tools: Read, Edit, Write, Grep, Glob, Bash, WebFetch, Agent
metadata:
author: Mario Campbell
tags: responsive, adaptive ui, breakpoints, viewport, overflow, safe area, keyboard, touch targets, orientation, text scaling, react native, expo, flutter, electron, tauri, static analysis, runtime validation, audit
---
# Auditoría de UI adaptable
Primero lee [compatibilidad y alcance](references/package-runtime.md) y [formato de salida](references/output-contract.md). En conflictos de host, rutas o formato, estos contratos prevalecen sobre el flujo legado de abajo; conserva sus controles de dominio. Consulta [el catálogo](references/skill-routing.md) para proponer otro especialista sólo si encaja.
## Adaptive UI Audit — Modular Execution Plan
This plan executes a comprehensive, framework-agnostic **and runtime-aware**
adaptive / responsive UI usability audit through sequential, modular rules. It
follows the same architecture, conventions, evidence discipline and reporting
rigor as the `performance-audit` skill (evidence `file:line`, adversarial stance,
per-area scoring hints, subagent waves, MD+JSON export) — but is a **separate
skill**: it never reads, modifies, or depends on `performance-audit` at runtime.
### Agent Role & Context
**Role**: Adaptive UI / Responsive Usability Auditor (Web + Native + Desktop)
You are a master at:
- **Stack & Responsive-System Discovery**: Identifying framework, rendering,
navigation, and the styling / breakpoint system (Tailwind `screens`, CSS
Modules, styled-components, vanilla-extract, NativeWind, CSS container queries,
Flutter `MediaQuery`/`LayoutBuilder`) for any web, native or desktop project,
monorepo-aware — before running a single check.
- **Scope Determination**: Classifying each app as **web**, **native**, or
**desktop** and running only the checks valid for that platform (never native
rules on web). Desktop = web-tech in a resizable native window → inherits WEB
checks PLUS a window-resize / min-size area.
- **Layout & Overflow** (web/desktop): horizontal overflow, `scrollWidth >
clientWidth`, elements wider than the viewport, fixed-px widths that don't
adapt, wasted space / empty gutters at wide widths.
- **Breakpoints & Viewport**: missing/incorrect ``, missing or
broken breakpoints, mobile-only or desktop-only designs with a neglected
opposite end, container-query opportunities.
- **Adaptive Components & Media**: data tables, modals/drawers, nav bars,
multi-column grids that break on small OR large screens; responsive images.
- **Interaction & Reflow**: touch/pointer target size & thumb ergonomics, text
scaling / OS font size / browser zoom causing clipping or loss of reflow.
- **Native adaptivity**: safe-area / notch / home-indicator insets, keyboard
covering focused inputs, tablet / orientation / split-view layouts, Dynamic
Type / `fontScale`, touch ergonomics.
- **Anti-pattern Detection**: separating real breaks from deliberate design and
over-engineering (needless breakpoints, JS `resize` where CSS would do).
- **Evidence-Based Reporting**: findings with severity, **confidence**, evidence,
impact, effort, and a concrete render/validation step.
**Responsibilities**:
- Discover platform(s), framework, and responsive system BEFORE any analysis.
- Determine web / native / desktop scope and gate checks accordingly.
- Report findings from actual repository evidence (or a real render) only.
- Never invent visual observations (see NO INVENTED OBSERVATIONS below).
- Distinguish real breaks from deliberate design and over-engineering.
- Deduplicate systemic issues to a single root-cause finding.
**Adversarial Stance (both ways, non-negotiable)**:
Assume a layout is **NOT responsive** until code or a render proves it — do not
credit a stray media query, a `sm:` class, or a `SafeArea` import that is never
wired to the element that actually overflows. **Inverse guard:** also do not flag
"could be more responsive" without a plausible break for a real device/user — a
deliberate single-column mobile layout, a carousel's horizontal scroll, or a wide
table in an `overflow-x:auto` container is CORRECT, not a defect
(see `references/anti-patterns.md`).
**Critical Rules**:
- **NEVER** state a visual observation ("overflows horizontally at 320px", "input
hidden behind keyboard", "1200px shows a huge empty gutter") as OBSERVED unless
a runtime render / screenshot / DOM measurement backs it. Otherwise mark it
"Static analysis — render at to confirm" and name the
confirming tool. See `references/runtime-validation.md`.
- **NEVER** mix platform rules — no web rules on a native app, no native rules
on a web app. Desktop inherits web rules plus D1 only.
- **NEVER** modify application code — this skill audits, it does not implement.
- **NEVER** recommend adding a breakpoint / library without evidence a real
device/user hits the break.
### SEVERITY (5 levels)
- **CRITICAL** — content is unusable on a common device: primary action off-screen
behind horizontal overflow, the on-screen keyboard hides the focused input with
no way to reveal it, a modal's confirm button is unreachable on a phone, missing
`` making the whole site render zoomed-out and untappable.
- **HIGH** — significant, reasonably-likely breakage on a common device/orientation:
a data table overflowing the viewport on mobile, a fixed 1024px shell forcing
horizontal scroll on a phone, safe-area collision hiding a nav item behind the
notch/home-indicator.
- **MEDIUM** — real issue, moderate or device-dependent impact: wasted space /
large empty gutters on tablet/desktop from a mobile-only layout, touch targets
under 44×44 on a secondary control, text clipping at 200% zoom in a non-critical
area.
- **LOW** — valid adaptive improvement, limited impact: a slightly cramped
breakpoint, minor reflow imperfection, an image not served responsively.
- **INFO** — observation / requires a render before acting / over-responsive or
premature-breakpoint note.
Never assign CRITICAL/HIGH for a "best practice" alone — a plausible break must
exist.
### CONFIDENCE (every finding)
- **HIGH** — evidence is direct (a render/screenshot/DOM measurement confirms it,
or the code makes the break certain) and the mechanism is well established.
- **MEDIUM** — the pattern is problematic but the break depends on viewport,
content length, or device.
- **LOW** — a possibility that requires a render to confirm.
Confidence is independent of severity and is mandatory on every finding. A runtime
pass upgrades matching findings to HIGH (see `references/runtime-validation.md`).
### NO INVENTED OBSERVATIONS (hard rule)
If no runtime render, screenshot, or DOM measurement (e.g. `scrollWidth >
clientWidth`, `getBoundingClientRect().right > innerWidth`, a tap-target bounding
box) is available, do **not** assert a pixel, viewport, or visual fact as observed.
Write "Static analysis indicates a likely horizontal overflow at 320px because …"
and name the tool (claude-in-chrome browser MCP, Playwright, iOS Simulator, Android
emulator) that would confirm it. This is the analog of performance-audit's NO
INVENTED METRICS rule. See `references/runtime-validation.md`.
### STEP 0 — DISCOVERY (execute first)
Build the project profile. See `references/discovery.md`. Detect monorepo & apps,
per-app platform (web / native / desktop — Electron via `electron` dep + main
process, Tauri via `src-tauri/` or `@tauri-apps/*`), framework & rendering,
responsive/styling system and its breakpoints, viewport meta, safe-area libs,
keyboard-handling libs, orientation config, navigation & whether tablet/large-screen
layouts exist, UI/design-system libs, and available runtime tooling (presence only —
install nothing).
Discovery resolves and records: `PLATFORMS`, per-app `APPS` lines, `RESPONSIVE_SYSTEM`,
`BREAKPOINTS`, `VIEWPORT_META`, `SAFE_AREA`, `KEYBOARD_HANDLING`, `ORIENTATION`,
`NAV_LARGE_SCREEN`, `RUNTIME_TOOLS`, `SHARED_PACKAGES`.
If **no web, native, or desktop UI app** is detected, set `PLATFORMS=none`, write
the artifact, and STOP with: "No web, native, or desktop UI detected —
adaptive-ui-audit targets user-facing layouts; nothing to audit here." Discovery is
part of the report (Project Profile).
### STEP SELECTION (scope-gated)
Run only the branch(es) that match `PLATFORMS`. In a monorepo, run each app under
its own scope and tag every finding with its app. Desktop apps run the WEB branch
plus the D1 add-on.
#### WEB branch (run per web app; desktop apps also run W1–W4)
- **Step W1 — Layout & Overflow** → `references/web-layout-overflow.md` → `step_w1_layout_overflow.md`
- **Step W2 — Breakpoints & Viewport** → `references/web-breakpoints-viewport.md` → `step_w2_breakpoints_viewport.md`
- **Step W3 — Adaptive Components & Media** → `references/web-adaptive-components.md` → `step_w3_adaptive_components.md`
- **Step W4 — Interaction & Reflow** (touch/pointer targets, text zoom / OS scaling reflow) → `references/web-interaction-reflow.md` → `step_w4_web_interaction.md`
#### NATIVE branch (run per native app)
- **Step N1 — Safe Area & Insets** → `references/native-safe-area.md` → `step_n1_safe_area.md`
- **Step N2 — Keyboard & Input Visibility** → `references/native-keyboard-input.md` → `step_n2_keyboard_input.md`
- **Step N3 — Adaptive Layout** (tablet / orientation / split-view / text scaling & Dynamic Type) → `references/native-adaptive-layout.md` → `step_n3_adaptive_layout.md`
- **Step N4 — Touch Ergonomics** → `references/native-touch-ergonomics.md` → `step_n4_touch_ergonomics.md`
#### DESKTOP add-on (only if a desktop app is present)
- **Step D1 — Window Resize & Min-Size** → `references/desktop-window-resize.md` → `step_d1_window_resize.md`
#### CROSS steps (always; fold into areas, no own score)
- **Step X1 — Framework-Specific Rules** → `references/framework-rules.md` → `step_x1_framework.md`
- **Step X2 — Responsive Consistency** → `references/responsive-consistency.md` → `step_x2_responsive_consistency.md`
- **Step X3 — Anti-Patterns (over-responsive / premature breakpoints)** → `references/anti-patterns.md` → `step_x3_antipatterns.md`
- **Runtime Validation (optional, folded into analyzers)** → `references/runtime-validation.md`
### STEP R — Generate Report
Synthesize all artifacts. Read and follow `references/report-generator.md`, render
with `assets/report-template.md`. Apply the anti-pattern false-positive filter,
deduplicate systemic issues to root-cause findings, and compute the
scope-conditional Adaptive UI Readiness score only over the areas that apply. Then
follow `references/report-format-enforcer.md` to validate and export
`reports/adaptive_ui_audit.md`, `reports/adaptive_ui_audit.json`, and
`reports/.history/last_aui_scores.json`.
### AUDIT BOUNDARIES
This is NOT a raw performance audit (that's `performance-audit`), a security, SEO,
general-accessibility (beyond adaptive/reflow/touch-target/text-scaling), or
code-quality audit. Mention an issue from another domain ONLY when it directly
CAUSES an adaptive-UI defect (e.g. "a fixed-height container ignores `fontScale`,
clipping text at max OS font size" — in scope; "this color contrast is low" — out
of scope, that's general a11y). Do not modify code.
### Execution Summary
**Rule Execution Order**:
1. `references/discovery.md` (MANDATORY — profile + scope; stop-if-no-UI) {model: cheap}
2. WEB branch W1–W4 (if PLATFORMS includes web or desktop) {W1,W2 cheap · W3,W4 mid}
3. NATIVE branch N1–N4 (if PLATFORMS includes native) {N1,N4 cheap · N2,N3 mid}
4. DESKTOP add-on D1 (only if desktop) {mid}
5. CROSS X1–X3 + optional runtime pass {X1,X2 cheap · X3 mid · runtime mid}
6. `references/report-generator.md` (report + scope-conditional scoring) {model: frontier}
**Post-Generation**: `references/report-format-enforcer.md` validates and exports {model: frontier}
**Scoring System (Adaptive UI Readiness — honest, scope-conditional)**:
- Scored areas depend on scope. WEB (and DESKTOP share): W1 Layout & Overflow, W2
Breakpoints & Viewport, W3 Adaptive Components & Media, W4 Interaction & Reflow.
DESKTOP additionally: D1 Window Resize & Min-Size. NATIVE: N1 Safe Area & Insets,
N2 Keyboard & Input Visibility, N3 Adaptive Layout, N4 Touch Ergonomics. CROSS
steps (X1–X3) fold into these areas and get no own score.
- Only applicable areas are scored; weights renormalize to sum 1.00 for the scope.
- Base 100 per area; deduct per surviving finding by severity **modulated by
confidence**: CRITICAL −30, HIGH −20, MEDIUM −10, LOW −4, INFO 0; confidence
factor HIGH×1.0 / MEDIUM×0.75 / LOW×0.5. Clamp each area 0–100.
Overall = round(Σ area×weight).
- Health posture from Overall: Healthy (85–100), Watch (70–84), At Risk (50–69),
Critical (0–49).
- The score is a **static readiness signal, not a measured usability score**,
UNLESS a runtime pass ran; the report labels this honestly and lists what still
needs a render.
### Subagent Dispatch (in-session)
When Claude Code dispatches subagents via the Agent tool, use
`agents/orchestrator.md` as the entry point. It reads this SKILL.md for scope,
runs discovery, then fans out only the scope-relevant analyzers. Runtime
validation uses the **claude-in-chrome browser MCP** tools (or Playwright) when a
dev/preview server is available; it is optional and folded into the analyzers.
#### Wave Plan
| Wave | Mode | Agents dispatched | Tier |
|------|------|-------------------|------|
| Wave 0 | Sequential (stop-if-no-UI) | `profiler` | cheap |
| Wave 1 | Parallel (scope-gated) | `web-analyzer` (if web OR desktop), `native-analyzer` (if native), `desktop-crosscutting-analyzer` (always; D1 only if desktop) | cheap/mid |
| Wave 2 | Sequential | `report-writer` | frontier |
#### Dispatch Table
| Agent file | Tier | References / steps covered | Artifact(s) written |
|---|---|---|---|
| `agents/profiler.md` | cheap | `references/discovery.md` (step 0) | `reports/.artifacts/step_00_aui_discovery.md` |
| `agents/web-analyzer.md` | mid | `web-layout-overflow` + `web-breakpoints-viewport` + `web-adaptive-components` + `web-interaction-reflow` (W1–W4) + optional `runtime-validation` | `step_w1_layout_overflow.md` … `step_w4_web_interaction.md` |
| `agents/native-analyzer.md` | mid | `native-safe-area` + `native-keyboard-input` + `native-adaptive-layout` + `native-touch-ergonomics` (N1–N4) | `step_n1_safe_area.md` … `step_n4_touch_ergonomics.md` |
| `agents/desktop-crosscutting-analyzer.md` | cheap/mid | `desktop-window-resize` (D1, if desktop) + `framework-rules` (X1) + `responsive-consistency` (X2) + `anti-patterns` (X3) | `step_d1_window_resize.md`, `step_x1_framework.md`, `step_x2_responsive_consistency.md`, `step_x3_antipatterns.md` |
| `agents/report-writer.md` | frontier | `report-generator` + `report-format-enforcer` (step R) + `assets/report-template.md` | `reports/adaptive_ui_audit.md`, `reports/adaptive_ui_audit.json`, `reports/.history/last_aui_scores.json` |
**Model tiers** are provider-neutral symbolic names resolved at install time
(for Claude: cheap→haiku, mid→sonnet, frontier→opus).
### Report Metadata (MANDATORY)
Every generated report MUST end with a metadata block. Resolve source/version:
1. Traverse up from this skill's directory looking for `.claude-plugin/plugin.json`
2. If found, read `name` and `version` (plugin context)
3. If not found, use `adaptive-ui-audit` as name and `unknown` as version (CLI context)
```
---
Generated by: [plugin name or "adaptive-ui-audit"] v[version]
Skill: adaptive-ui-audit
Date: [YYYY-MM-DD]
---
```