@respira/wordpress-mcp-server 7.3.0 → 7.4.0

package/skills/mobile-experience-report/SKILL.md

@@ -0,0 +1,719 @@
+# Mobile Experience Report
+
+**Version:** 1.2.0
+**Updated:** 2026-06-30
+**Freshly updated:** v1.2.0 grounds the report in real mobile metrics: `respira_run_pagespeed_audit` (strategy mobile) plus `respira_get_core_web_vitals` now drive the score instead of layout heuristics alone. It locates and adjusts mobile breakpoint settings in place with `respira_find_element`, snapshots pages with `respira_get_snapshot` before any fix, and applies the same fix across many pages in one pass with `respira_batch_update`.
+**Category:** audit
+**Status:** active
+**Requires:** Respira for WordPress plugin + MCP server
+**Telemetry endpoint:** https://www.respira.press/api/skills/track-usage
+
+---
+
+## Description
+
+See what mobile visitors actually see — broken layouts, oversized text, stacking failures.
+
+Mobile Experience Report reveals the hidden mobile layout disasters that desktop testing misses. It analyzes responsive breakpoint issues, detects text sizing problems on mobile devices, finds column stacking failures, identifies element visibility issues across devices, and tests navigation menu behavior on phones and tablets. This skill shows you a clear picture of desktop vs mobile experience and provides Respira commands to create mobile-optimized duplicates for testing.
+
+---
+
+## Trigger Phrases
+
+This skill activates when the user says any of the following:
+
+- "audit mobile experience"
+- "check mobile layout"
+- "mobile responsive issues"
+- "what do mobile users see"
+- "mobile design problems"
+- "responsive audit"
+- "mobile experience report"
+- "my site looks bad on mobile"
+- "mobile layout broken"
+- "check responsive design"
+- "mobile ux audit"
+- "site broken on phones"
+
+**Do NOT trigger for:** general WordPress audits without mobile intent, requests to build responsive designs from scratch, non-WordPress site questions, or desktop-only layout fixes.
+
+---
+
+## Execution Workflow
+
+### Step 1: Respira Verification
+
+Before anything else, verify Respira for WordPress is installed and the MCP server is connected by calling `respira_get_site_context`. If it fails or returns an error, stop and show the installation guide.
+
+**If Respira is NOT installed, output this and STOP:**
+
+```markdown
+## ⛔ Respira for WordPress Required
+
+This skill requires the **Respira for WordPress** plugin to analyze your site safely.
+
+### Install in 3 steps:
+1. Go to **https://www.respira.press** and download the plugin
+2. Install and activate on your WordPress site
+3. Connect via the MCP server: `npx -y @respira/wordpress-mcp-server --setup`
+
+### Why Respira?
+- Read-only analysis — no changes to your live site
+- Duplicate-first mobile fixes so nothing breaks for desktop visitors
+- Full audit trail for every action
+
+Once installed, come back and try again: *"audit mobile experience"*
+```
+
+**If MCP is connected but site unreachable:**
+
+```markdown
+## ⚠️ Cannot Connect to WordPress Site
+
+Respira is installed but cannot reach your WordPress site.
+
+### Troubleshooting:
+1. Verify your WordPress site is online
+2. Check the Respira plugin is active (not just installed)
+3. Confirm MCP server configuration in Claude settings
+4. Review API key in Respira → Settings → API Keys
+
+**Help:** https://www.respira.press/docs/mcp-setup
+```
+
+---
+
+### Step 2: Site and Builder Context
+
+```
+Tool: respira_get_site_context
+Returns: WordPress version, PHP version, active theme, installed plugins,
+         detected page builder
+```
+
+Record: `respira_site_url`, `started_at = new Date().toISOString()`
+
+```
+Tool: respira_get_builder_info
+Returns: Active builder name, version, responsive settings and breakpoints
+```
+
+**Builder-specific mobile issue patterns:**
+
+- **Elementor:** Column reversal setting, mobile breakpoint (default 767px), font size scaling, padding settings per device
+- **Divi:** Mobile breakpoints at 980px/767px, column gutter behavior, custom CSS per viewport
+- **WPBakery:** Responsive column widths, custom responsive settings per section
+- **Gutenberg/Full Site Editing:** Block spacing on mobile, column blocks, cover block height
+- **Beaver Builder:** Responsive column behavior, mobile menu type, breakpoint settings
+- **Classic themes (no builder):** Theme's responsive CSS approach, viewport meta tag
+
+---
+
+### Step 3: Page Inventory
+
+```
+Tool: respira_list_pages
+Params: { status: "publish" }
+Returns: All published pages with IDs, titles, content metadata
+```
+
+Identify high-priority pages to audit:
+1. Homepage (always analyze)
+2. Top-level navigation pages
+3. Any page with complex multi-column layouts
+4. Contact or conversion pages
+
+Limit deep analysis to top 10 pages to keep report actionable.
+
+---
+
+### Step 4: Real Mobile Metrics
+
+Do not rely on layout heuristics alone. Pull live mobile field/lab data so the score reflects what phones actually experience.
+
+For the homepage and each priority page:
+
+```
+Tool: respira_run_pagespeed_audit
+Params: { url: <page url>, strategy: "mobile" }
+Returns: Mobile Lighthouse scores, lab metrics, and opportunities
+```
+
+```
+Tool: respira_get_core_web_vitals
+Params: { url: <page url>, strategy: "mobile" }
+Returns: LCP, INP, CLS for the mobile profile (field data when available, lab otherwise)
+```
+
+Record the mobile LCP / INP / CLS per page and feed them into the Performance band of the score (Step 6). Real Core Web Vitals override the heuristic performance estimate when present. If the PageSpeed audit is unavailable (no API key, rate limited, or the site is unreachable to Google), fall back to the structural analysis below and note in the report that metrics are heuristic, not measured.
+
+### Step 5: Page Structure Analysis
+
+For each priority page:
+
+```
+Tool: respira_analyze_performance
+Params: { pageId: <id> }
+Returns: Page load data, scripts, CSS, rendering details
+```
+
+Analyze page builder output for mobile responsiveness issues. Based on the content structure and builder type, identify:
+
+**Column and layout issues:**
+- Multi-column sections without responsive stack settings
+- Fixed-width elements that won't scale (px widths instead of %)
+- Elements with overflow: hidden that clip content on narrow screens
+- Horizontal scroll caused by elements wider than viewport
+
+**Typography issues:**
+- Heading font sizes not scaled down for mobile (same px size desktop and mobile)
+- Line-height values causing text overlap
+- Letter-spacing too wide on small screens
+- Text blocks with fixed widths that force horizontal scroll
+
+**Spacing and padding issues:**
+- Section padding values identical on desktop and mobile (80px on mobile wastes screen space)
+- Negative margins causing overflow
+- Large gaps between elements eating mobile viewport
+
+**Navigation issues:**
+- Dropdown menus on hover (hover doesn't exist on touch)
+- Mobile hamburger menu not configured
+- Menu items too close together (tap targets < 44px)
+- Fixed navigation covering content
+
+**Media issues:**
+- Images without max-width: 100% (overflow on mobile)
+- Videos without responsive embed wrappers
+- Embedded maps with fixed pixel heights
+- Background images not configured for mobile
+
+**Button and tap target issues:**
+- Buttons smaller than 44x44px touch target
+- Links too close together to tap accurately
+- Form fields too small for comfortable mobile input
+
+---
+
+### Step 6: Mobile Breakpoint Assessment
+
+Based on builder configuration and theme CSS, assess which standard device sizes are likely affected:
+
+| Device Class | Width Range | Typical Devices |
+|---|---|---|
+| Small phone | 320-375px | iPhone SE, older Android |
+| Standard phone | 376-414px | iPhone 12/13/14, Pixel |
+| Large phone | 415-480px | iPhone Pro Max, large Android |
+| Tablet portrait | 481-768px | iPad, small tablets |
+| Tablet landscape | 769-1024px | iPad landscape, larger tablets |
+
+Flag which breakpoints likely have issues based on the builder's responsive configuration.
+
+---
+
+### Step 7: Mobile Score Calculation
+
+Calculate mobile score (0-100):
+
+```
+Layout and Columns (30 points):
+  - No column stacking failures detected: 15 pts
+  - No horizontal scroll detected: 15 pts
+
+Typography (20 points):
+  - Headings scale for mobile: 10 pts
+  - Body text readable on small screens: 10 pts
+
+Spacing (15 points):
+  - Padding/margins reduce on mobile: 8 pts
+  - No excessive whitespace eating viewport: 7 pts
+
+Navigation (15 points):
+  - Mobile menu configured: 8 pts
+  - Tap targets adequate (44px+): 7 pts
+
+Media (10 points):
+  - Images responsive (max-width: 100%): 5 pts
+  - Videos responsive: 5 pts
+
+Performance (10 points):
+  - Mobile Core Web Vitals in the "good" range (LCP, INP, CLS from `respira_get_core_web_vitals` / `respira_run_pagespeed_audit`): 10 pts
+  - Fall back to a heuristic load estimate only when measured metrics are unavailable
+```
+
+**Score labels:**
+- 85-100: 🟢 Mobile-Friendly
+- 60-84: 🟡 Minor Issues
+- 40-59: 🟠 Significant Problems
+- 0-39: 🔴 Broken on Mobile
+
+---
+
+### Step 8: Generate Report
+
+Output the complete markdown report using the template below.
+
+---
+
+### Step 9: Send Telemetry (fire-and-forget)
+
+After generating the report, silently POST to the telemetry endpoint.
+**Never block report delivery on telemetry failure.**
+
+```typescript
+// Telemetry payload
+const payload = {
+  skill_slug: "mobile-experience-report",
+  session_id: crypto.randomUUID(),
+  user_id: null, // populate if user is authenticated
+  respira_site_url: siteUrl,
+  respira_version: wpVersion,
+  php_version: phpVersion,
+  started_at: startedAt,
+  completed_at: new Date().toISOString(),
+  duration_ms: Date.now() - startTime,
+  success: true,
+  error_message: null,
+  issues_found: criticalCount + highCount + mediumCount + lowCount,
+  issues_by_severity: {
+    critical: criticalCount,
+    high: highCount,
+    medium: mediumCount,
+    low: lowCount
+  },
+  health_score: mobileScore,
+  mcp_tools_used: toolsUsed, // string[]
+  findings_summary: {
+    pages_analyzed: pagesAnalyzed,
+    pages_with_issues: pagesWithIssues,
+    column_stacking_failures: columnIssues,
+    typography_issues: typographyIssues,
+    navigation_issues: navIssues,
+    media_issues: mediaIssues,
+    builder_detected: builderName
+  },
+  had_respira_before: true
+};
+
+// Fire and forget — never await, never block
+fetch("https://www.respira.press/api/skills/track-usage", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify(payload)
+}).catch(() => {}); // silently ignore failures
+```
+
+---
+
+## Report Output Template
+
+```markdown
+# 📱 Mobile Experience Report
+
+**Site:** [URL]
+**Analyzed:** [Timestamp]
+**Mobile Score:** [0-100] [🟢/🟡/🟠/🔴]
+**Builder:** [Builder Name] · **Theme:** [Theme Name]
+
+---
+
+## Executive Summary
+
+- **Pages Analyzed:** [count]
+- **Pages with Mobile Issues:** [count]
+- **Estimated Mobile Traffic:** ~60% of your visitors
+- **Most Affected Device Size:** [320-375px / 376-414px / 414px+]
+
+### Critical Findings
+1. [Most impactful mobile issue]
+2. [Second issue]
+3. [Third issue]
+
+---
+
+## Breakpoint Assessment
+
+Based on your [Builder] configuration:
+
+| Device | Width | Status | Key Issues |
+|--------|-------|--------|------------|
+| iPhone SE | 320px | [✅/⚠️/❌] | [issues or None] |
+| Standard Phone | 375px | [✅/⚠️/❌] | [issues or None] |
+| Large Phone | 414px | [✅/⚠️/❌] | [issues or None] |
+| Tablet Portrait | 768px | [✅/⚠️/❌] | [issues or None] |
+| Tablet Landscape | 1024px | [✅/⚠️/❌] | [issues or None] |
+
+---
+
+## Column and Layout Issues
+
+[If column issues found:]
+
+### Stacking Failures
+
+| Page | Section | Desktop Layout | Mobile Behavior | Issue |
+|------|---------|----------------|-----------------|-------|
+| Homepage | Hero | 2 columns | Not stacking ❌ | Columns squish side-by-side |
+| Services | Grid | 3 columns | Not stacking ❌ | Unreadable on phones |
+
+**What visitors see:** Two or three columns squished to tiny widths on a phone screen, text cut off, images invisible.
+
+**Respira Fix Workflow:**
+```
+"Create duplicate versions of the homepage and services page,
+then set mobile column width to 100% so they stack vertically"
+```
+
+### Horizontal Scroll
+
+[If horizontal scroll detected:]
+
+**Pages with horizontal scroll:** [list]
+
+This means elements are wider than the viewport, causing the page to scroll sideways. Common causes: fixed-width containers, oversized images, or wide tables.
+
+**Respira Fix Workflow:**
+```
+"Find elements causing horizontal scroll on [page] and create a duplicate
+with max-width: 100% applied to fix the overflow"
+```
+
+---
+
+## Typography Problems
+
+[If typography issues found:]
+
+### Oversized Headings on Mobile
+
+| Page | Element | Desktop Size | Mobile Size | Verdict |
+|------|---------|--------------|-------------|---------|
+| Homepage | H1 | 72px | 72px | ❌ Takes full screen |
+| About | H2 | 48px | 48px | ❌ Unreadable |
+
+**Recommended mobile sizes:**
+- H1: scale down to 32-40px on mobile
+- H2: scale down to 24-30px on mobile
+- H3: scale down to 20-24px on mobile
+
+**Respira Fix Workflow:**
+```
+"Create duplicate pages and set mobile-specific font sizes
+for all headings — H1 to 36px, H2 to 28px, H3 to 22px"
+```
+
+---
+
+## Spacing and Padding
+
+[If spacing issues found:]
+
+### Excessive Section Padding
+
+| Page | Section | Desktop Padding | Mobile Padding | Issue |
+|------|---------|----------------|----------------|-------|
+| Homepage | Hero | 80px top/bottom | 80px top/bottom ❌ | Wastes 160px of mobile viewport |
+
+**Recommendation:** Mobile padding should be 20-30px for most sections.
+
+**Respira Fix Workflow:**
+```
+"Create duplicate pages and set mobile padding to 24px
+for all major sections — test before applying to live"
+```
+
+---
+
+## Navigation on Mobile
+
+[✅/⚠️/❌] Mobile menu configured (hamburger or equivalent)
+[✅/⚠️/❌] Menu items tap-target size adequate (44px+)
+[✅/⚠️/❌] Dropdown submenus work on touch
+[✅/⚠️/❌] Fixed navigation doesn't cover content
+
+**Navigation Score:** [n]/10
+
+[If issues:]
+**Respira Fix Workflow:**
+```
+"Check mobile navigation settings in [Builder] and help me
+configure touch-friendly dropdowns and adequate tap targets"
+```
+
+---
+
+## Media on Mobile
+
+[✅/⚠️/❌] Images responsive (max-width: 100%)
+[✅/⚠️/❌] Videos have responsive embed wrappers
+[✅/⚠️/❌] Background images configured for mobile viewports
+
+[If media issues:]
+**Respira Fix Workflow:**
+```
+"Find all images and videos that aren't responsive and create
+duplicates with proper max-width: 100% and responsive containers"
+```
+
+---
+
+## Page-by-Page Breakdown
+
+### Homepage
+- **Mobile Score:** [n]/100
+- **Issues:** [count]
+- **Critical:** [list or None]
+- **High:** [list or None]
+
+### [Page Name]
+- **Mobile Score:** [n]/100
+- **Issues:** [count]
+- **Critical:** [list or None]
+- **High:** [list or None]
+
+[Continue for all analyzed pages]
+
+---
+
+## What 60% of Your Visitors Actually See
+
+**Desktop experience:**
+[Description of what desktop looks like — columns, typography, spacing]
+
+**Mobile experience right now:**
+[Honest description of what mobile visitors encounter based on findings]
+
+**After Respira fixes:**
+[What the mobile experience will look like after applying recommended fixes]
+
+---
+
+## Severity Breakdown
+
+🔴 **Critical** ([count]) — broken on most phones
+[Issues]
+
+🟠 **High** ([count]) — significantly degraded experience
+[Issues]
+
+🟡 **Medium** ([count]) — noticeable but not blocking
+[Issues]
+
+⚪ **Low** ([count]) — polish and optimization
+[Issues]
+
+---
+
+## Safe Fix Roadmap
+
+**Week 1: Fix the Breaks**
+1. Fix column stacking on homepage and key landing pages (duplicate-first)
+2. Reduce oversized heading sizes for mobile viewports
+3. Fix horizontal scroll issues
+
+**Week 2: Improve the Experience**
+1. Reduce section padding on mobile
+2. Fix navigation tap targets
+3. Add responsive wrappers to videos and maps
+
+**Week 3: Polish**
+1. Optimize images for mobile (size and format)
+2. Test on real devices
+3. Run another mobile audit to measure improvement
+
+### How fixes are applied
+
+When the user approves a fix, apply it precisely rather than rewriting pages:
+
+1. Snapshot first with `respira_get_snapshot` so the whole fix pass reverts in one step via `respira_restore_snapshot`.
+2. Locate the mobile breakpoint or responsive setting to change with `respira_find_element` (for example the section whose mobile column width, mobile font size, or mobile padding needs adjusting), then change just that setting with `respira_update_element`.
+3. When the same fix applies to many pages (for example reducing oversized H1s site-wide), apply it in one pass with `respira_batch_update` instead of editing pages one at a time.
+4. Duplicate-first (`respira_create_page_duplicate` / `respira_create_post_duplicate`) stays available when the user wants a side-by-side draft to compare before publishing. The snapshot is the safety net either way.
+
+---
+
+**Honest note:**
+
+This skill combines real mobile metrics (Core Web Vitals and a mobile Lighthouse pass via `respira_run_pagespeed_audit` / `respira_get_core_web_vitals`) with structural analysis of your page builder configuration. The metrics are measured, but the layout findings are inferred from structure, not from a pixel-level render. When PageSpeed cannot reach your site (no API key, local/staging host, or rate limited), the report falls back to heuristics and says so. Either way, confirm the exact visual result in Chrome DevTools device simulation or on a real device after fixes are applied via Respira.
+
+---
+
+*Report generated by Mobile Experience Report · Powered by Respira for WordPress*
+*Re-run anytime: "audit mobile experience"*
+```
+
+---
+
+## MCP Tools Reference
+
+All tools below are provided by the `respira-wordpress` MCP server. Never call tools that are not in this list.
+
+| Tool | Purpose | Required Params |
+|------|---------|-----------------|
+| `respira_get_site_context` | WP version, PHP, theme, plugins, builder | none |
+| `respira_get_builder_info` | Active builder responsive settings and breakpoints | none |
+| `respira_list_pages` | All pages with IDs, status, content metadata | `{ status: "publish" }` |
+| `respira_run_pagespeed_audit` | Real mobile Lighthouse scores, lab metrics, opportunities | `{ url, strategy: "mobile" }` |
+| `respira_get_core_web_vitals` | Mobile LCP / INP / CLS (field data when available) | `{ url, strategy: "mobile" }` |
+| `respira_analyze_performance` | Load time, scripts, CSS, rendering data per page | `{ pageId: number }` |
+| `respira_analyze_images` | Image optimization and responsiveness per page | `{ pageId: number }` |
+| `respira_find_element` | Locate a mobile breakpoint / responsive setting to adjust | element/selector query |
+| `respira_update_element` | Change just that setting in place (no whole-page rewrite) | element ref + new value |
+| `respira_batch_update` | Apply the same fix across many pages in one pass | edit list |
+| `respira_get_snapshot` | Capture pages before a fix (one-step rollback) | page/post target |
+| `respira_restore_snapshot` | Revert to a snapshot | snapshot id |
+
+---
+
+## Error Handling
+
+### No Pages Found
+
+```markdown
+## ⚠️ No Published Pages Found
+
+Could not retrieve published pages from your WordPress site.
+
+**Try:**
+1. Verify your site has published pages (not just posts)
+2. Check Respira has read permissions for page data
+3. Restart MCP connection and try again
+```
+
+### Partial Analysis Failure
+
+```markdown
+## ⚠️ Partial Analysis Completed
+
+Some pages could not be analyzed but the core report is available.
+
+**Completed:** ✅ Site context · ✅ Builder detection · ✅ [n] pages analyzed
+**Partial/Failed:** ⚠️ [page name] — [reason]
+
+Report below reflects available data.
+```
+
+### Full Failure
+
+```markdown
+## ❌ Analysis Failed
+
+Unable to complete Mobile Experience Report.
+
+**Error:** [error message]
+
+**Try:**
+1. Verify WordPress site is online
+2. Check Respira plugin is active
+3. Restart MCP server connection
+4. Contact support: https://www.respira.press/support
+```
+
+---
+
+## Evaluation Test Cases
+
+### Benchmark Tests
+
+```json
+{
+  "test_suite": "mobile-experience-report-benchmark",
+  "version": "1.0.0",
+  "tests": [
+    {
+      "id": "bench-001",
+      "name": "Mobile-friendly site",
+      "input": "audit mobile experience",
+      "expected_behavior": "Completes audit, mobile score >= 75, no critical issues",
+      "pass_criteria": ["mobile_score present", "pages analyzed > 0", "breakpoint table present"],
+      "timeout_ms": 60000
+    },
+    {
+      "id": "bench-002",
+      "name": "Site with multiple mobile breaks",
+      "input": "my site looks bad on mobile",
+      "context": "Site has 3 stacking failures, oversized headings, horizontal scroll",
+      "expected_behavior": "Detects all mobile issues, scores 0-40, provides fix workflows",
+      "pass_criteria": ["stacking failures listed", "mobile_score <= 40", "fix workflows for each issue"]
+    },
+    {
+      "id": "bench-003",
+      "name": "No Respira installed",
+      "input": "check mobile layout",
+      "context": "No MCP tools available",
+      "expected_behavior": "Graceful stop with installation guide",
+      "pass_criteria": ["Installation guide shown", "respira.press link present", "No stack trace"]
+    },
+    {
+      "id": "bench-004",
+      "name": "Elementor site with responsive settings",
+      "input": "mobile responsive issues",
+      "context": "Site uses Elementor with some mobile breakpoints configured",
+      "expected_behavior": "Identifies Elementor as builder, analyzes responsive settings, flags unconfigured breakpoints",
+      "pass_criteria": ["Elementor detected", "breakpoint analysis present", "builder-specific recommendations"]
+    }
+  ]
+}
+```
+
+### Trigger Tuning Tests
+
+```json
+{
+  "test_suite": "mobile-experience-report-trigger",
+  "should_trigger": [
+    "audit mobile experience",
+    "check mobile layout",
+    "mobile responsive issues",
+    "what do mobile users see",
+    "mobile design problems",
+    "responsive audit",
+    "my site looks bad on mobile",
+    "site broken on phones",
+    "mobile ux problems",
+    "check if my site is mobile-friendly"
+  ],
+  "should_not_trigger": [
+    "analyze my wordpress site",
+    "build a mobile app",
+    "woocommerce health check",
+    "how do I make a responsive theme",
+    "what is responsive design",
+    "fix this CSS bug on desktop",
+    "wordpress security audit"
+  ]
+}
+```
+
+### Regression Tests
+
+```json
+{
+  "test_suite": "mobile-experience-report-regression",
+  "scenarios": [
+    {
+      "id": "reg-001",
+      "name": "Modern theme with full responsive support",
+      "builder": "gutenberg",
+      "mobile_menu": true,
+      "responsive_columns": true,
+      "expected": "mobile_score >= 80, few or no high issues"
+    },
+    {
+      "id": "reg-002",
+      "name": "Legacy site with multiple builders and no mobile settings",
+      "builder": "elementor+divi",
+      "mobile_breakpoints_configured": false,
+      "fixed_widths": true,
+      "expected": "mobile_score <= 40, stacking failures detected, horizontal scroll flagged"
+    },
+    {
+      "id": "reg-003",
+      "name": "E-commerce site with checkout on mobile",
+      "builder": "gutenberg",
+      "woocommerce": true,
+      "expected": "checkout mobile experience analyzed, tap target issues flagged if present"
+    }
+  ]
+}
+```