Visual DOM Auditor

A command-line tool that detects visual layout issues on websites by analyzing the DOM structure using Playwright browser automation.

What This Skill Does

This skill helps you work with a CLI tool that inspects web pages for common visual layout problems including:

**Overlapping elements** - Detects when DOM elements visually overlap each other

**Insufficient padding** - Checks if interactive elements (buttons, links) have adequate clickable area

**Spacing issues** - Validates proper spacing between UI components

The tool uses Playwright to render pages in a real browser and analyze the computed layout properties.

Architecture & Technologies

**Core Stack:**

**TypeScript** - Strongly typed throughout

**Commander.js** - CLI argument parsing

**Playwright** - Browser automation and DOM inspection

**ts-results** - Functional error handling (Result<T, E> pattern)

**Vitest** - Unit testing

**Tsup** - Build tooling

**Code Principles:**

Pure functions for maximum testability

Functional error handling (no try/catch except at boundaries)

Modular design with clear separation of concerns

kebab-case naming, 2-space indentation, double quotes

Project Structure

```

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

```

Step-by-Step Instructions

1. Understanding the CLI Entry Point

When working with `src/index.ts`:

Parse arguments using Commander.js

Validate URL and options

Initialize Playwright browser context

Call the core auditor

Handle results and exit with appropriate codes (0=success, 1=error)

Use `console.error` for errors, `console.log` for success output

2. Building Analyzers

When creating or modifying analyzers in `src/analyzers/`:

Each analyzer should be a pure function that takes DOM elements and returns `Result<Issue[], Error>`

Use Playwright's page locator API to query elements

Use `getBoundingClientRect()` to get computed layout positions

Return structured issue objects with:

- `type`: string identifier (e.g., 'overlap', 'insufficient-padding')

- `element`: CSS selector or description

- `severity`: 'error' | 'warning' | 'info'

- `message`: Human-readable description

- `details`: Additional context

3. Error Handling Pattern

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);

}

```

Never use try/catch except at system boundaries

Chain Result types using `.map()`, `.andThen()`, `.unwrap()`

Provide descriptive error messages

4. DOM Helpers

When working with `src/utils/dom-helpers.ts`:

Create reusable functions for common DOM queries

Use Playwright's locator API for element selection

Return Result types for operations that might fail

Keep functions pure (no side effects)

5. Type Definitions

When adding types to `src/types/`:

Define clear interfaces for all domain concepts

Export types from index.ts

Use discriminated unions for variant types

Document complex types with JSDoc comments

6. Configuration

When working with `src/config/defaults.ts`:

Define sensible defaults for all CLI options

Make thresholds configurable (padding minimums, spacing rules, etc.)

Export as typed constants

7. Testing

When writing tests:

Place test files adjacent to implementation: `{name}.test.ts`

Use Vitest (NOT Jest)

Test pure functions with various inputs

Mock Playwright browser interactions when necessary

Aim for high coverage of business logic

8. Code Style

Follow these conventions:

**Case**: kebab-case for files and functions

**Indentation**: 2 spaces

**Quotes**: Double quotes

**Line length**: Max 100 characters

**Trailing commas**: Yes

**Semicolons**: Yes

**Logging**: Use Pino logger (do NOT use console.log except for final output)

9. Adding New Analyzers

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`

10. CLI Usage

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

```

Constraints

Exit with code 0 on success, 1 on error

Never silence errors

Use descriptive error messages

Prefer pure functions

Use Result types for fallible operations

Place tests adjacent to implementation

Use Vitest for testing (not Jest)

Use Pino for logging (not console.log)

Example Usage

```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);

}

```

Visual DOM Auditor

Visual DOM Auditor

What This Skill Does

Architecture & Technologies

Project Structure

Step-by-Step Instructions

1. Understanding the CLI Entry Point

2. Building Analyzers

3. Error Handling Pattern

4. DOM Helpers

5. Type Definitions

6. Configuration

7. Testing

8. Code Style

9. Adding New Analyzers

10. CLI Usage

Constraints

Example Usage

Reviews (0)