Initial commit

skills/playwright-e2e-automation/examples/react-vite/example-page-object.ts

@@ -0,0 +1,91 @@
+import { Page, Locator } from '@playwright/test';
+
+/**
+ * HomePage Page Object Model
+ *
+ * Example POM for a React + Vite application homepage
+ * Demonstrates best practices for locator selection
+ */
+
+export class HomePage {
+  readonly page: Page;
+
+  // Locators - Using semantic selectors (priority: getByRole > getByLabel > getByText > getByTestId)
+  readonly welcomeMessage: Locator;
+  readonly aboutLink: Locator;
+  readonly contactLink: Locator;
+  readonly navbar: Locator;
+  readonly heroSection: Locator;
+  readonly ctaButton: Locator;
+  readonly featureCards: Locator;
+
+  constructor(page: Page) {
+    this.page = page;
+
+    // Initialize locators with semantic selectors
+    this.navbar = page.getByRole('navigation');
+    this.welcomeMessage = page.getByRole('heading', { name: /welcome/i });
+    this.aboutLink = page.getByRole('link', { name: /about/i });
+    this.contactLink = page.getByRole('link', { name: /contact/i });
+    this.heroSection = page.getByRole('banner');
+    this.ctaButton = page.getByRole('button', { name: /get started/i });
+    this.featureCards = page.getByRole('article');
+  }
+
+  /**
+   * Navigate to homepage
+   */
+  async goto() {
+    await this.page.goto('/');
+    await this.page.waitForLoadState('networkidle');
+  }
+
+  /**
+   * Wait for page to be fully loaded and ready
+   */
+  async waitForReady() {
+    await this.welcomeMessage.waitFor({ state: 'visible' });
+    await this.navbar.waitFor({ state: 'visible' });
+  }
+
+  /**
+   * Navigate to About page
+   */
+  async goToAbout() {
+    await this.aboutLink.click();
+    await this.page.waitForURL('**/about');
+  }
+
+  /**
+   * Navigate to Contact page
+   */
+  async goToContact() {
+    await this.contactLink.click();
+    await this.page.waitForURL('**/contact');
+  }
+
+  /**
+   * Click the main CTA button
+   */
+  async clickCTA() {
+    await this.ctaButton.click();
+  }
+
+  /**
+   * Get count of feature cards
+   */
+  async getFeatureCardCount(): Promise<number> {
+    return await this.featureCards.count();
+  }
+
+  /**
+   * Take screenshot of homepage
+   */
+  async screenshot(name: string = 'homepage') {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    await this.page.screenshot({
+      path: `screenshots/current/${name}-${timestamp}.png`,
+      fullPage: true,
+    });
+  }
+}

skills/playwright-e2e-automation/examples/react-vite/example-test.spec.ts

@@ -0,0 +1,149 @@
+import { test, expect } from '@playwright/test';
+import { HomePage } from '../pages/home.page';
+import { captureWithContext } from '../utils/screenshot-helper';
+
+/**
+ * Example Playwright Test for React + Vite Application
+ *
+ * This demonstrates best practices for e2e testing with screenshot capture
+ */
+
+test.describe('Homepage', () => {
+  let homePage: HomePage;
+
+  test.beforeEach(async ({ page }) => {
+    homePage = new HomePage(page);
+    await homePage.goto();
+
+    // Capture initial page load
+    await captureWithContext(page, 'homepage-initial-load', 'Homepage loaded successfully');
+  });
+
+  test('should display welcome message', async ({ page }) => {
+    // Arrange: Page is already loaded in beforeEach
+
+    // Act: No action needed, just checking initial state
+    await captureWithContext(page, 'homepage-welcome-check', 'Checking for welcome message');
+
+    // Assert: Welcome message is visible
+    await expect(homePage.welcomeMessage).toBeVisible();
+    await expect(homePage.welcomeMessage).toContainText('Welcome');
+  });
+
+  test('should navigate to about page when clicking About link', async ({ page }) => {
+    // Arrange: Page loaded
+    await captureWithContext(page, 'homepage-before-nav', 'Before clicking About link');
+
+    // Act: Click About link
+    await homePage.aboutLink.click();
+
+    // Capture after navigation
+    await page.waitForURL('**/about');
+    await captureWithContext(page, 'about-page-loaded', 'About page after navigation');
+
+    // Assert: URL changed and about page content visible
+    expect(page.url()).toContain('/about');
+    await expect(page.getByRole('heading', { name: 'About' })).toBeVisible();
+  });
+
+  test('should submit contact form successfully', async ({ page }) => {
+    // Arrange: Navigate to contact page
+    await page.goto('/contact');
+    await captureWithContext(page, 'contact-form-initial', 'Contact form initial state');
+
+    // Act: Fill out form
+    await page.getByLabel('Name').fill('John Doe');
+    await page.getByLabel('Email').fill('john@example.com');
+    await page.getByLabel('Message').fill('This is a test message');
+
+    await captureWithContext(page, 'contact-form-filled', 'Form filled before submission');
+
+    await page.getByRole('button', { name: 'Send Message' }).click();
+
+    // Wait for success message
+    await page.waitForSelector('[data-testid="success-message"]', { state: 'visible' });
+
+    await captureWithContext(page, 'contact-form-success', 'Success message displayed');
+
+    // Assert: Success message appears
+    await expect(page.getByTestId('success-message')).toBeVisible();
+    await expect(page.getByTestId('success-message')).toContainText('Message sent successfully');
+  });
+
+  test('should validate required fields', async ({ page }) => {
+    // Arrange: Navigate to contact page
+    await page.goto('/contact');
+    await captureWithContext(page, 'contact-form-validation-init', 'Before validation check');
+
+    // Act: Try to submit empty form
+    await page.getByRole('button', { name: 'Send Message' }).click();
+
+    await captureWithContext(page, 'contact-form-validation-errors', 'Validation errors displayed');
+
+    // Assert: Error messages appear
+    await expect(page.getByText('Name is required')).toBeVisible();
+    await expect(page.getByText('Email is required')).toBeVisible();
+    await expect(page.getByText('Message is required')).toBeVisible();
+  });
+
+  test('should not have accessibility violations', async ({ page }) => {
+    const AxeBuilder = (await import('@axe-core/playwright')).default;
+
+    const accessibilityScanResults = await new AxeBuilder({ page })
+      .withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'])
+      .analyze();
+
+    await captureWithContext(
+      page,
+      'homepage-accessibility-check',
+      `Found ${accessibilityScanResults.violations.length} accessibility violations`
+    );
+
+    // Log violations for review
+    if (accessibilityScanResults.violations.length > 0) {
+      console.log('\n⚠️  Accessibility Violations:');
+      accessibilityScanResults.violations.forEach((violation) => {
+        console.log(`\n- ${violation.id}: ${violation.description}`);
+        console.log(`  Impact: ${violation.impact}`);
+        console.log(`  Nodes: ${violation.nodes.length}`);
+      });
+    }
+
+    // Fail on critical violations only (for this example)
+    const criticalViolations = accessibilityScanResults.violations.filter(
+      (v) => v.impact === 'critical' || v.impact === 'serious'
+    );
+
+    expect(criticalViolations).toEqual([]);
+  });
+
+  test('should display correctly across viewports', async ({ page }) => {
+    const viewports = [
+      { name: 'desktop', width: 1280, height: 720 },
+      { name: 'tablet', width: 768, height: 1024 },
+      { name: 'mobile', width: 375, height: 667 },
+    ];
+
+    for (const viewport of viewports) {
+      await page.setViewportSize(viewport);
+      await page.waitForTimeout(500); // Let responsive changes settle
+
+      await captureWithContext(
+        page,
+        `homepage-responsive-${viewport.name}`,
+        `${viewport.width}x${viewport.height} viewport`
+      );
+
+      // Verify no horizontal scroll on mobile/tablet
+      if (viewport.name !== 'desktop') {
+        const scrollWidth = await page.evaluate(() => document.body.scrollWidth);
+        const clientWidth = await page.evaluate(() => document.body.clientWidth);
+        expect(scrollWidth).toBeLessThanOrEqual(clientWidth + 1); // Allow 1px tolerance
+      }
+
+      // Verify main navigation is accessible
+      const nav = page.getByRole('navigation');
+      await expect(nav).toBeVisible();
+    }
+  });
+});

skills/playwright-e2e-automation/examples/reports/fix-recommendations.example.md

@@ -0,0 +1,592 @@
+# Fix Recommendations
+
+**Generated**: 2025-11-01 16:35:22
+**Based On**: visual-analysis-report.md
+**Issues Addressed**: 8
+**Estimated Effort**: 4-6 hours
+
+---
+
+## How to Use This Report
+
+Each fix includes:
+- **File location** with line numbers (when identifiable)
+- **Current code** showing the problematic implementation
+- **Recommended fix** with specific code changes
+- **Reasoning** explaining why this fix works
+- **Testing steps** to validate the fix
+
+Apply fixes in priority order: Critical → High → Medium → Low
+
+---
+
+## Critical Fixes (Implement Immediately)
+
+### Fix #1: Increase Form Label Contrast
+
+**Issue**: Insufficient color contrast on form labels (2.6:1, requires 4.5:1)
+
+**Location**: `src/components/ContactForm.tsx:45-52`
+
+**Current Code**:
+```tsx
+<label htmlFor="name" className="block text-gray-400 text-sm mb-1">
+  Name
+</label>
+<input
+  id="name"
+  type="text"
+  className="w-full px-4 py-2 border border-gray-300 rounded"
+  placeholder="Enter your name"
+/>
+```
+
+**Recommended Fix**:
+```tsx
+<label htmlFor="name" className="block text-gray-700 text-sm font-medium mb-1">
+  Name
+</label>
+<input
+  id="name"
+  type="text"
+  className="w-full px-4 py-2 border border-gray-300 rounded"
+  placeholder="Enter your name"
+  aria-required="true"
+/>
+```
+
+**Changes Made**:
+- `text-gray-400` → `text-gray-700` (changes color from #AAAAAA to #374151)
+- Added `font-medium` for improved readability
+- Added `aria-required="true"` for accessibility
+
+**Reasoning**:
+- `text-gray-700` (#374151) on white (#FFFFFF) = 9.7:1 contrast ratio ✅
+- Exceeds WCAG 2.1 AA requirement (4.5:1)
+- `font-medium` improves readability without affecting contrast
+- `aria-required` helps screen reader users identify required fields
+
+**Testing**:
+1. Visual check: Labels should be clearly readable
+2. Contrast tool: Verify 9.7:1 ratio at https://webaim.org/resources/contrastchecker/
+3. Accessibility audit: Run axe-core, verify no contrast violations
+4. Screen reader: Test with NVDA/VoiceOver, verify required field announcement
+
+**Impact**: Fixes critical WCAG 2.1 violation, improves usability for low-vision users
+
+---
+
+### Fix #2: Responsive Button Text Sizing
+
+**Issue**: Button text truncated on mobile (shows "Send Mes...")
+
+**Location**: `src/components/ContactForm.tsx:78`
+
+**Current Code**:
+```tsx
+<button
+  type="submit"
+  className="w-full px-6 py-3 text-xl font-bold bg-blue-600 text-white rounded"
+>
+  Send Message
+</button>
+```
+
+**Recommended Fix**:
+```tsx
+<button
+  type="submit"
+  className="w-full px-4 py-2 text-sm sm:text-base md:text-lg font-bold bg-blue-600 text-white rounded whitespace-nowrap overflow-visible"
+>
+  Send Message
+</button>
+```
+
+**Changes Made**:
+- `px-6` → `px-4` (reduced padding to allow more text space)
+- `py-3` → `py-2` (slightly reduced vertical padding)
+- `text-xl` → `text-sm sm:text-base md:text-lg` (responsive text sizing)
+- Added `whitespace-nowrap` (prevent text wrapping)
+- Added `overflow-visible` (ensure text isn't hidden)
+
+**Reasoning**:
+- Mobile (375px): 14px font (text-sm) fits comfortably
+- Tablet (768px): 16px font (text-base) for better readability
+- Desktop (1280px): 18px font (text-lg) for prominence
+- Reduced padding provides more space for text
+- `whitespace-nowrap` prevents awkward line breaks
+
+**Testing**:
+1. Mobile (375px viewport): Verify full text "Send Message" visible
+2. Tablet (768px): Check font size scales appropriately
+3. Desktop (1280px): Ensure button looks proportional
+4. Accessibility: Verify button is tappable (min 44x44px)
+
+**Impact**: Fixes broken user experience on mobile, ensures button purpose is clear
+
+---
+
+## High Priority Fixes
+
+### Fix #3: Prevent Navigation Overlap on Tablet
+
+**Issue**: Nav items overlap on tablet breakpoint (768px)
+
+**Location**: `src/components/Header.tsx:32-45`
+
+**Current Code**:
+```tsx
+<nav className="flex space-x-6">
+  <a href="/" className="text-gray-700 hover:text-blue-600">
+    Home
+  </a>
+  <a href="/about" className="text-gray-700 hover:text-blue-600">
+    About
+  </a>
+  <a href="/contact" className="text-gray-700 hover:text-blue-600">
+    Contact
+  </a>
+  <a href="/blog" className="text-gray-700 hover:text-blue-600">
+    Blog
+  </a>
+</nav>
+```
+
+**Recommended Fix**:
+```tsx
+<nav className="flex flex-col md:flex-row md:space-x-6 space-y-2 md:space-y-0">
+  <a href="/" className="text-gray-700 hover:text-blue-600 py-2 md:py-0">
+    Home
+  </a>
+  <a href="/about" className="text-gray-700 hover:text-blue-600 py-2 md:py-0">
+    About
+  </a>
+  <a href="/contact" className="text-gray-700 hover:text-blue-600 py-2 md:py-0">
+    Contact
+  </a>
+  <a href="/blog" className="text-gray-700 hover:text-blue-600 py-2 md:py-0">
+    Blog
+  </a>
+</nav>
+```
+
+**Alternative Fix** (if horizontal menu required):
+```tsx
+<nav className="flex space-x-3 md:space-x-6 text-sm md:text-base">
+  <a href="/" className="text-gray-700 hover:text-blue-600 whitespace-nowrap">
+    Home
+  </a>
+  <a href="/about" className="text-gray-700 hover:text-blue-600 whitespace-nowrap">
+    About
+  </a>
+  <a href="/contact" className="text-gray-700 hover:text-blue-600 whitespace-nowrap">
+    Contact
+  </a>
+  <a href="/blog" className="text-gray-700 hover:text-blue-600 whitespace-nowrap">
+    Blog
+  </a>
+</nav>
+```
+
+**Reasoning**:
+- **Option 1**: Stack links vertically on tablet/mobile, horizontal on desktop
+  - More reliable, works with any link text length
+  - Better for mobile usability
+- **Option 2**: Reduce spacing and font size on smaller screens
+  - Maintains horizontal layout
+  - Risk: May still overflow with longer link text
+
+**Recommendation**: Use Option 1 for reliability
+
+**Testing**:
+1. Tablet (768px): Verify links stack vertically or have adequate spacing
+2. Desktop (1024px+): Verify links display horizontally
+3. Check all breakpoints: 640px, 768px, 1024px, 1280px
+4. Test with longer link text (e.g., "Our Services" instead of "Blog")
+
+**Impact**: Fixes navigation usability on tablet devices
+
+---
+
+### Fix #4: Prevent Hero Image Distortion
+
+**Issue**: Hero background image stretched on mobile viewport
+
+**Location**: `src/components/Hero.tsx:15-25`
+
+**Current Code**:
+```tsx
+<div
+  className="hero-section h-96 bg-cover bg-center"
+  style={{
+    backgroundImage: "url('/images/hero-bg.jpg')",
+  }}
+>
+  <div className="container mx-auto h-full flex items-center">
+    <h1 className="text-4xl font-bold text-white">Welcome to Our Site</h1>
+  </div>
+</div>
+```
+
+**Recommended Fix**:
+```tsx
+<div className="hero-section h-96 relative overflow-hidden">
+  <img
+    src="/images/hero-bg.jpg"
+    alt=""
+    className="absolute inset-0 w-full h-full object-cover object-center"
+    aria-hidden="true"
+  />
+  <div className="container mx-auto h-full flex items-center relative z-10">
+    <h1 className="text-4xl font-bold text-white drop-shadow-lg">
+      Welcome to Our Site
+    </h1>
+  </div>
+</div>
+```
+
+**Changes Made**:
+- Replaced CSS background image with `<img>` tag
+- Added `object-cover` to maintain aspect ratio while filling container
+- Added `object-center` for centered focal point
+- Made container `relative` with image `absolute` for layering
+- Added `drop-shadow-lg` to h1 for better text visibility
+- Added `aria-hidden="true"` since image is decorative
+
+**Reasoning**:
+- `object-cover` scales image proportionally to fill container
+- Crops excess rather than stretching to fit
+- Maintains image quality and recognizability
+- Works consistently across all viewport sizes
+
+**Testing**:
+1. Mobile (375px): Verify image not stretched, focal point visible
+2. Tablet (768px): Check image scales appropriately
+3. Desktop (1280px): Ensure full image coverage
+4. Test with different aspect ratio images (16:9, 4:3, 1:1)
+
+**Impact**: Professional appearance maintained across all devices
+
+---
+
+### Fix #5: Add Visible Error Messages
+
+**Issue**: Form validation errors indicated only by red border (no text)
+
+**Location**: `src/components/ContactForm.tsx:55-95`
+
+**Current Code**:
+```tsx
+<input
+  id="email"
+  type="email"
+  className={`w-full px-4 py-2 border rounded ${
+    errors.email ? 'border-red-500' : 'border-gray-300'
+  }`}
+/>
+```
+
+**Recommended Fix**:
+```tsx
+<div className="mb-4">
+  <label htmlFor="email" className="block text-gray-700 text-sm font-medium mb-1">
+    Email Address <span className="text-red-600" aria-label="required">*</span>
+  </label>
+  <input
+    id="email"
+    type="email"
+    className={`w-full px-4 py-2 border rounded ${
+      errors.email
+        ? 'border-red-500 focus:ring-red-500'
+        : 'border-gray-300 focus:ring-blue-500'
+    }`}
+    aria-invalid={errors.email ? 'true' : 'false'}
+    aria-describedby={errors.email ? 'email-error' : undefined}
+  />
+  {errors.email && (
+    <div
+      id="email-error"
+      className="mt-1 text-sm text-red-600 flex items-center"
+      role="alert"
+    >
+      <svg
+        className="w-4 h-4 mr-1 flex-shrink-0"
+        fill="currentColor"
+        viewBox="0 0 20 20"
+        aria-hidden="true"
+      >
+        <path
+          fillRule="evenodd"
+          d="M10 18a8 8 0 100-16 8 8 0 000 16zM8.707 7.293a1 1 0 00-1.414 1.414L8.586 10l-1.293 1.293a1 1 0 101.414 1.414L10 11.414l1.293 1.293a1 1 0 001.414-1.414L11.414 10l1.293-1.293a1 1 0 00-1.414-1.414L10 8.586 8.707 7.293z"
+          clipRule="evenodd"
+        />
+      </svg>
+      {errors.email}
+    </div>
+  )}
+</div>
+```
+
+**Changes Made**:
+- Added required indicator (*) with `aria-label`
+- Added `aria-invalid` attribute for screen readers
+- Added `aria-describedby` linking to error message
+- Added visible error message below input
+- Added error icon for visual reinforcement
+- Added `role="alert"` to announce errors to screen readers
+
+**Reasoning**:
+- Error text provides specific guidance (not just "there's an error")
+- Icon + color + text = multiple indicators (not color alone)
+- ARIA attributes ensure screen reader compatibility
+- Error message ID allows programmatic association with input
+
+**Testing**:
+1. Visual: Submit empty form, verify error text appears below inputs
+2. Screen reader: Verify error messages are announced
+3. Keyboard: Tab to input, verify error is read aloud
+4. Contrast: Verify error text meets 4.5:1 ratio (red-600 on white)
+
+**Impact**: Makes form errors accessible to all users, improves error recovery
+
+---
+
+## Medium Priority Fixes
+
+### Fix #6: Standardize Feature Card Heights
+
+**Issue**: Feature cards have inconsistent heights
+
+**Location**: `src/components/FeatureSection.tsx:28-42`
+
+**Current Code**:
+```tsx
+<div className="grid grid-cols-1 md:grid-cols-3 gap-6">
+  {features.map((feature) => (
+    <div key={feature.id} className="bg-white p-6 rounded shadow">
+      <h3 className="text-xl font-bold mb-2">{feature.title}</h3>
+      <p className="text-gray-600">{feature.description}</p>
+    </div>
+  ))}
+</div>
+```
+
+**Recommended Fix**:
+```tsx
+<div className="grid grid-cols-1 md:grid-cols-3 gap-6 items-start">
+  {features.map((feature) => (
+    <div key={feature.id} className="bg-white p-6 rounded shadow flex flex-col h-full">
+      <h3 className="text-xl font-bold mb-2">{feature.title}</h3>
+      <p className="text-gray-600 flex-grow">{feature.description}</p>
+      {feature.link && (
+        <a
+          href={feature.link}
+          className="mt-4 text-blue-600 hover:text-blue-700 font-medium"
+        >
+          Learn more →
+        </a>
+      )}
+    </div>
+  ))}
+</div>
+```
+
+**Changes Made**:
+- Added `items-start` to grid (align cards to top)
+- Added `flex flex-col h-full` to card (flexbox layout)
+- Added `flex-grow` to description (fills available space)
+- Positioned link at bottom with `mt-4` (consistent spacing)
+
+**Reasoning**:
+- `h-full` makes all cards same height (tallest card determines height)
+- `flex-grow` on description pushes "Learn more" link to bottom
+- Creates visual consistency across grid
+- Maintains readability while looking polished
+
+**Testing**:
+1. Desktop (3 columns): Verify all cards same height
+2. Test with varying description lengths
+3. Ensure "Learn more" links align at bottom
+4. Mobile (1 column): Verify cards still look good stacked
+
+**Impact**: More professional, polished appearance
+
+---
+
+### Fix #7: Increase Footer Link Spacing on Mobile
+
+**Issue**: Footer links only 4-6px apart on mobile, difficult to tap
+
+**Location**: `src/components/Footer.tsx:45-58`
+
+**Current Code**:
+```tsx
+<div className="flex flex-col space-y-1">
+  <a href="/about" className="text-gray-600 hover:text-gray-900">
+    About
+  </a>
+  <a href="/contact" className="text-gray-600 hover:text-gray-900">
+    Contact
+  </a>
+  <a href="/privacy" className="text-gray-600 hover:text-gray-900">
+    Privacy Policy
+  </a>
+</div>
+```
+
+**Recommended Fix**:
+```tsx
+<div className="flex flex-col space-y-3">
+  <a
+    href="/about"
+    className="text-gray-600 hover:text-gray-900 py-2 -my-2 inline-block"
+  >
+    About
+  </a>
+  <a
+    href="/contact"
+    className="text-gray-600 hover:text-gray-900 py-2 -my-2 inline-block"
+  >
+    Contact
+  </a>
+  <a
+    href="/privacy"
+    className="text-gray-600 hover:text-gray-900 py-2 -my-2 inline-block"
+  >
+    Privacy Policy
+  </a>
+</div>
+```
+
+**Changes Made**:
+- `space-y-1` → `space-y-3` (increased spacing from ~4px to ~12px)
+- Added `py-2` (8px vertical padding, expanding tap area)
+- Added `-my-2` (negative margin to maintain visual spacing)
+- Added `inline-block` (allow vertical padding on inline element)
+
+**Reasoning**:
+- `space-y-3` provides minimum 8px spacing (WCAG recommendation)
+- `py-2` creates 44px minimum tap target height (8px padding + ~28px text)
+- Negative margin prevents excessive visual spacing
+- Easier to tap accurately on mobile devices
+
+**Testing**:
+1. Mobile (375px): Verify 44x44px minimum tap target
+2. Test tapping each link with finger (not stylus)
+3. Ensure no accidental mis-taps to adjacent links
+4. Check visual spacing looks appropriate
+
+**Impact**: Improved mobile usability, reduces user frustration
+
+---
+
+## Low Priority Fixes
+
+### Fix #8: Improve Heading Size Hierarchy
+
+**Issue**: H2 and H3 appear same size, reducing visual hierarchy
+
+**Location**: `src/styles/globals.css:15-25` OR Tailwind config
+
+**Current Code** (CSS):
+```css
+h2, h3 {
+  font-size: 1.25rem; /* 20px */
+  font-weight: 700;
+}
+```
+
+**Recommended Fix** (CSS):
+```css
+h2 {
+  font-size: 1.5rem; /* 24px */
+  font-weight: 700;
+  margin-bottom: 0.75rem;
+}
+
+h3 {
+  font-size: 1.25rem; /* 20px */
+  font-weight: 600;
+  margin-bottom: 0.5rem;
+}
+```
+
+**OR** (Tailwind utility classes):
+
+Replace `text-xl` on H2s with `text-2xl`, keep `text-xl` on H3s:
+
+```tsx
+<h2 className="text-2xl font-bold mb-3">Section Heading</h2>
+<h3 className="text-xl font-semibold mb-2">Subsection Heading</h3>
+```
+
+**Reasoning**:
+- H2 (24px) → H3 (20px) creates clear hierarchy
+- Progressively lighter font weights reinforce hierarchy
+- Proper heading sizes aid content scanning
+- Improves semantic structure perception
+
+**Testing**:
+1. Visual check: H1 > H2 > H3 size progression
+2. Compare before/after screenshots
+3. Test with screen reader: Verify heading navigation still works
+4. Check across different pages for consistency
+
+**Impact**: Improved content scanability and professional appearance
+
+---
+
+## Implementation Checklist
+
+### Critical (Do First)
+- [ ] Fix #1: Form label contrast
+- [ ] Fix #2: Button text sizing
+
+### High (This Sprint)
+- [ ] Fix #3: Navigation overlap
+- [ ] Fix #4: Hero image aspect ratio
+- [ ] Fix #5: Visible error messages
+
+### Medium (Next Iteration)
+- [ ] Fix #6: Card height consistency
+- [ ] Fix #7: Footer link spacing
+
+### Low (Backlog)
+- [ ] Fix #8: Heading hierarchy
+
+---
+
+## Testing After Implementation
+
+1. **Re-run Playwright tests**:
+   ```bash
+   npm run test:e2e
+   ```
+
+2. **Capture new screenshots**:
+   ```bash
+   npm run test:e2e -- --update-snapshots
+   ```
+
+3. **Run accessibility audit**:
+   ```bash
+   npm run test:e2e -- accessibility.spec.ts
+   ```
+
+4. **Manual testing**:
+   - Test on real devices (iPhone, Android, iPad)
+   - Test with screen reader (VoiceOver on iOS, TalkBack on Android)
+   - Verify color contrast with browser DevTools
+
+5. **Compare screenshots**:
+   - Before: `screenshots/baselines/`
+   - After: `screenshots/current/`
+   - Ensure visual improvements visible
+
+---
+
+**Generated by**: playwright-e2e-automation skill
+**Estimated Total Time**: 4-6 hours
+**Confidence Level**: High (fixes based on standard patterns)
+
+All fixes follow React + Tailwind CSS best practices and maintain existing code structure.

skills/playwright-e2e-automation/examples/reports/visual-analysis-report.example.md

@@ -0,0 +1,266 @@
+# Visual Analysis Report
+
+**Generated**: 2025-11-01 16:30:45
+**Test Run**: Homepage e2e tests
+**Screenshots Analyzed**: 23
+**Issues Found**: 8 (2 Critical, 3 High, 2 Medium, 1 Low)
+
+---
+
+## Executive Summary
+
+Analyzed 23 screenshots across 3 viewports (desktop 1280x720, tablet 768x1024, mobile 375x667). Found 8 UI/UX issues requiring attention, including 2 critical accessibility violations and 3 high-priority layout bugs.
+
+### Issue Breakdown by Category
+
+- **Layout Issues**: 4
+- **Accessibility Violations**: 2
+- **Typography Problems**: 1
+- **Responsive Design Issues**: 1
+
+### Issue Breakdown by Severity
+
+- **Critical** (P0): 2 issues - Fix immediately
+- **High** (P1): 3 issues - Fix within sprint
+- **Medium** (P2): 2 issues - Address in next iteration
+- **Low** (P3): 1 issue - Polish/enhancement
+
+---
+
+## Critical Issues (P0)
+
+### 1. Insufficient Color Contrast on Form Labels
+
+**Severity**: Critical
+**Category**: Accessibility
+**Viewport**: All viewports
+**Screenshot**: `screenshots/current/contact-form-initial-2025-11-01T16-28-32.png`
+
+**Description**:
+Form input labels use light gray (#AAAAAA) on white background (#FFFFFF), resulting in a contrast ratio of only 2.6:1. WCAG 2.1 AA requires 4.5:1 for normal text.
+
+**User Impact**:
+Users with low vision or color blindness cannot read form labels, making the contact form unusable for accessibility-dependent users. Fails WCAG 2.1 criterion 1.4.3 (Contrast Minimum).
+
+**Visual Evidence**:
+In the screenshot, the "Name", "Email", and "Message" labels appear very faint and difficult to read against the white background.
+
+**Affected Elements**:
+- Name label
+- Email label
+- Message label
+
+**Recommended Fix**: See fix-recommendations.md #1
+
+---
+
+### 2. Button Text Truncated on Mobile Viewport
+
+**Severity**: Critical
+**Category**: Layout / Responsive
+**Viewport**: Mobile (375x667)
+**Screenshot**: `screenshots/current/contact-form-filled-mobile-2025-11-01T16-29-15.png`
+
+**Description**:
+The "Send Message" button text is cut off mid-word on mobile viewport, displaying "Send Mes..." due to fixed width and large font size.
+
+**User Impact**:
+Users cannot see the full button text, creating confusion about the button's purpose and reducing trust in the interface.
+
+**Visual Evidence**:
+The submit button shows truncated text with an ellipsis, indicating the button width is insufficient for the text content at the current font size.
+
+**Recommended Fix**: See fix-recommendations.md #2
+
+---
+
+## High Priority Issues (P1)
+
+### 3. Navigation Menu Items Overlap on Tablet Viewport
+
+**Severity**: High
+**Category**: Layout
+**Viewport**: Tablet (768x1024)
+**Screenshot**: `screenshots/current/homepage-responsive-tablet-2025-11-01T16-27-45.png`
+
+**Description**:
+Navigation menu items in the header overlap each other at tablet breakpoint (768px), causing "About" and "Contact" links to partially obscure each other.
+
+**User Impact**:
+Users cannot click on navigation links reliably, potentially clicking the wrong link or missing links entirely.
+
+**Visual Evidence**:
+Screenshot shows "About" and "Contact" link text overlapping in the header navigation bar.
+
+**Recommended Fix**: See fix-recommendations.md #3
+
+---
+
+### 4. Hero Section Image Stretched on Mobile
+
+**Severity**: High
+**Category**: Responsive / Layout
+**Viewport**: Mobile (375x667)
+**Screenshot**: `screenshots/current/homepage-responsive-mobile-2025-11-01T16-27-52.png`
+
+**Description**:
+Hero section background image appears stretched and distorted on mobile viewport. The 16:9 image is forced into a narrow vertical space, causing visible distortion.
+
+**User Impact**:
+Unprofessional appearance reduces user trust and brand perception. Image content may be unrecognizable when distorted.
+
+**Visual Evidence**:
+The hero image shows obvious stretching, with circular elements appearing oval-shaped and text in the image appearing compressed vertically.
+
+**Recommended Fix**: See fix-recommendations.md #4
+
+---
+
+### 5. Missing Error State Indication
+
+**Severity**: High
+**Category**: Accessibility / UX
+**Viewport**: All viewports
+**Screenshot**: `screenshots/current/contact-form-validation-errors-2025-11-01T16-29-45.png`
+
+**Description**:
+Form validation errors are indicated only by a red border around inputs. No error text is visible, and there's no icon or other non-color indicator.
+
+**User Impact**:
+Users relying on screen readers won't hear error messages. Color-blind users may not notice the red border. Error messages are essential for understanding what went wrong.
+
+**Visual Evidence**:
+Screenshot shows inputs with red borders but no visible error text below them explaining what the error is.
+
+**Recommended Fix**: See fix-recommendations.md #5
+
+---
+
+## Medium Priority Issues (P2)
+
+### 6. Inconsistent Card Heights in Feature Section
+
+**Severity**: Medium
+**Category**: Layout
+**Viewport**: Desktop (1280x720)
+**Screenshot**: `screenshots/current/homepage-initial-load-2025-11-01T16-27-18.png`
+
+**Description**:
+Feature cards have varying heights due to different content lengths. The grid layout doesn't maintain consistent card heights, creating a jagged appearance.
+
+**User Impact**:
+Visually inconsistent and less professional. Makes the page feel unpolished.
+
+**Visual Evidence**:
+Three feature cards visible - first card is noticeably taller than the second, and third is somewhere in between, creating uneven rows.
+
+**Recommended Fix**: See fix-recommendations.md #6
+
+---
+
+### 7. Footer Links Too Close Together on Mobile
+
+**Severity**: Medium
+**Category**: Responsive / Touch Targets
+**Viewport**: Mobile (375x667)
+**Screenshot**: `screenshots/current/homepage-responsive-mobile-2025-11-01T16-27-52.png`
+
+**Description**:
+Footer navigation links are spaced only 4-6px apart vertically on mobile, making them difficult to tap accurately. WCAG 2.1 recommends minimum 44x44px touch targets with 8px spacing.
+
+**User Impact**:
+Users frequently mis-tap links, requiring multiple attempts to navigate. Particularly frustrating for users with motor impairments or large fingers.
+
+**Visual Evidence**:
+Footer links appear very close together with minimal spacing between each link.
+
+**Recommended Fix**: See fix-recommendations.md #7
+
+---
+
+## Low Priority Issues (P3)
+
+### 8. Heading Sizes Not Progressively Smaller
+
+**Severity**: Low
+**Category**: Typography / Visual Hierarchy
+**Viewport**: All viewports
+**Screenshot**: `screenshots/current/about-page-loaded-2025-11-01T16-28-05.png`
+
+**Description**:
+H2 and H3 headings appear to be the same size (approximately 20px), reducing visual hierarchy and making it harder to scan content structure.
+
+**User Impact**:
+Minor impact on content scanability. Users may not immediately recognize the content hierarchy.
+
+**Visual Evidence**:
+Page title (H1) is clearly larger, but H2 section headings and H3 subsection headings are visually identical in size.
+
+**Recommended Fix**: See fix-recommendations.md #8
+
+---
+
+## Summary Statistics
+
+### By Severity
+| Severity | Count | Percentage |
+|----------|-------|------------|
+| Critical | 2     | 25%        |
+| High     | 3     | 37.5%      |
+| Medium   | 2     | 25%        |
+| Low      | 1     | 12.5%      |
+
+### By Category
+| Category       | Count |
+|----------------|-------|
+| Layout         | 4     |
+| Accessibility  | 2     |
+| Typography     | 1     |
+| Responsive     | 1     |
+
+### By Viewport
+| Viewport | Issues |
+|----------|--------|
+| Mobile   | 5      |
+| Tablet   | 1      |
+| Desktop  | 1      |
+| All      | 3      |
+
+---
+
+## Recommended Actions
+
+1. **Immediate (Critical)**:
+   - Fix form label contrast (#1)
+   - Fix button text truncation on mobile (#2)
+
+2. **This Sprint (High)**:
+   - Fix navigation overlap on tablet (#3)
+   - Fix hero image stretching (#4)
+   - Add visible error messages (#5)
+
+3. **Next Iteration (Medium)**:
+   - Standardize feature card heights (#6)
+   - Increase footer link spacing on mobile (#7)
+
+4. **Backlog (Low)**:
+   - Adjust heading size hierarchy (#8)
+
+---
+
+## Testing Recommendations
+
+After fixes are implemented:
+
+1. Re-run Playwright test suite to capture updated screenshots
+2. Compare new screenshots with current baseline
+3. Run accessibility audit with axe-core
+4. Test on real devices (iOS Safari, Android Chrome)
+5. Validate color contrast with WebAIM tool
+6. Test with screen reader (VoiceOver, NVDA)
+
+---
+
+**Generated by**: playwright-e2e-automation skill
+**Analysis Method**: LLM-powered visual screenshot analysis
+**Reference Guides**: accessibility-checks.md, common-ui-bugs.md