From 7b95c1fc7443b00811c5aab1a792eebdfff5701d Mon Sep 17 00:00:00 2001
From: Virgil <virgil@lethean.io>
Date: Fri, 3 Apr 2026 18:51:28 +0000
Subject: [PATCH] feat(html): add aria-description helper

Co-Authored-By: Virgil <virgil@lethean.io>
---
 docs/architecture.md |  1 +
 node.go              | 10 ++++++++++
 node_test.go         | 17 +++++++++++++++++
 3 files changed, 28 insertions(+)

diff --git a/docs/architecture.md b/docs/architecture.md
index 74d4a49..f188d73 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -41,6 +41,7 @@ Accessibility-oriented helpers are also provided for common attribute patterns:
 - `AriaCurrent(node, current)`
 - `AriaBusy(node, busy)`
 - `AriaLive(node, live)`
+- `AriaDescription(node, description)`
 - `Role(node, role)`
 - `Lang(node, locale)`
 - `Dir(node, direction)`
diff --git a/node.go b/node.go
index dd8572a..95116b4 100644
--- a/node.go
+++ b/node.go
@@ -233,6 +233,16 @@ func AriaLive(n Node, live string) Node {
 	return Attr(n, "aria-live", live)
 }
 
+// node.go: AriaDescription sets the aria-description attribute on an element node.
+// Example: AriaDescription(El("button"), "Opens the navigation menu").
+// An empty value leaves the node unchanged so callers can opt out cleanly.
+func AriaDescription(n Node, description string) Node {
+	if description == "" {
+		return n
+	}
+	return Attr(n, "aria-description", description)
+}
+
 // node.go: Role sets the role attribute on an element node.
 // Example: Role(El("aside"), "complementary").
 func Role(n Node, role string) Node {
diff --git a/node_test.go b/node_test.go
index 0bae74f..4e0ccc3 100644
--- a/node_test.go
+++ b/node_test.go
@@ -337,6 +337,23 @@ func TestAriaLiveHelper(t *testing.T) {
 	}
 }
 
+func TestAriaDescriptionHelper(t *testing.T) {
+	ctx := NewContext()
+
+	described := AriaDescription(El("button", Raw("menu")), "Opens the navigation menu")
+	gotDescribed := described.Render(ctx)
+	wantDescribed := `<button aria-description="Opens the navigation menu">menu</button>`
+	if gotDescribed != wantDescribed {
+		t.Errorf("AriaDescription() = %q, want %q", gotDescribed, wantDescribed)
+	}
+
+	silent := AriaDescription(El("button", Raw("menu")), "")
+	gotSilent := silent.Render(ctx)
+	if strings.Contains(gotSilent, `aria-description=`) {
+		t.Errorf("AriaDescription(\"\") = %q, want no aria-description attribute", gotSilent)
+	}
+}
+
 func TestRoleHelper(t *testing.T) {
 	ctx := NewContext()
 	node := Role(El("button", Raw("menu")), "navigation")