eslint-plugin-html-simbiat

Custom @html-eslint rules used in the simbiat.eu project, for Twig templates. Created with the use of Claude AI, but manually reviewed, adjusted, and tested on the existing codebase. All are suggestions and fixable.

Installation

npm install --save-dev @simbiat/hmtl-eslint-plugin-simbiat

Usage (flat config)

// eslint.config.js
import htmlPlugin from '@html-eslint/eslint-plugin';
import htmlParser from '@html-eslint/parser';
import simbiat from '@simbiat/eslint-plugin-html-simbiat';

export default [
  {
    files: ['**/*.html'],
    plugins: { html: htmlPlugin, simbiat },
    language: 'html/html',
    rules: {
      'simbiat/require-span-in-anchor-text': 'warn',
      'simbiat/prefer-button-over-input':    'warn',
      'simbiat/no-redundant-alt':            'warn',
      'simbiat/checkbox-label-structure':    'warn',
      'require-float-label-wrapper':         'warn',
    },
  },
];

Rules

simbiat/require-span-in-anchor-text

Requires every direct, non-whitespace-only Text child of an <a> to be wrapped in <span>, so anchor content can be targeted by CSS consistently. This is useful since CSS itself cannot target text nodes, and depending on how you style the links, you can get various abnormalities. Whitespace-only text (pure formatting/indentation) is left alone; only the trimmed inner content is wrapped, so surrounding whitespace stays outside the <span>.

<!-- ✗ flagged -->
<a href="/profile">
    <img src="avatar.png" alt="">
    {{ user.name }}
</a>

<!-- ✓ OK -->
<a href="/profile">
    <img src="avatar.png" alt="">
    <span>{{ user.name }}</span>
</a>

simbiat/prefer-button-over-input

Flags <input type="button|submit|reset|image">, suggesting <button> instead:

<!-- ✗ flagged -->
<input type="submit" value="Send">

<!-- ✓ suggested replacement -->
<button type="submit" value="Send">
    Send
</button>

simbiat/no-redundant-alt

Flags <img alt="X"> sitting directly next to a sibling whose own text content is that same X - the alt text is then read out twice by a screen reader. Matches both a tag-wrapped duplicate and bare adjacent text:

<!-- ✗ flagged (both forms) -->
<a href="/edit"><img src="edit.png" alt="Edit"><span>Edit</span></a>
<a href="/edit"><img src="edit.png" alt="Edit">Edit</a>

<!-- ✓ OK -->
<a href="/edit"><img src="edit.png" alt=""><span>Edit</span></a>

simbiat/checkbox-label-structure

Requires <input type="checkbox" id="X"> paired with an adjacent <label for="X"> to structure the label's content as four spans, so CSS can toggle checked/unchecked text and icon independently per instance without use of JavaScript.

<!-- ✗ flagged -->
<input id="agree" type="checkbox">
<label for="agree">I agree</label>

<!-- ✓ OK (structure required; content is yours to customize) -->
<input id="agree" type="checkbox">
<label for="agree">
    <span class="checkbox_checked_icon" aria-hidden="true"></span>
    <span class="checkbox_checked">I agree</span>
    <span class="checkbox_not_checked_icon" aria-hidden="true"></span>
    <span class="checkbox_not_checked">I agree</span>
</label>

Detection is structural only: a label already containing all four required span classes is conformant regardless of its actual content, since customizing that content per instance (different wording, a custom icon) is the entire point of the pattern.

Options

'simbiat/checkbox-label-structure': ['warn', {
  checkedIconClass:   'checkbox_checked_icon',
  checkedClass:        'checkbox_checked',
  uncheckedIconClass: 'checkbox_not_checked_icon',
  uncheckedClass:      'checkbox_not_checked',
}]

All four default to the values shown above. Only the class names are configurable - the four-span shape itself isn't.

simbiat/require-float-label-wrapper

Wraps input, select and textarea elements with their adjacent label into a div (default) with class float_label (default). This is a common pattern for making "floating" labels, which move on top of the element on interactions or when the element has content. If already wrapped into any tag with respective class - will not be suggested.

<!-- ✗ flagged -->
<input id="input_box" type="text">
<label for="input_box">Some random text</label>

<!-- ✓ OK (structure required; content is yours to customize) -->
<div class="float_label">
    <input id="input_box" type="text">
    <label for="input_box">Some random text</label>
</div>

Options

'simbiat/require-float-label-wrapper': ['warn', {
    wrapperClass:   'float_label',
    wrapperClass:   'div',
}]