html-lint-runner

naporin0624's avatarfrom naporin0624

Runs automated HTML linting using @axe-core/playwright (WCAG accessibility) and markuplint (HTML standards). Use when user asks to "lint HTML", "run automated checks", "validate HTML", "check accessibility", or mentions "axe-core", "markuplint", "automated audit".

⭐0stars🔀0forks📁View on GitHub🕐Updated Dec 26, 2025
[Testing and QA]

When & Why to Use This Skill

The HTML Lint Runner is a comprehensive Claude skill designed for automated web quality assurance and accessibility compliance. By integrating industry-standard tools like @axe-core/playwright and markuplint, it allows developers to perform deep audits of HTML files and JSX/TSX components. This skill focuses on identifying WCAG 2.1 AA accessibility violations and enforcing HTML semantic standards, providing structured feedback to ensure web projects are inclusive, bug-free, and SEO-friendly.

Use Cases

  • Automated Accessibility Auditing: Use axe-core to detect WCAG 2.1 AA violations such as insufficient color contrast, missing alt text, and improper ARIA roles to ensure web content is accessible to all users.
  • HTML Semantic Validation: Run markuplint to identify non-standard attributes, deprecated tags, and structural errors in .html, .jsx, or .tsx files to maintain high code quality.
  • Issue Prioritization and Debugging: Leverage the structured JSON output to categorize issues by impact levels (critical, serious, moderate, minor), allowing teams to focus on fixing the most damaging bugs first.
  • Pre-deployment Quality Checks: Integrate automated linting into the development workflow to catch markup errors and accessibility gaps before code is merged or deployed to production.
namehtml-lint-runner
descriptionRuns automated HTML linting using @axe-core/playwright (WCAG accessibility) and markuplint (HTML standards). Use when user asks to "lint HTML", "run automated checks", "validate HTML", "check accessibility", or mentions "axe-core", "markuplint", "automated audit".

HTML Lint Runner

Automated HTML linting using @axe-core/playwright and markuplint with JSON output.

Tools Overview

Tool Focus Output
@axe-core/playwright WCAG 2.1 AA accessibility JSON with violations
markuplint HTML standards, semantics JSON with problems

Quick Start

# Install dependencies
cd ${CLAUDE_PLUGIN_ROOT}/skills/html-lint-runner && npm install

# Run combined lint (development)
npm --prefix ${CLAUDE_PLUGIN_ROOT}/skills/html-lint-runner run dev -- path/to/file.html

# Run with build
npm --prefix ${CLAUDE_PLUGIN_ROOT}/skills/html-lint-runner run build
node ${CLAUDE_PLUGIN_ROOT}/skills/html-lint-runner/dist/index.js path/to/file.html

Options

Option Description
--json Output as JSON (default)
--text Output as human-readable text
--axe-only Run only axe-core (accessibility)
--markuplint-only Run only markuplint (HTML standards)

Supported File Types

Extension axe-core markuplint Notes
.html Yes Yes Full support
.htm Yes Yes Full support
.jsx No* Yes markuplint only
.tsx No* Yes markuplint only

*JSX/TSX require rendering to HTML for axe-core analysis

Output Structure

{
  "file": "target.html",
  "timestamp": "2025-01-01T00:00:00Z",
  "axe": {
    "violations": [...],
    "passes": [...],
    "incomplete": [...]
  },
  "markuplint": {
    "problems": [...]
  },
  "summary": {
    "axe_violations": 3,
    "markuplint_problems": 5,
    "total_issues": 8
  }
}

axe-core Violations

{
  "id": "color-contrast",
  "impact": "serious",
  "description": "Elements must have sufficient color contrast",
  "nodes": [
    {
      "html": "<p class=\"light\">...</p>",
      "failureSummary": "Fix: Increase contrast ratio to 4.5:1"
    }
  ]
}

Impact levels: critical > serious > moderate > minor

markuplint Problems

{
  "severity": "error",
  "ruleId": "required-attr",
  "message": "The \"alt\" attribute is required",
  "line": 15,
  "col": 5,
  "raw": "<img src=\"photo.jpg\">"
}

Workflow

  1. Run combined lint - Check both accessibility and HTML standards
  2. Parse JSON results - Identify issues by severity
  3. Prioritize issues - critical > serious > error > warning
  4. Apply fixes - Address high-priority issues first
  5. Re-run to verify - Confirm fixes resolved issues

Common Fixes

Missing alt text

<!-- Before -->
<img src="photo.jpg">

<!-- After -->
<img src="photo.jpg" alt="Description of image">

Low contrast

/* Before: #999 on #fff = 2.85:1 */
.text { color: #999; }

/* After: #595959 on #fff = 7:1 */
.text { color: #595959; }

References