diff --git a/docs/src/pages/components/PasswordInput.svx b/docs/src/pages/components/PasswordInput.svx
index a67c2099..07dc282d 100644
--- a/docs/src/pages/components/PasswordInput.svx
+++ b/docs/src/pages/components/PasswordInput.svx
@@ -3,8 +3,12 @@
   import Preview from "../../components/Preview.svelte";
 </script>
 
+`PasswordInput` provides a secure text input field with a visibility toggle for password entry. It includes features for validation, warnings, and accessibility.
+
 ## Default
 
+Create a basic password input with a label and placeholder.
+
 <PasswordInput labelText="Password" placeholder="Enter password..." />
 
 ## Custom tooltip alignment
@@ -21,36 +25,54 @@ Set prop `type` to `"text"` to toggle password visibility.
 
 ## Hidden label
 
+Visually hide the label while maintaining accessibility.
+
 <PasswordInput hideLabel labelText="Password" placeholder="Enter password..." />
 
 ## Light variant
 
+Enable the light variant for use on dark backgrounds.
+
 <PasswordInput light labelText="Password" placeholder="Enter password..." />
 
 ## Inline
 
+Display the input with an inline label layout.
+
 <PasswordInput inline labelText="Password" placeholder="Enter password..." />
 
 ## Extra-large size
 
+Use the extra-large size variant for increased visibility.
+
 <PasswordInput size="xl" labelText="Password" placeholder="Enter password..." />
 
 ## Small size
 
+Use the small size variant for compact layouts.
+
 <PasswordInput size="sm" labelText="Password" placeholder="Enter password..." />
 
 ## Invalid state
 
+Display an error message when the input is invalid.
+
 <PasswordInput invalid invalidText="Incorrect user name or password." labelText="Password" placeholder="Enter password..." />
 
 ## Warning state
 
+Show a warning message for non-critical issues.
+
 <PasswordInput warn warnText="Password has been reset." labelText="Password" placeholder="Enter password..." />
 
 ## Disabled state
 
+Disable the input to prevent user interaction.
+
 <PasswordInput disabled labelText="Password" placeholder="Enter password..." />
 
 ## With helper text
 
+Add helper text to provide additional context or instructions.
+
 <PasswordInput helperText="Your password should be hard to guess" labelText="Password" placeholder="Enter password..." />