refactor: cleanup

thedaviddias · Feb 9, 2025 · bca71ce · bca71ce
1 parent bd6c2ac
commit bca71ce
Show file tree

Hide file tree

Showing 9 changed files with 238 additions and 34 deletions.
diff --git a/content/en/patterns/content-management/expandable-text.mdx b/content/en/patterns/content-management/expandable-text.mdx
@@ -61,35 +61,57 @@ Use **Expandable Text** when you need to **manage lengthy content while keeping
 
 ```mermaid
 flowchart TB
-    A[Expandable Text] --> B[Trigger Button]
-    A --> C[Content Section]
-    B -->|Collapsed| D[Label + Icon ▾]
-    B -->|Expanded| E[Label + Icon ▴]
-    C -->|Collapsed by Default| F[Hidden Content]
-    C -->|Expanded| G[Visible Content]
+    subgraph ExpandableText[Expandable Text Component]
+        A[Trigger Button] -->|Collapsed| B[Label + Icon ▾]
+        A -->|Expanded| C[Label + Icon ▴]
+        A -.->|Toggles State| D[Updates aria-expanded]
+
+        subgraph ContentSection[Content Section]
+            E[Hidden Content] -->|Expands| F[Visible Content]
+        end
+    end
 ```
 
-### Component Structure
+### **Component Structure**
 
 1. **Trigger Button**
 
-- Used to expand or collapse the text.
-- Should be clearly labeled (e.g., "Read More" / "Read Less").
-- Includes an icon (▾ for collapsed, ▴ for expanded) to reinforce expand/collapse state.
-- Should indicate the expanded state using `aria-expanded`.
+- Used to **expand or collapse** the text.
+- Should be **clearly labeled** (e.g., "Read More" / "Read Less").
+- Includes an **icon** (▾ for collapsed, ▴ for expanded) to reinforce expand/collapse state.
+- Should indicate the expanded state using **`aria-expanded="true|false"`** for accessibility.
+- Must be **keyboard navigable** (activated via `Enter` or `Space` key).
 
 2. **Content Section**
 
-- Contains the expandable/collapsible text.
-- Hidden by default but fully visible when expanded.
+- Contains the **expandable/collapsible** text.
+- Remains in the **DOM at all times** to maintain accessibility.
+- Should be **visually styled** to clearly indicate expandable behavior.
 
 3. **Hidden Content**
 
-- The part of the text that is initially collapsed.
-- Should remain in the DOM to ensure accessibility.
-- Use `hidden` or `aria-hidden="true"` to prevent screen readers from announcing it prematurely.
-- When expanded, remove `hidden` and update `aria-expanded="true"` on the trigger button.
-- Consider using `max-height` with `overflow: hidden` instead of `display: none` to allow screen readers to detect changes.
+- The part of the text that is **initially collapsed**.
+- Should remain in the DOM but hidden using **`aria-hidden="true"`**.
+- When expanded:
+  - Remove `aria-hidden`.
+  - Set `aria-expanded="true"` on the **Trigger Button**.
+- Consider using **`max-height` with `overflow: hidden`** instead of `display: none` to ensure screen readers detect changes.
+
+4. **Visual States**
+
+- **Collapsed:** Only a preview of the text is visible, with a "Read More" button.
+- **Expanded:** The full content is shown, and the button updates to "Read Less".
+- **Hover & Focus:** The button should have a **clear focus indicator** for accessibility.
+
+### **📌 Summary of Components**
+
+| Component                | Required? | Purpose                                           |
+| ------------------------ | --------- | ------------------------------------------------- |
+| **Trigger Button**       | ✅ Yes    | Expands or collapses the text.                    |
+| **Content Section**      | ✅ Yes    | Contains the expandable/collapsible text.         |
+| **Hidden Content**       | ✅ Yes    | Represents the initially collapsed text.          |
+| **Expand/Collapse Icon** | ❌ No     | Provides a visual cue for expand/collapse states. |
+| **Hover & Focus States** | ✅ Yes    | Ensures proper accessibility and interaction.     |
 
 ## Best Practices
 

diff --git a/content/en/patterns/content-management/popover.mdx b/content/en/patterns/content-management/popover.mdx
@@ -187,8 +187,6 @@ end
 - Allow the popover to display off-screen; always adjust its placement.
 - Fix its position in a way that it overlaps essential navigation elements.
 
-Certainly! Here's a similar section for the popover pattern:
-
 ## Code Examples
 
 ### Method 1: Custom Popover Implementation

diff --git a/content/en/patterns/forms/button.mdx b/content/en/patterns/forms/button.mdx
@@ -119,6 +119,16 @@ end
 - Disabled: Indicates non-interactive state
 - Loading: Shows processing state
 
+### **📌 Summary of Components**
+
+| Component         | Required? | Purpose                                                   |
+| ----------------- | --------- | --------------------------------------------------------- |
+| **Container**     | ✅ Yes    | Wraps all button elements and handles interactions.       |
+| **Label Text**    | ✅ Yes    | Communicates the action that the button performs.         |
+| **Icon**          | ❌ No     | Enhances clarity of the action (typically placed left).   |
+| **Loading State** | ❌ No     | Indicates an ongoing process (e.g., saving, submitting).  |
+| **Visual States** | ✅ Yes    | Defines button interactions (hover, focus, active, etc.). |
+
 ## Best Practices
 
 ### Content

diff --git a/content/en/patterns/forms/form-validation.mdx b/content/en/patterns/forms/form-validation.mdx
@@ -7,8 +7,12 @@ import { Callout } from "nextra/components";
 
 # Form Validation
 
-<Callout type="warning">
-  This page is empty for now. Please help us by
-  [contributing](https://github.com/thedaviddias/ux-patterns-for-developers/blob/main/.github/CONTRIBUTING.md)
-  to add content.
-</Callout>
+## Comparison of Required Field Marking Methods
+
+| Alternative                                          | Description                                                              | Pros ✅                                                                                                                              | Cons ❌                                                                                                                                                                                                            |
+| ---------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **1️⃣ Explicit "Required" Label**                     | Displays **"(Required)"** next to the label.                             | - Works for **all users**, including screen readers and color-blind users.<br/>- No need for extra ARIA attributes.                  | - Takes slightly more space in the UI.                                                                                                                                                                             |
+| **2️⃣ Asterisk (\*) with ARIA Explanation**           | Uses **`*`** but adds an `aria-describedby` explanation.                 | - Keeps UI cleaner while maintaining accessibility.<br/>- Screen readers announce **"Fields marked with an asterisk are required."** | - **Requires additional explanation** (`aria-describedby`).<br/>- **Without the extra message, asterisks alone are not accessible**.                                                                               |
+| **3️⃣ Required Field with Visually Hidden Text**      | Uses a **hidden label** for screen readers but remains minimal visually. | - **Looks clean visually** while still accessible.<br/>- **Screen readers announce it as "Email Required"**.                         | - **Not visible for sighted users** who rely on visual cues.                                                                                                                                                       |
+| **4️⃣ Required Field with an Inline Icon + Tooltip**  | Uses **an asterisk (\*) inside a focusable icon** with a tooltip.        | - **Visually clear** while keeping text minimal.<br/>- Works well when paired with a **tooltip on hover or focus**.                  | - **Requires CSS for styling** (ensuring asterisks are not the only indicator).<br/>- Users **might not see tooltip hints** if they don’t hover over the icon.                                                     |
+| **5️⃣ Required Field with `required` Attribute Only** | Uses only the `required` attribute without visible markers.              | - Works well for **basic validation**.<br/>- Screen readers **will announce the field as required**.                                 | - No **visible indicator for sighted users** before form submission.<br/>- **Errors only appear after submission**, which may confuse users.<br/>- Some browsers may **not enforce required fields consistently**. |
diff --git a/content/en/patterns/forms/input-selection-guide.mdx b/content/en/patterns/forms/input-selection-guide.mdx
@@ -0,0 +1,28 @@
+---
+description: ""
+icon: Text
+---
+
+### When to use Different Types of Text Fields?
+
+```mermaid
+graph TD
+  A[Do users need to enter freeform text?] -->|Yes| B[Does it require a single line?]
+  B -->|Yes| C[Use Standard Text Field `<input type="text">`]
+  B -->|No| D[Use Textarea `<textarea>` for multi-line input]
+
+  A -->|No| E[Is the input structured or formatted?]
+  E -->|Yes| F[Use Specific Input Type]
+  E -->|No| C[Use Standard Text Field `<input type="text">`]
+```
+
+| Feature                         | Standard Text Field (`<input type="text">`) | Email Field (`<input type="email">`) | Password Field (`<input type="password">`) | Search Field (`<input type="search">`) | Telephone Field (`<input type="tel">`) | Number Field (`<input type="number">`) |
+| ------------------------------- | ------------------------------------------- | ------------------------------------ | ------------------------------------------ | -------------------------------------- | -------------------------------------- | -------------------------------------- |
+| **Use Case**                    | General text input                          | Email addresses                      | Password entry                             | Search queries                         | Phone numbers                          | Numeric inputs                         |
+| **Supports Auto-Validation?**   | ❌ No                                       | ✅ Yes (valid email format)          | ❌ No                                      | ❌ No                                  | ❌ No                                  | ✅ Yes (only numeric input allowed)    |
+| **Supports Autofill?**          | ✅ Yes                                      | ✅ Yes                               | ✅ Yes                                     | ✅ Yes                                 | ✅ Yes                                 | ✅ Yes                                 |
+| **Masking Support?**            | ❌ No                                       | ❌ No                                | ✅ Yes (hides input characters)            | ❌ No                                  | ❌ No                                  | ❌ No                                  |
+| **Allows Non-Standard Input?**  | ✅ Yes                                      | ❌ No (only valid email formats)     | ✅ Yes (hidden input)                      | ✅ Yes (optimized for search)          | ✅ Yes (any phone number format)       | ❌ No (only numbers allowed)           |
+| **Special Keyboard on Mobile?** | ❌ No                                       | ✅ Yes (`@` and `.com` on keyboards) | ✅ Yes (secure keyboard)                   | ✅ Yes (optimized for searches)        | ✅ Yes (numeric keyboard)              | ✅ Yes (numeric keyboard)              |
+| **Supports Pattern Matching?**  | ✅ Yes                                      | ✅ Yes                               | ❌ No                                      | ✅ Yes                                 | ✅ Yes                                 | ✅ Yes                                 |
+| **Best For**                    | General-purpose text input                  | Emails                               | Secure password entry                      | Search bars                            | Phone number input                     | Numeric-only input                     |
diff --git a/content/en/patterns/forms/password.mdx b/content/en/patterns/forms/password.mdx
@@ -1,14 +1,143 @@
 ---
 description: "Secure password entry with feedback"
 icon: Lock
+status: complete
 ---
 
-import { Callout } from "nextra/components";
-
 # Password
 
-<Callout type="warning">
-  This page is empty for now. Please help us by
-  [contributing](https://github.com/thedaviddias/ux-patterns-for-developers/blob/main/.github/CONTRIBUTING.md)
-  to add content.
-</Callout>
+import { BrowserSupport } from "@app/_components/browser-support";
+import { BuildEffort } from "@app/_components/build-effort";
+
+## Overview
+
+A **Password Input** is a specialized text field designed to securely collect user passwords. It masks characters to prevent onlookers from reading the input and may include additional security features such as password visibility toggles, strength indicators, and validation requirements.
+
+Password fields are commonly used in **authentication forms, account creation, and security-related input fields** where sensitive data entry is required.
+
+<BuildEffort
+  level="medium"
+  description="Requires input masking, secure storage considerations, optional password strength validation, and accessibility features."
+/>
+
+## Use Cases
+
+### When to use:
+
+- **Login and authentication forms** – Securing user access to accounts.
+- **Account creation and password updates** – Ensuring users create strong, secure passwords.
+- **Two-factor authentication (2FA) or PIN entry** – Protecting access to critical information.
+- **Security-sensitive fields** – Protecting data such as encryption keys or private access codes.
+
+### When not to use:
+
+- **For non-sensitive text input** – Use a standard [text field](/patterns/forms/text-field) instead.
+- **For one-time codes (OTP) or PINs** – Use the [Code Confirmation](/patterns/forms/code-confirmation) pattern instead.
+- **For password confirmation fields** – Use an inline validation approach to avoid user frustration.
+
+## Benefits
+
+- **Enhances security** – Prevents passwords from being visible to onlookers.
+- **Reduces accidental exposure** – Masks characters by default.
+- **Encourages strong password usage** – Supports strength indicators and validation rules.
+- **Supports accessibility** – Allows users to toggle visibility when needed.
+
+## Drawbacks
+
+- **Usability concerns** – Masking can lead to mistyped passwords.
+- **Increased cognitive load** – Users may struggle to recall their input without visibility.
+- **Potential security trade-offs** – Some password visibility toggles may pose a risk if not well-implemented.
+
+## Best Practices
+
+### Content & Usability
+
+**Do's ✅**
+
+- Provide a **password visibility toggle** to allow users to verify input.
+- Display **clear error messages** when password criteria are not met.
+- Indicate **password requirements before users type** to prevent frustration.
+- Offer **password strength indicators** to encourage secure choices.
+- Allow **paste functionality** to support password managers.
+
+**Don'ts ❌**
+
+- Don’t enforce **arbitrary complexity rules** (e.g., forcing special characters unnecessarily).
+- Avoid disabling **autofill** unless there is a valid security reason.
+- Don’t store passwords in plaintext or insecurely transmit them.
+
+### Accessibility
+
+**Do's ✅**
+
+- Ensure the password toggle is **keyboard accessible**.
+- Use **aria-describedby** to associate password requirements with the input field.
+- Maintain **high contrast and clear focus states**.
+- Allow users to **verify their input** without compromising security.
+
+**Don'ts ❌**
+
+- Don’t rely on placeholder text for password guidance—it disappears when users type.
+- Avoid requiring **excessive special characters** that make passwords difficult to remember.
+- Don’t assume all users can see visual strength indicators—provide **text-based guidance**.
+
+### Security Considerations
+
+**Do's ✅**
+
+- Use **secure hashing algorithms** when storing passwords.
+- Enforce **rate-limiting and lockouts** for repeated failed attempts.
+- Implement **2FA options** for high-security applications.
+- Allow **longer passphrases** for enhanced security.
+
+**Don'ts ❌**
+
+- Don’t log passwords in any form.
+- Avoid showing **password hints** that expose sensitive information.
+- Don’t rely solely on client-side validation—perform checks on the server as well.
+
+### Layout & Positioning
+
+**Do's ✅**
+
+- Place password fields **close to their confirmation fields** if applicable.
+- Use **inline validation** to inform users of errors in real time.
+- Ensure adequate **spacing and alignment** for clarity.
+
+**Don'ts ❌**
+
+- Avoid forcing **password confirmation fields** unless absolutely necessary.
+- Don’t position error messages far from the field they relate to.
+
+## Testing Guidelines
+
+### Functional Testing
+
+**Should ✓**
+
+- [ ] Verify that the password field **masks input by default**.
+- [ ] Ensure the **password visibility toggle works correctly**.
+- [ ] Test **autofill and password manager compatibility**.
+- [ ] Validate that **password strength indicators update dynamically**.
+
+### Accessibility Testing
+
+**Should ✓**
+
+- [ ] Ensure **screen readers announce password requirements and errors clearly**.
+- [ ] Confirm **toggle visibility button is keyboard navigable**.
+- [ ] Check for **high contrast between text and background**.
+
+### Security Testing
+
+**Should ✓**
+
+- [ ] Ensure **passwords are encrypted before storage**.
+- [ ] Validate that **passwords are never logged or stored in plaintext**.
+- [ ] Test **rate-limiting and brute-force protections**.
+
+## Related Patterns
+
+- [Text Field](/patterns/forms/text-field) – Standard input for non-sensitive text.
+- [Two-Factor Authentication](/patterns/security/2fa) – Additional authentication layer.
+- [Security Best Practices](/patterns/security/best-practices) – Guidelines for secure input handling.
diff --git a/content/en/patterns/forms/text-field.mdx b/content/en/patterns/forms/text-field.mdx
@@ -119,7 +119,7 @@ graph TD
    - Static text **after the input** (e.g., `.com` for domain fields).
    - Helps users understand **expected input formats**.
 
-### **📌 Summary of Components**
+#### **📌 Summary of Components**
 
 | Component                    | Required? | Purpose                                      |
 | ---------------------------- | --------- | -------------------------------------------- |
@@ -533,3 +533,9 @@ Text fields should support **standard keyboard navigation and interactions** to
 - [Autocomplete](/patterns/forms/autocomplete) – Suggests options as users type.
 - [Password](/patterns/forms/password) – Specialized text field for secure input.
 - [Search Field](/patterns/forms/search-field) – Optimized for search queries.
+
+## Resources
+
+### Libraries
+
+[Input - Origin UI](https://originui.com/input)
diff --git a/content/en/patterns/navigation/load-more.mdx b/content/en/patterns/navigation/load-more.mdx
@@ -110,7 +110,7 @@ flowchart TB
    - Appears **if more content is available after the first load**.
    - Helps users **incrementally explore content** without scrolling endlessly.
 
-### **📌 Summary of Components**
+#### **📌 Summary of Components**
 
 | Component                    | Required? | Purpose                                                      |
 | ---------------------------- | --------- | ------------------------------------------------------------ |

diff --git a/templates/patterns/component.mdx.hbs b/templates/patterns/component.mdx.hbs
@@ -65,6 +65,13 @@ end
 
 1. **Container**
 
+- xxxxxx
+
+#### **📌 Summary of Components**
+
+| Component                    | Required? | Purpose                                      |
+| ---------------------------- | --------- | -------------------------------------------- |
+
 ## Best Practices
 
 ### Content