From 4ddbf6d462f8e52dca57c2f1af280a0e38cff670 Mon Sep 17 00:00:00 2001
From: Andrew Moore <andrew@lessthanseventy.com>
Date: Sat, 11 Apr 2026 00:55:28 -0600
Subject: [PATCH] feat: 4 new LiveView rules (#102, #103, #105, #106)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Builds on the LiveViewRules framework shipped in 0.13.0 by adding
four new rules that catch Phoenix-specific a11y anti-patterns
axe-core can't see. Each rule is a single module in
lib/excessibility/live_view_rules/rules/, auto-discovered at compile
time.

- :toggle_missing_aria_state (#102)
  Parses the serialized JSON in phx-click to detect
  JS.toggle/show/hide operations; flags triggers that have no
  aria-expanded. Surfaces the target id from the JS command in the
  finding message.

- :click_away_without_escape (#103)
  Flags phx-click-away without a matching phx-window-keydown or
  phx-keydown paired with phx-key="Escape". role="dialog" /
  role="alertdialog" are accepted as evidence of keyboard dismissal.

- :debounce_without_live_region (#105)
  Conservative heuristic: flags <input phx-debounce> only when the
  whole snapshot has zero aria-live / role=status|alert|log regions.
  Avoids false positives when an app announces updates somewhere
  else in the page.

- :hidden_form_control_without_aria (#106)
  Flags <input type="checkbox|radio" class="hidden|sr-only"> when
  the wrapping <label> doesn't expose state via aria-checked,
  aria-pressed, role="checkbox" or role="radio".

Also registers discovered rule files as @external_resource so edits
to existing rules trigger recompilation of the scanner module.
(Adding a brand-new rule file still requires touching the scanner or
running mix clean — documented in CHANGELOG.)

The #104 cross-snapshot diffing rule is deliberately left for a
follow-up PR because it requires a different rule protocol (two
snapshots instead of one HTML) and new snapshot-pairing logic in
mix excessibility.

Version stays at 0.13.0 (not yet published to Hex).

Closes #102
Closes #103
Closes #105
Closes #106

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                                  |   8 +-
 README.md                                     |   4 +
 lib/excessibility/live_view_rules.ex          |  11 +-
 .../rules/click_away_without_escape.ex        | 105 ++++++++++++
 .../rules/debounce_without_live_region.ex     |  96 +++++++++++
 .../rules/hidden_form_control_without_aria.ex | 152 ++++++++++++++++++
 .../rules/toggle_missing_aria_state.ex        | 134 +++++++++++++++
 .../rules/click_away_without_escape_test.exs  |  62 +++++++
 .../debounce_without_live_region_test.exs     |  68 ++++++++
 .../hidden_form_control_without_aria_test.exs |  95 +++++++++++
 .../rules/toggle_missing_aria_state_test.exs  |  71 ++++++++
 11 files changed, 801 insertions(+), 5 deletions(-)
 create mode 100644 lib/excessibility/live_view_rules/rules/click_away_without_escape.ex
 create mode 100644 lib/excessibility/live_view_rules/rules/debounce_without_live_region.ex
 create mode 100644 lib/excessibility/live_view_rules/rules/hidden_form_control_without_aria.ex
 create mode 100644 lib/excessibility/live_view_rules/rules/toggle_missing_aria_state.ex
 create mode 100644 test/live_view_rules/rules/click_away_without_escape_test.exs
 create mode 100644 test/live_view_rules/rules/debounce_without_live_region_test.exs
 create mode 100644 test/live_view_rules/rules/hidden_form_control_without_aria_test.exs
 create mode 100644 test/live_view_rules/rules/toggle_missing_aria_state_test.exs

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d51786a..da001a9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -13,8 +13,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Richer `axe-runner.js` output: `final_url` (after redirects), `duration_ms`, `engine.axe_version`, `engine.chromium_version`, `passes_count`, `inapplicable_count`.
 - `mix excessibility.check` gains `--wait-until`, `--tags`, `--timeout`, `--viewport`, `--user-agent` flags.
 - **`Excessibility.LiveViewRules` — LiveView-aware accessibility rules** that complement axe-core on Phoenix-specific patterns. Rules auto-discovered from `lib/excessibility/live_view_rules/rules/`; custom rules registered via `config :excessibility, custom_live_view_rules: [...]`. `mix excessibility` now runs both axe-core AND these rules on each snapshot and fails if either finds issues. Rules are no-ops on HTML without `phx-*` attributes, so the feature is safe on non-Phoenix snapshots.
-- **Rule: `:phx_click_on_non_interactive`** ([#101](https://github.com/lessthanseventy/excessibility/issues/101)) — flags `phx-click` / `phx-click-away` on elements that are not natively keyboard-accessible (anything other than `<a>`/`<button>`/`<input>`/`<select>`/`<textarea>`/`<summary>`/`<details>`, or elements with `tabindex` or an interactive `role`).
 - Config knobs: `:lv_rules_enabled?` (default `true`) and `:lv_rules_disabled` (list of rule ids to skip).
+- **Built-in LiveView rules:**
+  - **`:phx_click_on_non_interactive`** ([#101](https://github.com/lessthanseventy/excessibility/issues/101)) — flags `phx-click` / `phx-click-away` on elements that are not natively keyboard-accessible (anything other than `<a>`/`<button>`/`<input>`/`<select>`/`<textarea>`/`<summary>`/`<details>`, or elements with `tabindex` or an interactive `role`).
+  - **`:toggle_missing_aria_state`** ([#102](https://github.com/lessthanseventy/excessibility/issues/102)) — flags elements whose `phx-click` serializes `JS.toggle/show/hide` but have no `aria-expanded`. Parses the serialized JSON to detect toggle operations and target ids.
+  - **`:click_away_without_escape`** ([#103](https://github.com/lessthanseventy/excessibility/issues/103)) — flags `phx-click-away` without a matching `phx-window-keydown`/`phx-keydown` + `phx-key="Escape"` (or `role="dialog"`), so keyboard users can actually dismiss the overlay.
+  - **`:debounce_without_live_region`** ([#105](https://github.com/lessthanseventy/excessibility/issues/105)) — flags `<input phx-debounce>` when the snapshot has no `aria-live`, `role="status"`, `role="alert"`, or `role="log"` region anywhere. Conservative: only fires when the whole snapshot lacks any live region.
+  - **`:hidden_form_control_without_aria`** ([#106](https://github.com/lessthanseventy/excessibility/issues/106)) — flags `<input type="checkbox|radio">` hidden via `hidden` or `sr-only` when the wrapping `<label>` does not expose state via `aria-checked`, `aria-pressed`, `role="checkbox"`, or `role="radio"`.
+- `Excessibility.LiveViewRules` registers discovered rule files as `@external_resource` so edits to existing rules trigger recompilation of the scanner module.
 
 ### Changed
 - **`Excessibility.AxeRunner` removed and folded into `Excessibility.Scanner`.** The old module was an internal helper; all callers (`mix excessibility`, `mix excessibility.check`, the `a11y_check` MCP tool, snapshot screenshotting) now go through `Scanner.scan/2`. No end-user behavior change for existing Mix task users.
diff --git a/README.md b/README.md
index 4e4b4a3..3656abd 100644
--- a/README.md
+++ b/README.md
@@ -37,6 +37,10 @@ Built-in rules:
 | Rule | What it flags |
 | --- | --- |
 | `:phx_click_on_non_interactive` | `phx-click` / `phx-click-away` on `<div>`, `<li>`, `<span>`, `<tr>`, etc. without `tabindex` or an interactive `role` — visually clickable but unreachable by keyboard |
+| `:toggle_missing_aria_state` | Elements whose `phx-click` uses `JS.toggle/show/hide` but are missing `aria-expanded` — screen readers can't tell whether the target is open or closed |
+| `:click_away_without_escape` | `phx-click-away` with no matching `phx-window-keydown` + `phx-key="Escape"` (or `role="dialog"`) — keyboard users can't dismiss the overlay |
+| `:debounce_without_live_region` | `<input phx-debounce>` when the page has no `aria-live` / `role="status"` region anywhere — screen readers never hear that results updated |
+| `:hidden_form_control_without_aria` | Visually hidden `<input type="checkbox\|radio">` whose wrapping `<label>` doesn't expose state via `aria-checked` or `role="checkbox"`/`"radio"` |
 
 On non-Phoenix HTML (no `phx-*` attributes) these rules are no-ops, so
 enabling them never adds noise for projects that don't use LiveView.
diff --git a/lib/excessibility/live_view_rules.ex b/lib/excessibility/live_view_rules.ex
index 7e1dd2b..584da73 100644
--- a/lib/excessibility/live_view_rules.ex
+++ b/lib/excessibility/live_view_rules.ex
@@ -43,12 +43,15 @@ defmodule Excessibility.LiveViewRules do
   # ── Compile-time rule discovery ────────────────────────────────────
 
   rules_dir = Path.join([__DIR__, "live_view_rules", "rules"])
+  rule_files = rules_dir |> Path.join("*.ex") |> Path.wildcard()
+
+  # Force recompilation of this module whenever an existing rule file
+  # changes. Note: adding a NEW rule file still requires `mix clean` on
+  # this module (or touching it) so the wildcard re-runs.
+  for path <- rule_files, do: @external_resource(path)
 
   rule_modules =
-    rules_dir
-    |> Path.join("*.ex")
-    |> Path.wildcard()
-    |> Enum.map(fn path ->
+    Enum.map(rule_files, fn path ->
       module_name = path |> Path.basename(".ex") |> Macro.camelize()
       Module.concat([Excessibility.LiveViewRules.Rules, module_name])
     end)
diff --git a/lib/excessibility/live_view_rules/rules/click_away_without_escape.ex b/lib/excessibility/live_view_rules/rules/click_away_without_escape.ex
new file mode 100644
index 0000000..cfcc23e
--- /dev/null
+++ b/lib/excessibility/live_view_rules/rules/click_away_without_escape.ex
@@ -0,0 +1,105 @@
+defmodule Excessibility.LiveViewRules.Rules.ClickAwayWithoutEscape do
+  @moduledoc """
+  Flags elements that use `phx-click-away` for dismissal but provide no
+  keyboard equivalent, leaving keyboard and screen-reader users unable
+  to close the overlay.
+
+  ## What's flagged
+
+  An element with `phx-click-away` that is not:
+
+    * carrying a `phx-window-keydown` or `phx-keydown` handler paired
+      with `phx-key="Escape"` on the same element
+    * a dialog (`role="dialog"` or `role="alertdialog"`), which is
+      assumed to manage its own focus and Escape handling
+
+  ## Fix
+
+      <!-- Bad -->
+      <div id="menu" phx-click-away={JS.hide(to: "#menu")}>
+        ...
+      </div>
+
+      <!-- Good -->
+      <div
+        id="menu"
+        phx-click-away={JS.hide(to: "#menu")}
+        phx-window-keydown={JS.hide(to: "#menu")}
+        phx-key="Escape"
+      >
+        ...
+      </div>
+  """
+
+  @behaviour Excessibility.LiveViewRules.Rule
+
+  @dialog_roles ~w(dialog alertdialog)
+
+  @impl true
+  def id, do: :click_away_without_escape
+
+  @impl true
+  def default_enabled?, do: true
+
+  @impl true
+  def check(tree, _opts) do
+    tree
+    |> Floki.find("[phx-click-away]")
+    |> Enum.reject(&has_escape_handling?/1)
+    |> Enum.map(&build_finding/1)
+  end
+
+  # ── Implementation ────────────────────────────────────────────────
+
+  defp has_escape_handling?({_tag, attrs, _children}) do
+    dialog?(attrs) or escape_keydown?(attrs)
+  end
+
+  defp dialog?(attrs) do
+    case find_attr(attrs, "role") do
+      nil -> false
+      role -> role in @dialog_roles
+    end
+  end
+
+  defp escape_keydown?(attrs) do
+    has_keydown? = has_attr?(attrs, "phx-keydown") or has_attr?(attrs, "phx-window-keydown")
+    escape_key? = find_attr(attrs, "phx-key") == "Escape"
+    has_keydown? and escape_key?
+  end
+
+  defp build_finding({tag, attrs, _children} = element) do
+    %{
+      rule: id(),
+      severity: :serious,
+      message:
+        "<#{tag}> uses phx-click-away for dismissal but has no keyboard " <>
+          "equivalent. Keyboard and screen-reader users cannot close this overlay.",
+      element: element |> Floki.raw_html() |> String.slice(0, 300),
+      selector: build_selector(tag, attrs),
+      help:
+        "Add `phx-window-keydown` (or `phx-keydown`) with `phx-key=\"Escape\"` " <>
+          "on the same element, pointing at the same JS command. For modal " <>
+          "dialogs, use `role=\"dialog\"` with proper focus management.",
+      help_url: "https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/"
+    }
+  end
+
+  defp find_attr(attrs, name) do
+    Enum.find_value(attrs, fn
+      {^name, v} -> v
+      _ -> nil
+    end)
+  end
+
+  defp has_attr?(attrs, name) do
+    Enum.any?(attrs, fn {n, _} -> n == name end)
+  end
+
+  defp build_selector(tag, attrs) do
+    case find_attr(attrs, "id") do
+      nil -> tag
+      id -> "#{tag}##{id}"
+    end
+  end
+end
diff --git a/lib/excessibility/live_view_rules/rules/debounce_without_live_region.ex b/lib/excessibility/live_view_rules/rules/debounce_without_live_region.ex
new file mode 100644
index 0000000..f7fc2c8
--- /dev/null
+++ b/lib/excessibility/live_view_rules/rules/debounce_without_live_region.ex
@@ -0,0 +1,96 @@
+defmodule Excessibility.LiveViewRules.Rules.DebounceWithoutLiveRegion do
+  @moduledoc """
+  Flags `<input phx-debounce>` when the snapshot has no ARIA live region
+  anywhere.
+
+  LiveView search-style inputs with `phx-debounce` push updates silently;
+  screen-reader users typing a search term have no idea that results
+  appeared or changed. At minimum, the page should contain an
+  `aria-live` region (or `role="status" | "alert" | "log"`) somewhere
+  the updated results can land.
+
+  ## Detection
+
+  This rule is conservative: it only flags a debounced input when the
+  **entire snapshot** has zero ARIA live regions. If any live region
+  exists, we assume the app is announcing changes correctly. This
+  minimizes false positives at the cost of missing cases where a live
+  region exists but isn't where the results actually render.
+
+  ## Fix
+
+      <!-- Bad -->
+      <input type="search" name="q" phx-debounce="200" />
+      <table><tbody>...results...</tbody></table>
+
+      <!-- Good -->
+      <input type="search" name="q" phx-debounce="200" />
+      <div aria-live="polite">
+        <table><tbody>...results...</tbody></table>
+      </div>
+  """
+
+  @behaviour Excessibility.LiveViewRules.Rule
+
+  @live_region_selectors [
+    "[aria-live]",
+    "[role=\"status\"]",
+    "[role=\"alert\"]",
+    "[role=\"log\"]"
+  ]
+
+  @impl true
+  def id, do: :debounce_without_live_region
+
+  @impl true
+  def default_enabled?, do: true
+
+  @impl true
+  def check(tree, _opts) do
+    if has_live_region?(tree) do
+      []
+    else
+      tree
+      |> Floki.find("input[phx-debounce]")
+      |> Enum.map(&build_finding/1)
+    end
+  end
+
+  # ── Implementation ────────────────────────────────────────────────
+
+  defp has_live_region?(tree) do
+    Enum.any?(@live_region_selectors, fn selector ->
+      tree |> Floki.find(selector) |> Enum.any?()
+    end)
+  end
+
+  defp build_finding({tag, attrs, _children} = element) do
+    %{
+      rule: id(),
+      severity: :moderate,
+      message:
+        "<#{tag}> has phx-debounce but the page has no aria-live region. " <>
+          "Screen readers will not announce result updates when the user types.",
+      element: element |> Floki.raw_html() |> String.slice(0, 300),
+      selector: build_selector(tag, attrs),
+      help:
+        "Wrap the results container in an element with `aria-live=\"polite\"` " <>
+          "or add `role=\"status\"` so assistive tech announces updates.",
+      help_url: "https://www.w3.org/WAI/ARIA/apg/practices/live-regions/"
+    }
+  end
+
+  defp find_attr(attrs, name) do
+    Enum.find_value(attrs, fn
+      {^name, v} -> v
+      _ -> nil
+    end)
+  end
+
+  defp build_selector(tag, attrs) do
+    case find_attr(attrs, "id") do
+      nil -> tag
+      id -> "#{tag}##{id}"
+    end
+  end
+end
diff --git a/lib/excessibility/live_view_rules/rules/hidden_form_control_without_aria.ex b/lib/excessibility/live_view_rules/rules/hidden_form_control_without_aria.ex
new file mode 100644
index 0000000..d55b328
--- /dev/null
+++ b/lib/excessibility/live_view_rules/rules/hidden_form_control_without_aria.ex
@@ -0,0 +1,152 @@
+defmodule Excessibility.LiveViewRules.Rules.HiddenFormControlWithoutAria do
+  @moduledoc """
+  Flags visually hidden `<input type="checkbox">` / `<input type="radio">`
+  elements used as the programmatic backing for custom UI, when the
+  visual replacement does not communicate checked state via ARIA.
+
+  ## What's flagged
+
+  An `<input type="checkbox|radio">` whose `class` attribute contains
+  `hidden` or `sr-only`, whose enclosing `<label>` ancestor (if any)
+  does not carry `aria-checked`, `aria-pressed`, `role="checkbox"`, or
+  `role="radio"`. If no `<label>` wraps the input, the input is flagged
+  because screen readers will see an unlabeled, hidden control.
+
+  This rule is deliberately conservative; the issue tracker notes this
+  pattern is "harder to detect reliably."
+
+  ## Fix
+
+      <!-- Bad -->
+      <label class="chip">
+        <input type="checkbox" class="hidden" name="color[]" value="red" checked />
+        Red
+      </label>
+
+      <!-- Good -->
+      <label class="chip" role="checkbox" aria-checked="true">
+        <input type="checkbox" class="hidden" name="color[]" value="red" checked />
+        Red
+      </label>
+  """
+
+  @behaviour Excessibility.LiveViewRules.Rule
+
+  @hidden_classes ~w(hidden sr-only)
+  @ok_roles ~w(checkbox radio switch)
+
+  @impl true
+  def id, do: :hidden_form_control_without_aria
+
+  @impl true
+  def default_enabled?, do: true
+
+  @impl true
+  def check(tree, _opts) do
+    tree
+    |> Floki.find("input")
+    |> Enum.filter(&hidden_toggle?/1)
+    |> Enum.flat_map(&maybe_finding(&1, tree))
+  end
+
+  # ── Implementation ────────────────────────────────────────────────
+
+  defp hidden_toggle?({"input", attrs, _children}) do
+    type = find_attr(attrs, "type")
+    classes = find_attr(attrs, "class") || ""
+
+    type in ["checkbox", "radio"] and
+      Enum.any?(String.split(classes, ~r/\s+/, trim: true), &(&1 in @hidden_classes))
+  end
+
+  defp hidden_toggle?(_), do: false
+
+  defp maybe_finding({_tag, attrs, _children} = element, tree) do
+    input_id = find_attr(attrs, "id")
+    wrapping = wrapping_label(tree, input_id)
+
+    if wrapping_has_aria?(wrapping) do
+      []
+    else
+      [build_finding(element, attrs, input_id)]
+    end
+  end
+
+  # Look for a <label> that either contains this input or has for=<id>.
+  defp wrapping_label(tree, nil), do: find_parent_label(tree)
+
+  defp wrapping_label(tree, input_id) do
+    case Floki.find(tree, "label[for=\"#{input_id}\"]") do
+      [label | _] -> label
+      [] -> find_parent_label(tree)
+    end
+  end
+
+  # Fallback: check every <label> in the tree that contains a hidden
+  # input. Floki doesn't give us parent pointers, so we approximate by
+  # looking at each label's descendants.
+  defp find_parent_label(tree) do
+    tree
+    |> Floki.find("label")
+    |> Enum.find(fn label ->
+      Enum.any?(Floki.find(label, "input"), &hidden_toggle?/1)
+    end)
+  end
+
+  defp wrapping_has_aria?(nil), do: false
+
+  defp wrapping_has_aria?({_tag, attrs, _children}) do
+    has_attr?(attrs, "aria-checked") or
+      has_attr?(attrs, "aria-pressed") or
+      role_is_ok?(attrs)
+  end
+
+  defp role_is_ok?(attrs) do
+    case find_attr(attrs, "role") do
+      nil -> false
+      role -> role in @ok_roles
+    end
+  end
+
+  defp build_finding({tag, _attrs, _children} = element, attrs, input_id) do
+    target =
+      case input_id do
+        nil -> "(unnamed)"
+        id -> "##{id}"
+      end
+
+    %{
+      rule: id(),
+      severity: :moderate,
+      message:
+        "<#{tag} type=\"#{find_attr(attrs, "type")}\"> #{target} is visually hidden but its " <>
+          "visual replacement does not expose checked state via aria-checked/aria-pressed " <>
+          "or role=\"checkbox\"/\"radio\". Screen-reader users won't know the control is toggled.",
+      element: element |> Floki.raw_html() |> String.slice(0, 300),
+      selector: build_selector(tag, attrs),
+      help:
+        "Either stop hiding the native input (use `opacity: 0` + absolute " <>
+          "positioning with focusability intact) OR add `role=\"checkbox\"` " <>
+          "and `aria-checked` to the visual wrapper and sync them with the hidden input.",
+      help_url: "https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/"
+    }
+  end
+
+  defp find_attr(attrs, name) do
+    Enum.find_value(attrs, fn
+      {^name, v} -> v
+      _ -> nil
+    end)
+  end
+
+  defp has_attr?(attrs, name) do
+    Enum.any?(attrs, fn {n, _} -> n == name end)
+  end
+
+  defp build_selector(tag, attrs) do
+    case find_attr(attrs, "id") do
+      nil -> tag
+      id -> "#{tag}##{id}"
+    end
+  end
+end
diff --git a/lib/excessibility/live_view_rules/rules/toggle_missing_aria_state.ex b/lib/excessibility/live_view_rules/rules/toggle_missing_aria_state.ex
new file mode 100644
index 0000000..de72645
--- /dev/null
+++ b/lib/excessibility/live_view_rules/rules/toggle_missing_aria_state.ex
@@ -0,0 +1,134 @@
+defmodule Excessibility.LiveViewRules.Rules.ToggleMissingAriaState do
+  @moduledoc """
+  Flags elements that use `Phoenix.LiveView.JS.toggle/show/hide` in
+  `phx-click` but do not expose the expand/collapse state to assistive
+  technology.
+
+  LiveView's `JS` commands serialize to a JSON array in the rendered
+  HTML: `phx-click="[[\\"toggle\\",{\\"to\\":\\"#menu\\"}]]"`. This rule
+  parses that JSON, detects toggle/show/hide operations, and verifies
+  that the trigger element carries `aria-expanded`. Missing
+  `aria-controls` is reported in the same finding when the toggle
+  target is known.
+
+  ## What's flagged
+
+  Elements whose `phx-click` contains a `toggle`, `show`, or `hide`
+  operation, and that are missing `aria-expanded`. `aria-haspopup` is
+  not required (not every toggle is a menu or listbox).
+
+  ## Fix
+
+      <!-- Bad -->
+      <div phx-click={JS.toggle(to: "#menu")}>
+        Open menu
+      </div>
+
+      <!-- Good -->
+      <button
+        type="button"
+        phx-click={JS.toggle(to: "#menu")}
+        aria-expanded="false"
+        aria-controls="menu"
+      >
+        Open menu
+      </button>
+  """
+
+  @behaviour Excessibility.LiveViewRules.Rule
+
+  @toggle_ops ~w(toggle show hide)
+
+  @impl true
+  def id, do: :toggle_missing_aria_state
+
+  @impl true
+  def default_enabled?, do: true
+
+  @impl true
+  def check(tree, _opts) do
+    tree
+    |> Floki.find("[phx-click]")
+    |> Enum.flat_map(&maybe_finding/1)
+  end
+
+  # ── Implementation ────────────────────────────────────────────────
+
+  defp maybe_finding({_tag, attrs, _children} = element) do
+    with value when is_binary(value) <- find_attr(attrs, "phx-click"),
+         {:ok, targets} <- toggle_targets(value) do
+      if has_attr?(attrs, "aria-expanded") do
+        []
+      else
+        [build_finding(element, targets)]
+      end
+    else
+      _ -> []
+    end
+  end
+
+  defp toggle_targets(value) do
+    case Jason.decode(value) do
+      {:ok, ops} when is_list(ops) ->
+        targets = extract_toggle_targets(ops)
+        if targets == [], do: :not_a_toggle, else: {:ok, targets}
+
+      _ ->
+        :not_a_toggle
+    end
+  end
+
+  defp extract_toggle_targets(ops) do
+    Enum.flat_map(ops, fn
+      [op, %{"to" => target}] when op in @toggle_ops -> [target]
+      [op, _params] when op in @toggle_ops -> [nil]
+      _ -> []
+    end)
+  end
+
+  defp build_finding({tag, attrs, _children} = element, targets) do
+    %{
+      rule: id(),
+      severity: :serious,
+      message: message(tag, targets),
+      element: element |> Floki.raw_html() |> String.slice(0, 300),
+      selector: build_selector(tag, attrs),
+      help:
+        "Add `aria-expanded` to the trigger (toggle its value in your " <>
+          "event handler). Also set `aria-controls` to the target id, and " <>
+          "`aria-haspopup` if the target is a menu, listbox, or dialog.",
+      help_url: "https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/"
+    }
+  end
+
+  defp message(tag, targets) do
+    target_hint =
+      targets
+      |> Enum.reject(&is_nil/1)
+      |> case do
+        [] -> ""
+        [t | _] -> " (toggles #{t})"
+      end
+
+    "<#{tag}> uses JS.toggle/show/hide#{target_hint} but has no aria-expanded. " <>
+      "Screen readers cannot tell whether the target is open or closed."
+  end
+
+  defp find_attr(attrs, name) do
+    Enum.find_value(attrs, fn
+      {^name, v} -> v
+      _ -> nil
+    end)
+  end
+
+  defp has_attr?(attrs, name) do
+    Enum.any?(attrs, fn {n, _} -> n == name end)
+  end
+
+  defp build_selector(tag, attrs) do
+    case find_attr(attrs, "id") do
+      nil -> tag
+      id -> "#{tag}##{id}"
+    end
+  end
+end
diff --git a/test/live_view_rules/rules/click_away_without_escape_test.exs b/test/live_view_rules/rules/click_away_without_escape_test.exs
new file mode 100644
index 0000000..d7d9977
--- /dev/null
+++ b/test/live_view_rules/rules/click_away_without_escape_test.exs
@@ -0,0 +1,62 @@
+defmodule Excessibility.LiveViewRules.Rules.ClickAwayWithoutEscapeTest do
+  use ExUnit.Case, async: true
+
+  alias Excessibility.LiveViewRules
+
+  @rule_id :click_away_without_escape
+
+  defp findings(html) do
+    LiveViewRules.scan(html, only: [@rule_id]).findings
+  end
+
+  describe "flags missing keyboard dismissal" do
+    test "div with only phx-click-away" do
+      html = ~s(<div id="menu" phx-click-away="close">Panel</div>)
+      assert [finding] = findings(html)
+      assert finding.rule == @rule_id
+      assert finding.severity == :serious
+      assert finding.selector == "div#menu"
+    end
+
+    test "keydown present but phx-key is not Escape" do
+      html = ~s(<div phx-click-away="close" phx-window-keydown="close" phx-key="Enter">Panel</div>)
+      assert [_] = findings(html)
+    end
+
+    test "phx-key=Escape without keydown handler (invalid pairing)" do
+      html = ~s(<div phx-click-away="close" phx-key="Escape">Panel</div>)
+      assert [_] = findings(html)
+    end
+  end
+
+  describe "allows elements with Escape handling" do
+    test "phx-window-keydown + phx-key=Escape" do
+      html = ~s(<div phx-click-away="close" phx-window-keydown="close" phx-key="Escape">Panel</div>)
+      assert [] = findings(html)
+    end
+
+    test "phx-keydown + phx-key=Escape" do
+      html = ~s(<div phx-click-away="close" phx-keydown="close" phx-key="Escape">Panel</div>)
+      assert [] = findings(html)
+    end
+  end
+
+  describe "allows dialog roles" do
+    test "role=dialog" do
+      html = ~s(<div phx-click-away="close" role="dialog">Modal</div>)
+      assert [] = findings(html)
+    end
+
+    test "role=alertdialog" do
+      html = ~s(<div phx-click-away="close" role="alertdialog">Alert</div>)
+      assert [] = findings(html)
+    end
+  end
+
+  describe "does not flag elements without phx-click-away" do
+    test "plain div" do
+      html = ~s(<div>Plain</div>)
+      assert [] = findings(html)
+    end
+  end
+end
diff --git a/test/live_view_rules/rules/debounce_without_live_region_test.exs b/test/live_view_rules/rules/debounce_without_live_region_test.exs
new file mode 100644
index 0000000..810818f
--- /dev/null
+++ b/test/live_view_rules/rules/debounce_without_live_region_test.exs
@@ -0,0 +1,68 @@
+defmodule Excessibility.LiveViewRules.Rules.DebounceWithoutLiveRegionTest do
+  use ExUnit.Case, async: true
+
+  alias Excessibility.LiveViewRules
+
+  @rule_id :debounce_without_live_region
+
+  defp findings(html) do
+    LiveViewRules.scan(html, only: [@rule_id]).findings
+  end
+
+  describe "flags debounced inputs when no live region exists" do
+    test "search input without any aria-live anywhere" do
+      html = """
+      <html><body>
+        <input type="search" name="q" phx-debounce="200" />
+        <table><tbody><tr><td>Result</td></tr></tbody></table>
+      </body></html>
+      """
+
+      assert [finding] = findings(html)
+      assert finding.rule == @rule_id
+      assert finding.severity == :moderate
+      assert finding.message =~ "aria-live"
+    end
+
+    test "input with phx-debounce blur" do
+      html = ~s(<input type="text" name="q" phx-debounce="blur" />)
+      assert [_] = findings(html)
+    end
+  end
+
+  describe "does not flag when a live region exists" do
+    test "page with aria-live=polite container" do
+      html = """
+      <input type="search" name="q" phx-debounce="200" />
+      <div aria-live="polite"><table><tbody><tr><td>Result</td></tr></tbody></table></div>
+      """
+
+      assert [] = findings(html)
+    end
+
+    test "page with role=status container" do
+      html = """
+      <input type="search" name="q" phx-debounce="200" />
+      <div role="status">Results</div>
+      """
+
+      assert [] = findings(html)
+    end
+
+    test "page with role=alert container" do
+      html = """
+      <input type="search" name="q" phx-debounce="200" />
+      <div role="alert">Updated</div>
+      """
+
+      assert [] = findings(html)
+    end
+  end
+
+  describe "does not flag inputs without phx-debounce" do
+    test "plain input" do
+      html = ~s(<input type="search" name="q" />)
+      assert [] = findings(html)
+    end
+  end
+end
diff --git a/test/live_view_rules/rules/hidden_form_control_without_aria_test.exs b/test/live_view_rules/rules/hidden_form_control_without_aria_test.exs
new file mode 100644
index 0000000..f027be3
--- /dev/null
+++ b/test/live_view_rules/rules/hidden_form_control_without_aria_test.exs
@@ -0,0 +1,95 @@
+defmodule Excessibility.LiveViewRules.Rules.HiddenFormControlWithoutAriaTest do
+  use ExUnit.Case, async: true
+
+  alias Excessibility.LiveViewRules
+
+  @rule_id :hidden_form_control_without_aria
+
+  defp findings(html) do
+    LiveViewRules.scan(html, only: [@rule_id]).findings
+  end
+
+  describe "flags hidden checkboxes/radios without ARIA on wrapper" do
+    test "hidden checkbox inside plain label" do
+      html = """
+      <label for="c1" class="chip">
+        <input type="checkbox" id="c1" class="hidden" name="color[]" value="red" checked />
+        Red
+      </label>
+      """
+
+      assert [finding] = findings(html)
+      assert finding.rule == @rule_id
+      assert finding.severity == :moderate
+      assert finding.message =~ "checkbox"
+    end
+
+    test "hidden radio with sr-only class" do
+      html = """
+      <label for="r1">
+        <input type="radio" id="r1" class="sr-only" name="size" value="s" />
+        Small
+      </label>
+      """
+
+      assert [_] = findings(html)
+    end
+
+    test "hidden checkbox with no label at all" do
+      html = ~s(<input type="checkbox" class="hidden" name="x" value="1" />)
+      assert [_] = findings(html)
+    end
+  end
+
+  describe "allows hidden inputs whose wrapper has ARIA state" do
+    test "label with role=checkbox + aria-checked" do
+      html = """
+      <label for="c1" role="checkbox" aria-checked="true">
+        <input type="checkbox" id="c1" class="hidden" name="color[]" value="red" checked />
+        Red
+      </label>
+      """
+
+      assert [] = findings(html)
+    end
+
+    test "label with role=radio" do
+      html = """
+      <label for="r1" role="radio" aria-checked="false">
+        <input type="radio" id="r1" class="sr-only" name="size" value="s" />
+        Small
+      </label>
+      """
+
+      assert [] = findings(html)
+    end
+
+    test "label with aria-pressed" do
+      html = """
+      <label for="c1" aria-pressed="true">
+        <input type="checkbox" id="c1" class="hidden" name="t" value="1" />
+        Toggle
+      </label>
+      """
+
+      assert [] = findings(html)
+    end
+  end
+
+  describe "does not flag non-hidden or non-toggle inputs" do
+    test "visible checkbox" do
+      html = ~s(<input type="checkbox" name="x" />)
+      assert [] = findings(html)
+    end
+
+    test "hidden text input (not a toggle)" do
+      html = ~s(<input type="text" name="x" class="hidden" value="secret" />)
+      assert [] = findings(html)
+    end
+
+    test "non-interactive hidden div with class hidden" do
+      html = ~s(<div class="hidden">not an input</div>)
+      assert [] = findings(html)
+    end
+  end
+end
diff --git a/test/live_view_rules/rules/toggle_missing_aria_state_test.exs b/test/live_view_rules/rules/toggle_missing_aria_state_test.exs
new file mode 100644
index 0000000..4946e2c
--- /dev/null
+++ b/test/live_view_rules/rules/toggle_missing_aria_state_test.exs
@@ -0,0 +1,71 @@
+defmodule Excessibility.LiveViewRules.Rules.ToggleMissingAriaStateTest do
+  use ExUnit.Case, async: true
+
+  alias Excessibility.LiveViewRules
+
+  @rule_id :toggle_missing_aria_state
+
+  defp findings(html) do
+    LiveViewRules.scan(html, only: [@rule_id]).findings
+  end
+
+  # JS.toggle/show/hide serialize to a JSON array in the HTML attribute.
+  defp js(op, target \\ "#menu"), do: ~s([["#{op}",{"to":"#{target}"}]])
+
+  describe "flags missing aria-expanded" do
+    test "div with JS.toggle and no ARIA" do
+      html = ~s(<div phx-click='#{js("toggle")}'>Open</div>)
+      assert [finding] = findings(html)
+      assert finding.rule == @rule_id
+      assert finding.severity == :serious
+      assert finding.message =~ "aria-expanded"
+      assert finding.message =~ "#menu"
+    end
+
+    test "button with JS.show and no ARIA" do
+      html = ~s(<button phx-click='#{js("show")}'>Show</button>)
+      assert [_] = findings(html)
+    end
+
+    test "button with JS.hide and no ARIA" do
+      html = ~s(<button phx-click='#{js("hide")}'>Hide</button>)
+      assert [_] = findings(html)
+    end
+  end
+
+  describe "allows elements with aria-expanded" do
+    test "div with toggle + aria-expanded" do
+      html = ~s(<div phx-click='#{js("toggle")}' aria-expanded="false">Open</div>)
+      assert [] = findings(html)
+    end
+
+    test "button with toggle + aria-expanded + aria-controls" do
+      html = ~s(<button phx-click='#{js("toggle")}' aria-expanded="false" aria-controls="menu">Open</button>)
+      assert [] = findings(html)
+    end
+  end
+
+  describe "does not flag non-toggle phx-click" do
+    test "plain string phx-click value" do
+      html = ~s(<button phx-click="save">Save</button>)
+      assert [] = findings(html)
+    end
+
+    test "JSON phx-click with a non-toggle op like push" do
+      html = ~s(<button phx-click='[["push",{"event":"save"}]]'>Save</button>)
+      assert [] = findings(html)
+    end
+  end
+
+  describe "multiple elements" do
+    test "reports one finding per offending element" do
+      html = """
+      <div phx-click='#{js("toggle", "#m1")}'>A</div>
+      <div phx-click='#{js("toggle", "#m2")}'>B</div>
+      <div phx-click='#{js("toggle", "#m3")}' aria-expanded="false">C</div>
+      """
+
+      assert [_a, _b] = findings(html)
+    end
+  end
+end