From fd4cded708829b74c33769fabfcf208d6e044658 Mon Sep 17 00:00:00 2001
From: Brian Talbot <hi.talbs@gmail.com>
Date: Tue, 16 Sep 2025 09:17:07 -0400
Subject: [PATCH] Add Input-Based Visually Hidden Utilities (#1454)

* adding input-based visually hidden utilities
* documenting input-based visually hidden utilities
---
 .../docs/docs/utilities/visually-hidden.md    | 57 +++++++++++++++++++
 .../src/styles/utilities/visually-hidden.css  |  4 +-
 2 files changed, 60 insertions(+), 1 deletion(-)

diff --git a/packages/webawesome/docs/docs/utilities/visually-hidden.md b/packages/webawesome/docs/docs/utilities/visually-hidden.md
index 23e608548..8a0b75077 100644
--- a/packages/webawesome/docs/docs/utilities/visually-hidden.md
+++ b/packages/webawesome/docs/docs/utilities/visually-hidden.md
@@ -43,6 +43,63 @@ Adding a label may seem redundant at times, but they're very helpful for unsight
 </wa-card>
 ```
 
+### Visually Hidden Input Parts
+
+Sometimes you want a form control to have a cleaner, more minimal appearance by hiding the `label` or `hint` visually. However, removing these elements entirely would make the form inaccessible to users with assistive devices.
+
+Instead, you can hide them visually while keeping them available to screen readers by adding the `wa-visually-hidden-label` or `wa-visually-hidden-hint` class.
+
+```html {.example}
+<wa-input
+  label="Search Articles"
+  type="search"
+  placeholder="Search for..."
+  class="wa-visually-hidden-label"
+  style="margin-block-end: 1rem;"
+>
+  <wa-icon slot="start" name="magnifying-glass" variant="regular"></wa-icon>
+</wa-input>
+
+<wa-input
+  label="Phone Number"
+  type="tel"
+  hint="We'll send you a verification code"
+  placeholder="(555) 867-5309"
+  class="wa-visually-hidden-hint"
+  style="margin-block-end: 1rem;"
+>
+  <wa-icon slot="start" name="phone" variant="regular"></wa-icon>
+</wa-input>
+
+<wa-select
+  label="Country"
+  hint="Select your country for shipping calculations"
+  class="wa-visually-hidden-hint"
+  style="margin-block-end: 1rem;"
+>
+  <wa-option value="us">United States</wa-option>
+  <wa-option value="ca">Canada</wa-option>
+  <wa-option value="mx">Mexico</wa-option>
+  <wa-option value="uk">United Kingdom</wa-option>
+  <wa-option value="de">Germany</wa-option>
+  <wa-option value="fr">France</wa-option>
+  <wa-option value="wakanda">Wakanda</wa-option>
+  <wa-option value="genovia">Genovia</wa-option>
+  <wa-option value="elbonia">Elbonia</wa-option>
+  <wa-icon slot="start" name="globe" variant="regular"></wa-icon>
+</wa-select>
+
+<wa-input
+  label="Email Address"
+  type="email"
+  hint="We'll never share your email or secret identity"
+  placeholder="e.g. miles.morales@brooklynvisions.edu"
+  class="wa-visually-hidden-label wa-visually-hidden-hint"
+>
+  <wa-icon slot="start" name="envelope" variant="regular"></wa-icon>
+</wa-input>
+```
+
 ### Force Visually Hidden
 
 There are cases where you want to _always_ visually hide certain content, even when it's focused.
diff --git a/packages/webawesome/src/styles/utilities/visually-hidden.css b/packages/webawesome/src/styles/utilities/visually-hidden.css
index 994cea8bc..a2bb193c0 100644
--- a/packages/webawesome/src/styles/utilities/visually-hidden.css
+++ b/packages/webawesome/src/styles/utilities/visually-hidden.css
@@ -1,6 +1,8 @@
 @layer wa-utilities {
   .wa-visually-hidden:not(:focus-within),
-  .wa-visually-hidden-force {
+  .wa-visually-hidden-force,
+  .wa-visually-hidden-hint::part(hint),
+  .wa-visually-hidden-label::part(label) {
     position: absolute !important;
     width: 1px !important;
     height: 1px !important;