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

Author: brennercruvinel

.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

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