feat: add draft for expandable text

content/en/patterns/content-management/expandable-text.mdx

@@ -0,0 +1,255 @@
+---
+description: "Show or hide additional text content on demand"
+icon: PlusSquare
+status: complete
+---
+
+# Expandable Text
+
+**_(Also called collapsible text, Read More/Read Less)_**
+
+## Overview
+
+**Expandable Text** is a content management pattern that allows users to expand and collapse sections of text. This pattern improves readability by initially hiding non-essential content while keeping it accessible on demand.
+
+Expandable Text is commonly used to manage lengthy descriptions, article summaries, or additional details that are helpful but not immediately necessary. It helps users scan content efficiently while maintaining a clean and minimal interface.
+
+## Use Cases
+
+### When to use:
+
+- **Summarizing content** – Showing a short preview of a longer article, product description, or FAQ answer.
+- **Reducing page clutter** – Keeping the interface clean by hiding secondary details.
+- **Improving mobile usability** – Managing screen space efficiently on smaller devices.
+- **Progressive disclosure** – Revealing additional information only when needed.
+- **Enhancing readability** – Preventing information overload while keeping details accessible.
+
+### When not to use:
+
+- **For critical information** – Users should not need to expand content to access essential details, such as pricing, terms, or important warnings.
+- **For frequently accessed content** – If most users expand the content, it may be better to display it by default.
+- **When full content is needed upfront** – Avoid hiding information that helps users make informed decisions quickly.
+
+## Benefits
+
+- **Improves readability** – Helps users scan and navigate content more efficiently.
+- **Enhances user control** – Users can choose to expand or collapse information as needed.
+- **Saves space** – Keeps interfaces clean and reduces clutter, especially on mobile.
+- **Supports progressive disclosure** – Prioritizes important content while making additional details available.
+- **Improves accessibility when properly implemented** – Ensures all users can interact with hidden content.
+
+## Anatomy
+
+```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]
+```
+
+### 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`.
+
+2. **Content Section**
+
+- Contains the expandable/collapsible text.
+- Hidden by default but fully visible when expanded.
+
+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.
+
+## Best Practices
+
+### Content
+
+**Do's ✅**
+
+- Use clear and concise labels for the expand/collapse button (e.g., "Read More" / "Read Less").
+- Keep the collapsed preview meaningful and informative.
+- Ensure expanded content is relevant and enhances the user experience.
+
+**Don'ts ❌**
+
+- Don't hide essential information that users need to make decisions.
+- Don't use vague labels like "Click Here" without context.
+- Don't force users to expand content just to understand the main point.
+
+### Accessibility
+
+**Do's ✅**
+
+- Use a `<button>` element for the trigger to ensure keyboard accessibility.
+- Add `aria-expanded="false"` to the button and update it dynamically.
+- Use `aria-controls` to associate the button with the expandable content.
+- Maintain logical focus order, ensuring the expanded content follows naturally.
+
+**Don'ts ❌**
+
+- Don't rely on color alone to indicate the expanded state.
+- Don't remove focus styles on the trigger button.
+- Don't make expandable content difficult to navigate for screen reader users.
+
+### Visual Design
+
+**Do's ✅**
+
+- Use **clear expand/collapse icons** (`▸` / `▾`, `+` / `-`, `►` / `▼`) and ensure they change state when toggled.
+- **Pair icons with text labels** (e.g., `Read More ▾` / `Read Less ▴`) for clarity.
+- **Place icons consistently**:
+  - **Inline text expansion**: Position the icon on the **right** (`Read More ▾`).
+  - **List-based or block sections**: Position the icon on the **left** (`▸ Section Title`).
+- Provide **smooth animations** for expanding/collapsing content.
+- Ensure **text contrast** remains high for readability.
+
+**Don'ts ❌**
+
+- **Don't use unclear icons** (e.g., dots `...` or generic arrows that don't rotate).
+- **Don't rely on icons alone**—ensure a text label is present.
+- **Don't mix left/right placements** inconsistently within the same interface.
+- **Don't make the trigger button too small** or difficult to tap on mobile.
+- **Don't create unexpected layout shifts** when expanding content.
+
+### Layout & Positioning
+
+**Do's ✅**
+
+- Place expandable content near the primary text to maintain context.
+- Ensure the collapsed content remains visually connected to its trigger.
+- Make sure expanded content does not overlap or obscure other UI elements.
+
+**Don'ts ❌**
+
+- Don't place the trigger button far from the expandable content.
+- Don't create an inconsistent layout by having some sections expand and others not.
+
+## Code Examples
+
+### Basic Implementation
+
+```html
+<div>
+  <p id="expandable-text">
+    This is the visible content...
+    <span id="hidden-text" hidden>
+      This is the additional content that is initially hidden.
+    </span>
+  </p>
+  <button id="expand-button" aria-expanded="false" aria-controls="hidden-text">
+    Read More <span aria-hidden="true">▾</span>
+  </button>
+</div>
+
+<script>
+  const button = document.getElementById("expand-button");
+  const text = document.getElementById("hidden-text");
+  const icon = button.querySelector("span");
+
+  button.addEventListener("click", () => {
+    const isExpanded = button.getAttribute("aria-expanded") === "true";
+
+    button.setAttribute("aria-expanded", !isExpanded);
+    text.hidden = isExpanded;
+
+    button.textContent = isExpanded ? "Read More" : "Read Less";
+    button.appendChild(icon);
+    icon.textContent = isExpanded ? "▾" : "▴";
+  });
+</script>
+```
+
+## Accessibility
+
+### ARIA Attributes
+
+**Required ARIA attributes:**
+
+- `aria-expanded="false"` on the button (updated dynamically).
+- `aria-controls="id-of-content"` to link the button to the expandable content.
+- `hidden` attribute on the expandable content when collapsed.
+
+### Screen Reader Support
+
+- Ensure that the expanded content is properly announced by screen readers.
+- Use `aria-live="polite"` if the content update needs to be announced.
+
+## SEO
+
+- Ensure that expandable text is still **present in the DOM** so search engines can index it.
+- Avoid hiding critical content that users or crawlers need upfront.
+
+## Testing Guidelines
+
+### Functional Testing
+
+**Should ✓**
+
+- [ ] Verify that clicking the trigger expands and collapses the content.
+- [ ] Ensure the `aria-expanded` attribute updates correctly.
+- [ ] Confirm that expanded content is focusable and navigable.
+- [ ] Ensure the trigger works when activated via keyboard (`Enter` and `Space` keys).
+- [ ] Check that clicking outside the expanded content does not cause unintended collapse (unless designed to do so).
+- [ ] Ensure content remains in the DOM when collapsed, and it reappears correctly when expanded.
+
+### Accessibility Testing
+
+**Should ✓**
+
+- [ ] Validate that the trigger button is **focusable** and properly labeled.
+- [ ] Test with screen readers to **ensure correct announcement** of expanded content.
+- [ ] Verify `aria-controls` properly links the trigger to the expandable content.
+- [ ] Ensure `aria-expanded` updates dynamically and is announced correctly.
+- [ ] Check that **expanded content is navigable via keyboard** and follows logical tab order.
+- [ ] Validate that expandable content does **not rely solely on color** for visual cues.
+- [ ] Confirm that **touch targets** meet WCAG guidelines (minimum 44x44px).
+
+### Visual Testing
+
+**Should ✓**
+
+- [ ] Ensure smooth animations and transitions.
+- [ ] Verify that expanded content does not break the layout.
+- [ ] Ensure that icons properly change direction (`▾` to `▴` or `+` to `-`).
+- [ ] Check that expand/collapse actions **do not create layout shifts** affecting surrounding content.
+- [ ] Ensure that the transition effect does not make content unreadable.
+
+### Performance Testing
+
+**Should ✓**
+
+- [ ] Test that expansion does not introduce layout shifts (Cumulative Layout Shift - CLS).
+- [ ] Verify that expandable content does not trigger **excessive reflows** or repaints.
+- [ ] Ensure that animations run at **60 FPS** without jank.
+- [ ] Confirm that expanding/collapsing does not introduce memory leaks or excessive DOM updates.
+
+### SEO Testing
+
+**Should ✓**
+
+- [ ] Ensure that **collapsed content is still in the DOM** and indexable by search engines.
+- [ ] Verify that search engines **can crawl and access** the hidden content.
+- [ ] Check that expandable content is **not blocked by JavaScript** for crawlers.
+- [ ] Test using **Google's Mobile-Friendly Test** and **Lighthouse** to ensure SEO impact is minimal.
+
+## Related Patterns
+
+- [Accordion](/patterns/content-management/accordion) – Best for **multi-section collapsible content**, where multiple expandable panels are grouped together (e.g., FAQs or settings menus).
+- [Tooltip](/patterns/content-management/tooltip) – Useful for **brief inline explanations**, where additional information is needed on hover or focus, rather than expanding a large content section.
+- [Modal](/patterns/content-management/modal) – Ideal when **expanded content requires full attention**, such as confirmations, forms, or important details that should block interaction with the rest of the page.
+
+## Resources
+
+### Articles

content/en/patterns/content-management/modal.mdx

@@ -1,6 +1,6 @@
 ---
 description: "Display focused content or actions"
-icon: Square
+icon: Maximize2
 status: complete
 ---
 

content/en/patterns/content-management/popover.mdx

@@ -1,6 +1,6 @@
 ---
 description: "Display focused content or actions"
-icon: Square
+icon: MessageSquare
 status: complete
 ---
 
@@ -103,7 +103,7 @@ end
 **Don'ts ❌**
 
 - Avoid overloading with too much information.
-- Don’t include critical navigation or forms better suited for a modal.
+- Don't include critical navigation or forms better suited for a modal.
 - Do not expect users to scroll through extensive content.
 
 ### Accessibility

content/en/patterns/navigation/pagination.mdx

@@ -13,7 +13,7 @@ import { BrowserSupport } from "@app/_components/browser-support";
 **Pagination** is a navigation pattern used to divide large collections of content into manageable chunks or pages.
 This helps users to navigate through data sets, search results, or product listings without overwhelming the page with too much information at once.
 
-While pagination is a common and effective pattern, it's important to consider alternatives like infinite scroll or "Load More" buttons for certain types of content. The choice between pagination and infinite scroll depends on factors such as the nature of the content, user behavior, and the goals of the interface.
+While pagination is a common and effective pattern, it's important to consider alternatives like [infinite scroll](/patterns/navigation/infinite-scroll) or ["Load More"](/patterns/navigation/load-more) buttons for certain types of content. The choice between pagination and infinite scroll depends on factors such as the nature of the content, user behavior, and the goals of the interface.
 
 ## Use Cases
 
@@ -29,7 +29,7 @@ While pagination is a common and effective pattern, it's important to consider a
 ### When not to use:
 
 - When all content is better presented on a single page (e.g., short lists or summaries).
-- If infinite scroll or a “load more” pattern better suits the user experience.
+- If [infinite scroll](/patterns/navigation/infinite-scroll) or a ["load more"](/patterns/navigation/load-more) pattern better suits the user experience.
 - In scenarios where users need continuous comparison between items on different pages.
 
 ## Benefits
@@ -51,8 +51,6 @@ flowchart TB
     A --> C[Pagination Items]
     A --> D[Next Button]
   end
-  classDef container stroke:#666,stroke-width:2px
-  class Pagination container
 ```
 
 ### Component Structure
@@ -72,7 +70,7 @@ flowchart TB
 
 - Numbered buttons or links for each page.
 - Clearly indicate the current page (using visual cues and ARIA attributes).
-- May include an ellipsis (“…”) for large ranges of pages.
+- May include an ellipsis ("…") for large ranges of pages.
 
 4. **Next Button**
 
@@ -106,7 +104,7 @@ flowchart TB
 - Don't use ambiguous labels that could confuse the user
 - Avoid loading unnecessary data or assets that aren't relevant to the current page
 
-### Accessibility & UX
+### Accessibility
 
 **Do's ✅**
 
@@ -276,12 +274,6 @@ The following table outlines the standard keyboard interactions for pagination c
 - [ ] Ensure that pagination does not cause significant loading delays.
 - [ ] Validate that new page content loads efficiently when navigating.
 
-## Browser Support
-
-<BrowserSupport
-  features={["CSS Grid/Flexbox for layout", "ARIA roles and attributes"]}
-/>
-
 ## Design Tokens
 
 These design tokens follow the [Design Tokens Format](https://design-tokens.github.io/community-group/format/) specification and can be used with various token transformation tools to generate platform-specific variables.
@@ -313,6 +305,7 @@ These design tokens follow the [Design Tokens Format](https://design-tokens.gith
 ## Related Patterns
 
 - [Infinite Scroll](/patterns/navigation/infinite-scroll) - An alternative to pagination for certain types of content, particularly suited for content streams or social media feeds
+- [Load More](/patterns/navigation/load-more) - A simpler alternative to pagination that gives users manual control over loading additional content
 
 ## Resources