@codelaw/rules-html 0.0.0-stage → 0.2.0

package/rules/html/element-required-ancestor.md

@@ -0,0 +1,45 @@
+---
+id: html/element-required-ancestor
+title: "Elements are inside the ancestor they need"
+languages: [html]
+fix: manual
+fix_reason: "whether to add the ancestor or use other elements depends on the intent"
+stability: preview
+ported_from: [html-validate/element-required-ancestor]
+since: 0.1.0
+---
+
+Elements that only work inside a given ancestor are there: `<area>` in a `<map>`, `<dt>` and `<dd>` in a `<dl>`.
+
+**Why:** Outside it they have no meaning and are rendered as plain text, or not at all.
+
+```codelaw
+native: html/element-required-ancestor
+```
+
+## How to fix
+
+1. Wrap the elements in the ancestor the message names.
+2. Or replace them with elements that make sense where they are.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<div>
+  <dt>Term</dt>
+  <dd>Definition</dd>
+</div>
+```
+
+#### Do
+
+```html
+<dl>
+  <dt>Term</dt>
+  <dd>Definition</dd>
+</dl>
+```

package/rules/html/element-required-attributes.md

@@ -0,0 +1,44 @@
+---
+id: html/element-required-attributes
+title: "Elements have the attributes HTML requires"
+languages: [html]
+fix: manual
+fix_reason: "the value can only come from the author"
+stability: preview
+ported_from: [html-validate/element-required-attributes, htmlhint/html-lang-require]
+since: 0.1.0
+---
+
+Elements have their required attributes: `src` on `<img>`, `lang` on `<html>`, `title` on `<iframe>`, `href` (or `imagesrcset`) on `<link>`, and so on.
+
+**Why:** Without them the element does nothing useful: an `<img>` without `src` shows nothing, and an `<html>` without `lang` makes screen readers guess the language.
+
+```codelaw
+native: html/element-required-attributes
+```
+
+## How to fix
+
+1. Add the attribute the message names, with the right value.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<html>
+  <head><title>Home</title></head>
+  <body><img alt="Logo"></body>
+</html>
+```
+
+#### Do
+
+```html
+<html lang="en">
+  <head><title>Home</title></head>
+  <body><img src="logo.png" alt="Logo"></body>
+</html>
+```

package/rules/html/element-required-content.cases.md

@@ -0,0 +1,23 @@
+# html/element-required-content — cases
+
+### case: an implied head does not count
+
+```html
+<html lang="en">
+  <body></body>
+</html>
+```
+
+```expect
+1:1 html/element-required-content
+```
+
+### case: a fragment head is checked too
+
+```html
+<head></head>
+```
+
+```expect
+1:1 html/element-required-content
+```

package/rules/html/element-required-content.md

@@ -0,0 +1,43 @@
+---
+id: html/element-required-content
+title: "Elements contain the children HTML requires"
+languages: [html]
+fix: manual
+fix_reason: "the content of the missing child needs a human"
+stability: preview
+ported_from: [html-validate/element-required-content, htmlhint/title-require]
+since: 0.1.0
+---
+
+Elements that need a particular child have it: `<html>` has `<head>` and `<body>`, `<head>` has `<title>`, `<details>` has `<summary>`.
+
+**Why:** A page without a `<title>` has no name in tabs, bookmarks and screen readers; a `<details>` without `<summary>` gets a generic label.
+
+```codelaw
+native: html/element-required-content
+```
+
+## How to fix
+
+1. Add the child the message names, with real content.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<head>
+  <meta charset="utf-8">
+</head>
+```
+
+#### Do
+
+```html
+<head>
+  <meta charset="utf-8">
+  <title>Pricing</title>
+</head>
+```

package/rules/html/empty-heading.md

@@ -0,0 +1,40 @@
+---
+id: html/empty-heading
+title: "Headings have text"
+languages: [html]
+fix: manual
+fix_reason: "the heading text needs a human"
+stability: preview
+ported_from: [html-validate/empty-heading]
+tags: [a11y]
+since: 0.1.0
+---
+
+Every `<h1>`–`<h6>` has text, or an image with `alt` text.
+
+**Why:** Screen-reader users navigate by headings; an empty heading is a stop with nothing to announce.
+
+```codelaw
+native: html/empty-heading
+```
+
+## How to fix
+
+1. Give the heading text, or remove it if it only made space (use CSS for that).
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<h2></h2>
+<h2><span hidden>Pricing</span></h2>
+```
+
+#### Do
+
+```html
+<h2>Pricing</h2>
+```

package/rules/html/empty-title.md

@@ -0,0 +1,39 @@
+---
+id: html/empty-title
+title: "<title> has text"
+languages: [html]
+fix: manual
+fix_reason: "the page title needs a human"
+stability: preview
+ported_from: [html-validate/empty-title]
+tags: [a11y]
+since: 0.1.0
+---
+
+The `<title>` element has text.
+
+**Why:** The title names the page in tabs, history, bookmarks, search results and screen readers.
+
+```codelaw
+native: html/empty-title
+```
+
+## How to fix
+
+1. Write a short title that says what the page is.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<title></title>
+```
+
+#### Do
+
+```html
+<title>Pricing — Acme</title>
+```

package/rules/html/fieldset-legend.md

@@ -0,0 +1,44 @@
+---
+id: html/fieldset-legend
+title: "<fieldset> has a legend"
+languages: [html]
+fix: manual
+fix_reason: "the group's name needs a human"
+stability: preview
+ported_from: [html-validate/wcag/h71]
+tags: [a11y]
+since: 0.1.0
+---
+
+A `<fieldset>` has a `<legend>` child.
+
+**Why:** The legend names the group of controls; screen readers announce it with each control in the group.
+
+```codelaw
+native: html/fieldset-legend
+```
+
+## How to fix
+
+1. Add a `<legend>` as the fieldset's first child, naming the group.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<fieldset>
+  <label><input type="radio" name="size" value="s"> Small</label>
+</fieldset>
+```
+
+#### Do
+
+```html
+<fieldset>
+  <legend>Size</legend>
+  <label><input type="radio" name="size" value="s"> Small</label>
+</fieldset>
+```

package/rules/html/form-dup-name.cases.md

@@ -0,0 +1,38 @@
+# html/form-dup-name — cases
+
+### case: array names may repeat
+
+```html
+<form>
+  <input type="text" name="tags[]">
+  <input type="text" name="tags[]">
+</form>
+```
+
+```expect
+(none)
+```
+
+### case: separate forms are separate
+
+```html
+<form><input type="text" name="q"></form>
+<form><input type="text" name="q"></form>
+```
+
+```expect
+(none)
+```
+
+### case: disabled controls are not submitted
+
+```html
+<form>
+  <input type="text" name="q">
+  <input type="text" name="q" disabled>
+</form>
+```
+
+```expect
+(none)
+```

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

@@ -0,0 +1,48 @@
+---
+id: html/form-dup-name
+title: "Form controls have unique names"
+languages: [html]
+fix: manual
+fix_reason: "renaming a control changes what the server receives"
+stability: preview
+options:
+  allowArrayBrackets: { type: "boolean", default: true, description: "let `name[]` repeat" }
+  allowCheckboxDefault: { type: "boolean", default: true, description: "allow a hidden input before a checkbox of the same name" }
+  shared: { type: "string[]", default: ["radio", "button", "reset", "submit"], description: "control types that may share a name" }
+ported_from: [html-validate/form-dup-name]
+since: 0.1.0
+---
+
+Within a form, no two controls share a `name`, except radio buttons of one group, buttons, and a hidden default before a checkbox. A `name[]` array name is not mixed with the plain `name`.
+
+**Why:** The server receives both values under one name and usually keeps only one of them.
+
+```codelaw
+native: html/form-dup-name
+```
+
+## How to fix
+
+1. Give each control its own name, and update the code that reads the form.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<form>
+  <input type="text" name="email">
+  <input type="email" name="email">
+</form>
+```
+
+#### Do
+
+```html
+<form>
+  <input type="text" name="name">
+  <input type="email" name="email">
+</form>
+```

package/rules/html/form-submit.md

@@ -0,0 +1,44 @@
+---
+id: html/form-submit
+title: "Forms have a submit button"
+languages: [html]
+fix: manual
+fix_reason: "the button's label and placement need a human"
+stability: preview
+ported_from: [html-validate/wcag/h32]
+tags: [a11y]
+since: 0.1.0
+---
+
+A `<form>` has a submit button, inside it or associated with it by `form=`.
+
+**Why:** Without one there is no visible way to send the form; Enter-to-submit isn't obvious and doesn't work everywhere.
+
+```codelaw
+native: html/form-submit
+```
+
+## How to fix
+
+1. Add a `<button type="submit">` with a label that says what it does.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<form action="/search">
+  <input type="search" name="q" aria-label="Search">
+</form>
+```
+
+#### Do
+
+```html
+<form action="/search">
+  <input type="search" name="q" aria-label="Search">
+  <button type="submit">Search</button>
+</form>
+```

package/rules/html/heading-level.cases.md

@@ -0,0 +1,26 @@
+# html/heading-level — cases
+
+### case: a dialog starts its own outline
+
+```html
+<h1>Page</h1>
+<h2>Part</h2>
+<dialog><h2>Confirm</h2><h3>Details</h3></dialog>
+```
+
+```expect
+(none)
+```
+
+### case: going back up any number of levels is fine
+
+```html
+<h1>a</h1>
+<h2>b</h2>
+<h3>c</h3>
+<h2>d</h2>
+```
+
+```expect
+(none)
+```

package/rules/html/heading-level.md

@@ -0,0 +1,44 @@
+---
+id: html/heading-level
+title: "Headings start at <h1> and go down one level at a time"
+languages: [html]
+fix: manual
+fix_reason: "changing a heading level changes its style and the outline"
+stability: preview
+options:
+  allowMultipleH1: { type: "boolean", default: false, description: "allow more than one `<h1>`" }
+  minInitialRank: { type: "string", default: "h1", description: "the lowest level the first heading may have (`h1`–`h6`, or `any`)" }
+  sectioningRoots: { type: "string[]", default: ["dialog", "[role=\"dialog\"]", "[role=\"alertdialog\"]"], description: "selectors of elements that start their own outline" }
+ported_from: [html-validate/heading-level]
+since: 0.1.0
+---
+
+The first heading is `<h1>`, there is one `<h1>`, and each heading is at most one level below the one before it. A `<dialog>` starts its own outline.
+
+**Why:** Screen-reader users navigate the heading outline; a skipped level looks like missing content.
+
+```codelaw
+native: html/heading-level
+```
+
+## How to fix
+
+1. Change the heading to the level the message expects, and restyle it with CSS if it looked right before.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<h1>Guide</h1>
+<h3>Install</h3>
+```
+
+#### Do
+
+```html
+<h1>Guide</h1>
+<h2>Install</h2>
+```

package/rules/html/hidden-focusable.cases.md

@@ -0,0 +1,23 @@
+# html/hidden-focusable — cases
+
+### case: a disabled button can not take focus
+
+```html
+<button type="button" aria-hidden="true" disabled>x</button>
+```
+
+```expect
+(none)
+```
+
+### case: hidden by an ancestor
+
+```html
+<div aria-hidden="true">
+  <a href="/a">a</a>
+</div>
+```
+
+```expect
+2:3 html/hidden-focusable
+```

package/rules/html/hidden-focusable.md

@@ -0,0 +1,40 @@
+---
+id: html/hidden-focusable
+title: "Focusable elements are not aria-hidden"
+languages: [html]
+fix: manual
+fix_reason: "whether to unhide it, take it out of the tab order or remove it depends on the design"
+stability: preview
+ported_from: [html-validate/hidden-focusable]
+tags: [a11y]
+since: 0.1.0
+---
+
+An element keyboard focus can reach — a link, a form control, anything with `tabindex="0"` — is not `aria-hidden`, itself or through an ancestor.
+
+**Why:** Keyboard users land on it while screen readers say nothing, so blind keyboard users reach a silent stop.
+
+```codelaw
+native: html/hidden-focusable
+```
+
+## How to fix
+
+1. Remove `aria-hidden` if the element should be announced.
+2. Otherwise take it out of the tab order with `tabindex="-1"`, or hide it from everyone with `hidden` or `inert`.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<a href="/home" aria-hidden="true">Home</a>
+```
+
+#### Do
+
+```html
+<a href="/home" aria-hidden="true" tabindex="-1">Home</a>
+```

package/rules/html/img-alt.cases.md

@@ -0,0 +1,22 @@
+# html/img-alt — cases
+
+### case: a hidden image is not announced
+
+```html
+<img src="a.png" hidden>
+<div aria-hidden="true"><img src="b.png"></div>
+```
+
+```expect
+(none)
+```
+
+### case: an empty alt marks a decorative image
+
+```html
+<img src="a.png" alt="">
+```
+
+```expect
+(none)
+```

package/rules/html/img-alt.md

@@ -0,0 +1,44 @@
+---
+id: html/img-alt
+title: "<img> has alt text"
+languages: [html]
+fix: manual
+fix_reason: "only a human can describe the image, or decide it is decorative"
+stability: preview
+options:
+  allowEmpty: { type: "boolean", default: true, description: "accept `alt=\"\"` for decorative images" }
+  alias: { type: "string[]", default: [], description: "other attributes that count as alt text, such as a framework binding" }
+ported_from: [html-validate/wcag/h37, htmlhint/alt-require]
+tags: [a11y]
+since: 0.1.0
+---
+
+Every `<img>` has an `alt` attribute: a description, or `alt=""` for a purely decorative image.
+
+**Why:** Screen readers read the file name of an image without `alt`; `alt` is also shown when the image fails to load.
+
+```codelaw
+native: html/img-alt
+```
+
+## How to fix
+
+1. Describe what the image shows, or what it is for, in `alt`.
+2. If the image is decorative, write `alt=""`.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<img src="team.jpg">
+```
+
+#### Do
+
+```html
+<img src="team.jpg" alt="The team at the 2024 offsite">
+<img src="divider.png" alt="">
+```

package/rules/html/img-title.md

@@ -0,0 +1,40 @@
+---
+id: html/img-title
+title: "Decorative images have no title"
+languages: [html]
+fix: manual
+fix_reason: "whether the image is decorative or informative is the author's call"
+stability: preview
+ported_from: [html-validate/wcag/h67]
+tags: [a11y]
+since: 0.1.0
+---
+
+An `<img>` with empty `alt` has no `title`.
+
+**Why:** `alt=""` marks the image as decorative, while a `title` suggests it carries information; screen readers handle the mix inconsistently.
+
+```codelaw
+native: html/img-title
+```
+
+## How to fix
+
+1. If the image carries information, move the text from `title` to `alt`.
+2. If it is decorative, remove the `title`.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<img src="logo.png" alt="" title="Acme">
+```
+
+#### Do
+
+```html
+<img src="logo.png" alt="Acme">
+```

package/rules/html/input-attributes.md

@@ -0,0 +1,34 @@
+---
+id: html/input-attributes
+title: "Input attributes fit the input type"
+languages: [html]
+fix: suggest
+fix_reason: "scripts or attribute selectors may still read the attribute"
+stability: preview
+ported_from: [html-validate/input-attributes]
+since: 0.1.0
+---
+
+An `<input>` has only attributes its `type` uses: no `accept` on a text field, no `placeholder` on a checkbox, no `min` on an email field.
+
+**Why:** The browser ignores them, so they mislead readers about how the field behaves.
+
+```codelaw
+native: html/input-attributes
+```
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<input type="text" name="photo" accept="image/png">
+```
+
+#### Do
+
+```html
+<input type="text" name="photo">
+```