SKILL.md
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.htmlOptions
| 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; }