# Validate PDF-to-HTML Visual Accuracy

PDF-to-HTML conversions can look correct in markup while losing layout, hierarchy, or spacing. This skill guides Claude, Codex, or Claude Code through screenshot-based visual review with scored pass/fail output.

## Install

```bash
npx skillstore add abejitsu/ai-visual-accuracy-check
```

## Metadata

- - Slug: abejitsu-ai-visual-accuracy-check
- - Version: 1.0.0
- - Author: AbeJitsu
- - GitHub username: AbeJitsu
- - License: MIT
- - Repository: https://github.com/AbeJitsu/Game-Settings-Panel/tree/main/.claude/skills/calypso/ai-visual-accuracy-check
- - Ref: main
- - Supported tools: Claude, Codex, Claude Code
- - Risk level: medium
- - Risk factors: network, filesystem, external\_commands
- - Quality score: 50
- - Quality tier: warning
- - Public page: https://skillstore.pages.dev/skills/abejitsu-ai-visual-accuracy-check
- - Manifest: https://skillstore.pages.dev/api/skills/abejitsu-ai-visual-accuracy-check/manifest

## Capabilities

- Defines inputs for generated HTML, original PDF page images, output directory, chapter metadata, and score threshold.
- Guides rendering of HTML into a screenshot with a headless browser such as Playwright or Selenium.
- Provides a detailed visual comparison prompt for Claude with weighted layout, hierarchy, positioning, and typography criteria.
- Specifies a structured report with scores, differences, confidence, explanation, and recommendation.
- Defines a blocking quality gate where scores below 85 stop the pipeline.
- Supports multi-page chapter review through key-page comparison and averaged scoring.

## Use Cases

- Check converted textbook chapters: Compare generated chapter HTML against source PDF page images before release.
- Gate document conversion pipelines: Add a score threshold that blocks deployment when visual fidelity falls below the expected level.
- Review layout regressions: Use scored visual feedback to identify spacing, hierarchy, or positioning changes after CSS updates.

## Prompt Templates

### Run a single-page check

```
Use ai-visual-accuracy-check to compare chapter_02.html with 02_page_16.png. Use the default 85 threshold and summarize the pass or fail result.
```

### Review a chapter sample

```
Use ai-visual-accuracy-check on the opening, middle, and final pages for chapter 4. Average the page scores and list the main visual differences.
```

### Investigate a failed gate

```
Use ai-visual-accuracy-check to explain why the latest chapter failed the 85 visual threshold. Prioritize layout, hierarchy, positioning, and typography fixes.
```

### Compare conversion variants

```
Use ai-visual-accuracy-check to compare two rendered HTML versions against the same PDF page. Recommend the version with stronger visual fidelity and explain the tradeoffs.
```

## Limitations

- The skill is procedural documentation and does not include an executable implementation.
- Visual scoring depends on the AI model and may vary between runs.
- Sensitive PDF pages or screenshots may be sent to an external AI service during review.
- It focuses on visual fidelity and does not verify semantic HTML quality or accessibility compliance.

## Best Practices

- Use non-confidential samples unless your AI service policy allows document image sharing.
- Keep the default 85 threshold until you have project-specific calibration data.
- Store original PDF images and rendered screenshots with stable names for repeatable review.

## Anti Patterns

- Do not treat the AI score as a replacement for accessibility or content correctness checks.
- Do not lower the threshold to pass known layout defects without documenting the reason.
- Do not render untrusted HTML outside a sandboxed browser environment.

## Security Audit

- - Safe to publish: true
- - Audited at: 2026-06-28T04:03:38.317\+00:00
- - Summary: The static analyzer's Ruby backtick, weak cryptography, and system reconnaissance findings are false positives caused by Markdown code fences, filenames, and ordinary prose. The skill still has medium operational risk because its intended workflow reads local HTML and image files, renders screenshots with a headless browser, and sends visual content to Claude for analysis.

## Stats

- - Views: 255
- - Downloads: 5
- - Favorites: 0
- - Popularity score: 0