CLI tool for detecting visual layout issues on websites by analyzing the DOM structure using Playwright browser automation
A command-line tool that detects visual layout issues on websites by analyzing the DOM structure using Playwright browser automation.
This skill helps you work with a CLI tool that inspects web pages for common visual layout problems including:
The tool uses Playwright to render pages in a real browser and analyze the computed layout properties.
**Core Stack:**
**Code Principles:**
```
src/
index.ts # CLI entry point (#!/usr/bin/env node)
auditor.ts # Core DOM auditing engine
analyzers/ # Specialized analyzers
overlap.ts # Overlapping element detection
padding.ts # Button padding validation
spacing.ts # Element spacing checks
types/ # TypeScript definitions
index.ts
options.ts
errors.ts
issues.ts # Issue type definitions
utils/ # Utilities
viewport.ts
error.ts
validator.ts
dom-helpers.ts # DOM traversal helpers
config/ # Configuration
defaults.ts
```
When working with `src/index.ts`:
When creating or modifying analyzers in `src/analyzers/`:
- `type`: string identifier (e.g., 'overlap', 'insufficient-padding')
- `element`: CSS selector or description
- `severity`: 'error' | 'warning' | 'info'
- `message`: Human-readable description
- `details`: Additional context
Always use ts-results for fallible operations:
```typescript
import { Result, Ok, Err } from 'ts-results';
function analyzeElement(): Result<Issue[], DOMError> {
if (someCondition) {
return Err(new DOMError('Failed to analyze'));
}
return Ok(issues);
}
```
When working with `src/utils/dom-helpers.ts`:
When adding types to `src/types/`:
When working with `src/config/defaults.ts`:
When writing tests:
Follow these conventions:
To add a new layout analyzer:
1. Create `src/analyzers/{analyzer-name}.ts`
2. Export a function with signature: `(page: Page, options: Options) => Promise<Result<Issue[], Error>>`
3. Query relevant DOM elements using Playwright locators
4. Analyze layout properties (bounding boxes, computed styles, etc.)
5. Return array of Issue objects for problems found
6. Add tests in `src/analyzers/{analyzer-name}.test.ts`
7. Register analyzer in `src/auditor.ts`
The tool should support:
```bash
visual-dom-auditor <url> [options]
Options:
--viewport <size> Viewport size (e.g., 1920x1080)
--device <name> Emulate device (e.g., iPhone 12)
--output <format> Output format (json, text, html)
--selectors <list> CSS selectors to analyze
--exclude <list> Selectors to exclude
```
```typescript
// Analyzer example
export async function detectOverlap(
page: Page,
options: AuditorOptions
): Promise<Result<Issue[], DOMError>> {
const elements = await page.locator(options.selectors || '*').all();
const issues: Issue[] = [];
for (let i = 0; i < elements.length; i++) {
for (let j = i + 1; j < elements.length; j++) {
const box1 = await elements[i].boundingBox();
const box2 = await elements[j].boundingBox();
if (box1 && box2 && boxesOverlap(box1, box2)) {
issues.push({
type: 'overlap',
element: await elements[i].evaluate(el => el.tagName),
severity: 'warning',
message: 'Elements overlap',
details: { box1, box2 }
});
}
}
}
return Ok(issues);
}
```
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/visual-dom-auditor/raw