@codelaw/rules-html 0.0.0-stage → 0.2.0

package/rules/html/input-image-alt.md

@@ -0,0 +1,39 @@
+---
+id: html/input-image-alt
+title: "Image buttons have alt text"
+languages: [html]
+fix: manual
+fix_reason: "the text needs a human"
+stability: preview
+ported_from: [html-validate/wcag/h36]
+tags: [a11y]
+since: 0.1.0
+---
+
+An `<input type="image">` has non-empty `alt` text.
+
+**Why:** The `alt` is the button's only name for screen readers and when the image doesn't load.
+
+```codelaw
+native: html/input-image-alt
+```
+
+## How to fix
+
+1. Add `alt` saying what the button does.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<input type="image" src="go.png">
+```
+
+#### Do
+
+```html
+<input type="image" src="go.png" alt="Search">
+```

package/rules/html/input-missing-label.md

@@ -0,0 +1,40 @@
+---
+id: html/input-missing-label
+title: "Form controls have a label"
+languages: [html]
+fix: manual
+fix_reason: "the label text needs a human"
+stability: preview
+ported_from: [html-validate/input-missing-label, htmlhint/input-requires-label]
+since: 0.1.0
+---
+
+Every visible `<input>`, `<select>` and `<textarea>` has a label: a `<label for>`, a wrapping `<label>`, `aria-label` or `aria-labelledby`, with text.
+
+**Why:** Without a label, screen readers announce the control as "edit text" with no hint of what to enter.
+
+```codelaw
+native: html/input-missing-label
+```
+
+## How to fix
+
+1. Add a `<label for>` with text, or wrap the control in a `<label>`.
+2. If a visible label is impossible, add `aria-label`.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<input type="text" name="q">
+```
+
+#### Do
+
+```html
+<label for="q">Search</label>
+<input type="text" id="q" name="q">
+```

package/rules/html/link-text.md

@@ -0,0 +1,39 @@
+---
+id: html/link-text
+title: "Links have text"
+languages: [html]
+fix: manual
+fix_reason: "the link text needs a human"
+stability: preview
+ported_from: [html-validate/wcag/h30]
+tags: [a11y]
+since: 0.1.0
+---
+
+A link with `href` has text that says where it goes: content, an image with `alt`, or `aria-label`.
+
+**Why:** Screen readers announce a link by its text; without it the user hears only "link".
+
+```codelaw
+native: html/link-text
+```
+
+## How to fix
+
+1. Give the link text, an image with `alt`, or an `aria-label`.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<a href="/cart"><img src="cart.png" alt=""></a>
+```
+
+#### Do
+
+```html
+<a href="/cart"><img src="cart.png" alt="Cart"></a>
+```

package/rules/html/long-title.md

@@ -0,0 +1,40 @@
+---
+id: html/long-title
+title: "Page titles are short"
+languages: [html]
+fix: manual
+fix_reason: "shortening a title needs a human"
+stability: preview
+options:
+  maxlength: { type: "integer", default: 70, description: "the longest title allowed, in characters" }
+ported_from: [html-validate/long-title]
+since: 0.1.0
+---
+
+The `<title>` text is at most 70 characters.
+
+**Why:** Search results and browser tabs cut long titles, often before the words that matter.
+
+```codelaw
+native: html/long-title
+```
+
+## How to fix
+
+1. Shorten the title to what identifies the page.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<title>Acme Corporation — Products, Services, Pricing, Support, Downloads and Contact Details</title>
+```
+
+#### Do
+
+```html
+<title>Pricing — Acme</title>
+```

package/rules/html/map-dup-name.md

@@ -0,0 +1,40 @@
+---
+id: html/map-dup-name
+title: "Image maps have unique names"
+languages: [html]
+fix: manual
+fix_reason: "renaming a map means updating the `usemap` that points at it"
+stability: preview
+ported_from: [html-validate/map-dup-name]
+since: 0.1.0
+---
+
+No two `<map>` elements share a `name`.
+
+**Why:** An image's `usemap` picks one by name, so the other map is unreachable.
+
+```codelaw
+native: html/map-dup-name
+```
+
+## How to fix
+
+1. Rename one map and the `usemap` attributes that refer to it.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<map name="nav"></map>
+<map name="nav"></map>
+```
+
+#### Do
+
+```html
+<map name="nav"></map>
+<map name="footer-nav"></map>
+```

package/rules/html/map-id-name.md

@@ -0,0 +1,38 @@
+---
+id: html/map-id-name
+title: "A map's id and name match"
+languages: [html]
+fix: manual
+fix_reason: "which of the two names is right depends on what refers to the map"
+stability: preview
+ported_from: [html-validate/map-id-name]
+since: 0.1.0
+---
+
+When a `<map>` has both `id` and `name`, they are the same.
+
+**Why:** HTML requires them to match; tools that look maps up by `id` and browsers that use `name` would find different maps.
+
+```codelaw
+native: html/map-id-name
+```
+
+## How to fix
+
+1. Make `id` and `name` equal, and update references to the one you changed.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<map id="nav" name="menu"></map>
+```
+
+#### Do
+
+```html
+<map id="nav" name="nav"></map>
+```

package/rules/html/meta-refresh.md

@@ -0,0 +1,42 @@
+---
+id: html/meta-refresh
+title: "Meta refresh redirects at once"
+languages: [html]
+fix: manual
+fix_reason: "redirecting at once or removing the refresh changes the page's behaviour"
+stability: preview
+options:
+  allowLongDelay: { type: "boolean", default: false, description: "allow delays over 20 hours (72,000 seconds)" }
+ported_from: [html-validate/meta-refresh]
+tags: [a11y]
+since: 0.1.0
+---
+
+A `<meta http-equiv="refresh">` redirects immediately (`0;url=…`); it doesn't wait, and doesn't reload the page.
+
+**Why:** A timed refresh moves on before slower readers and screen-reader users have finished; a reload without a URL repeats forever.
+
+```codelaw
+native: html/meta-refresh
+```
+
+## How to fix
+
+1. Make the refresh instant with `0;url=…`.
+2. Or replace it with a link the user follows when ready.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<meta http-equiv="refresh" content="5;url=/next">
+```
+
+#### Do
+
+```html
+<meta http-equiv="refresh" content="0;url=/next">
+```

package/rules/html/missing-doctype.cases.md

@@ -0,0 +1,24 @@
+# html/missing-doctype — cases
+
+### case: a fragment is not a document
+
+```html
+<div>
+  <p>Partial</p>
+</div>
+```
+
+```expect
+(none)
+```
+
+### case: a malformed doctype still counts
+
+```html
+<!DOCTYPE>
+<html lang="en"></html>
+```
+
+```expect
+(none)
+```

package/rules/html/missing-doctype.md

@@ -0,0 +1,43 @@
+---
+id: html/missing-doctype
+title: "The document has a doctype"
+languages: [html]
+fix: suggest
+fix_reason: "leaving quirks mode can change the page's layout"
+stability: preview
+ported_from: [html-validate/missing-doctype]
+since: 0.1.0
+---
+
+A document starts with `<!DOCTYPE html>`.
+
+**Why:** Without it browsers render in quirks mode, which lays the page out differently from the standard.
+
+```codelaw
+native: html/missing-doctype
+```
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<html lang="en">
+  <title>Home</title>
+</html>
+```
+
+#### Do
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <title>Home</title>
+</html>
+```
+
+## Differences from the source
+
+Only files with an `<html>` element are checked: a fragment or template partial is not a document, and gets no doctype of its own.

package/rules/html/multiple-labeled-controls.md

@@ -0,0 +1,40 @@
+---
+id: html/multiple-labeled-controls
+title: "A label labels one control"
+languages: [html]
+fix: manual
+fix_reason: "each control needs its own label text"
+stability: preview
+ported_from: [html-validate/multiple-labeled-controls]
+tags: [a11y]
+since: 0.1.0
+---
+
+A `<label>` is associated with at most one control, by nesting or by `for`.
+
+**Why:** A label names one control; assistive technology announces the others without the right name.
+
+```codelaw
+native: html/multiple-labeled-controls
+```
+
+## How to fix
+
+1. Give each control its own `<label>`.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<label>Name <input type="text" name="first"> <input type="text" name="last"></label>
+```
+
+#### Do
+
+```html
+<label>First name <input type="text" name="first"></label>
+<label>Last name <input type="text" name="last"></label>
+```

package/rules/html/no-abstract-role.md

@@ -0,0 +1,39 @@
+---
+id: html/no-abstract-role
+title: "No abstract ARIA roles"
+languages: [html]
+fix: manual
+fix_reason: "the concrete role depends on what the element is"
+stability: preview
+ported_from: [html-validate/no-abstract-role]
+tags: [a11y]
+since: 0.1.0
+---
+
+`role` does not name one of ARIA's abstract roles (`widget`, `input`, `landmark`, `section`, `command`, …).
+
+**Why:** Abstract roles only organise the ARIA specification; browsers don't map them, so the element gets no role at all.
+
+```codelaw
+native: html/no-abstract-role
+```
+
+## How to fix
+
+1. Use the concrete role that describes the element, or a native element.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<div role="landmark">News</div>
+```
+
+#### Do
+
+```html
+<div role="region" aria-label="News">News</div>
+```

package/rules/html/no-autoplay.md

@@ -0,0 +1,37 @@
+---
+id: html/no-autoplay
+title: "Media does not play by itself"
+languages: [html]
+fix: suggest
+fix_reason: "the media no longer starts on load"
+stability: preview
+options:
+  include: { type: "string[]", default: ["audio", "video"], description: "elements on which `autoplay` is reported" }
+ported_from: [html-validate/no-autoplay]
+tags: [a11y]
+since: 0.1.0
+---
+
+`<audio>` and `<video>` don't have `autoplay`.
+
+**Why:** Sound that starts by itself talks over screen readers and startles users; WCAG asks that users control playback.
+
+```codelaw
+native: html/no-autoplay
+```
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<video src="intro.mp4" autoplay controls></video>
+```
+
+#### Do
+
+```html
+<video src="intro.mp4" controls></video>
+```

package/rules/html/no-conditional-comment.md

@@ -0,0 +1,39 @@
+---
+id: html/no-conditional-comment
+title: "No Internet Explorer conditional comments"
+languages: [html]
+fix: manual
+fix_reason: "whether the markup inside is still needed is the author's call"
+stability: preview
+ported_from: [html-validate/no-conditional-comment]
+since: 0.1.0
+---
+
+The document has no conditional comments (`<!--[if IE]>…<![endif]-->`).
+
+**Why:** Only Internet Explorer 9 and older read them; every current browser treats them as comments, so the markup inside is dead.
+
+```codelaw
+native: html/no-conditional-comment
+```
+
+## How to fix
+
+1. Delete the conditional comment, or move markup that is still needed out of it.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<!--[if lt IE 9]><script src="html5shiv.js"></script><![endif]-->
+<p>Hello</p>
+```
+
+#### Do
+
+```html
+<p>Hello</p>
+```

package/rules/html/no-deprecated-attr.md

@@ -0,0 +1,39 @@
+---
+id: html/no-deprecated-attr
+title: "No obsolete attributes"
+languages: [html]
+fix: manual
+fix_reason: "the replacement is usually CSS, which needs a class and a rule"
+stability: preview
+ported_from: [html-validate/no-deprecated-attr]
+since: 0.1.0
+---
+
+Elements don't use attributes HTML has made obsolete, such as `align`, `bgcolor`, `border` on `<img>`, or `name` on `<a>`.
+
+**Why:** Browsers support them unevenly; CSS and current attributes do the same job reliably.
+
+```codelaw
+native: html/no-deprecated-attr
+```
+
+## How to fix
+
+1. Replace presentational attributes with a class and CSS.
+2. Replace other obsolete attributes with their current equivalent (for example `id` for `<a name>`).
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<img src="a.png" alt="Chart" align="left">
+```
+
+#### Do
+
+```html
+<img src="a.png" alt="Chart" class="float-left">
+```

package/rules/html/no-dup-attr.md

@@ -0,0 +1,37 @@
+---
+id: html/no-dup-attr
+title: "No attribute written twice"
+languages: [html]
+fix: auto
+stability: preview
+ported_from: [html-validate/no-dup-attr, htmlhint/attr-no-duplication]
+since: 0.1.0
+---
+
+An element does not have the same attribute twice (names compare without case).
+
+**Why:** Browsers keep the first one and silently drop the rest, which is rarely what the author meant.
+
+```codelaw
+native: html/no-dup-attr
+```
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<input type="text" name="q" name="search">
+```
+
+#### Do
+
+```html
+<input type="text" name="q">
+```
+
+## Differences from the source
+
+The fix removes the later copies, keeping what browsers already use. Check that the first value is the one you meant.

package/rules/html/no-dup-class.md

@@ -0,0 +1,33 @@
+---
+id: html/no-dup-class
+title: "No class listed twice"
+languages: [html]
+fix: auto
+stability: preview
+ported_from: [html-validate/no-dup-class]
+since: 0.1.0
+---
+
+A `class` attribute lists each class once.
+
+**Why:** The repeat does nothing, and suggests a merge went wrong.
+
+```codelaw
+native: html/no-dup-class
+```
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<p class="lead lead">Text</p>
+```
+
+#### Do
+
+```html
+<p class="lead">Text</p>
+```

package/rules/html/no-duplicate-id.cases.md

@@ -0,0 +1,23 @@
+# html/no-duplicate-id — cases
+
+### case: ids in separate templates do not clash
+
+```html
+<template><p id="a"></p></template>
+<template><p id="a"></p></template>
+```
+
+```expect
+(none)
+```
+
+### case: template code is not compared
+
+```html
+<p id="{{ id }}"></p>
+<p id="{{ id }}"></p>
+```
+
+```expect
+(none)
+```

package/rules/html/no-duplicate-id.md

@@ -0,0 +1,42 @@
+---
+id: html/no-duplicate-id
+title: "Ids are unique in the document"
+languages: [html]
+fix: manual
+fix_reason: "renaming an id breaks the CSS, scripts and links that use it"
+stability: preview
+ported_from: [html-validate/no-dup-id, htmlhint/id-unique]
+tags: [a11y]
+since: 0.1.0
+---
+
+No two elements in the document have the same `id`. Ids inside a `<template>` only need to be unique within it.
+
+**Why:** `getElementById`, `label for`, `aria-labelledby` and fragment links all find the first element with the id and miss the others.
+
+```codelaw
+native: html/no-duplicate-id
+```
+
+## How to fix
+
+1. Decide which element keeps the id.
+2. Rename the other one, and update the CSS, scripts, `for`, `aria-*` and links that refer to it.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<h2 id="intro">Intro</h2>
+<p id="intro">Text</p>
+```
+
+#### Do
+
+```html
+<h2 id="intro">Intro</h2>
+<p id="intro-text">Text</p>
+```