Responsive Layout Scanner¶

Scans FastHTML applications for responsive layout issues using Playwright screenshots and Claude vision analysis.

Quick Start¶

# Install dependencies
pip install playwright anthropic
playwright install chromium

# Set API key
export ANTHROPIC_API_KEY=your_key_here

# Run scan
python scripts/scan.py https://your-app.com

Usage¶

# Single page (homepage)
python scripts/scan.py https://example.com

# Multiple pages
python scripts/scan.py https://example.com --pages / /about /dashboard

# Custom output directory
python scripts/scan.py https://example.com --output ./my-report

# Debug mode (visible browser)
python scripts/scan.py https://example.com --headed

Output Structure¶

responsive-scan-results/
├── report.md          # Human-readable report with screenshots
├── report.json        # Structured data for programmatic use
├── home/
│   ├── mobile.png
│   ├── tablet.png
│   └── desktop.png
└── dashboard/
    ├── mobile.png
    ├── tablet.png
    └── desktop.png

Issue Categories¶

The scanner detects issues in these categories:

Category	Examples
`overflow`	Horizontal scroll, content bleeding
`spacing`	Cramped elements, inconsistent margins
`typography`	Text too small, lines too long
`touch_target`	Buttons <44px, elements too close
`layout`	Overlapping, broken columns/stacking
`hierarchy`	Important content below fold
`component`	Form, table, card, image issues

Severity Levels¶

critical: Breaks usability (must fix)
warning: Degrades experience (should fix)
suggestion: Could be improved (nice to have)

Customization¶

Adding Viewports¶

Edit VIEWPORTS dict in scan.py:

VIEWPORTS = {
    "mobile": {"width": 375, "height": 812, "device_scale_factor": 2},
    "tablet": {"width": 768, "height": 1024, "device_scale_factor": 2},
    "desktop": {"width": 1280, "height": 900, "device_scale_factor": 1},
    "wide": {"width": 1920, "height": 1080, "device_scale_factor": 1},  # Add this
}

Custom Analysis Prompts¶

Modify LAYOUT_CHECKS string to focus on specific concerns for your app.

Integration with CI/CD¶

# Exit with error if critical issues found
python scripts/scan.py https://staging.example.com --output ./qa
if grep -q '"severity": "critical"' ./qa/report.json; then
    echo "Critical responsive issues found!"
    exit 1
fi

Programmatic Usage¶

import asyncio
from scan import scan_page, ScanReport
from playwright.async_api import async_playwright
import anthropic

async def custom_scan():
    client = anthropic.Anthropic()
    async with async_playwright() as p:
        browser = await p.chromium.launch()
        analysis = await scan_page(
            browser, client, 
            "https://example.com", 
            Path("./output")
        )
        # Process analysis.issues programmatically
        for issue in analysis.issues:
            if issue.severity == "critical":
                print(f"CRITICAL: {issue.description}")