ZemDomu

https://zemdomu.dev/docs
Admin
ZemDomu is a semantic accessibility static analysis tool that detects structural and markup issues...
Tokens:22,589
Snippets:445
Trust Score:2
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install and run ZemDomu CLI

Source: https://zemdomu.dev/docs/installation/cli

Install ZemDomu as a development dependency and execute it against HTML, JSX, TSX, and Vue files.

```bash
npm install --save-dev zemdomu
npx zemdomu "**/*.{html,jsx,tsx,vue}"
```

--------------------------------

### Good example: <li> nested inside <ul>

Source: https://zemdomu.dev/docs/enforceListNesting

Shows the correct structure where list items are wrapped in a <ul> element.

```html
<ul>
  <li>First item</li>
  <li>Second item</li>
</ul>
```

--------------------------------

### Good example: non-empty strong element

Source: https://zemdomu.dev/docs/preventEmptyInlineTags

Shows a <strong> element with text content, which is acceptable because it conveys emphasis.

```html
<p>This is <strong>really</strong> important.</p>
```

--------------------------------

### Bad example: empty strong element

Source: https://zemdomu.dev/docs/preventEmptyInlineTags

Shows an empty <strong> element that triggers the rule because it has no text content.

```html
<p>This is <strong></strong> important.</p>
```

--------------------------------

### Good example: image input with alt

Source: https://zemdomu.dev/docs/requireImageInputAlt

A compliant image input with a non-empty alt attribute that describes the control's action.

```html
<input type="image" src="submit.png" alt="Submit form">
```

--------------------------------

### Good heading order example

Source: https://zemdomu.dev/docs/enforceHeadingOrder

Shows a correct heading sequence where each heading level increases by exactly one, avoiding skipped levels.

```html
<h2>Main section</h2>
<h3>Subpoint</h3>
<p>Details…</p>
```

--------------------------------

### Good example of a single <main> landmark

Source: https://zemdomu.dev/docs/requireSingleMain

A valid HTML structure containing exactly one <main> element for the primary content.

```html
<html>
  <body>
    <main>
      <h1>Dashboard</h1>
    </main>
  </body>
</html>
```

--------------------------------

### Good anchor usage

Source: https://zemdomu.dev/docs/requireHrefOnAnchors

An example of a correctly implemented anchor element with a valid href attribute.

```html
<a href="/learn-more">Learn more</a>
```

--------------------------------

### Good example: single <h1> with <h2> subsection

Source: https://zemdomu.dev/docs/singleH1

Shows the recommended structure with one <h1> and a <h2> for a subsection. Use this pattern to satisfy the rule.

```html
<h1>Home</h1>
<section>
  <h2>About Us</h2>
  <p>…</p>
</section>
```

--------------------------------

### Good image and SVG markup

Source: https://zemdomu.dev/docs/requireAltText

Examples of correctly implemented alt text for images and accessible names for inline SVGs.

```html
<img src="team-photo.jpg" alt="Our design team standing outside the new office building">

<svg role="img" aria-label="Close"></svg>

<svg role="img"><title>Close</title></svg>
```

--------------------------------

### Good example: unique ids for div elements

Source: https://zemdomu.dev/docs/uniqueIds

These two div elements have unique id values ('item-1' and 'item-2'). Used as an example of a correct, unique-id structure.

```html
<div id="item-1"></div>
<div id="item-2"></div>
```

--------------------------------

### Good example: replace TODOs with meaningful labels

Source: https://zemdomu.dev/docs/preventZemdomuPlaceholders

Shows correct markup without TODO-ZMD markers. Use this pattern for accessible names and labels.

```HTML
<button aria-label="Close"></button>
<label for="email">Email</label>
<input id="email" type="email">
```

--------------------------------

### ZemDomu JSON diagnostic output example

Source: https://zemdomu.dev/docs/diagnostics

A sample JSON array representing a diagnostic finding, including rule metadata, source location, and suggested edits.

```json
[
  {
    "schemaVersion": "1.0",
    "rule": "requireAltText",
    "code": "ZMD004",
    "severity": "error",
    "message": "<img> tag missing alt attribute",
    "source": {
      "file": "src/Hero.tsx",
      "line": 6,
      "column": 8,
      "offset": 142
    },
    "page": "src/App.tsx",
    "componentPath": ["App", "Hero"],
    "preferredEditLocation": {
      "file": "src/Hero.tsx",
      "line": 6,
      "column": 8
    },
    "suggestion": {
      "message": "Add alt text that describes the image's purpose."
    },
    "provenance": {
      "kind": "cross-component",
      "analyzer": "ProjectLinter"
    },
    "confidence": "certain"
  }
]
```

--------------------------------

### Bad heading order example

Source: https://zemdomu.dev/docs/enforceHeadingOrder

Shows an incorrect heading sequence where the heading level jumps from h2 to h4, skipping h3.

```html
<h2>Main section</h2>
<h4>Subpoint</h4>
<p>Details…</p>
```

--------------------------------

### Bad example: image input without alt

Source: https://zemdomu.dev/docs/requireImageInputAlt

A non-compliant image input missing the alt attribute, triggering the ZMD014 rule.

```html
<input type="image" src="submit.png">
```

--------------------------------

### SARIF 2.1.0 Output Structure

Source: https://zemdomu.dev/docs/diagnostics

Example of the SARIF output format generated by ZemDomu, including rule identity and namespaced properties.

```json
{
  "version": "2.1.0",
  "runs": [{
    "results": [{
      "ruleId": "ZMD004",
      "level": "error",
      "message": { "text": "<img> tag missing alt attribute" },
      "locations": [{
        "physicalLocation": {
          "artifactLocation": { "uri": "src/Hero.tsx" },
          "region": { "startLine": 7, "startColumn": 9 }
        }
      }],
      "properties": {
        "zemdomu/schemaVersion": "1.0",
        "zemdomu/rule": "requireAltText",
        "zemdomu/componentPath": ["App", "Hero"]
      }
    }]
  }]
}
```

--------------------------------

### Bad example: multiple <h1> elements

Source: https://zemdomu.dev/docs/singleH1

Shows a violation with two <h1> elements. Avoid this pattern; use a single <h1> and lower-level headings.

```html
<h1>Home</h1>
<section>
  <h1>About Us</h1>
  <p>…</p>
</section>
```

--------------------------------

### Bad image and SVG markup

Source: https://zemdomu.dev/docs/requireAltText

Examples of invalid markup missing required text alternatives for images and SVG controls.

```html
<img src="team-photo.jpg">

<svg role="img"></svg>

<a href="/home"><svg></svg></a>
```

--------------------------------

### Bad example of multiple <main> landmarks

Source: https://zemdomu.dev/docs/requireSingleMain

An invalid HTML structure containing more than one <main> element, which violates the ZMD020 rule.

```html
<html>
  <body>
    <main>Overview</main>
    <main>Details</main>
  </body>
</html>
```

--------------------------------

### Good usage of tabindex

Source: https://zemdomu.dev/docs/noTabindexGreaterThanZero

Example of using tabindex="0" to allow an element to join the natural keyboard focus sequence.

```html
<button tabindex="0">Next</button>
```

--------------------------------

### Bad example: orphaned <li> elements

Source: https://zemdomu.dev/docs/enforceListNesting

Shows the incorrect structure where list items are placed outside a valid list container, triggering the ZMD006 warning.

```html
<li>First item</li>
<li>Second item</li>
```

--------------------------------

### Bad example: TODO-ZMD placeholders in markup

Source: https://zemdomu.dev/docs/preventZemdomuPlaceholders

Shows incorrect usage of TODO-ZMD in attributes, text content, and href. Avoid these patterns; replace with real descriptive content.

```HTML
<button aria-label="TODO-ZMD"></button>
<label for="TODO-ZMD">TODO-ZMD</label>
<label for="TODO-ZMD">{TODO-ZMD}</label>
<p>TODO-ZMD</p>
<p>{`TODO-ZMD`}</p>
<a href="TODO-ZMD">TODO-ZMD</a>
```

--------------------------------

### Valid ARIA attribute usage

Source: https://zemdomu.dev/docs/ariaValidAttrValue

Examples of correctly formatted static ARIA attributes using valid boolean and integer values.

```html
<button aria-pressed="false">Mute</button>
<div role="heading" aria-level="2">Title</div>
```

--------------------------------

### Good example: iframe with title attribute

Source: https://zemdomu.dev/docs/requireIframeTitle

Use a concise, unique title that describes the embedded content or task. This passes the ZMD012 rule.

```html
<iframe src="video.html" title="Product demo video"></iframe>
```

--------------------------------

### Good: Accessible link examples

Source: https://zemdomu.dev/docs/requireLinkText

Three valid <a> elements: text link, aria-label with hidden SVG, and img with alt text. These provide accessible names via text, ARIA, or labeled content.

```html
<a href="/privacy">Read our Privacy Policy</a>
<a href="/settings" aria-label="Settings"><svg aria-hidden="true"></svg></a>
<a href="/home"><img src="/logo.svg" alt="ZemDomu home"></a>
```

--------------------------------

### Bad anchor usage

Source: https://zemdomu.dev/docs/requireHrefOnAnchors

An example of an anchor element missing the required href attribute.

```html
<a>Learn more</a>
```

--------------------------------

### Bad usage of tabindex

Source: https://zemdomu.dev/docs/noTabindexGreaterThanZero

Example of a positive tabindex value that overrides the natural document focus order.

```html
<button tabindex="2">Next</button>
```

--------------------------------

### Bad HTML document structure

Source: https://zemdomu.dev/docs/requireDocumentTitle

An example of an invalid HTML document missing the required <title> element in the <head>.

```html
<html>
  <head></head>
  <body>
    <main>...</main>
  </body>
</html>
```

--------------------------------

### Invalid ARIA attribute usage

Source: https://zemdomu.dev/docs/ariaValidAttrValue

Examples of incorrectly formatted static ARIA attributes that trigger the ZMD021 rule.

```html
<button aria-pressed="maybe">Mute</button>
<div role="heading" aria-level="high">Title</div>
```

--------------------------------

### Configure ZemDomu GitHub Action

Source: https://zemdomu.dev/docs/diagnostics

Use this workflow configuration to run the ZemDomu action and upload the resulting SARIF file to GitHub code scanning.

```yaml
- uses: actions/checkout@v4
- id: zemdomu
  uses: Zemdomu/ZemDomu-action@v0.3.6
  with:
    files: "src/**/*.{html,jsx,tsx,vue}"
    crossComponentAnalysis: "true"

- name: Upload ZemDomu SARIF
  if: always()
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: ${{ steps.zemdomu.outputs.sarif }}
```

--------------------------------

### Good HTML document structure

Source: https://zemdomu.dev/docs/requireDocumentTitle

An example of a valid HTML document containing a descriptive <title> element within the <head>.

```html
<html>
  <head>
    <title>Account Settings | ZemDomu</title>
  </head>
  <body>
    <main>...</main>
  </body>
</html>
```

--------------------------------

### Run ZemDomu CLI semantic checks

Source: https://zemdomu.dev/docs

Run ZemDomu CLI to lint HTML, JSX, TSX, and Vue templates. The first command scans all matching files; the second enables cross-component analysis with a depth of 3.

```bash
npx zemdomu "**/*.{html,jsx,tsx,vue}"
```

```bash
npx zemdomu "src/**/*.tsx" --cross --cross-depth 3
```
Tokens:
Raw