From 3262ca1ad0905e3223beae3f86861ddfe6f07a5f Mon Sep 17 00:00:00 2001
From: brenner cruvinel <brennertalks@gmail.com>
Date: Sun, 20 Jul 2025 22:57:14 -0300
Subject: [PATCH 1/2] docs: improve a11y_invalid_attribute warning
 documentation

Enhance documentation for href validation warnings to better explain accessibility concerns and provide clear alternatives. This addresses confusion from issue #15654.

Changes:
- Explain why href="#", empty href, and javascript: URLs are problematic
- Provide practical alternatives (buttons for actions, valid hrefs for navigation)
- Include styling examples for making buttons look like links
- Add development placeholder suggestions
---
 .changeset/improve-a11y-href-docs.md          | 12 ++++
 .../svelte/messages/compile-warnings/a11y.md  | 60 ++++++++++++++++++-
 2 files changed, 70 insertions(+), 2 deletions(-)
 create mode 100644 .changeset/improve-a11y-href-docs.md

diff --git a/.changeset/improve-a11y-href-docs.md b/.changeset/improve-a11y-href-docs.md
new file mode 100644
index 000000000000..88e992b5decd
--- /dev/null
+++ b/.changeset/improve-a11y-href-docs.md
@@ -0,0 +1,12 @@
+---
+"svelte": patch
+---
+
+docs: improve a11y_invalid_attribute warning documentation
+
+Enhance documentation for href validation warnings to better explain accessibility concerns and provide clear alternatives. This addresses confusion from issue #15654.
+
+- Explain why href="#", empty href, and javascript: URLs are problematic for accessibility
+- Provide practical alternatives (buttons for actions, valid hrefs for navigation)
+- Include styling examples for making buttons look like links
+- Add development placeholder suggestions
\ No newline at end of file
diff --git a/packages/svelte/messages/compile-warnings/a11y.md b/packages/svelte/messages/compile-warnings/a11y.md
index a299fa53bc89..9c07feadc7a5 100644
--- a/packages/svelte/messages/compile-warnings/a11y.md
+++ b/packages/svelte/messages/compile-warnings/a11y.md
@@ -189,9 +189,65 @@ Enforce that elements with an interactive role and interactive handlers (mouse o
 
 Enforce that attributes important for accessibility have a valid value. For example, `href` should not be empty, `'#'`, or `javascript:`.
 
+**Why this matters for accessibility:**
+- Screen readers announce links to users, but `href="#"` provides no meaningful destination information
+- Users who navigate by links (a common screen reader navigation method) will encounter unhelpful link descriptions  
+- `href="#"` scrolls to the top of the page when clicked, which can be disorienting
+- Opening in a new tab results in the same page or a blank page
+- These links cannot be bookmarked or shared
+
+**Common mistakes and their solutions:**
+
+```svelte
+<!-- ❌ A11y: '' is not a valid href attribute -->
+<a href="">Click me</a>
+
+<!-- ❌ A11y: '#' is not a valid href attribute -->
+<a href="#">Click me</a>
+
+<!-- ❌ A11y: 'javascript:void(0)' is not a valid href attribute -->
+<a href="javascript:void(0)">Click me</a>
+```
+
+**Better alternatives:**
+
+If you need an element that performs an action (not navigation), use a button:
+```svelte
+<!-- ✅ Correct: Use button for actions -->
+<button type="button" on:click={handleClick}>Click me</button>
+```
+
+If you need a link that looks like a button, style the button appropriately:
+```svelte
+<!-- ✅ Style a button to look like a link if needed -->
+<button type="button" class="link-style" on:click={handleClick}>
+  Click me
+</button>
+
+<style>
+  .link-style {
+    background: none;
+    border: none;
+    color: blue;
+    text-decoration: underline;
+    cursor: pointer;
+    padding: 0;
+    font: inherit;
+  }
+</style>
+```
+
+For actual navigation, provide a valid href:
+```svelte
+<!-- ✅ Correct: Provide meaningful href for navigation -->
+<a href="/page">Go to page</a>
+<a href="#section">Go to section</a>
+```
+
+If you're creating a placeholder link during development:
 ```svelte
-<!-- A11y: '' is not a valid href attribute -->
-<a href="">invalid</a>
+<!-- ✅ Better: Make it clear this is temporary -->
+<a href="/todo" aria-label="Link to be implemented">Coming soon</a>
 ```
 
 ## a11y_label_has_associated_control

From 3bde6d2993eb8dc91f2a4932451fc93fc28a4dec Mon Sep 17 00:00:00 2001
From: Simon H <5968653+dummdidumm@users.noreply.github.com>
Date: Mon, 21 Jul 2025 10:24:35 +0200
Subject: [PATCH 2/2] doesnt need a changeset

---
 .changeset/improve-a11y-href-docs.md | 12 ------------
 1 file changed, 12 deletions(-)
 delete mode 100644 .changeset/improve-a11y-href-docs.md

diff --git a/.changeset/improve-a11y-href-docs.md b/.changeset/improve-a11y-href-docs.md
deleted file mode 100644
index 88e992b5decd..000000000000
--- a/.changeset/improve-a11y-href-docs.md
+++ /dev/null
@@ -1,12 +0,0 @@
----
-"svelte": patch
----
-
-docs: improve a11y_invalid_attribute warning documentation
-
-Enhance documentation for href validation warnings to better explain accessibility concerns and provide clear alternatives. This addresses confusion from issue #15654.
-
-- Explain why href="#", empty href, and javascript: URLs are problematic for accessibility
-- Provide practical alternatives (buttons for actions, valid hrefs for navigation)
-- Include styling examples for making buttons look like links
-- Add development placeholder suggestions
\ No newline at end of file