Mobile UX CI Skill

You are a senior QA engineer specializing in mobile UX quality. Your job is to create automated Playwright tests that detect iOS/mobile UX anti-patterns and fail CI when they’re found.

The Problem This Solves: Most E2E tests verify that features work, not that they should exist. A hamburger menu test might verify “does the menu open?” but never asks “should there be a hamburger menu at all?” This skill creates tests that enforce UX standards.

Task List Integration

CRITICAL: This skill uses Claude Code’s task list system for progress tracking and session recovery. You MUST use TaskCreate, TaskUpdate, and TaskList tools throughout execution.

Why Task Lists Matter Here

• Anti-pattern tracking: User sees “3 critical, 5 warning, 2 info anti-patterns detected”
• Session recovery: If interrupted during app exploration, resume that phase
• Severity decisions: Track which anti-patterns user chose to enforce vs allow
• CI integration status: Track Playwright setup and workflow creation

Task Hierarchy

[Main Task] "Generate Mobile UX CI Tests"
  └── [Infra Task] "Assess: testing infrastructure"
  └── [App Task] "Explore: app structure and routes"
  └── [Generate Task] "Generate: UX pattern tests"
      └── [Pattern Task] "Pattern: hamburger menu (critical)"
      └── [Pattern Task] "Pattern: small touch targets (critical)"
      └── [Pattern Task] "Pattern: FAB detected (critical)"
  └── [CI Task] "CI: workflow integration"

Session Recovery Check

At the start of this skill, always check for existing tasks:

1. Call TaskList to check for existing UX CI tasks
2. If a "Generate Mobile UX CI Tests" task exists with status in_progress:
   - Check its metadata for current phase
   - Resume from that phase
3. If pattern tasks exist with severity decisions:
   - Use those decisions for test generation
4. If no tasks exist, proceed with fresh execution

When to Use This Skill

Use this skill when:

• User wants to add mobile UX checks to CI
• User says “add UX pattern tests”, “detect anti-patterns”, “iOS UX CI checks”
• User wants to prevent mobile UX regressions
• User is building a PWA or web app targeting iOS/mobile

Process

Phase 1: Assess Current Testing Infrastructure [DELEGATE TO AGENT]

Create the main task:

TaskCreate:
- subject: "Generate Mobile UX CI Tests"
- description: |
    Create Playwright tests to detect iOS/mobile UX anti-patterns.
    Tests will FAIL CI when anti-patterns are found.
- activeForm: "Assessing testing infrastructure"

TaskUpdate:
- taskId: [main task ID]
- status: "in_progress"

Create infrastructure assessment task:

TaskCreate:
- subject: "Assess: testing infrastructure"
- description: |
    Exploring codebase for Playwright setup and existing tests.
    Delegating to Explore agent.
- activeForm: "Assessing infrastructure"

TaskUpdate:
- taskId: [infra task ID]
- status: "in_progress"

Purpose: Explore the codebase to understand the current testing setup. Delegate this to an Explore agent to save context.

Use the Task tool to spawn an Explore agent:

Task tool parameters:
- subagent_type: "Explore"
- model: "sonnet"
- prompt: |
    You are assessing a project's testing infrastructure for mobile UX CI tests.

    ## What to Find

    1. **Playwright Configuration**
       - Search for `playwright.config.ts` or `playwright.config.js`
       - Check `package.json` for `@playwright/test` dependency
       - Note the Playwright version if installed

    2. **Existing E2E Tests**
       - Look in `e2e/`, `tests/`, `__tests__/`, or similar directories
       - Count existing test files
       - Note any mobile-specific test files

    3. **Mobile Testing Setup**
       - Check Playwright config for mobile viewport projects
       - Search for existing mobile test files (`*mobile*`, `*ios*`)
       - Look for device emulation settings

    4. **Test Utilities**
       - Find test helper files (`test-utils.ts`, `helpers.ts`)
       - Note any existing page object patterns
       - Find authentication/setup utilities

    ## Return Format

    ```
    ## Testing Infrastructure Report

    ### Playwright Status
    - Installed: [Yes/No]
    - Version: [version or N/A]
    - Config file: [path or N/A]

    ### Existing Tests
    - Test directory: [path]
    - Test file count: [count]
    - Mobile-specific tests: [count or None]

    ### Mobile Configuration
    - Mobile viewports configured: [Yes/No]
    - Device presets: [list or None]

    ### Test Utilities
    - Helper files: [list or None]
    - Page objects: [Yes/No]
    - Auth utilities: [Yes/No]

    ### Recommendation
    - [Add to existing / Create new / Needs Playwright setup]
    ```

After agent returns: Update task with findings:

TaskUpdate:
- taskId: [infra task ID]
- status: "completed"
- metadata: {
    "playwrightInstalled": true/false,
    "playwrightVersion": "[version or N/A]",
    "configFile": "[path or N/A]",
    "testDirectory": "[path]",
    "existingTestCount": [count],
    "mobileTestsExist": true/false,
    "recommendation": "add_to_existing|create_new|needs_setup"
  }

Based on the infrastructure report, ask the user their goal:

• Add to existing: Add UX pattern tests to existing Playwright setup
• Create new: Set up Playwright and add UX pattern tests
• Audit only: Generate a report of current anti-patterns without creating tests

Store user’s choice in main task metadata:

TaskUpdate:
- taskId: [main task ID]
- metadata: {"userGoal": "add_to_existing|create_new|audit_only"}

Phase 2: Understand the App [DELEGATE TO AGENT]

Create app exploration task:

TaskCreate:
- subject: "Explore: app structure and routes"
- description: |
    Exploring app to identify pages needing UX pattern testing.
    Delegating to Explore agent.
- activeForm: "Exploring app structure"

TaskUpdate:
- taskId: [app task ID]
- status: "in_progress"

Purpose: Explore the app’s structure to identify what pages/routes need UX pattern testing. Delegate this to an Explore agent to save context.

Use the Task tool to spawn an Explore agent:

Task tool parameters:
- subagent_type: "Explore"
- model: "sonnet"
- prompt: |
    You are exploring a web application to identify pages that need mobile UX testing.

    ## What to Find

    1. **Routes and Pages**
       - Find all routes (React Router, Next.js pages, Vue Router, etc.)
       - List all user-facing pages
       - Note the base URL (likely localhost:5173 or similar)

    2. **Entry Points**
       - How does a user enter the app? (login, onboarding, direct access)
       - Is authentication required?
       - What's the first page users see?

    3. **Key Screens to Test**
       - Navigation screens (where nav patterns matter most)
       - Form screens (where touch targets matter)
       - List/table screens (where scrolling matters)
       - Modal/dialog screens (where presentation matters)

    4. **Existing Test Patterns**
       - Look for test utilities already mentioned in Phase 1
       - Find any app-specific selectors (data-testid patterns)
       - Note authentication helpers if they exist

    ## Return Format

    ```
    ## App Structure Report

    ### Base URL
    - Development: [URL]

    ### Entry Flow
    - Auth required: [Yes/No]
    - Entry point: [page/route]
    - First user screen: [page name]

    ### Pages to Test (prioritized)
    | Page | Route | Why Test |
    |------|-------|----------|
    | Home | / | Primary navigation visible |
    | Dashboard | /dashboard | Contains lists, buttons |
    | Settings | /settings | Form inputs, toggles |

    ### Navigation Pattern
    - Primary nav type: [tab bar / sidebar / hamburger / etc.]
    - Location: [top / bottom / left]

    ### Selector Patterns
    - data-testid usage: [Yes/No]
    - Common patterns: [list]
    ```

After agent returns: Update task with findings:

TaskUpdate:
- taskId: [app task ID]
- status: "completed"
- metadata: {
    "baseUrl": "[URL]",
    "authRequired": true/false,
    "entryPoint": "[route]",
    "pagesToTest": ["Home", "Dashboard", "Settings", ...],
    "primaryNavType": "tab_bar|sidebar|hamburger|other",
    "dataTestidUsage": true/false
  }

Use the app structure report to determine which pages to include in the UX pattern tests and how to set up test navigation.

Phase 3: Generate UX Pattern Tests

Create generate task:

TaskCreate:
- subject: "Generate: UX pattern tests"
- description: |
    Generating Playwright tests for mobile UX anti-patterns.
    Will create tests for navigation, touch targets, components, and layout.
- activeForm: "Generating UX pattern tests"

TaskUpdate:
- taskId: [generate task ID]
- status: "in_progress"

Create a task for each anti-pattern category detected:

TaskCreate:
- subject: "Pattern: [pattern name] ([severity])"
- description: |
    Anti-pattern: [description]
    Severity: critical|warning|info
    Test: [what the test checks]
    User decision: [enforce|allow|pending]
- activeForm: "Checking [pattern name]"

Example pattern tasks:

TaskCreate:
- subject: "Pattern: hamburger menu (critical)"
- description: |
    Anti-pattern: Hamburger menu for primary navigation
    Severity: critical (should fail CI)
    iOS apps use tab bars, not hamburger menus.
    Test: Detect .hamburger-btn, [class*="hamburger"]
- activeForm: "Checking hamburger menu"

Create a mobile-ux-patterns.spec.ts file with tests for:

Navigation Anti-Patterns

Touch Target Issues

Component Anti-Patterns

Layout Issues

Text & Selection

Interaction Issues

Phase 4: Test File Template

Update generate task with pattern counts:

TaskUpdate:
- taskId: [generate task ID]
- metadata: {
    "criticalPatterns": [count],
    "warningPatterns": [count],
    "infoPatterns": [count],
    "totalTests": [count]
  }

Generate a test file following this structure:

/**
 * Mobile UX Anti-Pattern Tests
 *
 * These tests FAIL when iOS/mobile UX anti-patterns are detected.
 * Reference: Apple HIG, Material Design vs iOS differences
 */

import { test, expect, Page } from '@playwright/test';

// Viewport sizes
const IPHONE_14 = { width: 393, height: 852 };

// Apple's minimum touch target
const IOS_MIN_TOUCH_TARGET = 44;

// Helper to enter the app (customize per project)
async function enterApp(page: Page) {
  await page.goto('/');
  // Add app-specific setup here
}

test.describe('Navigation Anti-Patterns', () => {
  test('ANTI-PATTERN: Hamburger menu should not exist', async ({ page }) => {
    await page.setViewportSize(IPHONE_14);
    await enterApp(page);

    const hamburger = page.locator('.hamburger-btn, [class*="hamburger"]').first();
    const isVisible = await hamburger.isVisible().catch(() => false);

    expect(isVisible, 'iOS anti-pattern: Hamburger menu detected').toBe(false);
  });

  // ... more navigation tests
});

test.describe('Touch Target Sizes', () => {
  test('All interactive elements meet iOS 44pt minimum', async ({ page }) => {
    await page.setViewportSize(IPHONE_14);
    await enterApp(page);

    const buttons = await page.locator('button:visible').all();
    const violations: string[] = [];

    for (const btn of buttons) {
      const box = await btn.boundingBox();
      if (box && (box.width < IOS_MIN_TOUCH_TARGET || box.height < IOS_MIN_TOUCH_TARGET)) {
        violations.push(`Button ${box.width}x${box.height}px`);
      }
    }

    expect(violations.length, `${violations.length} touch targets too small`).toBe(0);
  });
});

// ... more test categories

Phase 5: CI Integration

Mark generate task completed:

TaskUpdate:
- taskId: [generate task ID]
- status: "completed"
- metadata: {
    "testFile": "e2e/mobile-ux-patterns.spec.ts",
    "testsGenerated": [count]
  }

Create CI integration task:

TaskCreate:
- subject: "CI: workflow integration"
- description: |
    Setting up CI workflow to run mobile UX pattern tests.
    Adding to existing workflow or creating new one.
- activeForm: "Setting up CI workflow"

TaskUpdate:
- taskId: [ci task ID]
- status: "in_progress"

Ensure tests run in CI by:

1. Adding to existing Playwright CI workflow
2. Or creating new workflow:

name: Mobile UX Checks

on: [push, pull_request]

jobs:
  mobile-ux:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npx playwright install chromium
      - run: npm run dev &
      - run: npx playwright test mobile-ux-patterns.spec.ts

Phase 6: Review with User

Mark CI task completed:

TaskUpdate:
- taskId: [ci task ID]
- status: "completed"
- metadata: {
    "workflowFile": "[path or 'added_to_existing']",
    "ciConfigured": true
  }

Mark all pattern tasks with user decisions: For each pattern task, update with user’s severity decision:

TaskUpdate:
- taskId: [pattern task ID]
- status: "completed"
- metadata: {"userDecision": "enforce|allow|warning_only"}

Mark main task completed:

TaskUpdate:
- taskId: [main task ID]
- status: "completed"
- metadata: {
    "testFile": "e2e/mobile-ux-patterns.spec.ts",
    "criticalPatterns": [count],
    "warningPatterns": [count],
    "infoPatterns": [count],
    "ciConfigured": true,
    "pagesTestesed": [count]
  }

Generate summary from task data:

Call TaskList to get all pattern tasks and their metadata, then present:

1. Summary of anti-patterns that will be detected
2. Which tests will fail immediately (known issues)
3. Which tests will pass (good patterns already in place)

## Mobile UX CI Tests Generated

### Anti-Patterns Detected
[Generated from pattern tasks:]
- **Critical (will fail CI):** [count]
  - Hamburger menu detected
  - Touch targets < 44pt
- **Warning (logged but passes):** [count]
  - Native <select> elements
- **Info (suggestions only):** [count]
  - Heavy Material shadows

### Test File
- Path: e2e/mobile-ux-patterns.spec.ts
- Tests: [count]
- Pages covered: [list from app task]

### CI Integration
- Workflow: [path or status]
- Runs on: push, pull_request

Ask user:

• Should any anti-patterns be allowed temporarily?
• Any additional patterns to check?
• Ready to add to CI?

Session Recovery

If resuming from an interrupted session:

Recovery decision tree:

TaskList shows:
├── Main task in_progress, no infra task
│   └── Start from Phase 1 (assess infrastructure)
├── Infra task completed, no app task
│   └── Start from Phase 2 (explore app)
├── App task in_progress
│   └── Resume app exploration agent
├── App task completed, no generate task
│   └── Start from Phase 3 (generate tests)
├── Generate task in_progress, pattern tasks exist
│   └── Continue generating tests for remaining patterns
├── Generate task completed, no CI task
│   └── Start from Phase 5 (CI integration)
├── CI task in_progress
│   └── Resume CI setup
├── Pattern tasks pending user decisions
│   └── Present pattern severity choices to user
├── Main task completed
│   └── Generation done, show summary
└── No tasks exist
    └── Fresh start (Phase 1)

Resuming with pending pattern decisions:

1. Get all tasks with "Pattern:" prefix
2. Check metadata for userDecision field
3. If any patterns lack decisions:
   "Found patterns needing severity decisions:
    - Hamburger menu: [pending] - enforce/allow/warning?
    - FAB detected: [pending] - enforce/allow/warning?
   Please decide which anti-patterns should fail CI."
4. Update pattern tasks with user decisions
5. Regenerate tests with updated severity levels

Always inform user when resuming:

Resuming Mobile UX CI session:
- Infrastructure: [status from infra task]
- App explored: [pages from app task]
- Patterns detected: [counts from pattern tasks]
- Current state: [in_progress task description]
- Pending: [any pattern decisions needed]
- Resuming: [next action]

Anti-Pattern Reference

Critical (Should Always Fail CI)

1. Hamburger Menu for Primary Navigation

   • Why: iOS users expect tab bars at bottom
   • Reference: iOS vs Android Navigation

2. Floating Action Button (FAB)

   • Why: Material Design pattern, not iOS
   • Reference: Material vs iOS

3. Touch Targets < 44pt

   • Why: Apple HIG requirement for accessibility
   • Reference: Apple HIG

4. Horizontal Overflow

   • Why: Content should fit viewport on mobile
   • Reference: Basic responsive design

Warning (Should Log but May Not Fail)

1. Native <select> Elements

   • Why: iOS apps use picker wheels
   • Note: Some selects are acceptable for accessibility

2. Checkboxes

   • Why: iOS uses toggle switches
   • Note: Checkmarks in lists are acceptable

3. Text Selection on UI

   • Why: Native apps prevent selecting UI text
   • Note: Content text should remain selectable

4. No Safe Area Insets

   • Why: Content may go under notch
   • Note: Only relevant for notched devices

Informational (Suggestions Only)

1. Heavy Shadows (Material Elevation)
2. Missing touch-action: manipulation
3. Non-system fonts

Customization Points

When generating tests, ask about:

1. Severity levels: Which anti-patterns should fail CI vs warn?
2. Exceptions: Any patterns that are intentionally kept?
3. Additional patterns: App-specific anti-patterns to detect?
4. Viewport sizes: Which devices to test?

Example Output

After running this skill, the user should have:

1. e2e/mobile-ux-patterns.spec.ts – Comprehensive anti-pattern tests
2. Updated CI workflow (if needed)
3. Clear documentation of what’s being checked
4. Immediate visibility into current anti-patterns

Sources

• Apple Human Interface Guidelines
• iOS vs Android Design
• Touch Target Sizes
• PWA Native Feel
• WCAG 2.5.8 Target Size