# TagCheck

> A checker for HTML pages: finds semantic and accessibility mistakes (missing alt text and labels, empty buttons and links, fake buttons, skipped headings, duplicate ids, references to missing ids) and classes or attributes the Tag family (TagBrush.css, TagAction) doesn't document. With `--browser` it also renders the page to check text contrast in light and dark mode and sideways scrolling on phones. Made for AI agents and CI: write a page, run TagCheck, fix what it reports, repeat until clean.

## Run it

```sh
npx @kovirlabs/tagcheck page.html                 # files or folders
npx @kovirlabs/tagcheck site/ --json              # machine-readable report
npx @kovirlabs/tagcheck page.html --browser       # also contrast and phone overflow (needs Playwright)
```

Exit code 0 means clean, 1 means problems to fix, 2 means bad usage. `--strict` also fails on warnings. `--ignore=rule-a,rule-b` skips rules. `--rules` lists every rule.

## The loop for agents

1. Write the page.
2. Run `npx @kovirlabs/tagcheck page.html --json` (add `--browser` if Playwright is installed).
3. For each problem, fix the HTML at `line` and `column` as the `message` says. Do not silence rules with `--ignore` unless the user asks.
4. Run it again until `errors` is 0.

The JSON report: `{ "tool": "tagcheck", "version": "…", "browser": true, "errors": 2, "warnings": 1, "files": [{ "file": "page.html", "problems": [{ "line": 12, "column": 3, "level": "error", "rule": "missing-alt", "message": "<img src=\"photo.jpg\"> needs alt text (alt=\"\" if it's decorative)" }] }] }`. `browser` says whether the `--browser` checks ran. Browser problems have `line` and `column` set to null. Offline, the TagBrush.css and TagAction CDN files are served from the copies installed next to TagCheck, if any.

## Rules

Errors:

- `missing-lang`: `<html>` needs `lang="en"` (or the page's language).
- `multiple-main`: only one visible `<main>`.
- `missing-alt`: every `<img>` needs `alt`; use `alt=""` for decoration.
- `unlabeled-field`: every input, select, and textarea needs a `<label for>`, a wrapping `<label>`, `aria-label`, or `aria-labelledby` (Disabled task-list checkboxes that Markdown tools such as Jekyll and Hugo generate are not reported.)
- `label-for-missing`: `<label for="x">` needs an element with `id="x"`.
- `empty-button`, `empty-link`: buttons and links need text or `aria-label`.
- `clickable-div`: a `<div>` or `<span>` with `onclick` or `role="button"` should be a `<button>` (or an `<a href>` for navigation).
- `duplicate-id`: ids must be unique. Ids inside a `<template>` don't count; TagAction renumbers copies.
- `broken-reference`: `aria-controls`, `aria-labelledby`, `aria-describedby`, `commandfor`, `popovertarget`, `list`, `form`, and `<output for>` must name ids that exist.
- `unknown-command`: `command` must be a browser command (`show-modal`, `close`, `request-close`, `toggle-popover`, `show-popover`, `hide-popover`) or TagAction's `--clone`.
- `clone-target`: `command="--clone"` must point at a `<template>`.
- `contrast` (`--browser`): text below 4.5:1 against its background in the light or dark scheme.
- `overflow` (`--browser`): the page scrolls sideways at 360px or 1280px wide.

Warnings:

- `not-loaded` (`--browser`): a stylesheet or script didn't load (offline, or a wrong URL), so contrast and phone width were measured without it. Fix the URL, or install `tagbrush` and `tagaction` next to TagCheck to check offline.
- `missing-viewport`: add `<meta name="viewport" content="width=device-width, initial-scale=1">`.
- `heading-skip`: don't jump from `<h2>` to `<h4>`.
- `remember-needs-id`: a `<details>` under `data-tag-remember` needs an `id`.
- `unknown-class`: a class TagBrush.css doesn't style. TagBrush documents only `button`, `secondary`, `outline`, `container`, `grid`, `card`, `striped`, `visually-hidden`, and `tagbrush`. Classes inside `<pre>` and `<code>` (syntax highlighting) are fine, and so are the classes Markdown tools such as Pandoc, Jekyll, and MkDocs generate (`sourceCode`, `footnotes`, `task-list`, `highlight`, `language-…`, `admonition`, …), and so is everything inside GitHub alerts (`markdown-alert`), KaTeX, and MathJax output.
- `unknown-attribute`: a `data-tag…` attribute (or TagBrush's `data-theme`, `data-layout`, `data-tone`, `data-density`, `data-reasoning`) or value that isn't documented. Other `data-*` attributes are the page's own and are not checked.
- `generated-markup`: `data-tag="…"` is added by TagAction while the page runs; it doesn't belong in source HTML.
- `inline-style`, `style-block`: on a page that uses TagBrush.css, CSS other than variables (layout, spacing, colors) usually isn't needed. `text-align` on table cells (column alignment) is fine.

## Use it from code

```js
import { check, checkFiles } from '@kovirlabs/tagcheck';
check('<img src="a.png">');                        // [{ line, column, level, rule, message }, …]
await checkFiles(['site/'], { browser: true });    // the same report as --json
```

## Links

- [The Tag family](https://kovirlabs.github.io/tagstack/llms.txt): how TagBrush.css, TagAction, and TagCheck fit together
- [README](https://github.com/kovirlabs/tagcheck#readme)
- [TagBrush.css](https://github.com/kovirlabs/tagbrush) and [TagAction](https://github.com/kovirlabs/tagaction): the libraries whose vocabulary TagCheck knows