regression-visual

What this skill does

# regression-visual

Detect visual and UI regressions through screenshot comparison and pixel-diff analysis.

## Triggers


Alternate expressions and non-obvious activations (primary phrases are matched automatically from the skill description):

- "visual diff" → screenshot/UI comparison
- "UI diff" → visual regression shorthand
- "Playwright screenshots" / "Storybook snapshots" → tool-specific visual regression

## Purpose

This skill manages visual regression detection by:
- Capturing screenshots across browsers and viewports
- Comparing current UI to baseline screenshots
- Detecting pixel-level differences with configurable thresholds
- Identifying layout shifts, color changes, and missing elements
- Running component-level visual tests
- Checking accessibility visual indicators
- Generating visual diff reports with side-by-side comparisons

## Behavior

When triggered, this skill:

1. **Identifies visual test scope**:
   - Determine which components/pages to test
   - Select browsers and devices (cross-browser testing)
   - Identify viewports for responsive testing
   - Check for existing visual baselines
   - Locate test configuration

2. **Captures screenshots**:
   - Run browser automation (Playwright, Puppeteer)
   - Take screenshots at each viewport size
   - Capture component states (hover, focus, error, disabled)
   - Handle dynamic content (hide timestamps, animations)
   - Store screenshots with metadata

3. **Compares to baseline**:
   - Load baseline screenshots
   - Perform pixel-by-pixel comparison
   - Calculate difference percentage
   - Apply threshold tolerance (e.g., 0.1%)
   - Generate diff images highlighting changes

4. **Categorizes differences**:
   - Layout shift (position/size changes)
   - Color changes (background, text, borders)
   - Typography changes (font, size, weight)
   - Spacing/alignment issues
   - Missing or extra elements
   - Visual accessibility issues

5. **Generates visual diff report**:
   - Side-by-side baseline vs current
   - Diff overlay highlighting changes
   - List of detected regressions by category
   - Severity assessment per change
   - Links to affected components

6. **Integrates with CI/CD**:
   - Run visual tests in pipeline
   - Block PRs if threshold exceeded
   - Upload screenshots to cloud storage
   - Comment on PRs with visual diff links

## Visual Regression Categories

### Layout Shift

```yaml
layout_shift:
  description: Position or dimension changes
  detection:
    - element_moved
    - element_resized
    - overflow_introduced
    - spacing_changed
    - alignment_broken

  example:
    component: "NavigationBar"
    issue: "Menu shifted 10px right"
    severity: medium
    cause: "CSS margin change"
    diff_percentage: 2.3
```

### Color Changes

```yaml
color_changes:
  description: Color, gradient, or opacity changes
  detection:
    - background_color_changed
    - text_color_changed
    - border_color_changed
    - gradient_modified
    - opacity_changed

  example:
    component: "PrimaryButton"
    issue: "Background color #007bff → #0056b3"
    severity: high
    cause: "Design system update not applied"
    diff_percentage: 0.8
```

### Typography Changes

```yaml
typography_changes:
  description: Font, size, weight, line-height changes
  detection:
    - font_family_changed
    - font_size_changed
    - font_weight_changed
    - line_height_changed
    - letter_spacing_changed

  example:
    component: "Heading"
    issue: "Font size 24px → 22px"
    severity: low
    cause: "CSS reset applied incorrectly"
    diff_percentage: 0.5
```

### Spacing/Alignment Issues

```yaml
spacing_alignment:
  description: Padding, margin, alignment issues
  detection:
    - padding_changed
    - margin_changed
    - text_alignment_changed
    - element_misalignment
    - grid_layout_broken

  example:
    component: "CardGrid"
    issue: "Cards no longer aligned in grid"
    severity: high
    cause: "Flexbox to Grid migration incomplete"
    diff_percentage: 4.2
```

### Missing/Extra Elements

```yaml
element_changes:
  description: Elements added, removed, or hidden
  detection:
    - element_missing
    - element_added
    - visibility_changed
    - display_none_applied
    - z_index_overlap

  example:
    component: "Footer"
    issue: "Privacy link missing"
    severity: critical
    cause: "Conditional rendering bug"
    diff_percentage: 1.2
```

### Accessibility Visual Indicators

```yaml
accessibility_visual:
  description: Focus indicators, contrast, icon visibility
  detection:
    - focus_outline_missing
    - color_contrast_reduced
    - screen_reader_text_visible
    - icon_missing_or_broken
    - keyboard_navigation_indicator_absent

  example:
    component: "FormInput"
    issue: "Focus outline removed"
    severity: critical
    cause: "CSS reset removed :focus styles"
    diff_percentage: 0.3
    accessibility_impact: "Keyboard users cannot see focus"
```

## Tool Integration

### Percy

```yaml
percy_integration:
  description: Visual testing platform with cloud diffing
  workflow:
    - capture: "percy snapshot <name>"
    - compare: "percy finalize"
    - review: "Percy dashboard for diffs"

  configuration:
    project_token: "PERCY_TOKEN"
    widths: [375, 768, 1280, 1920]
    min_height: 1024
    enable_javascript: true

  example_command:
    - "npx percy exec -- npm run test:visual"
```

### Chromatic

```yaml
chromatic_integration:
  description: Storybook visual testing platform
  workflow:
    - build_storybook: "npm run build-storybook"
    - publish: "npx chromatic --project-token=<token>"
    - review: "Chromatic dashboard"

  configuration:
    project_token: "CHROMATIC_TOKEN"
    exit_zero_on_changes: false
    auto_accept_changes: false

  example_command:
    - "npx chromatic --project-token=$CHROMATIC_TOKEN"
```

### BackstopJS

```yaml
backstopjs_integration:
  description: Open-source screenshot comparison tool
  workflow:
    - setup: "backstop init"
    - reference: "backstop reference"
    - test: "backstop test"
    - approve: "backstop approve"

  configuration_file: "backstop.json"
  configuration:
    viewports:
      - label: mobile
        width: 375
        height: 667
      - label: tablet
        width: 768
        height: 1024
      - label: desktop
        width: 1920
        height: 1080
    scenarios:
      - label: "Homepage"
        url: "http://localhost:3000"
        selectors: ["document"]
        delay: 500
        misMatchThreshold: 0.1

  example_command:
    - "backstop test --config=backstop.json"
```

### Playwright Screenshots

```yaml
playwright_integration:
  description: Cross-browser screenshot capture with Playwright
  workflow:
    - setup: "playwright install"
    - capture: "playwright test --project=visual"
    - compare: "Custom comparison or integrate with Percy/Chromatic"

  test_example: |
    test('visual regression - homepage', async ({ page }) => {
      await page.goto('http://localhost:3000');

      // Hide dynamic content
      await page.evaluate(() => {
        document.querySelectorAll('.timestamp').forEach(el => el.style.visibility = 'hidden');
      });

      // Take screenshot
      await expect(page).toHaveScreenshot('homepage.png', {
        maxDiffPixels: 100,  // Allow 100 pixels difference
      });
    });

  browsers: [chromium, firefox, webkit]
  viewports:
    - width: 375, height: 667   # Mobile
    - width: 768, height: 1024  # Tablet
    - width: 1920, height: 1080 # Desktop
```

## Diff Threshold Configuration

```yaml
diff_thresholds:
  critical_components:
    threshold: 0.01  # 0.01% difference allowed
    components:
      - authentication_flow
      - checkout_process
      - payment_forms
    action_on_exceed: fail

  standard_components:
    threshold: 0.1   # 0.1% difference allowed
    components:
      - navigation
      - footer
      - product_cards
    action_on_exceed: warn

  low_priority_components:
    threshold: 1.0   # 1% difference allowed
    com