From b2ccfa82e1c99fa6fe120abdaae8adc269f4c868 Mon Sep 17 00:00:00 2001
From: Abdullah Hashim <abdul@hey.com>
Date: Wed, 6 May 2026 07:21:19 -0400
Subject: [PATCH 1/7] Recognize sr-only accessible names via
 accessible_name_wrapper_classes

---
 CHANGELOG.md                                  |  4 +
 lib/a11y/lint/configuration.rb                |  5 ++
 lib/a11y/lint/phlex_node.rb                   |  7 ++
 lib/a11y/lint/phlex_runner.rb                 | 15 +++-
 .../lint/phlex_runner/block_text_scanner.rb   | 21 ++++-
 lib/a11y/lint/phlex_runner/phlex_call.rb      |  6 +-
 ...st_anchor_missing_accessible_name_phlex.rb | 80 +++++++++++++++++++
 ...st_button_missing_accessible_name_phlex.rb | 80 +++++++++++++++++++
 test/a11y/lint/test_configuration.rb          | 35 ++++++++
 test/fixtures/dummy_app/.a11y-lint.yml        |  7 ++
 .../fixtures/dummy_app/app/views/home_view.rb | 19 +++++
 11 files changed, 271 insertions(+), 8 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 36eb26f..cd2c9ce 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- `.a11y-lint.yml` now supports a top-level `accessible_name_wrapper_classes` list. Inside Phlex `a`/`button` tags whose direct child has a matching class, `AnchorMissingAccessibleName` and `ButtonMissingAccessibleName` treat ambiguous bare calls — receiverless calls whose name matches an HTML tag, with no arguments and no block — as text-emitting method calls rather than empty HTML elements. Fixes false positives on the `span(class: "sr-only") { label }` pattern, where `label` is an instance method that parses as a `Prism::CallNode` indistinguishable from the `<label>` HTML tag. Opt-in; default is no special handling. Distinct from `hidden_wrapper_classes` (which excludes the wrapper from the parent's accessible name); a wrapper-class list member here stays in the parent's children with `text_content?` set to true. No-op in the Slim and ERB pipelines, which have no analogous ambiguity
+
 ## [0.14.2] - 2026-05-05
 
 ### Fixed
diff --git a/lib/a11y/lint/configuration.rb b/lib/a11y/lint/configuration.rb
index 7c5ae36..f0cff1c 100644
--- a/lib/a11y/lint/configuration.rb
+++ b/lib/a11y/lint/configuration.rb
@@ -47,6 +47,11 @@ def hidden_wrapper_classes
           Array(@config["hidden_wrapper_classes"]).map(&:to_s).freeze
       end
 
+      def accessible_name_wrapper_classes
+        @accessible_name_wrapper_classes ||=
+          Array(@config["accessible_name_wrapper_classes"]).map(&:to_s).freeze
+      end
+
       def enabled_rules
         Rules.constants.filter_map do |name|
           klass = Rules.const_get(name)
diff --git a/lib/a11y/lint/phlex_node.rb b/lib/a11y/lint/phlex_node.rb
index f240b95..8313387 100644
--- a/lib/a11y/lint/phlex_node.rb
+++ b/lib/a11y/lint/phlex_node.rb
@@ -85,6 +85,13 @@ def self.build_helper(
         )
       end
 
+      # Resolves a Phlex tag call's `class:` kwarg to a list of class names.
+      # Intentionally narrow: only matches a literal `Prism::StringNode`.
+      # Misses array form (`class: ["sr-only", other]`), interpolation
+      # (`class: "sr-only #{foo}"`), helper-wrapped (`class: cn("sr-only")`),
+      # and computed values (`class: some_method`). Wrapper-class config
+      # (`hidden_wrapper_classes`, `accessible_name_wrapper_classes`)
+      # therefore only matches authors who write a single static literal.
       def self.kwarg_class_values(call_node)
         return [] unless call_node.arguments
 
diff --git a/lib/a11y/lint/phlex_runner.rb b/lib/a11y/lint/phlex_runner.rb
index 6b83d3e..a0ef735 100644
--- a/lib/a11y/lint/phlex_runner.rb
+++ b/lib/a11y/lint/phlex_runner.rb
@@ -91,7 +91,9 @@ def gather_children(parent, result)
 
       def gather_tag_child(call, result)
         kids = collect_block_children(call.block_node)
-        has_text = call.arg_has_text? || call.block_has_text?(kids)
+        accessible_name_wrapper = accessible_name_wrapper_tag?(call)
+        has_text = call.arg_has_text? ||
+                   call.block_has_text?(kids, wrapper: accessible_name_wrapper)
         tag = PhlexNode.build_tag(
           call.call_node, children: kids, text_content: has_text,
                           configuration: configuration
@@ -101,7 +103,16 @@ def gather_tag_child(call, result)
       end
 
       def hidden_wrapper_tag?(call)
-        classes = configuration.hidden_wrapper_classes
+        wrapper_class_match?(call, configuration.hidden_wrapper_classes)
+      end
+
+      def accessible_name_wrapper_tag?(call)
+        wrapper_class_match?(
+          call, configuration.accessible_name_wrapper_classes
+        )
+      end
+
+      def wrapper_class_match?(call, classes)
         return false if classes.empty?
 
         call.class_values.any? { |klass| classes.include?(klass) }
diff --git a/lib/a11y/lint/phlex_runner/block_text_scanner.rb b/lib/a11y/lint/phlex_runner/block_text_scanner.rb
index 3b50cff..f1428b8 100644
--- a/lib/a11y/lint/phlex_runner/block_text_scanner.rb
+++ b/lib/a11y/lint/phlex_runner/block_text_scanner.rb
@@ -22,8 +22,8 @@ class BlockTextScanner
           highlight excerpt
         ].to_set.freeze
 
-        def self.scan(block, children:)
-          new(block, children).scan
+        def self.scan(block, children:, wrapper: false)
+          new(block, children, wrapper: wrapper).scan
         end
 
         # Public recognizer for a single Prism node — used by PhlexRunner
@@ -50,9 +50,10 @@ def self.non_blank_string_literal?(node)
           end
         end
 
-        def initialize(block, children)
+        def initialize(block, children, wrapper: false)
           @block = block
           @children = children
+          @wrapper = wrapper
         end
 
         def scan
@@ -119,7 +120,15 @@ def auto_emitted_call?(call)
           return true if call.receiver
 
           name = call.name.to_s
-          return false if PhlexNode.html_tag?(name)
+          if PhlexNode.html_tag?(name)
+            # Inside a tag whose class signals an accessible-name wrapper
+            # (e.g. `sr-only`), an ambiguous bare call — name matches an
+            # HTML tag, no args, no block — is treated as a text-emitting
+            # method call rather than an empty HTML element. Matches
+            # author intent for patterns like `span(class: "sr-only") { label }`
+            # where `label` is an instance method, not the `<label>` tag.
+            return @wrapper && bare_call?(call)
+          end
           return true if TEXT_CALLS.include?(name)
 
           # Lowercase receiverless calls (locals, helper methods) auto-emit
@@ -128,6 +137,10 @@ def auto_emitted_call?(call)
           lowercase_name?(name)
         end
 
+        def bare_call?(call)
+          call.arguments.nil? && call.block.nil?
+        end
+
         def conditional_container?(node)
           node.is_a?(Prism::IfNode) ||
             node.is_a?(Prism::UnlessNode) ||
diff --git a/lib/a11y/lint/phlex_runner/phlex_call.rb b/lib/a11y/lint/phlex_runner/phlex_call.rb
index fb62519..7c5e043 100644
--- a/lib/a11y/lint/phlex_runner/phlex_call.rb
+++ b/lib/a11y/lint/phlex_runner/phlex_call.rb
@@ -61,8 +61,10 @@ def block_children
           block_node ? block_node.child_nodes.compact : []
         end
 
-        def block_has_text?(children = [])
-          BlockTextScanner.scan(block_node, children: children)
+        def block_has_text?(children = [], wrapper: false)
+          BlockTextScanner.scan(
+            block_node, children: children, wrapper: wrapper
+          )
         end
 
         # Phlex's tag API emits the first positional argument as text
diff --git a/test/a11y/lint/rules/robust/test_anchor_missing_accessible_name_phlex.rb b/test/a11y/lint/rules/robust/test_anchor_missing_accessible_name_phlex.rb
index 05409ca..0031469 100644
--- a/test/a11y/lint/rules/robust/test_anchor_missing_accessible_name_phlex.rb
+++ b/test/a11y/lint/rules/robust/test_anchor_missing_accessible_name_phlex.rb
@@ -698,6 +698,86 @@ def view_template
           assert_equal(["AnchorMissingAccessibleName"], result)
         end
 
+        def test_anchor_with_sr_only_bare_html_tag_call_reports_by_default
+          source = <<~RUBY
+            class TestView < Phlex::HTML
+              def view_template
+                a(href: "/back", class: "icon") do
+                  span(class: "absolute -inset-2.5")
+                  span(class: "sr-only") { label }
+                  ChevronLeft(variant: :solid)
+                end
+              end
+            end
+          RUBY
+
+          offenses = run_linter(source)
+          result = offenses.map(&:rule)
+
+          assert_equal(["AnchorMissingAccessibleName"], result)
+        end
+
+        def test_anchor_with_sr_only_bare_html_tag_call_passes_when_configured
+          source = <<~RUBY
+            class TestView < Phlex::HTML
+              def view_template
+                a(href: "/back", class: "icon") do
+                  span(class: "absolute -inset-2.5")
+                  span(class: "sr-only") { label }
+                  ChevronLeft(variant: :solid)
+                end
+              end
+            end
+          RUBY
+          configuration = Configuration.new(
+            "accessible_name_wrapper_classes" => ["sr-only"]
+          )
+
+          offenses = run_linter(source, configuration:)
+
+          assert_empty(offenses)
+        end
+
+        def test_anchor_with_sr_only_string_block_passes_when_configured
+          source = <<~RUBY
+            class TestView < Phlex::HTML
+              def view_template
+                a(href: "/back", class: "icon") do
+                  span(class: "sr-only") { "Back" }
+                end
+              end
+            end
+          RUBY
+          configuration = Configuration.new(
+            "accessible_name_wrapper_classes" => ["sr-only"]
+          )
+
+          offenses = run_linter(source, configuration:)
+
+          assert_empty(offenses)
+        end
+
+        def test_anchor_with_sr_only_in_hidden_wrapper_classes_still_reports
+          source = <<~RUBY
+            class TestView < Phlex::HTML
+              def view_template
+                a(href: "/back", class: "icon") do
+                  span(class: "sr-only") { label }
+                  ChevronLeft(variant: :solid)
+                end
+              end
+            end
+          RUBY
+          configuration = Configuration.new(
+            "hidden_wrapper_classes" => ["sr-only"]
+          )
+
+          offenses = run_linter(source, configuration:)
+          result = offenses.map(&:rule)
+
+          assert_equal(["AnchorMissingAccessibleName"], result)
+        end
+
         private
 
         def run_linter(
diff --git a/test/a11y/lint/rules/robust/test_button_missing_accessible_name_phlex.rb b/test/a11y/lint/rules/robust/test_button_missing_accessible_name_phlex.rb
index b358815..4f109d6 100644
--- a/test/a11y/lint/rules/robust/test_button_missing_accessible_name_phlex.rb
+++ b/test/a11y/lint/rules/robust/test_button_missing_accessible_name_phlex.rb
@@ -668,6 +668,86 @@ def view_template
           assert_equal(["ButtonMissingAccessibleName"], result)
         end
 
+        def test_button_with_sr_only_bare_html_tag_call_reports_by_default
+          source = <<~RUBY
+            class TestView < Phlex::HTML
+              def view_template
+                button(class: "icon") do
+                  span(class: "absolute -inset-2.5")
+                  span(class: "sr-only") { label }
+                  EllipsisVertical(variant: :solid)
+                end
+              end
+            end
+          RUBY
+
+          offenses = run_linter(source)
+          result = offenses.map(&:rule)
+
+          assert_equal(["ButtonMissingAccessibleName"], result)
+        end
+
+        def test_button_with_sr_only_bare_html_tag_call_passes_when_configured
+          source = <<~RUBY
+            class TestView < Phlex::HTML
+              def view_template
+                button(class: "icon") do
+                  span(class: "absolute -inset-2.5")
+                  span(class: "sr-only") { label }
+                  EllipsisVertical(variant: :solid)
+                end
+              end
+            end
+          RUBY
+          configuration = Configuration.new(
+            "accessible_name_wrapper_classes" => ["sr-only"]
+          )
+
+          offenses = run_linter(source, configuration:)
+
+          assert_empty(offenses)
+        end
+
+        def test_button_with_sr_only_string_block_passes_when_configured
+          source = <<~RUBY
+            class TestView < Phlex::HTML
+              def view_template
+                button(class: "icon") do
+                  span(class: "sr-only") { "Open menu" }
+                end
+              end
+            end
+          RUBY
+          configuration = Configuration.new(
+            "accessible_name_wrapper_classes" => ["sr-only"]
+          )
+
+          offenses = run_linter(source, configuration:)
+
+          assert_empty(offenses)
+        end
+
+        def test_button_with_sr_only_in_hidden_wrapper_classes_still_reports
+          source = <<~RUBY
+            class TestView < Phlex::HTML
+              def view_template
+                button(class: "icon") do
+                  span(class: "sr-only") { label }
+                  EllipsisVertical(variant: :solid)
+                end
+              end
+            end
+          RUBY
+          configuration = Configuration.new(
+            "hidden_wrapper_classes" => ["sr-only"]
+          )
+
+          offenses = run_linter(source, configuration:)
+          result = offenses.map(&:rule)
+
+          assert_equal(["ButtonMissingAccessibleName"], result)
+        end
+
         private
 
         def run_linter(
diff --git a/test/a11y/lint/test_configuration.rb b/test/a11y/lint/test_configuration.rb
index 6283030..6c3776a 100644
--- a/test/a11y/lint/test_configuration.rb
+++ b/test/a11y/lint/test_configuration.rb
@@ -91,6 +91,41 @@ def test_hidden_wrapper_classes_load_from_yaml
           assert_equal(["popover"], config.hidden_wrapper_classes)
         end
       end
+
+      def test_accessible_name_wrapper_classes_defaults_to_empty_array
+        assert_empty(Configuration.new.accessible_name_wrapper_classes)
+      end
+
+      def test_accessible_name_wrapper_classes_reads_top_level_key
+        config = Configuration.new(
+          "accessible_name_wrapper_classes" => %w[sr-only visually-hidden]
+        )
+
+        assert_equal(
+          %w[sr-only visually-hidden], config.accessible_name_wrapper_classes
+        )
+      end
+
+      def test_accessible_name_wrapper_classes_coerces_entries_to_strings
+        config = Configuration.new(
+          "accessible_name_wrapper_classes" => [:"sr-only"]
+        )
+
+        assert_equal(["sr-only"], config.accessible_name_wrapper_classes)
+      end
+
+      def test_accessible_name_wrapper_classes_load_from_yaml
+        Dir.mktmpdir do |dir|
+          path = File.join(dir, ".a11y-lint.yml")
+          File.write(
+            path, "accessible_name_wrapper_classes:\n  - sr-only\n"
+          )
+
+          config = Configuration.load(path)
+
+          assert_equal(["sr-only"], config.accessible_name_wrapper_classes)
+        end
+      end
     end
   end
 end
diff --git a/test/fixtures/dummy_app/.a11y-lint.yml b/test/fixtures/dummy_app/.a11y-lint.yml
index 2eab08c..7261592 100644
--- a/test/fixtures/dummy_app/.a11y-lint.yml
+++ b/test/fixtures/dummy_app/.a11y-lint.yml
@@ -18,3 +18,10 @@
 # does not count toward an element's accessible name.
 hidden_wrapper_classes:
   - popover
+
+# Class names that wrap content visible only to assistive technology
+# (e.g. CSS-clipped sr-only spans). Inside Phlex tags whose class
+# matches, ambiguous bare calls (HTML-tag-named, no args, no block)
+# are treated as auto-emitting text rather than empty HTML elements.
+accessible_name_wrapper_classes:
+  - sr-only
diff --git a/test/fixtures/dummy_app/app/views/home_view.rb b/test/fixtures/dummy_app/app/views/home_view.rb
index 0d4a042..20efc2c 100644
--- a/test/fixtures/dummy_app/app/views/home_view.rb
+++ b/test/fixtures/dummy_app/app/views/home_view.rb
@@ -141,6 +141,25 @@ def view_template(label: "Menu")
       span { label }
     end
 
+    # Good: anchor whose accessible name lives in an sr-only span
+    # whose body is an ambiguous bare call (`label` is an instance
+    # method, not the `<label>` HTML tag).
+    # Needs accessible_name_wrapper_classes: [sr-only] config.
+    a(href: "/back", class: "icon") do
+      span(class: "absolute -inset-2.5")
+      span(class: "sr-only") { label }
+      ChevronLeft(variant: :solid, class: "size-5")
+    end
+
+    # Good: button whose accessible name lives in an sr-only span
+    # with the same bare-call shape.
+    # Needs accessible_name_wrapper_classes: [sr-only] config.
+    button(class: "icon") do
+      span(class: "absolute -inset-2.5")
+      span(class: "sr-only") { label }
+      EllipsisVertical(variant: :solid, class: "size-5")
+    end
+
     # Good: button with bare string-literal block
     button(type: :submit, class: "btn") { "Filter" }
 

From c7e16955cc9a8a63d801f3a162c682db3dc9d5ae Mon Sep 17 00:00:00 2001
From: Abdullah Hashim <abdul@hey.com>
Date: Wed, 6 May 2026 07:27:31 -0400
Subject: [PATCH 2/7] wip [ci skip]

---
 lib/a11y/lint/phlex_runner/block_text_scanner.rb | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/lib/a11y/lint/phlex_runner/block_text_scanner.rb b/lib/a11y/lint/phlex_runner/block_text_scanner.rb
index f1428b8..88a8a40 100644
--- a/lib/a11y/lint/phlex_runner/block_text_scanner.rb
+++ b/lib/a11y/lint/phlex_runner/block_text_scanner.rb
@@ -23,14 +23,14 @@ class BlockTextScanner
         ].to_set.freeze
 
         def self.scan(block, children:, wrapper: false)
-          new(block, children, wrapper: wrapper).scan
+          new(block, children:, wrapper:).scan
         end
 
         # Public recognizer for a single Prism node — used by PhlexRunner
         # to inspect a tag's first positional argument, where Phlex emits
         # the value as text content (`a("Click", href: "/x")`).
         def self.text_emitting?(node)
-          new(nil, []).text_emitting?(node)
+          new(nil, children: []).text_emitting?(node)
         end
 
         def self.non_blank_string_literal?(node)
@@ -50,7 +50,7 @@ def self.non_blank_string_literal?(node)
           end
         end
 
-        def initialize(block, children, wrapper: false)
+        def initialize(block, children:, wrapper: false)
           @block = block
           @children = children
           @wrapper = wrapper

From 287340722332d7af149cb07c3c8ca14bfde31e76 Mon Sep 17 00:00:00 2001
From: Abdullah Hashim <abdul@hey.com>
Date: Wed, 6 May 2026 07:36:30 -0400
Subject: [PATCH 3/7] wip

---
 lib/a11y/lint/phlex_runner/phlex_call.rb       |  8 +-------
 test/a11y/lint/phlex_runner/test_phlex_call.rb | 10 ----------
 2 files changed, 1 insertion(+), 17 deletions(-)

diff --git a/lib/a11y/lint/phlex_runner/phlex_call.rb b/lib/a11y/lint/phlex_runner/phlex_call.rb
index 7c5e043..16929b0 100644
--- a/lib/a11y/lint/phlex_runner/phlex_call.rb
+++ b/lib/a11y/lint/phlex_runner/phlex_call.rb
@@ -57,14 +57,8 @@ def forwarded_block?
           block.is_a?(Prism::BlockArgumentNode)
         end
 
-        def block_children
-          block_node ? block_node.child_nodes.compact : []
-        end
-
         def block_has_text?(children = [], wrapper: false)
-          BlockTextScanner.scan(
-            block_node, children: children, wrapper: wrapper
-          )
+          BlockTextScanner.scan(block_node, children:, wrapper:)
         end
 
         # Phlex's tag API emits the first positional argument as text
diff --git a/test/a11y/lint/phlex_runner/test_phlex_call.rb b/test/a11y/lint/phlex_runner/test_phlex_call.rb
index bb2f088..4679a5d 100644
--- a/test/a11y/lint/phlex_runner/test_phlex_call.rb
+++ b/test/a11y/lint/phlex_runner/test_phlex_call.rb
@@ -76,16 +76,6 @@ def test_forwarded_block_false_when_no_block
           refute_predicate(wrap("img(src: 'x.jpg')"), :forwarded_block?)
         end
 
-        def test_block_children_returns_children_when_block_present
-          call = wrap("div { p { 'hi' } }")
-
-          refute_empty(call.block_children)
-        end
-
-        def test_block_children_empty_when_no_block
-          assert_empty(wrap("img(src: 'x.jpg')").block_children)
-        end
-
         def test_block_has_text_true_for_explicit_string
           assert(wrap("a(href: '/x') { 'click' }").block_has_text?)
         end

From 50824e7ba95d741e22835c0241429f0b2c6c87af Mon Sep 17 00:00:00 2001
From: Abdullah Hashim <abdul@hey.com>
Date: Wed, 6 May 2026 07:42:19 -0400
Subject: [PATCH 4/7] wip

---
 lib/a11y/lint/phlex_runner.rb                 |  6 ++++--
 .../lint/phlex_runner/block_text_scanner.rb   | 20 +++++++++----------
 lib/a11y/lint/phlex_runner/phlex_call.rb      |  4 ++--
 3 files changed, 15 insertions(+), 15 deletions(-)

diff --git a/lib/a11y/lint/phlex_runner.rb b/lib/a11y/lint/phlex_runner.rb
index a0ef735..ec44c21 100644
--- a/lib/a11y/lint/phlex_runner.rb
+++ b/lib/a11y/lint/phlex_runner.rb
@@ -91,9 +91,11 @@ def gather_children(parent, result)
 
       def gather_tag_child(call, result)
         kids = collect_block_children(call.block_node)
-        accessible_name_wrapper = accessible_name_wrapper_tag?(call)
         has_text = call.arg_has_text? ||
-                   call.block_has_text?(kids, wrapper: accessible_name_wrapper)
+                   call.block_has_text?(
+                     kids,
+                     accessible_name_wrapper: accessible_name_wrapper_tag?(call)
+                   )
         tag = PhlexNode.build_tag(
           call.call_node, children: kids, text_content: has_text,
                           configuration: configuration
diff --git a/lib/a11y/lint/phlex_runner/block_text_scanner.rb b/lib/a11y/lint/phlex_runner/block_text_scanner.rb
index 88a8a40..3244d85 100644
--- a/lib/a11y/lint/phlex_runner/block_text_scanner.rb
+++ b/lib/a11y/lint/phlex_runner/block_text_scanner.rb
@@ -22,8 +22,8 @@ class BlockTextScanner
           highlight excerpt
         ].to_set.freeze
 
-        def self.scan(block, children:, wrapper: false)
-          new(block, children:, wrapper:).scan
+        def self.scan(block, children:, accessible_name_wrapper: false)
+          new(block, children:, accessible_name_wrapper:).scan
         end
 
         # Public recognizer for a single Prism node — used by PhlexRunner
@@ -50,10 +50,10 @@ def self.non_blank_string_literal?(node)
           end
         end
 
-        def initialize(block, children:, wrapper: false)
+        def initialize(block, children:, accessible_name_wrapper: false)
           @block = block
           @children = children
-          @wrapper = wrapper
+          @accessible_name_wrapper = accessible_name_wrapper
         end
 
         def scan
@@ -121,13 +121,7 @@ def auto_emitted_call?(call)
 
           name = call.name.to_s
           if PhlexNode.html_tag?(name)
-            # Inside a tag whose class signals an accessible-name wrapper
-            # (e.g. `sr-only`), an ambiguous bare call — name matches an
-            # HTML tag, no args, no block — is treated as a text-emitting
-            # method call rather than an empty HTML element. Matches
-            # author intent for patterns like `span(class: "sr-only") { label }`
-            # where `label` is an instance method, not the `<label>` tag.
-            return @wrapper && bare_call?(call)
+            return accessible_name_wrapper? && bare_call?(call)
           end
           return true if TEXT_CALLS.include?(name)
 
@@ -141,6 +135,10 @@ def bare_call?(call)
           call.arguments.nil? && call.block.nil?
         end
 
+        def accessible_name_wrapper?
+          @accessible_name_wrapper
+        end
+
         def conditional_container?(node)
           node.is_a?(Prism::IfNode) ||
             node.is_a?(Prism::UnlessNode) ||
diff --git a/lib/a11y/lint/phlex_runner/phlex_call.rb b/lib/a11y/lint/phlex_runner/phlex_call.rb
index 16929b0..3a17f7b 100644
--- a/lib/a11y/lint/phlex_runner/phlex_call.rb
+++ b/lib/a11y/lint/phlex_runner/phlex_call.rb
@@ -57,8 +57,8 @@ def forwarded_block?
           block.is_a?(Prism::BlockArgumentNode)
         end
 
-        def block_has_text?(children = [], wrapper: false)
-          BlockTextScanner.scan(block_node, children:, wrapper:)
+        def block_has_text?(children = [], accessible_name_wrapper: false)
+          BlockTextScanner.scan(block_node, children:, accessible_name_wrapper:)
         end
 
         # Phlex's tag API emits the first positional argument as text

From 169d223eef528ec5490251c768b138350458ba93 Mon Sep 17 00:00:00 2001
From: Abdullah Hashim <abdul@hey.com>
Date: Wed, 6 May 2026 09:02:57 -0400
Subject: [PATCH 5/7] wip

---
 CHANGELOG.md                                  |  6 ++-
 lib/a11y/lint/configuration.rb                | 12 ++---
 lib/a11y/lint/erb_element_node.rb             | 10 ++---
 lib/a11y/lint/erb_runner.rb                   | 14 +++---
 lib/a11y/lint/phlex_node.rb                   |  2 +-
 lib/a11y/lint/phlex_runner.rb                 | 14 +++---
 .../lint/phlex_runner/block_text_scanner.rb   | 14 +++---
 lib/a11y/lint/phlex_runner/phlex_call.rb      |  4 +-
 lib/a11y/lint/slim_node.rb                    | 12 ++---
 ...test_anchor_missing_accessible_name_erb.rb |  6 +--
 ...st_anchor_missing_accessible_name_phlex.rb | 14 +++---
 ...est_anchor_missing_accessible_name_slim.rb |  6 +--
 ...test_button_missing_accessible_name_erb.rb |  6 +--
 ...st_button_missing_accessible_name_phlex.rb | 14 +++---
 ...est_button_missing_accessible_name_slim.rb |  6 +--
 ..._button_tag_missing_accessible_name_erb.rb |  6 +--
 ...utton_tag_missing_accessible_name_phlex.rb |  6 +--
 ...button_tag_missing_accessible_name_slim.rb |  6 +--
 ...est_link_to_missing_accessible_name_erb.rb |  6 +--
 ...t_link_to_missing_accessible_name_phlex.rb |  6 +--
 ...st_link_to_missing_accessible_name_slim.rb |  6 +--
 test/a11y/lint/test_configuration.rb          | 44 +++++++++----------
 test/fixtures/dummy_app/.a11y-lint.yml        | 43 +++++++++++++-----
 .../fixtures/dummy_app/app/views/home_view.rb |  6 +--
 24 files changed, 147 insertions(+), 122 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index cd2c9ce..302a026 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,9 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- **Breaking:** `.a11y-lint.yml`'s `hidden_wrapper_classes` key is now `inaccessible_wrapper_classes`. Behavior is unchanged. The rename mirrors the new `accessible_wrapper_classes` (below) and frames both keys around the same property — whether wrapped content is exposed to assistive technology. Projects with `hidden_wrapper_classes` in their config need to rename it
+
 ### Added
 
-- `.a11y-lint.yml` now supports a top-level `accessible_name_wrapper_classes` list. Inside Phlex `a`/`button` tags whose direct child has a matching class, `AnchorMissingAccessibleName` and `ButtonMissingAccessibleName` treat ambiguous bare calls — receiverless calls whose name matches an HTML tag, with no arguments and no block — as text-emitting method calls rather than empty HTML elements. Fixes false positives on the `span(class: "sr-only") { label }` pattern, where `label` is an instance method that parses as a `Prism::CallNode` indistinguishable from the `<label>` HTML tag. Opt-in; default is no special handling. Distinct from `hidden_wrapper_classes` (which excludes the wrapper from the parent's accessible name); a wrapper-class list member here stays in the parent's children with `text_content?` set to true. No-op in the Slim and ERB pipelines, which have no analogous ambiguity
+- `.a11y-lint.yml` now supports a top-level `accessible_wrapper_classes` list. Inside Phlex `a`/`button` tags whose direct child has a matching class, `AnchorMissingAccessibleName` and `ButtonMissingAccessibleName` treat ambiguous bare calls — receiverless calls whose name matches an HTML tag, with no arguments and no block — as text-emitting method calls rather than empty HTML elements. Fixes false positives on the `span(class: "sr-only") { label }` pattern, where `label` is an instance method that parses as a `Prism::CallNode` indistinguishable from the `<label>` HTML tag. Opt-in; default is no special handling. Distinct from `inaccessible_wrapper_classes` (which excludes the wrapper from the parent's accessible name); a wrapper-class list member here stays in the parent's children with `text_content?` set to true. No-op in the Slim and ERB pipelines, which have no analogous ambiguity
 
 ## [0.14.2] - 2026-05-05
 
diff --git a/lib/a11y/lint/configuration.rb b/lib/a11y/lint/configuration.rb
index f0cff1c..d92ea7f 100644
--- a/lib/a11y/lint/configuration.rb
+++ b/lib/a11y/lint/configuration.rb
@@ -42,14 +42,14 @@ def enabled?(rule_name)
         @config.dig(rule_name, "Enabled") != false
       end
 
-      def hidden_wrapper_classes
-        @hidden_wrapper_classes ||=
-          Array(@config["hidden_wrapper_classes"]).map(&:to_s).freeze
+      def inaccessible_wrapper_classes
+        @inaccessible_wrapper_classes ||=
+          Array(@config["inaccessible_wrapper_classes"]).map(&:to_s).freeze
       end
 
-      def accessible_name_wrapper_classes
-        @accessible_name_wrapper_classes ||=
-          Array(@config["accessible_name_wrapper_classes"]).map(&:to_s).freeze
+      def accessible_wrapper_classes
+        @accessible_wrapper_classes ||=
+          Array(@config["accessible_wrapper_classes"]).map(&:to_s).freeze
       end
 
       def enabled_rules
diff --git a/lib/a11y/lint/erb_element_node.rb b/lib/a11y/lint/erb_element_node.rb
index 50062c5..6d40d2f 100644
--- a/lib/a11y/lint/erb_element_node.rb
+++ b/lib/a11y/lint/erb_element_node.rb
@@ -47,7 +47,7 @@ def block_has_text_children?
       end
 
       def text_content?
-        return false if hidden_wrapper?(@nokogiri_node)
+        return false if inaccessible_wrapper?(@nokogiri_node)
 
         visible_text_or_output?(@nokogiri_node)
       end
@@ -58,7 +58,7 @@ def text_content?
       # to the accessible name.
       def children
         @nokogiri_node.element_children.filter_map do |child|
-          next if hidden_wrapper?(child)
+          next if inaccessible_wrapper?(child)
 
           ErbElementNode.new(
             nokogiri_node: child, line: child.line,
@@ -70,7 +70,7 @@ def children
       private
 
       def visible_text_or_output?(node)
-        return false if hidden_wrapper?(node)
+        return false if inaccessible_wrapper?(node)
         return true if own_text_or_marker?(node)
 
         node.element_children.any? { |c| visible_text_or_output?(c) }
@@ -86,8 +86,8 @@ def own_text_or_marker?(node)
         end
       end
 
-      def hidden_wrapper?(node)
-        classes = configuration.hidden_wrapper_classes
+      def inaccessible_wrapper?(node)
+        classes = configuration.inaccessible_wrapper_classes
         return false if classes.empty?
 
         node_classes(node).any? { |klass| classes.include?(klass) }
diff --git a/lib/a11y/lint/erb_runner.rb b/lib/a11y/lint/erb_runner.rb
index 43ebb98..edad607 100644
--- a/lib/a11y/lint/erb_runner.rb
+++ b/lib/a11y/lint/erb_runner.rb
@@ -98,7 +98,7 @@ def visible_codes_and_text(block_content)
         indexed_codes = []
         html = indexed_marker_html(block_content, indexed_codes)
         fragment = Nokogiri::HTML4::DocumentFragment.parse(html)
-        strip_hidden_wrappers!(fragment)
+        strip_inaccessible_wrappers!(fragment)
 
         remaining = fragment.to_html
         visible_codes = indexed_codes.each_with_index.filter_map do |code, i|
@@ -118,23 +118,23 @@ def non_marker_text?(html)
         !html.gsub(/#{ERB_OUTPUT_MARKER}\d+_/, "").strip.empty?
       end
 
-      def strip_hidden_wrappers!(node)
-        return if configuration.hidden_wrapper_classes.empty?
+      def strip_inaccessible_wrappers!(node)
+        return if configuration.inaccessible_wrapper_classes.empty?
 
         node.element_children.each do |child|
-          if hidden_wrapper_element?(child)
+          if inaccessible_wrapper_element?(child)
             child.remove
           else
-            strip_hidden_wrappers!(child)
+            strip_inaccessible_wrappers!(child)
           end
         end
       end
 
-      def hidden_wrapper_element?(node)
+      def inaccessible_wrapper_element?(node)
         value = node.attributes["class"]&.value
         return false unless value.is_a?(String)
 
-        classes = configuration.hidden_wrapper_classes
+        classes = configuration.inaccessible_wrapper_classes
         value.split.any? { |klass| classes.include?(klass) }
       end
 
diff --git a/lib/a11y/lint/phlex_node.rb b/lib/a11y/lint/phlex_node.rb
index 8313387..80e71f0 100644
--- a/lib/a11y/lint/phlex_node.rb
+++ b/lib/a11y/lint/phlex_node.rb
@@ -90,7 +90,7 @@ def self.build_helper(
       # Misses array form (`class: ["sr-only", other]`), interpolation
       # (`class: "sr-only #{foo}"`), helper-wrapped (`class: cn("sr-only")`),
       # and computed values (`class: some_method`). Wrapper-class config
-      # (`hidden_wrapper_classes`, `accessible_name_wrapper_classes`)
+      # (`inaccessible_wrapper_classes`, `accessible_wrapper_classes`)
       # therefore only matches authors who write a single static literal.
       def self.kwarg_class_values(call_node)
         return [] unless call_node.arguments
diff --git a/lib/a11y/lint/phlex_runner.rb b/lib/a11y/lint/phlex_runner.rb
index ec44c21..1f5c4a0 100644
--- a/lib/a11y/lint/phlex_runner.rb
+++ b/lib/a11y/lint/phlex_runner.rb
@@ -94,23 +94,23 @@ def gather_tag_child(call, result)
         has_text = call.arg_has_text? ||
                    call.block_has_text?(
                      kids,
-                     accessible_name_wrapper: accessible_name_wrapper_tag?(call)
+                     accessible_wrapper: accessible_wrapper_tag?(call)
                    )
         tag = PhlexNode.build_tag(
           call.call_node, children: kids, text_content: has_text,
                           configuration: configuration
         )
         check_node(tag)
-        result << tag unless hidden_wrapper_tag?(call)
+        result << tag unless inaccessible_wrapper_tag?(call)
       end
 
-      def hidden_wrapper_tag?(call)
-        wrapper_class_match?(call, configuration.hidden_wrapper_classes)
+      def inaccessible_wrapper_tag?(call)
+        wrapper_class_match?(call, configuration.inaccessible_wrapper_classes)
       end
 
-      def accessible_name_wrapper_tag?(call)
+      def accessible_wrapper_tag?(call)
         wrapper_class_match?(
-          call, configuration.accessible_name_wrapper_classes
+          call, configuration.accessible_wrapper_classes
         )
       end
 
@@ -144,7 +144,7 @@ def visit_helper_block_child(child, codes)
       end
 
       def handle_call_block_child(child_call, codes)
-        return false if child_call.tag? && hidden_wrapper_tag?(child_call)
+        return false if child_call.tag? && inaccessible_wrapper_tag?(child_call)
         return true if tag_call_has_text_block?(child_call)
         return false if child_call.tag?
 
diff --git a/lib/a11y/lint/phlex_runner/block_text_scanner.rb b/lib/a11y/lint/phlex_runner/block_text_scanner.rb
index 3244d85..ca87849 100644
--- a/lib/a11y/lint/phlex_runner/block_text_scanner.rb
+++ b/lib/a11y/lint/phlex_runner/block_text_scanner.rb
@@ -22,8 +22,8 @@ class BlockTextScanner
           highlight excerpt
         ].to_set.freeze
 
-        def self.scan(block, children:, accessible_name_wrapper: false)
-          new(block, children:, accessible_name_wrapper:).scan
+        def self.scan(block, children:, accessible_wrapper: false)
+          new(block, children:, accessible_wrapper:).scan
         end
 
         # Public recognizer for a single Prism node — used by PhlexRunner
@@ -50,10 +50,10 @@ def self.non_blank_string_literal?(node)
           end
         end
 
-        def initialize(block, children:, accessible_name_wrapper: false)
+        def initialize(block, children:, accessible_wrapper: false)
           @block = block
           @children = children
-          @accessible_name_wrapper = accessible_name_wrapper
+          @accessible_wrapper = accessible_wrapper
         end
 
         def scan
@@ -121,7 +121,7 @@ def auto_emitted_call?(call)
 
           name = call.name.to_s
           if PhlexNode.html_tag?(name)
-            return accessible_name_wrapper? && bare_call?(call)
+            return accessible_wrapper? && bare_call?(call)
           end
           return true if TEXT_CALLS.include?(name)
 
@@ -135,8 +135,8 @@ def bare_call?(call)
           call.arguments.nil? && call.block.nil?
         end
 
-        def accessible_name_wrapper?
-          @accessible_name_wrapper
+        def accessible_wrapper?
+          @accessible_wrapper
         end
 
         def conditional_container?(node)
diff --git a/lib/a11y/lint/phlex_runner/phlex_call.rb b/lib/a11y/lint/phlex_runner/phlex_call.rb
index 3a17f7b..907d155 100644
--- a/lib/a11y/lint/phlex_runner/phlex_call.rb
+++ b/lib/a11y/lint/phlex_runner/phlex_call.rb
@@ -57,8 +57,8 @@ def forwarded_block?
           block.is_a?(Prism::BlockArgumentNode)
         end
 
-        def block_has_text?(children = [], accessible_name_wrapper: false)
-          BlockTextScanner.scan(block_node, children:, accessible_name_wrapper:)
+        def block_has_text?(children = [], accessible_wrapper: false)
+          BlockTextScanner.scan(block_node, children:, accessible_wrapper:)
         end
 
         # Phlex's tag API emits the first positional argument as text
diff --git a/lib/a11y/lint/slim_node.rb b/lib/a11y/lint/slim_node.rb
index c1ddc15..1387932 100644
--- a/lib/a11y/lint/slim_node.rb
+++ b/lib/a11y/lint/slim_node.rb
@@ -91,7 +91,7 @@ def parse_call_node
 
       def collect_output_codes(sexp)
         return [] unless sexp.is_a?(Array)
-        return [] if hidden_wrapper_sexp?(sexp)
+        return [] if inaccessible_wrapper_sexp?(sexp)
         return [sexp[3]] if slim_output_sexp?(sexp)
 
         sexp.flat_map { |child| collect_output_codes(child) }
@@ -103,7 +103,7 @@ def slim_output_sexp?(sexp)
 
       def block_text_content?(sexp)
         return false unless sexp.is_a?(Array)
-        return false if hidden_wrapper_sexp?(sexp)
+        return false if inaccessible_wrapper_sexp?(sexp)
         return true if slim_text_sexp?(sexp) || html_tag_sexp?(sexp)
 
         sexp.any? { |child| block_text_content?(child) }
@@ -111,18 +111,18 @@ def block_text_content?(sexp)
 
       def text_or_output?(sexp)
         return false unless sexp.is_a?(Array)
-        return false if hidden_wrapper_sexp?(sexp)
+        return false if inaccessible_wrapper_sexp?(sexp)
         return true if slim_text_sexp?(sexp) || slim_output_sexp?(sexp)
 
         sexp.any? { |child| text_or_output?(child) }
       end
 
-      def hidden_wrapper_sexp?(sexp)
+      def inaccessible_wrapper_sexp?(sexp)
         return false unless html_tag_sexp?(sexp)
-        return false if configuration.hidden_wrapper_classes.empty?
+        return false if configuration.inaccessible_wrapper_classes.empty?
 
         class_values(sexp[3]).any? do |klass|
-          configuration.hidden_wrapper_classes.include?(klass)
+          configuration.inaccessible_wrapper_classes.include?(klass)
         end
       end
 
diff --git a/test/a11y/lint/rules/robust/test_anchor_missing_accessible_name_erb.rb b/test/a11y/lint/rules/robust/test_anchor_missing_accessible_name_erb.rb
index 37746af..edcb66a 100644
--- a/test/a11y/lint/rules/robust/test_anchor_missing_accessible_name_erb.rb
+++ b/test/a11y/lint/rules/robust/test_anchor_missing_accessible_name_erb.rb
@@ -126,7 +126,7 @@ def test_sets_filename_on_offense
           )
         end
 
-        def test_anchor_with_hidden_wrapper_text_passes_by_default
+        def test_anchor_with_inaccessible_wrapper_text_passes_by_default
           source = <<~ERB
             <a href="/path">
               <span class="popover">Move</span>
@@ -139,7 +139,7 @@ def test_anchor_with_hidden_wrapper_text_passes_by_default
           assert_empty(offenses)
         end
 
-        def test_anchor_with_hidden_wrapper_text_reports_when_configured
+        def test_anchor_with_inaccessible_wrapper_text_reports_when_configured
           source = <<~ERB
             <a href="/path">
               <span class="popover">Move</span>
@@ -147,7 +147,7 @@ def test_anchor_with_hidden_wrapper_text_reports_when_configured
             </a>
           ERB
           configuration = Configuration.new(
-            "hidden_wrapper_classes" => ["popover"]
+            "inaccessible_wrapper_classes" => ["popover"]
           )
 
           offenses = run_linter(source, configuration:)
diff --git a/test/a11y/lint/rules/robust/test_anchor_missing_accessible_name_phlex.rb b/test/a11y/lint/rules/robust/test_anchor_missing_accessible_name_phlex.rb
index 0031469..0c7a220 100644
--- a/test/a11y/lint/rules/robust/test_anchor_missing_accessible_name_phlex.rb
+++ b/test/a11y/lint/rules/robust/test_anchor_missing_accessible_name_phlex.rb
@@ -266,7 +266,7 @@ def view_template
           assert_equal("app/views/index_view.rb", offenses[0].filename)
         end
 
-        def test_anchor_with_hidden_wrapper_text_passes_by_default
+        def test_anchor_with_inaccessible_wrapper_text_passes_by_default
           source = <<~RUBY
             class TestView < Phlex::HTML
               def view_template
@@ -677,7 +677,7 @@ def view_template
           assert_empty(offenses)
         end
 
-        def test_anchor_with_hidden_wrapper_text_reports_when_configured
+        def test_anchor_with_inaccessible_wrapper_text_reports_when_configured
           source = <<~RUBY
             class TestView < Phlex::HTML
               def view_template
@@ -689,7 +689,7 @@ def view_template
             end
           RUBY
           configuration = Configuration.new(
-            "hidden_wrapper_classes" => ["popover"]
+            "inaccessible_wrapper_classes" => ["popover"]
           )
 
           offenses = run_linter(source, configuration:)
@@ -730,7 +730,7 @@ def view_template
             end
           RUBY
           configuration = Configuration.new(
-            "accessible_name_wrapper_classes" => ["sr-only"]
+            "accessible_wrapper_classes" => ["sr-only"]
           )
 
           offenses = run_linter(source, configuration:)
@@ -749,7 +749,7 @@ def view_template
             end
           RUBY
           configuration = Configuration.new(
-            "accessible_name_wrapper_classes" => ["sr-only"]
+            "accessible_wrapper_classes" => ["sr-only"]
           )
 
           offenses = run_linter(source, configuration:)
@@ -757,7 +757,7 @@ def view_template
           assert_empty(offenses)
         end
 
-        def test_anchor_with_sr_only_in_hidden_wrapper_classes_still_reports
+        def test_sr_only_in_inaccessible_wrapper_classes_still_reports
           source = <<~RUBY
             class TestView < Phlex::HTML
               def view_template
@@ -769,7 +769,7 @@ def view_template
             end
           RUBY
           configuration = Configuration.new(
-            "hidden_wrapper_classes" => ["sr-only"]
+            "inaccessible_wrapper_classes" => ["sr-only"]
           )
 
           offenses = run_linter(source, configuration:)
diff --git a/test/a11y/lint/rules/robust/test_anchor_missing_accessible_name_slim.rb b/test/a11y/lint/rules/robust/test_anchor_missing_accessible_name_slim.rb
index 310d289..2dc64f9 100644
--- a/test/a11y/lint/rules/robust/test_anchor_missing_accessible_name_slim.rb
+++ b/test/a11y/lint/rules/robust/test_anchor_missing_accessible_name_slim.rb
@@ -138,7 +138,7 @@ def test_sets_filename_on_offense
           )
         end
 
-        def test_anchor_with_hidden_wrapper_text_passes_by_default
+        def test_anchor_with_inaccessible_wrapper_text_passes_by_default
           source = <<~SLIM.chomp
             a href="/path"
               span.popover Move
@@ -150,14 +150,14 @@ def test_anchor_with_hidden_wrapper_text_passes_by_default
           assert_empty(offenses)
         end
 
-        def test_anchor_with_hidden_wrapper_text_reports_when_configured
+        def test_anchor_with_inaccessible_wrapper_text_reports_when_configured
           source = <<~SLIM.chomp
             a href="/path"
               span.popover Move
               img src="icon.svg"
           SLIM
           configuration = Configuration.new(
-            "hidden_wrapper_classes" => ["popover"]
+            "inaccessible_wrapper_classes" => ["popover"]
           )
 
           offenses = run_linter(source, configuration:)
diff --git a/test/a11y/lint/rules/robust/test_button_missing_accessible_name_erb.rb b/test/a11y/lint/rules/robust/test_button_missing_accessible_name_erb.rb
index ba25f01..3a43858 100644
--- a/test/a11y/lint/rules/robust/test_button_missing_accessible_name_erb.rb
+++ b/test/a11y/lint/rules/robust/test_button_missing_accessible_name_erb.rb
@@ -128,7 +128,7 @@ def test_sets_filename_on_offense
           )
         end
 
-        def test_button_with_hidden_wrapper_text_passes_by_default
+        def test_button_with_inaccessible_wrapper_text_passes_by_default
           source = <<~ERB
             <button type="button">
               <span class="popover">Move</span>
@@ -141,7 +141,7 @@ def test_button_with_hidden_wrapper_text_passes_by_default
           assert_empty(offenses)
         end
 
-        def test_button_with_hidden_wrapper_text_reports_when_configured
+        def test_button_with_inaccessible_wrapper_text_reports_when_configured
           source = <<~ERB
             <button type="button">
               <span class="popover">Move</span>
@@ -149,7 +149,7 @@ def test_button_with_hidden_wrapper_text_reports_when_configured
             </button>
           ERB
           configuration = Configuration.new(
-            "hidden_wrapper_classes" => ["popover"]
+            "inaccessible_wrapper_classes" => ["popover"]
           )
 
           offenses = run_linter(source, configuration:)
diff --git a/test/a11y/lint/rules/robust/test_button_missing_accessible_name_phlex.rb b/test/a11y/lint/rules/robust/test_button_missing_accessible_name_phlex.rb
index 4f109d6..5e2a16f 100644
--- a/test/a11y/lint/rules/robust/test_button_missing_accessible_name_phlex.rb
+++ b/test/a11y/lint/rules/robust/test_button_missing_accessible_name_phlex.rb
@@ -266,7 +266,7 @@ def view_template
           assert_equal("app/views/index_view.rb", offenses[0].filename)
         end
 
-        def test_button_with_hidden_wrapper_text_passes_by_default
+        def test_button_with_inaccessible_wrapper_text_passes_by_default
           source = <<~RUBY
             class TestView < Phlex::HTML
               def view_template
@@ -647,7 +647,7 @@ def view_template
           assert_empty(offenses)
         end
 
-        def test_button_with_hidden_wrapper_text_reports_when_configured
+        def test_button_with_inaccessible_wrapper_text_reports_when_configured
           source = <<~RUBY
             class TestView < Phlex::HTML
               def view_template
@@ -659,7 +659,7 @@ def view_template
             end
           RUBY
           configuration = Configuration.new(
-            "hidden_wrapper_classes" => ["popover"]
+            "inaccessible_wrapper_classes" => ["popover"]
           )
 
           offenses = run_linter(source, configuration:)
@@ -700,7 +700,7 @@ def view_template
             end
           RUBY
           configuration = Configuration.new(
-            "accessible_name_wrapper_classes" => ["sr-only"]
+            "accessible_wrapper_classes" => ["sr-only"]
           )
 
           offenses = run_linter(source, configuration:)
@@ -719,7 +719,7 @@ def view_template
             end
           RUBY
           configuration = Configuration.new(
-            "accessible_name_wrapper_classes" => ["sr-only"]
+            "accessible_wrapper_classes" => ["sr-only"]
           )
 
           offenses = run_linter(source, configuration:)
@@ -727,7 +727,7 @@ def view_template
           assert_empty(offenses)
         end
 
-        def test_button_with_sr_only_in_hidden_wrapper_classes_still_reports
+        def test_sr_only_in_inaccessible_wrapper_classes_still_reports
           source = <<~RUBY
             class TestView < Phlex::HTML
               def view_template
@@ -739,7 +739,7 @@ def view_template
             end
           RUBY
           configuration = Configuration.new(
-            "hidden_wrapper_classes" => ["sr-only"]
+            "inaccessible_wrapper_classes" => ["sr-only"]
           )
 
           offenses = run_linter(source, configuration:)
diff --git a/test/a11y/lint/rules/robust/test_button_missing_accessible_name_slim.rb b/test/a11y/lint/rules/robust/test_button_missing_accessible_name_slim.rb
index d28195e..dd2107b 100644
--- a/test/a11y/lint/rules/robust/test_button_missing_accessible_name_slim.rb
+++ b/test/a11y/lint/rules/robust/test_button_missing_accessible_name_slim.rb
@@ -138,7 +138,7 @@ def test_sets_filename_on_offense
           )
         end
 
-        def test_button_with_hidden_wrapper_text_passes_by_default
+        def test_button_with_inaccessible_wrapper_text_passes_by_default
           source = <<~SLIM.chomp
             button type="button"
               span.popover Move
@@ -150,14 +150,14 @@ def test_button_with_hidden_wrapper_text_passes_by_default
           assert_empty(offenses)
         end
 
-        def test_button_with_hidden_wrapper_text_reports_when_configured
+        def test_button_with_inaccessible_wrapper_text_reports_when_configured
           source = <<~SLIM.chomp
             button type="button"
               span.popover Move
               img src="thumbs-up.svg"
           SLIM
           configuration = Configuration.new(
-            "hidden_wrapper_classes" => ["popover"]
+            "inaccessible_wrapper_classes" => ["popover"]
           )
 
           offenses = run_linter(source, configuration:)
diff --git a/test/a11y/lint/rules/robust/test_button_tag_missing_accessible_name_erb.rb b/test/a11y/lint/rules/robust/test_button_tag_missing_accessible_name_erb.rb
index 97b58e7..083a58d 100644
--- a/test/a11y/lint/rules/robust/test_button_tag_missing_accessible_name_erb.rb
+++ b/test/a11y/lint/rules/robust/test_button_tag_missing_accessible_name_erb.rb
@@ -239,7 +239,7 @@ def test_multiline_button_tag_with_block_and_text_passes
           assert_empty(offenses)
         end
 
-        def test_hidden_wrapper_with_icon_passes_by_default
+        def test_inaccessible_wrapper_with_icon_passes_by_default
           source = <<~ERB
             <%= button_tag(class: "button-icon") do %>
               <div class="popover"><%= t(".move") %></div>
@@ -252,7 +252,7 @@ def test_hidden_wrapper_with_icon_passes_by_default
           assert_empty(offenses)
         end
 
-        def test_hidden_wrapper_with_icon_reports_when_configured
+        def test_inaccessible_wrapper_with_icon_reports_when_configured
           source = <<~ERB
             <%= button_tag(class: "button-icon") do %>
               <div class="popover"><%= t(".move") %></div>
@@ -260,7 +260,7 @@ def test_hidden_wrapper_with_icon_reports_when_configured
             <% end %>
           ERB
           configuration = Configuration.new(
-            "hidden_wrapper_classes" => ["popover"]
+            "inaccessible_wrapper_classes" => ["popover"]
           )
 
           offenses = run_linter(source, configuration:)
diff --git a/test/a11y/lint/rules/robust/test_button_tag_missing_accessible_name_phlex.rb b/test/a11y/lint/rules/robust/test_button_tag_missing_accessible_name_phlex.rb
index a861554..b71dfbf 100644
--- a/test/a11y/lint/rules/robust/test_button_tag_missing_accessible_name_phlex.rb
+++ b/test/a11y/lint/rules/robust/test_button_tag_missing_accessible_name_phlex.rb
@@ -213,7 +213,7 @@ def view_template
           assert_empty(offenses)
         end
 
-        def test_hidden_wrapper_with_icon_passes_by_default
+        def test_inaccessible_wrapper_with_icon_passes_by_default
           source = <<~RUBY
             class TestView < Phlex::HTML
               def view_template
@@ -230,7 +230,7 @@ def view_template
           assert_empty(offenses)
         end
 
-        def test_hidden_wrapper_with_icon_reports_when_configured
+        def test_inaccessible_wrapper_with_icon_reports_when_configured
           source = <<~RUBY
             class TestView < Phlex::HTML
               def view_template
@@ -242,7 +242,7 @@ def view_template
             end
           RUBY
           configuration = Configuration.new(
-            "hidden_wrapper_classes" => ["popover"]
+            "inaccessible_wrapper_classes" => ["popover"]
           )
 
           offenses = run_linter(source, configuration:)
diff --git a/test/a11y/lint/rules/robust/test_button_tag_missing_accessible_name_slim.rb b/test/a11y/lint/rules/robust/test_button_tag_missing_accessible_name_slim.rb
index fef9b31..814073d 100644
--- a/test/a11y/lint/rules/robust/test_button_tag_missing_accessible_name_slim.rb
+++ b/test/a11y/lint/rules/robust/test_button_tag_missing_accessible_name_slim.rb
@@ -266,7 +266,7 @@ def test_button_tag_with_block_without_parens_and_text_passes
           assert_empty(offenses)
         end
 
-        def test_hidden_wrapper_with_icon_passes_by_default
+        def test_inaccessible_wrapper_with_icon_passes_by_default
           source = <<~SLIM.chomp
             = button_tag(class: "button-icon") do
               .popover
@@ -279,7 +279,7 @@ def test_hidden_wrapper_with_icon_passes_by_default
           assert_empty(offenses)
         end
 
-        def test_hidden_wrapper_with_icon_reports_when_configured
+        def test_inaccessible_wrapper_with_icon_reports_when_configured
           source = <<~SLIM.chomp
             = button_tag(class: "button-icon") do
               .popover
@@ -287,7 +287,7 @@ def test_hidden_wrapper_with_icon_reports_when_configured
               = inline_svg("thumbs-up.svg")
           SLIM
           configuration = Configuration.new(
-            "hidden_wrapper_classes" => ["popover"]
+            "inaccessible_wrapper_classes" => ["popover"]
           )
 
           offenses = run_linter(source, configuration:)
diff --git a/test/a11y/lint/rules/robust/test_link_to_missing_accessible_name_erb.rb b/test/a11y/lint/rules/robust/test_link_to_missing_accessible_name_erb.rb
index 71e4a08..1c73ad9 100644
--- a/test/a11y/lint/rules/robust/test_link_to_missing_accessible_name_erb.rb
+++ b/test/a11y/lint/rules/robust/test_link_to_missing_accessible_name_erb.rb
@@ -343,7 +343,7 @@ def test_multiline_link_to_with_block_and_text_passes
           assert_empty(offenses)
         end
 
-        def test_hidden_wrapper_with_icon_passes_by_default
+        def test_inaccessible_wrapper_with_icon_passes_by_default
           source = <<~ERB
             <%= link_to("/path", class: "icon") do %>
               <div class="popover"><%= t(".label") %></div>
@@ -356,7 +356,7 @@ def test_hidden_wrapper_with_icon_passes_by_default
           assert_empty(offenses)
         end
 
-        def test_hidden_wrapper_with_icon_reports_when_configured
+        def test_inaccessible_wrapper_with_icon_reports_when_configured
           source = <<~ERB
             <%= link_to("/path", class: "icon") do %>
               <div class="popover"><%= t(".label") %></div>
@@ -364,7 +364,7 @@ def test_hidden_wrapper_with_icon_reports_when_configured
             <% end %>
           ERB
           configuration = Configuration.new(
-            "hidden_wrapper_classes" => ["popover"]
+            "inaccessible_wrapper_classes" => ["popover"]
           )
 
           offenses = run_linter(source, configuration:)
diff --git a/test/a11y/lint/rules/robust/test_link_to_missing_accessible_name_phlex.rb b/test/a11y/lint/rules/robust/test_link_to_missing_accessible_name_phlex.rb
index 1433823..60c9504 100644
--- a/test/a11y/lint/rules/robust/test_link_to_missing_accessible_name_phlex.rb
+++ b/test/a11y/lint/rules/robust/test_link_to_missing_accessible_name_phlex.rb
@@ -359,7 +359,7 @@ def view_template
           assert_equal("app/views/index_view.rb", offenses[0].filename)
         end
 
-        def test_hidden_wrapper_with_icon_passes_by_default
+        def test_inaccessible_wrapper_with_icon_passes_by_default
           source = <<~RUBY
             class TestView < Phlex::HTML
               def view_template
@@ -376,7 +376,7 @@ def view_template
           assert_empty(offenses)
         end
 
-        def test_hidden_wrapper_with_icon_reports_when_configured
+        def test_inaccessible_wrapper_with_icon_reports_when_configured
           source = <<~RUBY
             class TestView < Phlex::HTML
               def view_template
@@ -388,7 +388,7 @@ def view_template
             end
           RUBY
           configuration = Configuration.new(
-            "hidden_wrapper_classes" => ["popover"]
+            "inaccessible_wrapper_classes" => ["popover"]
           )
 
           offenses = run_linter(source, configuration:)
diff --git a/test/a11y/lint/rules/robust/test_link_to_missing_accessible_name_slim.rb b/test/a11y/lint/rules/robust/test_link_to_missing_accessible_name_slim.rb
index 4811065..50b885e 100644
--- a/test/a11y/lint/rules/robust/test_link_to_missing_accessible_name_slim.rb
+++ b/test/a11y/lint/rules/robust/test_link_to_missing_accessible_name_slim.rb
@@ -354,7 +354,7 @@ def test_multiline_link_to_with_block_and_text_passes
           assert_empty(offenses)
         end
 
-        def test_hidden_wrapper_with_icon_passes_by_default
+        def test_inaccessible_wrapper_with_icon_passes_by_default
           source = <<~SLIM.chomp
             = link_to("/path", class: "icon") do
               .popover
@@ -367,7 +367,7 @@ def test_hidden_wrapper_with_icon_passes_by_default
           assert_empty(offenses)
         end
 
-        def test_hidden_wrapper_with_icon_reports_when_configured
+        def test_inaccessible_wrapper_with_icon_reports_when_configured
           source = <<~SLIM.chomp
             = link_to("/path", class: "icon") do
               .popover
@@ -375,7 +375,7 @@ def test_hidden_wrapper_with_icon_reports_when_configured
               = inline_svg("icon.svg")
           SLIM
           configuration = Configuration.new(
-            "hidden_wrapper_classes" => ["popover"]
+            "inaccessible_wrapper_classes" => ["popover"]
           )
 
           offenses = run_linter(source, configuration:)
diff --git a/test/a11y/lint/test_configuration.rb b/test/a11y/lint/test_configuration.rb
index 6c3776a..70338b3 100644
--- a/test/a11y/lint/test_configuration.rb
+++ b/test/a11y/lint/test_configuration.rb
@@ -63,67 +63,67 @@ def test_load_handles_empty_yaml_file
         end
       end
 
-      def test_hidden_wrapper_classes_defaults_to_empty_array
-        assert_empty(Configuration.new.hidden_wrapper_classes)
+      def test_inaccessible_wrapper_classes_defaults_to_empty_array
+        assert_empty(Configuration.new.inaccessible_wrapper_classes)
       end
 
-      def test_hidden_wrapper_classes_reads_top_level_key
+      def test_inaccessible_wrapper_classes_reads_top_level_key
         config = Configuration.new(
-          "hidden_wrapper_classes" => %w[popover tooltip]
+          "inaccessible_wrapper_classes" => %w[popover tooltip]
         )
 
-        assert_equal(%w[popover tooltip], config.hidden_wrapper_classes)
+        assert_equal(%w[popover tooltip], config.inaccessible_wrapper_classes)
       end
 
-      def test_hidden_wrapper_classes_coerces_entries_to_strings
-        config = Configuration.new("hidden_wrapper_classes" => [:popover])
+      def test_inaccessible_wrapper_classes_coerces_entries_to_strings
+        config = Configuration.new("inaccessible_wrapper_classes" => [:popover])
 
-        assert_equal(["popover"], config.hidden_wrapper_classes)
+        assert_equal(["popover"], config.inaccessible_wrapper_classes)
       end
 
-      def test_hidden_wrapper_classes_load_from_yaml
+      def test_inaccessible_wrapper_classes_load_from_yaml
         Dir.mktmpdir do |dir|
           path = File.join(dir, ".a11y-lint.yml")
-          File.write(path, "hidden_wrapper_classes:\n  - popover\n")
+          File.write(path, "inaccessible_wrapper_classes:\n  - popover\n")
 
           config = Configuration.load(path)
 
-          assert_equal(["popover"], config.hidden_wrapper_classes)
+          assert_equal(["popover"], config.inaccessible_wrapper_classes)
         end
       end
 
-      def test_accessible_name_wrapper_classes_defaults_to_empty_array
-        assert_empty(Configuration.new.accessible_name_wrapper_classes)
+      def test_accessible_wrapper_classes_defaults_to_empty_array
+        assert_empty(Configuration.new.accessible_wrapper_classes)
       end
 
-      def test_accessible_name_wrapper_classes_reads_top_level_key
+      def test_accessible_wrapper_classes_reads_top_level_key
         config = Configuration.new(
-          "accessible_name_wrapper_classes" => %w[sr-only visually-hidden]
+          "accessible_wrapper_classes" => %w[sr-only visually-hidden]
         )
 
         assert_equal(
-          %w[sr-only visually-hidden], config.accessible_name_wrapper_classes
+          %w[sr-only visually-hidden], config.accessible_wrapper_classes
         )
       end
 
-      def test_accessible_name_wrapper_classes_coerces_entries_to_strings
+      def test_accessible_wrapper_classes_coerces_entries_to_strings
         config = Configuration.new(
-          "accessible_name_wrapper_classes" => [:"sr-only"]
+          "accessible_wrapper_classes" => [:"sr-only"]
         )
 
-        assert_equal(["sr-only"], config.accessible_name_wrapper_classes)
+        assert_equal(["sr-only"], config.accessible_wrapper_classes)
       end
 
-      def test_accessible_name_wrapper_classes_load_from_yaml
+      def test_accessible_wrapper_classes_load_from_yaml
         Dir.mktmpdir do |dir|
           path = File.join(dir, ".a11y-lint.yml")
           File.write(
-            path, "accessible_name_wrapper_classes:\n  - sr-only\n"
+            path, "accessible_wrapper_classes:\n  - sr-only\n"
           )
 
           config = Configuration.load(path)
 
-          assert_equal(["sr-only"], config.accessible_name_wrapper_classes)
+          assert_equal(["sr-only"], config.accessible_wrapper_classes)
         end
       end
     end
diff --git a/test/fixtures/dummy_app/.a11y-lint.yml b/test/fixtures/dummy_app/.a11y-lint.yml
index 7261592..f6b40e2 100644
--- a/test/fixtures/dummy_app/.a11y-lint.yml
+++ b/test/fixtures/dummy_app/.a11y-lint.yml
@@ -1,27 +1,48 @@
 # All rules enabled by default.
 # Uncomment to disable a rule:
 #
-# ImgMissingAlt:
+# AnchorMissingAccessibleName:
+#   Enabled: false
+#
+# AreaMissingAlt:
+#   Enabled: false
+#
+# ButtonMissingAccessibleName:
+#   Enabled: false
+#
+# ButtonTagMissingAccessibleName:
+#   Enabled: false
+#
+# ImageSubmitTagMissingAlt:
 #   Enabled: false
 #
 # ImageTagMissingAlt:
 #   Enabled: false
 #
+# ImgMissingAlt:
+#   Enabled: false
+#
+# InputImageMissingAlt:
+#   Enabled: false
+#
+# InputMissingAutocomplete:
+#   Enabled: false
+#
 # LinkToMissingAccessibleName:
 #   Enabled: false
 #
-# ButtonTagMissingAccessibleName:
+# ListInvalidChildren:
+#   Enabled: false
+#
+# SimpleFormInputMissingAccessibleName:
 #   Enabled: false
 
-# Class names that wrap content hidden from assistive technology
-# (e.g. via CSS `visibility: hidden`). Content inside these wrappers
-# does not count toward an element's accessible name.
-hidden_wrapper_classes:
+# Class names that wrap content hidden from assistive technology.
+# Content inside these wrappers does not count toward an element's accessible name.
+inaccessible_wrapper_classes:
   - popover
 
-# Class names that wrap content visible only to assistive technology
-# (e.g. CSS-clipped sr-only spans). Inside Phlex tags whose class
-# matches, ambiguous bare calls (HTML-tag-named, no args, no block)
-# are treated as auto-emitting text rather than empty HTML elements.
-accessible_name_wrapper_classes:
+# Class names that wrap content visible only to assistive technology.
+# Content inside these wrappers counts toward an element's accessible name.
+accessible_wrapper_classes:
   - sr-only
diff --git a/test/fixtures/dummy_app/app/views/home_view.rb b/test/fixtures/dummy_app/app/views/home_view.rb
index 20efc2c..813c1ca 100644
--- a/test/fixtures/dummy_app/app/views/home_view.rb
+++ b/test/fixtures/dummy_app/app/views/home_view.rb
@@ -56,7 +56,7 @@ def view_template(label: "Menu")
     end
 
     # Bad: button_tag block whose only text is inside a hidden wrapper
-    # Needs hidden_wrapper_classes: [popover] config
+    # Needs inaccessible_wrapper_classes: [popover] config
     # (ButtonTagMissingAccessibleName)
     button_tag(class: "button-icon") do
       span(class: "popover") { plain "Move" }
@@ -144,7 +144,7 @@ def view_template(label: "Menu")
     # Good: anchor whose accessible name lives in an sr-only span
     # whose body is an ambiguous bare call (`label` is an instance
     # method, not the `<label>` HTML tag).
-    # Needs accessible_name_wrapper_classes: [sr-only] config.
+    # Needs accessible_wrapper_classes: [sr-only] config.
     a(href: "/back", class: "icon") do
       span(class: "absolute -inset-2.5")
       span(class: "sr-only") { label }
@@ -153,7 +153,7 @@ def view_template(label: "Menu")
 
     # Good: button whose accessible name lives in an sr-only span
     # with the same bare-call shape.
-    # Needs accessible_name_wrapper_classes: [sr-only] config.
+    # Needs accessible_wrapper_classes: [sr-only] config.
     button(class: "icon") do
       span(class: "absolute -inset-2.5")
       span(class: "sr-only") { label }

From 3d2706d14288ddee8e618f0f1cefb098910663fb Mon Sep 17 00:00:00 2001
From: Abdullah Hashim <abdul@hey.com>
Date: Wed, 6 May 2026 09:07:52 -0400
Subject: [PATCH 6/7] wip

---
 CHANGELOG.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 302a026..cb0a045 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
-- **Breaking:** `.a11y-lint.yml`'s `hidden_wrapper_classes` key is now `inaccessible_wrapper_classes`. Behavior is unchanged. The rename mirrors the new `accessible_wrapper_classes` (below) and frames both keys around the same property — whether wrapped content is exposed to assistive technology. Projects with `hidden_wrapper_classes` in their config need to rename it
+- **Breaking:** `.a11y-lint.yml`'s `hidden_wrapper_classes` key is now `inaccessible_wrapper_classes`. Behavior is unchanged. The rename brings the key into line with the new `accessible_wrapper_classes` (below). Projects with `hidden_wrapper_classes` in their config need to rename it
 
 ### Added
 

From 532256440bb251e8583c4f7173c7ad3dd329ed41 Mon Sep 17 00:00:00 2001
From: Abdullah Hashim <abdul@hey.com>
Date: Wed, 6 May 2026 11:14:22 -0400
Subject: [PATCH 7/7] wip

---
 test/fixtures/dummy_app/app/views/home.html.erb  | 2 +-
 test/fixtures/dummy_app/app/views/home.html.slim | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/test/fixtures/dummy_app/app/views/home.html.erb b/test/fixtures/dummy_app/app/views/home.html.erb
index 1255ec8..bf7ffea 100644
--- a/test/fixtures/dummy_app/app/views/home.html.erb
+++ b/test/fixtures/dummy_app/app/views/home.html.erb
@@ -52,7 +52,7 @@
 <% end %>
 
 <!-- Bad: button_tag block whose only text is inside a hidden wrapper -->
-<!-- (ButtonTagMissingAccessibleName, requires hidden_wrapper_classes: [popover]) -->
+<!-- (ButtonTagMissingAccessibleName, requires inaccessible_wrapper_classes: [popover]) -->
 <%= button_tag(class: "button-icon") do %>
   <div class="popover"><%= t(".move") %></div>
   <%= inline_svg("thumbs-up.svg") %>
diff --git a/test/fixtures/dummy_app/app/views/home.html.slim b/test/fixtures/dummy_app/app/views/home.html.slim
index 30344b7..4e17bb7 100644
--- a/test/fixtures/dummy_app/app/views/home.html.slim
+++ b/test/fixtures/dummy_app/app/views/home.html.slim
@@ -48,7 +48,7 @@ area shape="rect" coords="0,0,82,126" href="/sun"
   = image_tag("home.svg", alt: "Home")
 
 / Bad: button_tag block whose only text is inside a hidden wrapper
-/ (ButtonTagMissingAccessibleName, requires hidden_wrapper_classes: [popover])
+/ (ButtonTagMissingAccessibleName, requires inaccessible_wrapper_classes: [popover])
 = button_tag(class: "button-icon") do
   .popover
     = t(".move")