From 9d6ee0110a679922f7456057db8fd416da01c77b Mon Sep 17 00:00:00 2001
From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com>
Date: Mon, 23 Feb 2026 15:01:44 -0500
Subject: [PATCH] Extract rule: template-no-heading-inside-button

---
 README.md                                     |  1 +
 .../template-no-heading-inside-button.md      | 32 ++++++++
 .../template-no-heading-inside-button.js      | 47 +++++++++++
 .../template-no-heading-inside-button.js      | 77 +++++++++++++++++++
 4 files changed, 157 insertions(+)
 create mode 100644 docs/rules/template-no-heading-inside-button.md
 create mode 100644 lib/rules/template-no-heading-inside-button.js
 create mode 100644 tests/lib/rules/template-no-heading-inside-button.js

diff --git a/README.md b/README.md
index ae2c7b3b6c..80506d23d9 100644
--- a/README.md
+++ b/README.md
@@ -186,6 +186,7 @@ rules in templates can be disabled with eslint directives with mustache or html
 | [template-no-aria-hidden-body](docs/rules/template-no-aria-hidden-body.md)                   | disallow aria-hidden on body element                                             |    | 🔧 |    |
 | [template-no-aria-unsupported-elements](docs/rules/template-no-aria-unsupported-elements.md) | disallow ARIA roles, states, and properties on elements that do not support them |    |    |    |
 | [template-no-autofocus-attribute](docs/rules/template-no-autofocus-attribute.md)             | disallow autofocus attribute                                                     |    | 🔧 |    |
+| [template-no-heading-inside-button](docs/rules/template-no-heading-inside-button.md)         | disallow heading elements inside button elements                                 |    |    |    |
 
 ### Best Practices
 
diff --git a/docs/rules/template-no-heading-inside-button.md b/docs/rules/template-no-heading-inside-button.md
new file mode 100644
index 0000000000..1c79e9293d
--- /dev/null
+++ b/docs/rules/template-no-heading-inside-button.md
@@ -0,0 +1,32 @@
+# ember/template-no-heading-inside-button
+
+<!-- end auto-generated rule header -->
+
+Assistive technology allows users to browse a page by heading elements (`<h1>` - `<h6>`). However, if those heading elements are nested inside of button elements, they will automatically be marked as presentational by browsers. Any HTML element where ["children presentational" is true](https://w3c.github.io/aria/#button) should be coerced by the browser to be presentational, and therefore not included in the accessibility tree.
+
+As such, nesting a heading element inside of a button element will cause failures for WCAG requirement 1.3.1, Info and Relationships, because the heading has lost semantic meaning.
+
+This rule checks `<button>` elements to see if they contain heading (`<h1>` - `<h6>`) elements, and gives an error message if they are found.
+
+## Examples
+
+This rule **forbids** the following:
+
+```gjs
+<template><button><h1>Some Text</h1></button></template>
+```
+
+This rule **allows** the following:
+
+```gjs
+<template><button><span>Button Text</span></button></template>
+```
+
+## Migration
+
+- Replace `<h1>` - `<h6>` elements inside of `<button>` elements with classes that reflect the desired styling.
+
+## References
+
+- <https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html>
+- <https://w3c.github.io/aria/#button>
diff --git a/lib/rules/template-no-heading-inside-button.js b/lib/rules/template-no-heading-inside-button.js
new file mode 100644
index 0000000000..748a709493
--- /dev/null
+++ b/lib/rules/template-no-heading-inside-button.js
@@ -0,0 +1,47 @@
+const HEADING_ELEMENTS = new Set(['h1', 'h2', 'h3', 'h4', 'h5', 'h6']);
+
+function hasButtonParent(node) {
+  let parent = node.parent;
+  while (parent) {
+    if (parent.type === 'GlimmerElementNode') {
+      // Check if it's a button element
+      if (parent.tag === 'button') {
+        return true;
+      }
+      // Check if it has role="button"
+      const roleAttr = parent.attributes?.find((a) => a.name === 'role');
+      if (roleAttr?.value?.type === 'GlimmerTextNode' && roleAttr.value.chars === 'button') {
+        return true;
+      }
+    }
+    parent = parent.parent;
+  }
+  return false;
+}
+
+/** @type {import('eslint').Rule.RuleModule} */
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'disallow heading elements inside button elements',
+      category: 'Accessibility',
+      strictGjs: true,
+      strictGts: true,
+      url: 'https://github.com/ember-cli/eslint-plugin-ember/tree/master/docs/rules/template-no-heading-inside-button.md',
+    },
+    schema: [],
+    messages: {
+      noHeading: 'Buttons should not contain heading elements',
+    },
+  },
+  create(context) {
+    return {
+      GlimmerElementNode(node) {
+        if (HEADING_ELEMENTS.has(node.tag) && hasButtonParent(node)) {
+          context.report({ node, messageId: 'noHeading' });
+        }
+      },
+    };
+  },
+};
diff --git a/tests/lib/rules/template-no-heading-inside-button.js b/tests/lib/rules/template-no-heading-inside-button.js
new file mode 100644
index 0000000000..8880cf66e0
--- /dev/null
+++ b/tests/lib/rules/template-no-heading-inside-button.js
@@ -0,0 +1,77 @@
+const rule = require('../../../lib/rules/template-no-heading-inside-button');
+const RuleTester = require('eslint').RuleTester;
+
+const ruleTester = new RuleTester({
+  parser: require.resolve('ember-eslint-parser'),
+  parserOptions: { ecmaVersion: 2022, sourceType: 'module' },
+});
+
+ruleTester.run('template-no-heading-inside-button', rule, {
+  valid: [
+    '<template><button>Click me</button></template>',
+    '<template><h1>Title</h1></template>',
+    '<template><div><h2>Heading</h2></div></template>',
+
+    // Test cases ported from ember-template-lint
+    '<template><button>Show More</button></template>',
+    '<template><button><span>thumbs-up emoji</span>Show More</button></template>',
+    '<template><button><div>Show More</div></button></template>',
+    '<template><div>Showing that it is not a button</div></template>',
+    '<template><div><h1>Page Title in a div is fine</h1></div></template>',
+    '<template><h1>Page Title</h1></template>',
+  ],
+  invalid: [
+    {
+      code: '<template><button><h1>Bad</h1></button></template>',
+      output: null,
+      errors: [{ messageId: 'noHeading' }],
+    },
+    {
+      code: '<template><div role="button"><h2>Bad</h2></div></template>',
+      output: null,
+      errors: [{ messageId: 'noHeading' }],
+    },
+
+    // Test cases ported from ember-template-lint
+    {
+      code: '<template><button><h1>Page Title</h1></button></template>',
+      output: null,
+      errors: [{ messageId: 'noHeading' }],
+    },
+    {
+      code: '<template><button><h2>Heading Title</h2></button></template>',
+      output: null,
+      errors: [{ messageId: 'noHeading' }],
+    },
+    {
+      code: '<template><button><h3>Heading Title</h3></button></template>',
+      output: null,
+      errors: [{ messageId: 'noHeading' }],
+    },
+    {
+      code: '<template><button><h4>Heading Title</h4></button></template>',
+      output: null,
+      errors: [{ messageId: 'noHeading' }],
+    },
+    {
+      code: '<template><button><h5>Heading Title</h5></button></template>',
+      output: null,
+      errors: [{ messageId: 'noHeading' }],
+    },
+    {
+      code: '<template><button><div><h1>Heading Title</h1></div></button></template>',
+      output: null,
+      errors: [{ messageId: 'noHeading' }],
+    },
+    {
+      code: '<template><button><h6>Heading Title</h6></button></template>',
+      output: null,
+      errors: [{ messageId: 'noHeading' }],
+    },
+    {
+      code: '<template><div role="button"><h6>Heading in a div with a role of button</h6></div></template>',
+      output: null,
+      errors: [{ messageId: 'noHeading' }],
+    },
+  ],
+});