Initial commit

2025-11-29 18:17:04 +08:00
commit e758c0ab84
56 changed files with 9997 additions and 0 deletions
--- a/skills/playwright-e2e-automation/examples/reports/fix-recommendations.example.md
+++ b/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.