The disclosure component uses native HTML <details> and <summary> elements to create expandable/collapsible content sections. No JavaScript required for the toggle behaviour.
Core Principles
- Uses native HTML (
<details>/<summary>) for built-in accessibility and keyboard support - Hidden by default — content is revealed on demand
- Chevron indicator sits on the left of the summary text, rotating from right-pointing (closed) to down-pointing (open)
- Disclosure content aligns with the summary text (indented past the chevron)
- Styled with design system tokens (fonts, colors, spacing, borders)
- The wrapper provides consistent padding and typography
- The pattern displays key-value pairs (e.g. CSS properties)
- The provides copy-to-clipboard functionality (requires minimal JS)
Basic Usage
Show details
Content revealed when expanded.
<details>
<summary>Show details</summary>
<div class="disclosure-content">
<p>Content revealed when expanded.</p>
</div>
</details>
Key-Value Table Pattern
Use with a <dl> to display property-value pairs:
Show details
- Font size
- var(--font-7xl) 48px
- Line height
- var(--line-height-s) 1
- Weight
- var(--font-weight-regular) 400
<details>
<summary>Show details</summary>
<div class="disclosure-content">
<dl class="disclosure-table">
<dt>Font size</dt>
<dd>var(--font-7xl) <span class="token-tag">48px</span></dd>
<dt>Line height</dt>
<dd>var(--line-height-s) <span class="token-tag">1</span></dd>
<dt>Weight</dt>
<dd>var(--font-weight-regular) <span class="token-tag">400</span></dd>
</dl>
</div>
</details>
The <dt> labels are styled with and the <dd> values with . The span shows the resolved value inline.
Copy Button
Add a inside with a data-copy attribute containing the text to copy. Use for newlines in the data-copy value.
Show details
- Font size
- var(--font-7xl) 48px
- Line height
- var(--line-height-s) 1
<details>
<summary>Show details</summary>
<div class="disclosure-content">
<dl class="disclosure-table">
<dt>Font size</dt>
<dd>var(--font-7xl) <span class="token-tag">48px</span></dd>
<dt>Line height</dt>
<dd>var(--line-height-s) <span class="token-tag">1</span></dd>
</dl>
<button class="button is-small copy-btn"
data-copy="font-size: var(--font-7xl); line-height: var(--line-height-s);"
aria-label="Copy CSS for Heading 1">
Copy CSS
</button>
</div>
</details>
The button requires a small JS handler:
document.addEventListener('click', function (event) {
var button = event.target.closest('.copy-btn');
if (!button) return;
var text = button.getAttribute('data-copy');
navigator.clipboard.writeText(text).then(function () {
button.textContent = 'Copied';
button.classList.add('is-copied');
setTimeout(function () {
button.textContent = 'Copy CSS';
button.classList.remove('is-copied');
}, 1500);
});
});
CSS Classes
| Class | Purpose |
|---|---|
| (element) | Base container — border, border-radius |
| (element) | Toggle trigger — left-side chevron via ::before, pointer cursor |
| Content wrapper — padding, border-top separator, monospace font | |
| Grid layout for key-value pairs (2-column: label + value) | |
.button.is-small.copy-btn |
Copy-to-clipboard button — uses design system button with copy state |
.copy-btn.is-copied |
Copied state — success color feedback |
Accessibility
- Native
<details>/<summary>provides keyboard support (Enter/Space to toggle) summaryis focusable and announced as a disclosure widget by screen readers- should include an
aria-labeldescribing what will be copied - Focus-visible outlines are styled using token
Design Tokens Used
| Token | Usage |
|---|---|
| Border width for container and content separator | |
| Border color | |
| Monospace font for summary and content | |
| Font size for summary and content text | |
| Summary text color, table labels | |
| Summary hover color, content text | |
| Table values | |
| Copy button text | |
| Copy button hover text | |
| Copy button background | |
| Copy button hover background | |
| Copied state color | |
| Focus ring color | |
| Border radius | |
| , | Padding values |
When to Use
- Styleguide: Show CSS details beneath typography, color, and component demos
- Documentation: Collapse supplementary information that not all readers need
- Forms: Hide advanced options or additional context
When Not to Use
- For primary content that all users need to see — use visible layout instead
- For navigation — use proper nav patterns
- For multi-panel accordions with mutual exclusion — this pattern allows multiple open simultaneously