@herb-tools/linter 0.5.0 → 0.6.0

package/dist/types/src/rules/rule-utils.d.ts

@@ -1,5 +1,5 @@
 import { Visitor, Location } from "@herb-tools/core";
-import type { HTMLAttributeNode, HTMLOpenTagNode, HTMLSelfCloseTagNode, LexResult, Token } from "@herb-tools/core";
+import type { HTMLAttributeNode, HTMLAttributeValueNode, HTMLOpenTagNode, LexResult, Token, Node } from "@herb-tools/core";
 import type { LintOffense, LintSeverity, LintContext } from "../types.js";
 /**
  * Base visitor class that provides common functionality for rule visitors
@@ -19,17 +19,52 @@ export declare abstract class BaseRuleVisitor extends Visitor {
     protected addOffense(message: string, location: Location, severity?: LintSeverity): void;
 }
 /**
- * Gets attributes from either an HTMLOpenTagNode or HTMLSelfCloseTagNode
+ * Gets attributes from an HTMLOpenTagNode
  */
-export declare function getAttributes(node: HTMLOpenTagNode | HTMLSelfCloseTagNode): any[];
+export declare function getAttributes(node: HTMLOpenTagNode): HTMLAttributeNode[];
 /**
  * Gets the tag name from an HTML tag node (lowercased)
  */
-export declare function getTagName(node: HTMLOpenTagNode | HTMLSelfCloseTagNode): string | null;
+export declare function getTagName(node: HTMLOpenTagNode): string | null;
 /**
  * Gets the attribute name from an HTMLAttributeNode (lowercased)
+ * Returns null if the attribute name contains dynamic content (ERB)
  */
 export declare function getAttributeName(attributeNode: HTMLAttributeNode): string | null;
+/**
+ * Checks if an attribute has a dynamic (ERB-containing) name
+ */
+export declare function hasDynamicAttributeName(attributeNode: HTMLAttributeNode): boolean;
+/**
+ * Gets the combined string representation of an attribute name (for debugging)
+ * This includes both static content and ERB syntax
+ */
+export declare function getCombinedAttributeNameString(attributeNode: HTMLAttributeNode): string;
+/**
+ * Checks if an attribute value contains only static content (no ERB)
+ */
+export declare function hasStaticAttributeValue(attributeNode: HTMLAttributeNode): boolean;
+/**
+ * Checks if an attribute value contains dynamic content (ERB)
+ */
+export declare function hasDynamicAttributeValue(attributeNode: HTMLAttributeNode): boolean;
+/**
+ * Gets the static string value of an attribute (returns null if it contains ERB)
+ */
+export declare function getStaticAttributeValue(attributeNode: HTMLAttributeNode): string | null;
+/**
+ * Gets the value nodes array for dynamic inspection
+ */
+export declare function getAttributeValueNodes(attributeNode: HTMLAttributeNode): Node[];
+/**
+ * Checks if an attribute value contains any static content (for validation purposes)
+ */
+export declare function hasStaticAttributeValueContent(attributeNode: HTMLAttributeNode): boolean;
+/**
+ * Gets the static content of an attribute value (all literal parts combined)
+ * Returns the concatenated literal content, or null if no literal nodes exist
+ */
+export declare function getStaticAttributeValueContent(attributeNode: HTMLAttributeNode): string | null;
 /**
  * Gets the attribute value content from an HTMLAttributeValueNode
  */
@@ -41,20 +76,25 @@ export declare function hasAttributeValue(attributeNode: HTMLAttributeNode): boo
 /**
  * Gets the quote type used for an attribute value
  */
-export declare function getAttributeValueQuoteType(attributeNode: HTMLAttributeNode): "single" | "double" | "none" | null;
+export declare function getAttributeValueQuoteType(nodeOrAttribute: HTMLAttributeNode | HTMLAttributeValueNode): "single" | "double" | "none" | null;
 /**
  * Finds an attribute by name in a list of attributes
  */
-export declare function findAttributeByName(attributes: any[], attributeName: string): HTMLAttributeNode | null;
+export declare function findAttributeByName(attributes: Node[], attributeName: string): HTMLAttributeNode | null;
 /**
  * Checks if a tag has a specific attribute
  */
-export declare function hasAttribute(node: HTMLOpenTagNode | HTMLSelfCloseTagNode, attributeName: string): boolean;
+export declare function hasAttribute(node: HTMLOpenTagNode, attributeName: string): boolean;
+/**
+ * Checks if a tag has a specific attribute
+ */
+export declare function getAttribute(node: HTMLOpenTagNode, attributeName: string): HTMLAttributeNode | null;
 /**
  * Common HTML element categorization
  */
 export declare const HTML_INLINE_ELEMENTS: Set<string>;
 export declare const HTML_BLOCK_ELEMENTS: Set<string>;
+export declare const HTML_VOID_ELEMENTS: Set<string>;
 export declare const HTML_BOOLEAN_ATTRIBUTES: Set<string>;
 export declare const HEADING_TAGS: Set<string>;
 /**
@@ -67,6 +107,37 @@ export declare const SVG_CAMEL_CASE_ELEMENTS: Set<string>;
  */
 export declare const SVG_LOWERCASE_TO_CAMELCASE: Map<string, string>;
 export declare const VALID_ARIA_ROLES: Set<string>;
+/**
+ * Parameter types for AttributeVisitorMixin methods
+ */
+export interface StaticAttributeStaticValueParams {
+    attributeName: string;
+    attributeValue: string;
+    attributeNode: HTMLAttributeNode;
+    parentNode: HTMLOpenTagNode;
+}
+export interface StaticAttributeDynamicValueParams {
+    attributeName: string;
+    valueNodes: Node[];
+    attributeNode: HTMLAttributeNode;
+    parentNode: HTMLOpenTagNode;
+    combinedValue?: string | null;
+}
+export interface DynamicAttributeStaticValueParams {
+    nameNodes: Node[];
+    attributeValue: string;
+    attributeNode: HTMLAttributeNode;
+    parentNode: HTMLOpenTagNode;
+    combinedName?: string;
+}
+export interface DynamicAttributeDynamicValueParams {
+    nameNodes: Node[];
+    valueNodes: Node[];
+    attributeNode: HTMLAttributeNode;
+    parentNode: HTMLOpenTagNode;
+    combinedName?: string;
+    combinedValue?: string | null;
+}
 export declare const ARIA_ATTRIBUTES: Set<string>;
 /**
  * Helper function to create a location at the end of the source with a 1-character range
@@ -80,21 +151,44 @@ export declare function isInlineElement(tagName: string): boolean;
  * Checks if an element is block-level
  */
 export declare function isBlockElement(tagName: string): boolean;
+/**
+ * Checks if an element is a void element
+ */
+export declare function isVoidElement(tagName: string): boolean;
 /**
  * Checks if an attribute is a boolean attribute
  */
 export declare function isBooleanAttribute(attributeName: string): boolean;
 /**
- * Abstract base class for rules that need to check individual attributes on HTML tags
- * Eliminates duplication of visitHTMLOpenTagNode/visitHTMLSelfCloseTagNode patterns
- * and attribute iteration logic. Provides simplified interface with extracted attribute info.
+ * Attribute visitor that provides granular processing based on both
+ * attribute name type (static/dynamic) and value type (static/dynamic)
+ *
+ * This gives you 4 distinct methods to override:
+ * - checkStaticAttributeStaticValue()   - name="class" value="foo"
+ * - checkStaticAttributeDynamicValue()  - name="class" value="<%= css_class %>"
+ * - checkDynamicAttributeStaticValue()  - name="data-<%= key %>" value="foo"
+ * - checkDynamicAttributeDynamicValue() - name="data-<%= key %>" value="<%= value %>"
  */
 export declare abstract class AttributeVisitorMixin extends BaseRuleVisitor {
     constructor(ruleName: string, context?: Partial<LintContext>);
     visitHTMLOpenTagNode(node: HTMLOpenTagNode): void;
-    visitHTMLSelfCloseTagNode(node: HTMLSelfCloseTagNode): void;
     private checkAttributesOnNode;
-    protected abstract checkAttribute(attributeName: string, attributeValue: string | null, attributeNode: HTMLAttributeNode, parentNode: HTMLOpenTagNode | HTMLSelfCloseTagNode): void;
+    /**
+     * Static attribute name with static value: class="container"
+     */
+    protected checkStaticAttributeStaticValue(params: StaticAttributeStaticValueParams): void;
+    /**
+     * Static attribute name with dynamic value: class="<%= css_class %>"
+     */
+    protected checkStaticAttributeDynamicValue(params: StaticAttributeDynamicValueParams): void;
+    /**
+     * Dynamic attribute name with static value: data-<%= key %>="foo"
+     */
+    protected checkDynamicAttributeStaticValue(params: DynamicAttributeStaticValueParams): void;
+    /**
+     * Dynamic attribute name with dynamic value: data-<%= key %>="<%= value %>"
+     */
+    protected checkDynamicAttributeDynamicValue(params: DynamicAttributeDynamicValueParams): void;
 }
 /**
  * Checks if an attribute value is quoted
@@ -103,7 +197,7 @@ export declare function isAttributeValueQuoted(attributeNode: HTMLAttributeNode)
 /**
  * Iterates over all attributes of a tag node, calling the callback for each attribute
  */
-export declare function forEachAttribute(node: HTMLOpenTagNode | HTMLSelfCloseTagNode, callback: (attributeNode: HTMLAttributeNode) => void): void;
+export declare function forEachAttribute(node: HTMLOpenTagNode, callback: (attributeNode: HTMLAttributeNode) => void): void;
 /**
  * Base lexer visitor class that provides common functionality for lexer-based rule visitors
  */

package/dist/types/src/types.d.ts

@@ -19,11 +19,27 @@ export declare abstract class ParserRule {
     static type: "parser";
     abstract name: string;
     abstract check(result: ParseResult, context?: Partial<LintContext>): LintOffense[];
+    /**
+     * Optional method to determine if this rule should run.
+     * If not implemented, rule is always enabled.
+     * @param result - The parse result to analyze
+     * @param context - Optional context for linting
+     * @returns true if rule should run, false to skip
+     */
+    isEnabled?(result: ParseResult, context?: Partial<LintContext>): boolean;
 }
 export declare abstract class LexerRule {
     static type: "lexer";
     abstract name: string;
     abstract check(lexResult: LexResult, context?: Partial<LintContext>): LintOffense[];
+    /**
+     * Optional method to determine if this rule should run.
+     * If not implemented, rule is always enabled.
+     * @param lexResult - The lex result to analyze
+     * @param context - Optional context for linting
+     * @returns true if rule should run, false to skip
+     */
+    isEnabled?(lexResult: LexResult, context?: Partial<LintContext>): boolean;
 }
 export interface LexerRuleConstructor {
     type: "lexer";
@@ -44,6 +60,14 @@ export declare abstract class SourceRule {
     static type: "source";
     abstract name: string;
     abstract check(source: string, context?: Partial<LintContext>): LintOffense[];
+    /**
+     * Optional method to determine if this rule should run.
+     * If not implemented, rule is always enabled.
+     * @param source - The source code to analyze
+     * @param context - Optional context for linting
+     * @returns true if rule should run, false to skip
+     */
+    isEnabled?(source: string, context?: Partial<LintContext>): boolean;
 }
 export interface SourceRuleConstructor {
     type: "source";

package/dist/types/types.d.ts

@@ -19,11 +19,27 @@ export declare abstract class ParserRule {
     static type: "parser";
     abstract name: string;
     abstract check(result: ParseResult, context?: Partial<LintContext>): LintOffense[];
+    /**
+     * Optional method to determine if this rule should run.
+     * If not implemented, rule is always enabled.
+     * @param result - The parse result to analyze
+     * @param context - Optional context for linting
+     * @returns true if rule should run, false to skip
+     */
+    isEnabled?(result: ParseResult, context?: Partial<LintContext>): boolean;
 }
 export declare abstract class LexerRule {
     static type: "lexer";
     abstract name: string;
     abstract check(lexResult: LexResult, context?: Partial<LintContext>): LintOffense[];
+    /**
+     * Optional method to determine if this rule should run.
+     * If not implemented, rule is always enabled.
+     * @param lexResult - The lex result to analyze
+     * @param context - Optional context for linting
+     * @returns true if rule should run, false to skip
+     */
+    isEnabled?(lexResult: LexResult, context?: Partial<LintContext>): boolean;
 }
 export interface LexerRuleConstructor {
     type: "lexer";
@@ -44,6 +60,14 @@ export declare abstract class SourceRule {
     static type: "source";
     abstract name: string;
     abstract check(source: string, context?: Partial<LintContext>): LintOffense[];
+    /**
+     * Optional method to determine if this rule should run.
+     * If not implemented, rule is always enabled.
+     * @param source - The source code to analyze
+     * @param context - Optional context for linting
+     * @returns true if rule should run, false to skip
+     */
+    isEnabled?(source: string, context?: Partial<LintContext>): boolean;
 }
 export interface SourceRuleConstructor {
     type: "source";

package/docs/rules/README.md

@@ -6,22 +6,32 @@ This page contains documentation for all Herb Linter rules.
 
 - [`erb-no-empty-tags`](./erb-no-empty-tags.md) - Disallow empty ERB tags
 - [`erb-no-output-control-flow`](./erb-no-output-control-flow.md) - Prevents outputting control flow blocks
+- [`erb-no-silent-tag-in-attribute-name`](./erb-no-silent-tag-in-attribute-name.md) - Disallow ERB silent tags in HTML attribute names
 - [`erb-prefer-image-tag-helper`](./erb-prefer-image-tag-helper.md) - Prefer `image_tag` helper over `<img>` with ERB expressions
-- [`erb-require-whitespace-inside-tags`](./erb-require-whitespace-inside-tags.md) - Requires whitespace around erb tags
+- [`erb-require-whitespace-inside-tags`](./erb-require-whitespace-inside-tags.md) - Requires whitespace around ERB tags
 - [`erb-requires-trailing-newline`](./erb-requires-trailing-newline.md) - Enforces that all HTML+ERB template files end with exactly one trailing newline character.
 - [`html-anchor-require-href`](./html-anchor-require-href.md) - Requires an href attribute on anchor tags
 - [`html-aria-attribute-must-be-valid`](./html-aria-attribute-must-be-valid.md) - Disallow invalid or unknown `aria-*` attributes.
+- [`html-aria-label-is-well-formatted`](./html-aria-label-is-well-formatted.md) - `aria-label` must be well-formatted
 - [`html-aria-level-must-be-valid`](./html-aria-level-must-be-valid.md) - `aria-level` must be between 1 and 6
 - [`html-aria-role-heading-requires-level`](./html-aria-role-heading-requires-level.md) - Requires `aria-level` when supplying a `role`
 - [`html-aria-role-must-be-valid`](./html-aria-role-must-be-valid.md) - The `role` attribute must have a valid WAI-ARIA Role.
 - [`html-attribute-double-quotes`](./html-attribute-double-quotes.md) - Enforces double quotes for attribute values
+- [`html-attribute-equals-spacing`](./html-attribute-equals-spacing.md) - No whitespace around `=` in HTML attributes
 - [`html-attribute-values-require-quotes`](./html-attribute-values-require-quotes.md) - Requires quotes around attribute values
+- [`html-avoid-both-disabled-and-aria-disabled`](./html-avoid-both-disabled-and-aria-disabled.md) - Avoid using both `disabled` and `aria-disabled` attributes
 - [`html-boolean-attributes-no-value`](./html-boolean-attributes-no-value.md) - Prevents values on boolean attributes
-- [`html-img-require-alt`](./html-img-require-alt.md) - Requires alt attributes on img tags
+- [`html-iframe-has-title`](./html-iframe-has-title.md) - `iframe` elements must have a `title` attribute
+- [`html-img-require-alt`](./html-img-require-alt.md) - Requires `alt` attributes on `<img>` tags
+- [`html-navigation-has-label`](./html-navigation-has-label.md) - Navigation landmarks must have accessible labels
+- [`html-no-aria-hidden-on-focusable`](./html-no-aria-hidden-on-focusable.md) - Focusable elements should not have `aria-hidden="true"`
 - [`html-no-block-inside-inline`](./html-no-block-inside-inline.md) - Prevents block-level elements inside inline elements
 - [`html-no-duplicate-attributes`](./html-no-duplicate-attributes.md) - Prevents duplicate attributes on HTML elements
 - [`html-no-duplicate-ids`](./html-no-duplicate-ids.md) - Prevents duplicate IDs within a document
 - [`html-no-nested-links`](./html-no-nested-links.md) - Prevents nested anchor tags
+- [`html-no-positive-tab-index`](./html-no-positive-tab-index.md) - Avoid positive `tabindex` values
+- [`html-no-self-closing`](./html-no-self-closing.md.md) - Disallow self closing tags
+- [`html-no-title-attribute`](./html-no-title-attribute.md) - Avoid using the `title` attribute
 - [`html-tag-name-lowercase`](./html-tag-name-lowercase.md) - Enforces lowercase tag names in HTML
 - [`parser-no-errors`](./parser-no-errors.md) - Disallow parser errors in HTML+ERB documents
 - [`svg-tag-name-capitalization`](./svg-tag-name-capitalization.md) - Enforces proper camelCase capitalization for SVG elements

package/docs/rules/erb-no-silent-tag-in-attribute-name.md

@@ -0,0 +1,34 @@
+# Linter Rule: Disallow ERB silent tags in HTML attribute names
+
+**Rule:** `erb-no-silent-tag-in-attribute-name`
+
+## Description
+
+Disallow the use of ERB silent tags (`<% ... %>`) inside HTML attribute names. These tags introduce Ruby logic that does not output anything, and placing them in attribute names leads to malformed HTML or completely unpredictable rendering.
+
+## Rationale
+
+HTML attribute names, ideally, must be valid, statically defined strings. Placing ERB silent tags (`<% ... %>`) that don't output anything inside attribute names might result in invalid HTML and is confusing. These cases are rarely intentional and almost always indicate a mistake or misuse of ERB templating.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<div data-<%= key %>-target="value"></div>
+<div <%= data_attributes_for(user) %>></div>
+```
+
+### 🚫 Bad
+
+```erb
+<div data-<% key %>-id="value"></div>
+
+<div data-<%# key %>-id="thing"></div>
+
+<div data-<%- key -%>-id="thing"></div>
+```
+
+## References
+
+\-

package/docs/rules/html-aria-label-is-well-formatted.md

@@ -0,0 +1,49 @@
+# Linter Rule: `aria-label` must be well-formatted
+
+**Rule:** `html-aria-label-is-well-formatted`
+
+## Description
+
+Ensure that the value of the `aria-label` attribute is formatted like natural, visual text. The text should use sentence case (capitalize the first letter), avoid line breaks, and not look like an ID or code identifier.
+
+## Rationale
+
+The `aria-label` attribute provides an accessible name for elements that will be read aloud by screen readers. The text should be formatted like natural language that users would expect to hear, not like technical identifiers. Using proper sentence case and avoiding formatting that looks like code (snake_case, kebab-case, camelCase) ensures a better user experience for assistive technology users.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<button aria-label="Close dialog">X</button>
+<input aria-label="Search products" type="search">
+<button aria-label="Page 2 of 10">2</button>
+```
+
+### 🚫 Bad
+
+```erb
+<!-- Starts with lowercase -->
+<button aria-label="close dialog">X</button>
+
+<!-- Contains line breaks -->
+<button aria-label="Close
+dialog">X</button>
+
+<!-- Looks like an ID (snake_case) -->
+<button aria-label="close_dialog">X</button>
+
+<!-- Looks like an ID (kebab-case) -->
+<button aria-label="close-dialog">X</button>
+
+<!-- Looks like an ID (camelCase) -->
+<button aria-label="closeDialog">X</button>
+
+<!-- HTML entity line breaks -->
+<button aria-label="Close&#10;dialog">X</button>
+```
+
+## References
+
+- [ARIA: `aria-label` attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label)
+- [erblint-github: GitHub::Accessibility::AriaLabelIsWellFormatted](https://github.com/github/erblint-github/blob/main/docs/rules/accessibility/aria-label-is-well-formatted.md)

package/docs/rules/html-attribute-equals-spacing.md

@@ -0,0 +1,35 @@
+# Linter Rule: No whitespace around `=` in HTML attributes
+
+**Rule:** `html-attribute-equals-spacing`
+
+## Description
+
+Disallow whitespace before or after the equals sign (`=`) for attribute values in HTML. Attributes must follow the canonical format (`name="value"`) with no spaces between the attribute name, the equals sign, or the opening quote.
+
+## Rationale
+
+Extra whitespace around the `=` in HTML attribute assignments is unnecessary, inconsistent, and not idiomatic. While browsers are usually forgiving, it can lead to confusing diffs, poor formatting, or inconsistent parsing in tools.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<div class="container"></div>
+<img src="/logo.png" alt="Logo">
+<input type="text" value="<%= @value %>">
+```
+
+### 🚫 Bad
+
+```erb
+<div class ="container"></div>
+
+<img src= "/logo.png" alt="Logo">
+
+<input  type  =  "text">
+```
+
+## References
+
+\-

package/docs/rules/html-avoid-both-disabled-and-aria-disabled.md

@@ -0,0 +1,48 @@
+# Linter Rule: Avoid using both `disabled` and `aria-disabled` attributes
+
+**Rule:** `html-avoid-both-disabled-and-aria-disabled`
+
+## Description
+
+Prevent using both the native `disabled` attribute and the `aria-disabled` attribute on the same HTML element. Elements should use either the native `disabled` attribute or `aria-disabled`, but not both.
+
+## Rationale
+
+Using both `disabled` and `aria-disabled` on the same element creates redundancy and potential confusion for assistive technologies. The native `disabled` attribute provides both visual and functional disabling, while `aria-disabled` only provides semantic information without preventing interaction. Having both can lead to inconsistent behavior and unclear expectations for users.
+
+Elements that support the native `disabled` attribute include: `button`, `fieldset`, `input`, `optgroup`, `option`, `select`, and `textarea`.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<!-- Use only the native disabled attribute -->
+<button disabled>Submit</button>
+<input type="text" disabled>
+
+<!-- Use only aria-disabled for custom elements -->
+<div role="button" aria-disabled="true">Custom Button</div>
+
+<!-- Use only aria-disabled -->
+<button aria-disabled="true">Submit</button>
+```
+
+### 🚫 Bad
+
+```erb
+<!-- Both disabled and aria-disabled -->
+<button disabled aria-disabled="true">Submit</button>
+
+<input type="text" disabled aria-disabled="true">
+
+<select disabled aria-disabled="true">
+  <option>Option 1</option>
+</select>
+```
+
+## References
+
+- [HTML: `disabled` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/disabled)
+- [ARIA: `aria-disabled` attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-disabled)
+- [erblint-github: GitHub::Accessibility::AvoidBothDisabledAndAriaDisabled](https://github.com/github/erblint-github/blob/main/docs/rules/accessibility/avoid-both-disabled-and-aria-disabled.md)

package/docs/rules/html-iframe-has-title.md

@@ -0,0 +1,43 @@
+# Linter Rule: `iframe` elements must have a `title` attribute
+
+**Rule:** `html-iframe-has-title`
+
+## Description
+
+Ensure that all `iframe` elements have a meaningful `title` attribute that describes the content of the frame. The title should not be empty or contain only whitespace.
+
+## Rationale
+
+The `title` attribute on `iframe` elements provides essential context for screen reader users about what content the frame contains. Without this information, users of assistive technology cannot understand the purpose or content of the embedded frame, creating significant accessibility barriers.
+
+::: tip Note
+`<iframe>`'s with `aria-hidden="true"` are exempt from this requirement as they are hidden from assistive technologies.
+:::
+
+## Examples
+
+### ✅ Good
+
+```erb
+<iframe src="https://youtube.com/embed/123" title="Product demonstration video"></iframe>
+<iframe src="https://example.com" title="Example website content"></iframe>
+
+<!-- Hidden from screen readers -->
+<iframe aria-hidden="true"></iframe>
+```
+
+### 🚫 Bad
+
+```erb
+<iframe src="https://example.com"></iframe>
+
+<iframe src="https://example.com" title=""></iframe>
+
+<iframe src="https://example.com" title="   "></iframe>
+```
+
+## References
+
+- [HTML: `iframe` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe)
+- [HTML: `title` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title)
+- [erblint-github: GitHub::Accessibility::IframeHasTitle](https://github.com/github/erblint-github/blob/main/docs/rules/accessibility/iframe-has-title.md)

package/docs/rules/html-navigation-has-label.md

@@ -0,0 +1,61 @@
+# Linter Rule: Navigation landmarks must have accessible labels
+
+**Rule:** `html-navigation-has-label`
+
+## Description
+
+Ensure that navigation landmarks have a unique accessible name via `aria-label` or `aria-labelledby` attributes. This applies to both `<nav>` elements and elements with `role="navigation"`.
+
+## Rationale
+
+Navigation landmarks help users of assistive technology quickly understand and navigate to different sections of a website. When multiple navigation landmarks exist on a page, each needs a unique accessible name so users can distinguish between them (e.g., "Main navigation", "Footer links", "Breadcrumb navigation").
+
+## Examples
+
+### ✅ Good
+
+```erb
+<nav aria-label="Main navigation">
+  <ul>
+    <li><a href="/">Home</a></li>
+    <li><a href="/about">About</a></li>
+  </ul>
+</nav>
+
+<nav aria-labelledby="breadcrumb-title">
+  <h2 id="breadcrumb-title">Breadcrumb</h2>
+  <ol>
+    <li><a href="/">Home</a></li>
+    <li>Current Page</li>
+  </ol>
+</nav>
+
+<div role="navigation" aria-label="Footer links">
+  <a href="/privacy">Privacy</a>
+  <a href="/terms">Terms</a>
+</div>
+```
+
+### 🚫 Bad
+
+```erb
+<nav>
+  <ul>
+    <li><a href="/">Home</a></li>
+    <li><a href="/about">About</a></li>
+  </ul>
+</nav>
+
+<div role="navigation">
+  <a href="/privacy">Privacy</a>
+  <a href="/terms">Terms</a>
+</div>
+```
+
+## References
+
+- [ARIA: `navigation` role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/navigation_role)
+- [HTML: `nav` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/nav)
+- [ARIA: `aria-label` attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label)
+- [ARIA: `aria-labelledby` attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby)
+- [erblint-github: GitHub::Accessibility::NavigationHasLabel](https://github.com/github/erblint-github/blob/main/docs/rules/accessibility/navigation-has-label.md)

package/docs/rules/html-no-aria-hidden-on-focusable.md

@@ -0,0 +1,54 @@
+# Linter Rule: Focusable elements should not have `aria-hidden="true"`
+
+**Rule:** `html-no-aria-hidden-on-focusable`
+
+## Description
+
+Prevent using `aria-hidden="true"` on elements that can receive keyboard focus. When an element is focusable but hidden from screen readers, it creates a confusing experience where keyboard users can tab to "invisible" elements.
+
+## Rationale
+
+Elements with `aria-hidden="true"` are completely hidden from assistive technologies, but they remain visible and interactive for mouse and keyboard users. If a focusable element is hidden from screen readers, keyboard-only users (especially those using screen readers) will encounter focused elements that provide no accessible information, creating a broken user experience.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<button>Submit</button>
+<a href="/link">Link</a>
+<input type="text">
+<textarea></textarea>
+
+<div aria-hidden="true">Decorative content</div>
+<span aria-hidden="true">🎉</span>
+
+<button tabindex="-1" aria-hidden="true">Hidden button</button>
+```
+
+### 🚫 Bad
+
+```erb
+<button aria-hidden="true">Submit</button>
+
+<a href="/link" aria-hidden="true">Link</a>
+
+<input type="text" aria-hidden="true">
+
+<textarea aria-hidden="true"></textarea>
+
+<select aria-hidden="true">
+  <option>Option</option>
+</select>
+
+<div tabindex="0" aria-hidden="true">Focusable div</div>
+
+<a href="/link" aria-hidden="true">Hidden link</a>
+```
+
+## References
+
+- [ARIA: `aria-hidden` attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden)
+- [HTML: `tabindex` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex)
+- [WebAIM: Keyboard Accessibility](https://webaim.org/techniques/keyboard/)
+- [erblint-github: GitHub::Accessibility::NoAriaHiddenOnFocusable](https://github.com/github/erblint-github/blob/main/docs/rules/accessibility/no-aria-hidden-on-focusable.md)