Skip to content

Commit 837551c

Browse files
taohsutaohsu
committed
update
1 parent 56f1909 commit 837551c

File tree

2 files changed

+633
-0
lines changed

2 files changed

+633
-0
lines changed

‎components/action/button/expand_button/expand_button.md‎

Lines changed: 305 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,305 @@
1+
# Guideline
2+
3+
## Intro 👈🤖
4+
5+
Expand button toggles content visibility, enabling users to progressively reveal or collapse sections while reducing visual clutter.
6+
7+
---
8+
9+
## Definition
10+
11+
Expand button is a control that toggles content visibility, allowing users to expand or collapse sections. It reduces visual clutter by showing only key information and providing access to more details when needed.
12+
13+
---
14+
15+
## Best for 👈🤔
16+
17+
✅ FAQ sections where questions can be expanded to reveal answers
18+
19+
✅ Collapsible panels that hide advanced or secondary options
20+
21+
✅ Mobile interfaces where screen space is limited
22+
23+
✅ Progressive disclosure of product details or specifications
24+
25+
✅ Settings menus with expandable advanced options
26+
27+
✅ Filtering panels with collapsible category groups
28+
29+
✅ Checkout flows revealing additional payment or shipping details
30+
31+
✅ Data tables with expandable row details
32+
33+
✅ Navigation menus with collapsible sub-sections
34+
35+
✅ Form sections that reveal conditional fields based on context
36+
37+
---
38+
39+
## Anatomy 👈🤖
40+
41+
| # | Element | Purpose | Optional |
42+
|---|---------|---------|----------|
43+
| 1 | Container | Houses all button elements and defines interactive hit area | N |
44+
| 2 | Label | Descriptive text indicating the expandable content or action | Y |
45+
| 3 | Icon | Visual indicator (chevron) showing expand/collapse direction | N |
46+
| 4 | Background | Visual surface providing hierarchy and state feedback | N |
47+
| 5 | Border | Defines button boundaries; varies by appearance variant | Y |
48+
| 6 | Focus ring | Visible outline indicating keyboard focus for accessibility | N |
49+
| 7 | Loading indicator | Spinner replacing icon during async content loading | Y |
50+
51+
---
52+
53+
## Appearance
54+
55+
**`Default`** Default expand buttons are used for standard interactions where expanding or collapsing content does not require strong emphasis. They provide a balanced and neutral look suitable for most layouts.
56+
Use case: Expanding FAQ sections or showing additional text in articles.
57+
58+
**`Strong`** The Strong expand button is prominent and visually emphasized, reserved for the most important expandable sections where visibility and clarity are critical.
59+
Use case: Expanding a key section in a form, such as "Payment details" in a checkout process.
60+
61+
**`Brand`** The Brand expand button uses the brand's primary color as an alternative to the Strong button. It should be used sparingly to anchor a branded moment or highlight a special section.
62+
Use case: Expanding promotional or branded content blocks.
63+
64+
**`Minimal`** Minimal expand buttons are lightweight and understated, best for secondary or less critical expandable areas. They reduce visual noise and integrate seamlessly with simple layouts.
65+
Use case: Expanding advanced options in a settings menu or filters in a search panel.
66+
67+
---
68+
69+
## appearance_do_&_dont 👈🤔
70+
71+
✅ **Do:** Use Default appearance for most standard expand/collapse interactions to maintain visual consistency across the interface.
72+
❌ **Don't:** Use Strong or Brand variants for every expandable section, as this diminishes their visual impact and importance.
73+
74+
✅ **Do:** Reserve Strong appearance for critical or high-priority expandable content that users must notice, such as payment details or important warnings.
75+
❌ **Don't:** Mix multiple high-emphasis variants (Strong and Brand) in the same view, creating visual competition.
76+
77+
✅ **Do:** Use Minimal appearance for secondary or nested expandable content to create clear visual hierarchy.
78+
❌ **Don't:** Use Minimal variant for primary actions or important content that users might overlook.
79+
80+
✅ **Do:** Apply Brand appearance sparingly for promotional content or branded moments that align with marketing campaigns.
81+
❌ **Don't:** Use Brand appearance throughout an interface, diluting brand emphasis and creating visual noise.
82+
83+
✅ **Do:** Maintain consistent appearance choices within the same context or component group.
84+
❌ **Don't:** Randomly alternate between appearance variants without a clear hierarchical purpose.
85+
86+
---
87+
88+
## Expanded
89+
90+
**`False`** The Expanded = false state indicates that the content controlled by the button is currently hidden or collapsed. The button should visually suggest that more information is available (e.g., with a downward chevron).
91+
Use case: Default state in FAQs, dropdowns, or collapsible panels before the user interacts with them.
92+
93+
**`True`** The Expanded = true state indicates that the content has been revealed or expanded. The button should update its visual affordance to show that the section is open (e.g., with an upward chevron) and that it can be collapsed again.
94+
Use case: Active state when a user expands details, advanced options, or additional filters in a panel.
95+
96+
---
97+
98+
## expanded_do_&_dont 👈🤔
99+
100+
✅ **Do:** Use clear visual indicators (chevron rotation) to communicate expanded/collapsed state immediately.
101+
❌ **Don't:** Rely solely on content visibility to indicate state; always update the button's visual affordance.
102+
103+
✅ **Do:** Ensure the chevron icon rotates smoothly (down → up) to reinforce state change with visual continuity.
104+
❌ **Don't:** Use inconsistent icon directions or swap between different icon types for expand/collapse states.
105+
106+
✅ **Do:** Announce state changes to screen readers using `aria-expanded` attribute that updates dynamically.
107+
❌ **Don't:** Omit `aria-expanded` or fail to update it when the expanded state changes.
108+
109+
✅ **Do:** Consider starting critical content sections in an expanded state if users typically need that information.
110+
❌ **Don't:** Force users to expand every section when the majority would benefit from seeing content by default.
111+
112+
✅ **Do:** Preserve the user's expanded/collapsed state choices when they return to a page within the same session.
113+
❌ **Don't:** Reset all sections to collapsed state on every page load if users have expressed preferences.
114+
115+
---
116+
117+
## Icon only
118+
119+
**`False`** The Icon only = false state displays both a text label and an icon. This version provides greater clarity and is recommended when users may need additional context to understand the button's action.
120+
Use case: Expanding or collapsing sections in forms or settings, where descriptive text improves usability.
121+
122+
**`True`** The Icon only = true state displays only the icon without a visible label. It creates a more compact appearance, suitable for space-constrained layouts or when the icon meaning is universally understood. For accessibility, always provide an alternative text label via aria-label or a tooltip.
123+
Use case: Expanding or collapsing filters, toolbars, or mobile panels where space is limited.
124+
125+
---
126+
127+
## icon_only_do_&_dont 👈🤔
128+
129+
✅ **Do:** Always provide an accessible name via `aria-label` when using icon-only buttons.
130+
❌ **Don't:** Assume users will understand icon-only buttons without providing accessible text for screen readers.
131+
132+
✅ **Do:** Use icon-only buttons only when space is constrained and the icon's meaning is universally understood.
133+
❌ **Don't:** Default to icon-only for all expand buttons; prefer labeled buttons for better usability.
134+
135+
✅ **Do:** Provide a tooltip on hover/focus to help sighted users understand the icon-only button's purpose.
136+
❌ **Don't:** Rely solely on `aria-label` for tooltip functionality; use a visible tooltip for all users.
137+
138+
✅ **Do:** Ensure icon-only buttons meet minimum touch target size requirements (44×44px) for mobile accessibility.
139+
❌ **Don't:** Create icon-only buttons that are too small to tap accurately on touch devices.
140+
141+
✅ **Do:** Use descriptive `aria-label` text like "Expand filters" rather than just "Expand".
142+
❌ **Don't:** Use generic labels that don't provide context about what content will be expanded.
143+
144+
---
145+
146+
## Rounded corner
147+
148+
**`False`** For a square finish.
149+
150+
**`True`** For a finish with rounded corner.
151+
To be favored in more emotional, immersive contexts or those tied to specific visual identities. For standard or business-oriented journeys, keep the default corners. This evolution addresses the need for flexibility in adapting the design to certain brand contexts.
152+
153+
---
154+
155+
## rounded_corner_do_&_dont 👈🤔
156+
157+
✅ **Do:** Use square corners (False) for standard business interfaces and professional contexts.
158+
❌ **Don't:** Apply rounded corners inconsistently across similar components in the same interface.
159+
160+
✅ **Do:** Apply rounded corners for immersive, emotional, or brand-focused experiences where softer aesthetics align with the design direction.
161+
❌ **Don't:** Mix square and rounded corner styles on the same page without a clear design rationale.
162+
163+
✅ **Do:** Maintain consistent corner radius with other interactive elements (buttons, cards) in the same context.
164+
❌ **Don't:** Use rounded expand buttons alongside square standard buttons, creating visual inconsistency.
165+
166+
✅ **Do:** Consider the overall design language and brand guidelines when choosing corner style.
167+
❌ **Don't:** Default to rounded corners just because they look "modern" without considering brand alignment.
168+
169+
✅ **Do:** Document corner radius choices in your design system to ensure team consistency.
170+
❌ **Don't:** Let individual designers choose corner styles ad-hoc without design system governance.
171+
172+
---
173+
174+
# Specs
175+
176+
## States
177+
178+
**`Enabled`** The default state of the Expand button when it is available for interaction.
179+
Use case: A collapsed section ready to be expanded by the user.
180+
181+
**`Hover`** The state when a user places the pointer over the Expand button without activating it. Provides a visual cue that the element is interactive.
182+
Use case: Highlighting that a FAQ or dropdown section can be opened.
183+
184+
**`Focus`** The state when the button is selected via keyboard or voice command but not yet activated. Usually shows an outline or border to ensure accessibility.
185+
Use case: Allowing users with keyboard navigation to expand or collapse sections clearly.
186+
187+
**`Pressed`** A transient state indicating that the user has clicked or tapped the Expand button and the action is being executed.
188+
Use case: User presses the button to reveal advanced options in a form.
189+
190+
**`Loading`** Used when expanding content requires fetching or processing data before it is displayed. The button shows a loading indicator.
191+
Use case: Expanding a collapsible panel that loads additional product details from the server.
192+
193+
**`Disabled`** Indicates that the Expand button cannot be interacted with, for example when expansion is not allowed or content is unavailable.
194+
Use case: Expand option disabled for sections restricted to certain user roles.
195+
196+
**`Skeleton`** A placeholder state that represents the Expand button before it is fully loaded. Improves perceived performance by showing the button will appear soon.
197+
Use case: During initial page load when collapsible components are still being fetched.
198+
199+
---
200+
201+
## Layout and spacing
202+
203+
🚧 Content to be added
204+
205+
---
206+
207+
# Accessibility 👈🤖
208+
209+
## Accessibility intro
210+
211+
The Expand button must meet WCAG 2.2 Level AA standards, ensuring all users can effectively toggle content visibility regardless of ability. For comprehensive accessibility guidance, see the [Orange Unified Design System Accessibility Overview](https://unified-design-system.orange.com/472794e18/p/88ebab-accessibility-and-sustainability).
212+
213+
---
214+
215+
## Accessibility Challenges
216+
217+
Expand buttons present unique accessibility challenges because they control hidden content and must communicate both their current state (expanded/collapsed) and their relationship to the content they reveal. Users relying on assistive technology need clear announcements of state changes and predictable keyboard interaction.
218+
219+
### Key Challenges
220+
221+
- Communicating expanded/collapsed state to screen readers dynamically
222+
- Ensuring keyboard users can operate the toggle with standard keys (Enter/Space)
223+
- Providing accessible names for icon-only variants without visible labels
224+
- Maintaining focus management when content expands or collapses
225+
226+
### Critical Success Factors
227+
228+
1. Use `aria-expanded` attribute that updates dynamically with state changes
229+
2. Associate button with controlled content via `aria-controls` referencing content `id`
230+
3. Provide visible focus indicator with ≥3:1 contrast ratio
231+
4. Ensure icon-only buttons have accessible names via `aria-label`
232+
233+
---
234+
235+
## Design Requirements
236+
237+
### Structure & Labels
238+
239+
- [ ] **Semantic markup**: Use native `<button>` element for automatic keyboard and screen reader support
240+
- [ ] **Accessible name**: Provide descriptive text label or `aria-label` for icon-only variants ([Visible label guidance](https://a11y-guidelines.orange.com/en/web/develop/textual-content/#make-sure-the-user-can-use-native-browser-options))
241+
- [ ] **State communication**: Include `aria-expanded="true|false"` that updates on interaction
242+
243+
### Visual Design
244+
245+
- [ ] **Focus visibility**: Display focus ring with ≥3:1 contrast against adjacent colors ([Focus guidance](https://a11y-guidelines.orange.com/en/web/design/navigation-focus/))
246+
- [ ] **Color independence**: Ensure state changes are not communicated by color alone; use chevron rotation
247+
- [ ] **Touch targets**: Maintain minimum 44×44px interactive area for touch devices
248+
249+
### Content
250+
251+
- [ ] **Descriptive labels**: ❌ "More" / ✅ "Show payment options" ([Content guidance](https://a11y-guidelines.orange.com/en/web/design/textual-content/))
252+
- [ ] **Consistent patterns**: Use same interaction model for all expand buttons in the interface
253+
254+
---
255+
256+
## Testing Checklist
257+
258+
### Screen Reader Testing
259+
260+
- [ ] Test with NVDA (Windows), JAWS (Windows), VoiceOver (macOS/iOS), TalkBack (Android)
261+
- [ ] Verify button role announced, `aria-expanded` state communicated, label read correctly
262+
263+
### Keyboard Testing
264+
265+
- [ ] Tab to button (focus visible), activate with Enter/Space, confirm state change announced
266+
- [ ] Verify focus remains on button after activation; expanded content follows in tab order
267+
268+
### Loading State Testing
269+
270+
- [ ] Confirm loading state announced to screen readers; button disabled during load
271+
272+
Resources: [Orange Accessibility Testing Guide](https://a11y-guidelines.orange.com/en/web/testing/)
273+
274+
---
275+
276+
## Key WCAG Criteria
277+
278+
- **2.1.1 Keyboard** (A): All expand/collapse functionality operable via keyboard without timing
279+
- **2.4.7 Focus Visible** (AA): Visible focus indicator present on button when focused
280+
- **4.1.2 Name, Role, Value** (A): Button role, accessible name, and `aria-expanded` state programmatically exposed
281+
- **1.4.11 Non-text Contrast** (AA): Focus indicator and interactive states meet ≥3:1 contrast
282+
- **1.3.1 Info and Relationships** (A): Relationship between button and controlled content established via `aria-controls`
283+
284+
For complete reference: [Orange Accessibility Guidelines - Components](https://a11y-guidelines.orange.com/en/web/components-examples/)
285+
286+
---
287+
288+
## Additional Resources
289+
290+
- [Orange Accessibility Guidelines - Interactive Components](https://a11y-guidelines.orange.com/en/web/components-examples/)
291+
- [W3C WAI - Disclosure Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/)
292+
- [WCAG 2.2 Understanding Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html)
293+
- [Orange Design System - Accessibility & Sustainability](https://unified-design-system.orange.com/472794e18/p/88ebab-accessibility-and-sustainability)
294+
295+
---
296+
297+
# Changelog
298+
299+
| Date | Number | Notes | Designer |
300+
|------|--------|-------|----------|
301+
| Sep 28, 2025 | 3.1.0 | <ul><li>Brand variant: New background and content color tokens added for hover/pressed/loading/focus states <li>The name of the "Hierarchy" variant has been replaced to "Appearance"</ul> | Maxime Tonnerre |
302+
| Jul 24, 2025 | 3.0.0 | <ul><li>New hierarchical variant: Brand → [Component tokens changelog 1.4.0](https://www.figma.com/design/Co2t6wHMf4GB9NJVGs2Hes/-OUDS-Core-Lib--Design-tokens?m=auto&node-id=9280-2568&t=HLVB4jOd35DWr8Bj-1) <li>Rounded corner property is now available → [Component tokens changelog 1.4.0](https://www.figma.com/design/Co2t6wHMf4GB9NJVGs2Hes/-OUDS-Core-Lib--Design-tokens?m=auto&node-id=9280-2568&t=HLVB4jOd35DWr8Bj-1) <li>Minimal variant: Color and width border tokens removed <li>Minimal variant: Color background tokens removed in the enabled state <li>Minimal variant: Color background tokens removed in the loading state <li>Minimal variant: Color background tokens removed in the disabled state</ul> | Maxime Tonnerre |
303+
| Jul 21, 2025 | 2.1.0 | <ul><li>Several design token updates: [Component tokens changelog 1.3.0](https://www.figma.com/design/Co2t6wHMf4GB9NJVGs2Hes/-OUDS-Core-Lib--Design-tokens?m=auto&node-id=9280-2568&t=HLVB4jOd35DWr8Bj-1) <li>Button: Expanded: The chevron is also present in the 'icon only' variant. The gap between these 2 elements is defined by a design token: ouds-action-button-space-column-gap-icon-chevron→ouds-space-column-gap-2xs</ul> | Maxime Tonnerre |
304+
| Apr 19, 2025 | 2.0.0 | <ul><li>Creation of "On colored bg" variant</ul> | Maxime Tonnerre |
305+
| Dec 5, 2024 | 1.0.0 | <ul><li>Component creation</ul> | Maxime Tonnerre |

0 commit comments

Comments
 (0)