html-lint-runner
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".
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 provides developers with a powerful solution to audit HTML for WCAG 2.1 AA accessibility violations and semantic standards. This skill helps ensure web content is inclusive, SEO-friendly, and technically sound by identifying critical issues such as low color contrast, missing alt text, and invalid markup structures.
Use Cases
- Automated Accessibility Auditing: Conduct deep scans of web pages to ensure compliance with WCAG 2.1 AA standards, identifying issues like insufficient color contrast, missing ARIA labels, and keyboard navigation hurdles.
- HTML Standards Validation: Use markuplint to verify HTML semantics and structure, catching unclosed tags, missing required attributes, and deprecated elements to improve browser compatibility and SEO.
- Pre-deployment Quality Checks: Run automated audits during the development phase to catch and fix high-priority accessibility and markup errors before they reach production.
- Component-Level Analysis: Analyze .jsx and .tsx files using markuplint to maintain high code quality and semantic integrity in modern frontend frameworks like React and Next.js.
| name | html-lint-runner |
|---|---|
| description | 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". |
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
- Run combined lint - Check both accessibility and HTML standards
- Parse JSON results - Identify issues by severity
- Prioritize issues - critical > serious > error > warning
- Apply fixes - Address high-priority issues first
- 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; }