cbrowser 17.6.1 → 18.1.0

package/docs/Tool-Competitive-Benchmark.md

@@ -0,0 +1,287 @@
+# Competitive Benchmark
+
+**See how your UX stacks up against competitors.**
+
+`competitive_benchmark` runs the same UX analysis across multiple sites and ranks them. Find out if your signup flow is faster than competitors, if your forms have more friction, and get specific recommendations for what to fix.
+
+---
+
+## Quick Start
+
+```json
+{
+  "urls": [
+    "https://example.com/signup",
+    "https://competitor1.com/signup",
+    "https://competitor2.com/signup"
+  ]
+}
+```
+
+**What happens**:
+1. Each URL is analyzed for UX metrics
+2. Sites are ranked on each metric
+3. You see where you're winning and losing
+4. Specific recommendations show how to improve
+
+---
+
+## Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `urls` | array | Yes | — | URLs to benchmark (2-5 sites) |
+| `metrics` | array | No | All | Specific metrics to compare |
+| `task` | string | No | — | Task to attempt on each site |
+| `persona` | string | No | `first-timer` | Persona to use for analysis |
+
+---
+
+## Metrics Compared
+
+### Form Friction
+
+| Metric | What It Measures |
+|--------|------------------|
+| **Field Count** | Number of required fields |
+| **Steps** | Multi-page vs single-page |
+| **Validation** | Inline vs on-submit |
+| **Password Rules** | Complexity requirements |
+| **Optional Fields** | Clear marking of optional |
+
+### Cognitive Load
+
+| Metric | What It Measures |
+|--------|------------------|
+| **Text Density** | Words per screen |
+| **Decision Points** | Choices user must make |
+| **Terminology** | Industry jargon usage |
+| **Visual Hierarchy** | Clear information flow |
+| **Navigation Clarity** | Obvious next steps |
+
+### Trust Signals
+
+| Metric | What It Measures |
+|--------|------------------|
+| **Security Badges** | HTTPS, security certifications |
+| **Social Proof** | Reviews, testimonials, logos |
+| **Privacy Info** | Clear data handling |
+| **Contact Options** | Accessible support |
+| **Professional Design** | Polish and consistency |
+
+### Performance
+
+| Metric | What It Measures |
+|--------|------------------|
+| **Load Time** | Time to interactive |
+| **LCP** | Largest Contentful Paint |
+| **CLS** | Cumulative Layout Shift |
+| **Input Latency** | Time to respond to clicks |
+
+---
+
+## Output
+
+```json
+{
+  "benchmark": {
+    "urls": [
+      "https://example.com/signup",
+      "https://competitor1.com/signup",
+      "https://competitor2.com/signup"
+    ],
+    "task": "Create an account",
+    "persona": "first-timer"
+  },
+  "rankings": {
+    "overall": [
+      { "url": "competitor2.com", "score": 87 },
+      { "url": "example.com", "score": 72 },
+      { "url": "competitor1.com", "score": 68 }
+    ],
+    "form_friction": [
+      { "url": "competitor2.com", "score": 95, "fields": 4 },
+      { "url": "example.com", "score": 70, "fields": 8 },
+      { "url": "competitor1.com", "score": 55, "fields": 12 }
+    ],
+    "cognitive_load": [
+      { "url": "competitor2.com", "score": 90 },
+      { "url": "competitor1.com", "score": 75 },
+      { "url": "example.com", "score": 65 }
+    ],
+    "trust_signals": [
+      { "url": "example.com", "score": 85 },
+      { "url": "competitor1.com", "score": 80 },
+      { "url": "competitor2.com", "score": 75 }
+    ],
+    "performance": [
+      { "url": "competitor2.com", "score": 92, "lcp": 1.2 },
+      { "url": "example.com", "score": 78, "lcp": 2.1 },
+      { "url": "competitor1.com", "score": 65, "lcp": 3.4 }
+    ]
+  },
+  "analysis": {
+    "example.com": {
+      "strengths": [
+        "Strong trust signals (security badges, testimonials)",
+        "Professional design quality"
+      ],
+      "weaknesses": [
+        "Form has 8 fields vs competitor's 4",
+        "High cognitive load - too much text on signup page",
+        "Password validation only shows on submit"
+      ],
+      "recommendations": [
+        {
+          "priority": "high",
+          "area": "form_friction",
+          "issue": "Too many required fields",
+          "action": "Defer Company Name and Phone to onboarding, reduce signup to 4 fields",
+          "impact": "Estimated 15-25% increase in completion rate"
+        },
+        {
+          "priority": "medium",
+          "area": "cognitive_load",
+          "issue": "Dense paragraph above form",
+          "action": "Replace with 3 bullet points",
+          "impact": "Reduced time-to-start"
+        }
+      ]
+    }
+  },
+  "opportunities": [
+    {
+      "insight": "Competitor2 wins on simplicity but lacks trust signals - you can beat them by simplifying while keeping your trust advantages",
+      "actionable": "Reduce form to 4 fields, keep security badges visible"
+    }
+  ]
+}
+```
+
+---
+
+## Use Cases
+
+### 1. Conversion Gap Analysis
+
+Your signup converts at 15%, competitor converts at 25%. Why?
+
+```json
+{
+  "urls": ["https://yoursite.com/signup", "https://competitor.com/signup"],
+  "task": "Create an account",
+  "persona": "first-timer"
+}
+```
+
+---
+
+### 2. Checkout Optimization
+
+Compare checkout experiences:
+
+```json
+{
+  "urls": [
+    "https://yourstore.com/checkout",
+    "https://amazon.com/checkout",
+    "https://shopify.com/checkout"
+  ],
+  "task": "Complete purchase"
+}
+```
+
+---
+
+### 3. Landing Page Effectiveness
+
+Compare landing pages for lead capture:
+
+```json
+{
+  "urls": [
+    "https://yoursite.com",
+    "https://competitor1.com",
+    "https://competitor2.com"
+  ],
+  "metrics": ["cognitive_load", "trust_signals"]
+}
+```
+
+---
+
+### 4. Industry Benchmarking
+
+See how you compare to industry leaders:
+
+```json
+{
+  "urls": [
+    "https://yourbank.com/apply",
+    "https://chase.com/apply",
+    "https://capitalone.com/apply"
+  ],
+  "task": "Apply for credit card"
+}
+```
+
+---
+
+## Interpreting Results
+
+### Score Ranges
+
+| Score | Meaning |
+|-------|---------|
+| 90-100 | Excellent - industry leading |
+| 80-89 | Good - competitive |
+| 70-79 | Average - room for improvement |
+| 60-69 | Below average - significant gaps |
+| <60 | Poor - major friction |
+
+### Priority Recommendations
+
+| Priority | Meaning | Typical Impact |
+|----------|---------|----------------|
+| **High** | Fix immediately | 15%+ conversion lift |
+| **Medium** | Fix soon | 5-15% conversion lift |
+| **Low** | Nice to have | <5% conversion lift |
+
+---
+
+## Tips
+
+### Choose Fair Comparisons
+
+Compare similar journeys:
+- Signup → Signup (not signup → checkout)
+- Same industry when possible
+- Similar target markets
+
+### Use Multiple Personas
+
+```json
+// Technical audience
+{ "persona": "technical-evaluator" }
+
+// Non-technical
+{ "persona": "first-timer" }
+```
+
+Different personas may rank competitors differently.
+
+### Focus on Actionable Metrics
+
+If you can't change it, don't benchmark it. Focus on metrics where you can realistically improve.
+
+---
+
+## Related Tools
+
+- [`marketing_compete`](/docs/Tools-Marketing-Intelligence/) — Deep competitive analysis with cognitive journeys (Enterprise)
+- [`hunt_bugs`](/docs/Tool-Hunt-Bugs/) — Find bugs in your own site
+- [`empathy_audit`](/docs/Tool-Empathy-Audit/) — Accessibility comparison
+
+---
+
+*Last updated: v17.6.0*

package/docs/Tool-Empathy-Audit.md

@@ -0,0 +1,325 @@
+# Empathy Audit
+
+**Experience your site through the eyes of someone with a disability.**
+
+`empathy_audit` doesn't just check WCAG compliance — it simulates actual humans with motor tremors, vision impairment, ADHD, and other conditions navigating your site. You'll see where they struggle, what makes them give up, and get specific remediation guidance.
+
+---
+
+## Quick Start
+
+```json
+{
+  "url": "https://example.com/checkout",
+  "personas": ["motor-tremor", "low-vision", "cognitive-adhd"],
+  "task": "Complete a purchase"
+}
+```
+
+**What happens**:
+1. Each disability persona attempts the task
+2. Their specific impairments affect how they interact (tremor = missed clicks, low vision = can't read small text)
+3. WCAG violations are detected and mapped to real user impact
+4. You get actionable remediation for each issue
+
+---
+
+## Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `url` | string | Yes | — | Page to audit |
+| `personas` | array | No | All | Disability personas to simulate |
+| `task` | string | No | General exploration | Specific task to attempt |
+| `wcagLevel` | string | No | `AA` | WCAG conformance level: `A`, `AA`, `AAA` |
+| `depth` | number | No | 1 | Pages to crawl |
+
+---
+
+## Disability Personas
+
+### `motor-tremor`
+
+**Simulates**: Essential tremor, Parkinson's, cerebral palsy, repetitive strain injury.
+
+**Behavioral Characteristics**:
+- Mouse movement is imprecise with jitter
+- Clicking small targets fails repeatedly
+- Can't maintain hover long enough for menus
+- Double-clicks unintentionally
+- Strongly prefers keyboard navigation
+
+**Common Barriers Detected**:
+
+| Barrier | WCAG | User Experience |
+|---------|------|-----------------|
+| Small click targets | 2.5.5 | 8 attempts to click a 24px button |
+| Hover-dependent menus | 2.1.1 | Menu closes before cursor reaches it |
+| Time-limited forms | 2.2.3 | Session expired during slow typing |
+| No keyboard shortcuts | 2.1.1 | Forced to use mouse for everything |
+
+---
+
+### `low-vision`
+
+**Simulates**: Macular degeneration, glaucoma, cataracts, legal blindness with partial sight.
+
+**Behavioral Characteristics**:
+- Uses 200-400% browser zoom
+- Relies on high contrast
+- Loses page context when zoomed
+- Can't perceive small text or icons
+- Needs clear visual hierarchy
+
+**Common Barriers Detected**:
+
+| Barrier | WCAG | User Experience |
+|---------|------|-----------------|
+| Fixed-width containers | 1.4.10 | Content cut off at 200% zoom |
+| Low contrast text | 1.4.3 | Can't read gray-on-white body text |
+| Icon-only buttons | 1.1.1 | No idea what the hamburger menu does |
+| Tiny form labels | 1.4.4 | Can't tell which field is which |
+
+---
+
+### `cognitive-adhd`
+
+**Simulates**: ADHD, executive function challenges, attention difficulties.
+
+**Behavioral Characteristics**:
+- Scans rapidly, doesn't read thoroughly
+- Clicks impulsively, sometimes wrong targets
+- Abandons long forms or processes
+- Easily distracted by movement/animation
+- Loses track of progress in multi-step flows
+
+**Common Barriers Detected**:
+
+| Barrier | WCAG | User Experience |
+|---------|------|-----------------|
+| Wall of text | 3.1.5 | Glazed over and missed key info |
+| Auto-playing video | 2.2.2 | Couldn't focus on the form |
+| No progress indicator | 3.3.4 | Didn't know how many steps remained |
+| Long forms | 3.3.2 | Abandoned at field 12 of 20 |
+
+---
+
+### `dyslexia`
+
+**Simulates**: Reading difficulties, letter reversal, word recognition challenges.
+
+**Behavioral Characteristics**:
+- Slow reading speed
+- Misreads similar words (their/there, form/from)
+- Struggles with justified text
+- Benefits from icons alongside text
+- Needs generous line spacing
+
+**Common Barriers Detected**:
+
+| Barrier | WCAG | User Experience |
+|---------|------|-----------------|
+| Justified text | Best practice | Letters swim, lost place |
+| Dense paragraphs | 1.4.12 | Couldn't parse the content |
+| Ambiguous labels | 3.3.2 | Confused "Email" for "E-mail" link |
+| Poor font choice | Best practice | Letters hard to distinguish |
+
+---
+
+### `deaf`
+
+**Simulates**: Deaf, hard of hearing, auditory processing disorder.
+
+**Behavioral Characteristics**:
+- Can't hear audio content
+- Misses audio alerts/notifications
+- Depends entirely on visual information
+- Needs captions or transcripts
+- May need sign language
+
+**Common Barriers Detected**:
+
+| Barrier | WCAG | User Experience |
+|---------|------|-----------------|
+| Video without captions | 1.2.2 | Missed entire product demo |
+| Audio-only alerts | 1.4.2 | Didn't know an error occurred |
+| Phone-only support | Best practice | No way to get help |
+
+---
+
+### `color-blind`
+
+**Simulates**: Protanopia, deuteranopia, tritanopia, and other color vision deficiencies.
+
+**Behavioral Characteristics**:
+- Can't distinguish red/green (most common)
+- May confuse blue/yellow (less common)
+- Depends on patterns, labels, position
+- Struggles with color-coded status
+
+**Common Barriers Detected**:
+
+| Barrier | WCAG | User Experience |
+|---------|------|-----------------|
+| Red/green validation | 1.4.1 | Can't tell which fields have errors |
+| Color-only charts | 1.4.1 | Graphs are meaningless |
+| Status indicators | 1.4.1 | All traffic lights look the same |
+
+---
+
+## Output
+
+```json
+{
+  "url": "https://example.com/checkout",
+  "wcagLevel": "AA",
+  "personas": {
+    "motor-tremor": {
+      "taskSuccess": false,
+      "abandonmentPoint": "Payment form - credit card expiry dropdown",
+      "timeToAbandon": 142,
+      "attempts": {
+        "clicks": 47,
+        "missedClicks": 23,
+        "successfulClicks": 24
+      },
+      "barriers": [
+        {
+          "type": "small-target",
+          "element": "#expiry-month",
+          "wcag": "2.5.5",
+          "severity": "critical",
+          "targetSize": "32x24",
+          "requiredSize": "44x44",
+          "userImpact": "Required 8 attempts to click, user patience exhausted",
+          "remediation": {
+            "summary": "Increase dropdown trigger to 44x44px minimum",
+            "code": "<select style='min-width: 44px; min-height: 44px;'>",
+            "effort": "low"
+          }
+        }
+      ]
+    },
+    "low-vision": {
+      "taskSuccess": true,
+      "timeToComplete": 287,
+      "zoomLevel": "200%",
+      "barriers": [
+        {
+          "type": "low-contrast",
+          "element": ".help-text",
+          "wcag": "1.4.3",
+          "severity": "moderate",
+          "contrastRatio": "3.2:1",
+          "requiredRatio": "4.5:1",
+          "userImpact": "Couldn't read CVV help text, had to guess format",
+          "remediation": {
+            "summary": "Increase text contrast to 4.5:1",
+            "code": "color: #595959; /* was #999999 */",
+            "effort": "low"
+          }
+        }
+      ]
+    }
+  },
+  "summary": {
+    "totalBarriers": 7,
+    "critical": 2,
+    "serious": 3,
+    "moderate": 2,
+    "wcagViolations": {
+      "A": 1,
+      "AA": 4
+    },
+    "recommendations": [
+      "Increase all interactive targets to 44px minimum",
+      "Add keyboard navigation to dropdown menus",
+      "Improve contrast ratio on help text",
+      "Add visible focus indicators"
+    ]
+  }
+}
+```
+
+---
+
+## Use Cases
+
+### 1. Pre-Launch Accessibility Review
+
+Before launching a new feature, run empathy audits across all disability personas:
+
+```json
+{
+  "url": "https://staging.example.com/new-feature",
+  "personas": ["motor-tremor", "low-vision", "cognitive-adhd", "deaf", "color-blind"],
+  "task": "Complete the new onboarding flow"
+}
+```
+
+---
+
+### 2. Prioritizing Accessibility Fixes
+
+You have 100 WCAG violations. Which ones matter?
+
+```json
+{
+  "url": "https://example.com",
+  "depth": 5
+}
+```
+
+The audit shows which violations caused actual abandonment vs minor inconvenience. Fix the critical ones first.
+
+---
+
+### 3. Compliance Documentation
+
+Need evidence for VPAT or accessibility statement:
+
+```json
+{
+  "url": "https://example.com",
+  "wcagLevel": "AA",
+  "depth": 10
+}
+```
+
+Generates detailed barrier documentation with WCAG mappings.
+
+---
+
+## Why This Is Different
+
+| WCAG Checker | Empathy Audit |
+|--------------|---------------|
+| "Button has no accessible name" | "Blind user couldn't proceed because the 'Next' button had no label" |
+| "Contrast ratio is 3.2:1" | "Low-vision user at 200% zoom couldn't read the error message and submitted invalid data" |
+| "Target size is 32px" | "User with tremor failed to click the dropdown 8 times before giving up" |
+| Counts violations | Predicts abandonment |
+| Compliance-focused | User-experience-focused |
+
+---
+
+## CI/CD Integration
+
+```bash
+# Fail build if critical accessibility barriers found
+npx cbrowser empathy-audit https://staging.example.com \
+  --task "Complete checkout" \
+  --fail-on critical \
+  --output accessibility-report.html
+```
+
+---
+
+## Related Tools
+
+- [`cognitive_journey_autonomous`](/docs/Tool-Cognitive-Journey-Autonomous/) — Full journey simulation
+- [`agent_ready_audit`](/docs/Tools-Utilities/) — AI agent friendliness
+- [UX Analysis Suite](/docs/UX-Analysis-Suite/) — Full UX analysis capabilities
+
+---
+
+*Last updated: v17.6.0*