Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

Improve Collapsible docs page and block examples (#1575)

rubyycheungc9f9d690ccff
diff --git a/apps/sandbox/src/app/(fullscreen)/BlockDocContext.tsx b/apps/sandbox/src/app/(fullscreen)/BlockDocContext.tsx
index 800bc63e84..38e9266eb6 100644
--- a/apps/sandbox/src/app/(fullscreen)/BlockDocContext.tsx
+++ b/apps/sandbox/src/app/(fullscreen)/BlockDocContext.tsx
@@ -44,6 +44,7 @@ export function BlockPreview({
}}>
<div
style={{
+ width: '100%',
transform: scale !== 1 ? `scale(${scale})` : undefined,
transformOrigin: 'center center',
}}>
diff --git a/packages/cli/templates/blocks/components/Collapsible/CollapsibleControlledAccordion.doc.mjs b/packages/cli/templates/blocks/components/Collapsible/CollapsibleControlledAccordion.doc.mjs
index 271a111751..21b787479b 100644
--- a/packages/cli/templates/blocks/components/Collapsible/CollapsibleControlledAccordion.doc.mjs
+++ b/packages/cli/templates/blocks/components/Collapsible/CollapsibleControlledAccordion.doc.mjs
@@ -1,10 +1,9 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'Collapsible — Controlled Accordion',
- description:
- 'Accordion with externally controlled open state that displays which section is active.',
+ name: 'Collapsible — Controlled',
+ description: 'Manage the open section from parent state. Use when the open state needs to sync with a URL param, form, or external control.',
isReady: true,
aspectRatio: 4 / 3,
- componentsUsed: ['Collapsible', 'Card', 'Layout'],
+ componentsUsed: ['Collapsible', 'Card', 'Text', 'Layout'],
};
diff --git a/packages/cli/templates/blocks/components/Collapsible/CollapsibleControlledAccordion.tsx b/packages/cli/templates/blocks/components/Collapsible/CollapsibleControlledAccordion.tsx
index ff573e4aa9..a9dcd4c3ca 100644
--- a/packages/cli/templates/blocks/components/Collapsible/CollapsibleControlledAccordion.tsx
+++ b/packages/cli/templates/blocks/components/Collapsible/CollapsibleControlledAccordion.tsx
@@ -3,34 +3,39 @@
import {useState} from 'react';
import {XDSCollapsible, XDSCollapsibleGroup} from '@xds/core/Collapsible';
import {XDSCard} from '@xds/core/Card';
+import {XDSText} from '@xds/core/Text';
import {XDSVStack} from '@xds/core/Layout';
export default function CollapsibleControlledAccordion() {
- const [open, setOpen] = useState<string | string[]>('section1');
+ const [open, setOpen] = useState<string | string[]>('profile');
return (
- <div>
- <p style={{fontSize: 14, color: '#65676B', margin: '0 0 12px'}}>
- Currently open: <strong>{String(open) || '(none)'}</strong>
- </p>
- <XDSCollapsibleGroup type="single" value={open} onChange={setOpen}>
+ <XDSCollapsibleGroup type="single" value={open} onChange={setOpen}>
<XDSVStack gap={2}>
<XDSCard>
- <XDSCollapsible trigger="Section 1" value="section1">
- <p style={{margin: 0}}>Content for section 1.</p>
+ <XDSCollapsible trigger="Profile Information" value="profile">
+ <XDSText type="body">
+ Update your name, email, and profile photo. Changes are saved
+ automatically.
+ </XDSText>
</XDSCollapsible>
</XDSCard>
<XDSCard>
- <XDSCollapsible trigger="Section 2" value="section2">
- <p style={{margin: 0}}>Content for section 2.</p>
+ <XDSCollapsible trigger="Security" value="security">
+ <XDSText type="body">
+ Manage two-factor authentication, active sessions, and login
+ history.
+ </XDSText>
</XDSCollapsible>
</XDSCard>
<XDSCard>
- <XDSCollapsible trigger="Section 3" value="section3">
- <p style={{margin: 0}}>Content for section 3.</p>
+ <XDSCollapsible trigger="Billing" value="billing">
+ <XDSText type="body">
+ View invoices, update payment method, and manage your
+ subscription plan.
+ </XDSText>
</XDSCollapsible>
</XDSCard>
</XDSVStack>
- </XDSCollapsibleGroup>
- </div>
+ </XDSCollapsibleGroup>
);
}
diff --git a/packages/cli/templates/blocks/components/Collapsible/CollapsibleFAQPage.doc.mjs b/packages/cli/templates/blocks/components/Collapsible/CollapsibleFAQPage.doc.mjs
deleted file mode 100644
index 97e9f68738..0000000000
--- a/packages/cli/templates/blocks/components/Collapsible/CollapsibleFAQPage.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Collapsible — FAQ Page',
- description:
- 'Frequently asked questions layout using single-mode accordion with card-wrapped sections.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Collapsible', 'Card', 'Layout'],
-};
diff --git a/packages/cli/templates/blocks/components/Collapsible/CollapsibleFAQPage.tsx b/packages/cli/templates/blocks/components/Collapsible/CollapsibleFAQPage.tsx
deleted file mode 100644
index 5a4e81a258..0000000000
--- a/packages/cli/templates/blocks/components/Collapsible/CollapsibleFAQPage.tsx
+++ /dev/null
@@ -1,47 +0,0 @@
-'use client';
-
-import {XDSCollapsible, XDSCollapsibleGroup} from '@xds/core/Collapsible';
-import {XDSCard} from '@xds/core/Card';
-import {XDSVStack} from '@xds/core/Layout';
-
-export default function CollapsibleFAQPage() {
- return (
- <XDSCollapsibleGroup type="single">
- <XDSVStack gap={2}>
- <XDSCard>
- <XDSCollapsible trigger="How do I reset my password?" value="q1">
- <p style={{margin: 0}}>
- Go to Settings &rarr; Security &rarr; Change Password. You'll
- receive a confirmation email.
- </p>
- </XDSCollapsible>
- </XDSCard>
- <XDSCard>
- <XDSCollapsible trigger="Can I change my username?" value="q2">
- <p style={{margin: 0}}>
- Usernames can be changed once every 30 days from your profile
- settings.
- </p>
- </XDSCollapsible>
- </XDSCard>
- <XDSCard>
- <XDSCollapsible trigger="How do I delete my account?" value="q3">
- <p style={{margin: 0}}>
- Account deletion is permanent. Go to Settings &rarr; Account
- &rarr; Delete Account. Your data will be removed within 30 days.
- </p>
- </XDSCollapsible>
- </XDSCard>
- <XDSCard>
- <XDSCollapsible
- trigger="What payment methods are accepted?"
- value="q4">
- <p style={{margin: 0}}>
- We accept Visa, Mastercard, American Express, and PayPal.
- </p>
- </XDSCollapsible>
- </XDSCard>
- </XDSVStack>
- </XDSCollapsibleGroup>
- );
-}
diff --git a/packages/cli/templates/blocks/components/Collapsible/CollapsibleMultipleAccordion.doc.mjs b/packages/cli/templates/blocks/components/Collapsible/CollapsibleMultipleAccordion.doc.mjs
index 2526113132..061f4e9a39 100644
--- a/packages/cli/templates/blocks/components/Collapsible/CollapsibleMultipleAccordion.doc.mjs
+++ b/packages/cli/templates/blocks/components/Collapsible/CollapsibleMultipleAccordion.doc.mjs
@@ -1,10 +1,9 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'Collapsible — Multiple Accordion',
- description:
- 'Accordion group in multiple mode allowing several sections to be open simultaneously.',
+ name: 'Collapsible — Multiple Mode',
+ description: 'Several sections open at once. Use when users need to compare content across sections, like feature lists or pricing tiers.',
isReady: true,
aspectRatio: 4 / 3,
- componentsUsed: ['Collapsible', 'Card', 'Layout'],
+ componentsUsed: ['Collapsible', 'Card', 'Text', 'Layout'],
};
diff --git a/packages/cli/templates/blocks/components/Collapsible/CollapsibleMultipleAccordion.tsx b/packages/cli/templates/blocks/components/Collapsible/CollapsibleMultipleAccordion.tsx
index 1d99873a11..5e933b03ce 100644
--- a/packages/cli/templates/blocks/components/Collapsible/CollapsibleMultipleAccordion.tsx
+++ b/packages/cli/templates/blocks/components/Collapsible/CollapsibleMultipleAccordion.tsx
@@ -2,31 +2,35 @@
import {XDSCollapsible, XDSCollapsibleGroup} from '@xds/core/Collapsible';
import {XDSCard} from '@xds/core/Card';
+import {XDSText} from '@xds/core/Text';
import {XDSVStack} from '@xds/core/Layout';
export default function CollapsibleMultipleAccordion() {
return (
- <XDSCollapsibleGroup type="multiple" defaultValue={['faq1', 'faq3']}>
+ <XDSCollapsibleGroup type="multiple" defaultValue={['features', 'pricing']}>
<XDSVStack gap={2}>
<XDSCard>
- <XDSCollapsible trigger="What is XDS?" value="faq1">
- <p style={{margin: 0}}>
- XDS is a design system for building internal tools and products.
- </p>
+ <XDSCollapsible trigger="Features" value="features">
+ <XDSText type="body">
+ Includes real-time collaboration, version history, and granular
+ permissions for teams of any size.
+ </XDSText>
</XDSCollapsible>
</XDSCard>
<XDSCard>
- <XDSCollapsible trigger="How do I install it?" value="faq2">
- <p style={{margin: 0}}>
- Run <code>npm install @xds/core</code> to get started.
- </p>
+ <XDSCollapsible trigger="Pricing" value="pricing">
+ <XDSText type="body">
+ Free for up to 5 users. Pro plans start at $12/user/month with
+ annual billing.
+ </XDSText>
</XDSCollapsible>
</XDSCard>
<XDSCard>
- <XDSCollapsible trigger="Is it open source?" value="faq3">
- <p style={{margin: 0}}>
- Yes! XDS is open source and available on GitHub.
- </p>
+ <XDSCollapsible trigger="Integrations" value="integrations">
+ <XDSText type="body">
+ Connect with Slack, GitHub, Jira, and 40+ other tools through our
+ REST API and pre-built connectors.
+ </XDSText>
</XDSCollapsible>
</XDSCard>
</XDSVStack>
diff --git a/packages/cli/templates/blocks/components/Collapsible/CollapsibleSingleAccordion.doc.mjs b/packages/cli/templates/blocks/components/Collapsible/CollapsibleSingleAccordion.doc.mjs
index 9c0d38e8ba..42b4bc92a2 100644
--- a/packages/cli/templates/blocks/components/Collapsible/CollapsibleSingleAccordion.doc.mjs
+++ b/packages/cli/templates/blocks/components/Collapsible/CollapsibleSingleAccordion.doc.mjs
@@ -1,10 +1,9 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'Collapsible — Single Accordion',
- description:
- 'Accordion group in single mode where only one section can be open at a time.',
+ name: 'Collapsible — Single Mode',
+ description: 'Only one section open at a time. Use for settings pages or any list where expanding one item should close the others.',
isReady: true,
aspectRatio: 4 / 3,
- componentsUsed: ['Collapsible', 'Card', 'Layout'],
+ componentsUsed: ['Collapsible', 'Section', 'Text', 'Layout'],
};
diff --git a/packages/cli/templates/blocks/components/Collapsible/CollapsibleSingleAccordion.tsx b/packages/cli/templates/blocks/components/Collapsible/CollapsibleSingleAccordion.tsx
index f808bbb515..e63cff8ae7 100644
--- a/packages/cli/templates/blocks/components/Collapsible/CollapsibleSingleAccordion.tsx
+++ b/packages/cli/templates/blocks/components/Collapsible/CollapsibleSingleAccordion.tsx
@@ -1,36 +1,37 @@
'use client';
import {XDSCollapsible, XDSCollapsibleGroup} from '@xds/core/Collapsible';
-import {XDSCard} from '@xds/core/Card';
+import {XDSSection} from '@xds/core/Section';
+import {XDSText} from '@xds/core/Text';
import {XDSVStack} from '@xds/core/Layout';
export default function CollapsibleSingleAccordion() {
return (
<XDSCollapsibleGroup type="single" defaultValue="general">
<XDSVStack gap={2}>
- <XDSCard>
+ <XDSSection>
<XDSCollapsible trigger="General Settings" value="general">
- <p style={{margin: 0}}>
+ <XDSText type="body">
Configure your general preferences including language, timezone,
and display options.
- </p>
+ </XDSText>
</XDSCollapsible>
- </XDSCard>
- <XDSCard>
+ </XDSSection>
+ <XDSSection>
<XDSCollapsible trigger="Privacy Settings" value="privacy">
- <p style={{margin: 0}}>
+ <XDSText type="body">
Manage who can see your profile, activity, and personal
information.
- </p>
+ </XDSText>
</XDSCollapsible>
- </XDSCard>
- <XDSCard>
+ </XDSSection>
+ <XDSSection>
<XDSCollapsible trigger="Notification Settings" value="notifications">
- <p style={{margin: 0}}>
+ <XDSText type="body">
Choose which notifications you receive and how they are delivered.
- </p>
+ </XDSText>
</XDSCollapsible>
- </XDSCard>
+ </XDSSection>
</XDSVStack>
</XDSCollapsibleGroup>
);
diff --git a/packages/cli/templates/blocks/components/Collapsible/CollapsibleWithoutCard.doc.mjs b/packages/cli/templates/blocks/components/Collapsible/CollapsibleWithoutCard.doc.mjs
index f28e152188..c9be191ee2 100644
--- a/packages/cli/templates/blocks/components/Collapsible/CollapsibleWithoutCard.doc.mjs
+++ b/packages/cli/templates/blocks/components/Collapsible/CollapsibleWithoutCard.doc.mjs
@@ -1,10 +1,9 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'Collapsible — Without Card',
- description:
- 'Standalone collapsible sections used without card wrappers.',
+ name: 'Collapsible — With Dividers',
+ description: 'Collapsible sections separated by dividers instead of cards. Use for inline disclosure in detail panels or sidebar content where cards would add too much weight.',
isReady: true,
aspectRatio: 4 / 3,
- componentsUsed: ['Collapsible', 'Layout'],
+ componentsUsed: ['Collapsible', 'Divider', 'Text', 'Layout'],
};
diff --git a/packages/cli/templates/blocks/components/Collapsible/CollapsibleWithoutCard.tsx b/packages/cli/templates/blocks/components/Collapsible/CollapsibleWithoutCard.tsx
index dd1b4ef0bc..bce0494900 100644
--- a/packages/cli/templates/blocks/components/Collapsible/CollapsibleWithoutCard.tsx
+++ b/packages/cli/templates/blocks/components/Collapsible/CollapsibleWithoutCard.tsx
@@ -1,18 +1,32 @@
'use client';
import {XDSCollapsible} from '@xds/core/Collapsible';
+import {XDSDivider} from '@xds/core/Divider';
+import {XDSText} from '@xds/core/Text';
import {XDSVStack} from '@xds/core/Layout';
export default function CollapsibleWithoutCard() {
return (
- <XDSVStack gap={2}>
- <XDSCollapsible trigger="Show more details">
- <p style={{margin: 0}}>
- XDSCollapsible works anywhere — it doesn't require a card wrapper.
- </p>
+ <XDSVStack gap={3}>
+ <XDSCollapsible trigger="Deployment Details">
+ <XDSText type="body">
+ Last deployed on April 18, 2026 at 3:42 PM by Sarah Chen. Build
+ duration was 2m 14s with zero warnings.
+ </XDSText>
</XDSCollapsible>
- <XDSCollapsible trigger="Another section" defaultIsOpen={false}>
- <p style={{margin: 0}}>This section starts collapsed.</p>
+ <XDSDivider />
+ <XDSCollapsible trigger="Environment Variables" defaultIsOpen={false}>
+ <XDSText type="body">
+ 12 variables configured. Last updated March 30, 2026. All secrets are
+ encrypted at rest with AES-256.
+ </XDSText>
+ </XDSCollapsible>
+ <XDSDivider />
+ <XDSCollapsible trigger="Build Logs" defaultIsOpen={false}>
+ <XDSText type="body">
+ Build completed successfully. 847 modules compiled, 0 errors, 0
+ warnings. Bundle size: 142 KB gzipped.
+ </XDSText>
</XDSCollapsible>
</XDSVStack>
);
diff --git a/packages/cli/templates/blocks/components/Divider/DividerFullBleed.doc.mjs b/packages/cli/templates/blocks/components/Divider/DividerFullBleed.doc.mjs
index 3dd8bb3c8b..a27129af84 100644
--- a/packages/cli/templates/blocks/components/Divider/DividerFullBleed.doc.mjs
+++ b/packages/cli/templates/blocks/components/Divider/DividerFullBleed.doc.mjs
@@ -2,8 +2,9 @@
export const doc = {
type: 'block',
name: 'Divider — Full Bleed',
- description: 'Full-bleed divider that extends past container padding.',
+ description:
+ 'Divider that extends past container padding to span the full width. Use inside cards or panels when you want a clean edge-to-edge separation, like between an order summary and total.',
isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Divider'],
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Divider', 'Card', 'Section', 'Layout', 'Text'],
};
diff --git a/packages/cli/templates/blocks/components/Divider/DividerFullBleed.tsx b/packages/cli/templates/blocks/components/Divider/DividerFullBleed.tsx
index c0c98d7871..d5fe8b12bc 100644
--- a/packages/cli/templates/blocks/components/Divider/DividerFullBleed.tsx
+++ b/packages/cli/templates/blocks/components/Divider/DividerFullBleed.tsx
@@ -3,7 +3,7 @@
import {XDSDivider} from '@xds/core/Divider';
import {XDSCard} from '@xds/core/Card';
import {XDSSection} from '@xds/core/Section';
-import {XDSVStack} from '@xds/core/Layout';
+import {XDSVStack, XDSHStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
export default function DividerFullBleed() {
@@ -11,12 +11,25 @@ export default function DividerFullBleed() {
<XDSSection variant="wash">
<XDSCard>
<XDSVStack gap={3}>
- <XDSText type="label">Full bleed divider</XDSText>
- <XDSText type="body">
- The divider extends to container edges, ignoring padding.
- </XDSText>
+ <XDSText type="label">Order Summary</XDSText>
+ <XDSHStack hAlign="between">
+ <XDSText type="body">3 items</XDSText>
+ <XDSText type="body">$127.00</XDSText>
+ </XDSHStack>
<XDSDivider isFullBleed />
- <XDSText type="body">Content below the divider.</XDSText>
+ <XDSHStack hAlign="between">
+ <XDSText type="body">Shipping</XDSText>
+ <XDSText type="body">$7.99</XDSText>
+ </XDSHStack>
+ <XDSHStack hAlign="between">
+ <XDSText type="body">Tax</XDSText>
+ <XDSText type="body">$10.16</XDSText>
+ </XDSHStack>
+ <XDSDivider isFullBleed />
+ <XDSHStack hAlign="between">
+ <XDSText type="label">Total</XDSText>
+ <XDSText type="label">$145.15</XDSText>
+ </XDSHStack>
</XDSVStack>
</XDSCard>
</XDSSection>
diff --git a/packages/cli/templates/blocks/components/Divider/DividerInCard.doc.mjs b/packages/cli/templates/blocks/components/Divider/DividerInCard.doc.mjs
deleted file mode 100644
index f7e6fbba01..0000000000
--- a/packages/cli/templates/blocks/components/Divider/DividerInCard.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Divider — In Card',
- description:
- 'Multiple dividers within a card to separate title, body, and details.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Divider'],
-};
diff --git a/packages/cli/templates/blocks/components/Divider/DividerInCard.tsx b/packages/cli/templates/blocks/components/Divider/DividerInCard.tsx
deleted file mode 100644
index e8b33b7b1d..0000000000
--- a/packages/cli/templates/blocks/components/Divider/DividerInCard.tsx
+++ /dev/null
@@ -1,28 +0,0 @@
-'use client';
-
-import {XDSDivider} from '@xds/core/Divider';
-import {XDSCard} from '@xds/core/Card';
-import {XDSSection} from '@xds/core/Section';
-import {XDSVStack} from '@xds/core/Layout';
-import {XDSText} from '@xds/core/Text';
-
-export default function DividerInCard() {
- return (
- <XDSSection variant="wash">
- <XDSCard>
- <XDSVStack gap={3}>
- <XDSText type="label">Card Title</XDSText>
- <XDSDivider />
- <XDSText type="body">
- This demonstrates how a divider can be used to separate content
- sections within a card or panel.
- </XDSText>
- <XDSDivider label="More Info" />
- <XDSText type="supporting">
- Additional details can appear below a labeled divider.
- </XDSText>
- </XDSVStack>
- </XDSCard>
- </XDSSection>
- );
-}
diff --git a/packages/cli/templates/blocks/components/Divider/DividerVariants.doc.mjs b/packages/cli/templates/blocks/components/Divider/DividerVariants.doc.mjs
new file mode 100644
index 0000000000..c4b2a3e013
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Divider/DividerVariants.doc.mjs
@@ -0,0 +1,10 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'Divider — Variants',
+ description:
+ 'Subtle, labeled, and strong dividers in a single card. Use subtle between related sections, labeled for alternatives like "or", and strong for high-contrast boundaries.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Divider', 'Card', 'Section', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/Divider/DividerVariants.tsx b/packages/cli/templates/blocks/components/Divider/DividerVariants.tsx
new file mode 100644
index 0000000000..5148872bb8
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Divider/DividerVariants.tsx
@@ -0,0 +1,35 @@
+'use client';
+
+import {XDSDivider} from '@xds/core/Divider';
+import {XDSCard} from '@xds/core/Card';
+import {XDSSection} from '@xds/core/Section';
+import {XDSVStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+export default function DividerVariants() {
+ return (
+ <XDSSection variant="wash">
+ <XDSCard>
+ <XDSVStack gap={3}>
+ <XDSVStack gap={1}>
+ <XDSText type="label">Sign in with email</XDSText>
+ <XDSText type="body">
+ Enter your email and password to access your account.
+ </XDSText>
+ </XDSVStack>
+ <XDSDivider label="or" />
+ <XDSVStack gap={1}>
+ <XDSText type="label">Sign in with SSO</XDSText>
+ <XDSText type="body">
+ Use your company credentials to sign in automatically.
+ </XDSText>
+ </XDSVStack>
+ <XDSDivider variant="strong" />
+ <XDSText type="supporting" color="secondary">
+ By signing in, you agree to our Terms of Service and Privacy Policy.
+ </XDSText>
+ </XDSVStack>
+ </XDSCard>
+ </XDSSection>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Divider/DividerVertical.doc.mjs b/packages/cli/templates/blocks/components/Divider/DividerVertical.doc.mjs
index fc9dfe3706..628694bea6 100644
--- a/packages/cli/templates/blocks/components/Divider/DividerVertical.doc.mjs
+++ b/packages/cli/templates/blocks/components/Divider/DividerVertical.doc.mjs
@@ -2,8 +2,9 @@
export const doc = {
type: 'block',
name: 'Divider — Vertical',
- description: 'Vertical divider separating side-by-side content.',
+ description:
+ 'Vertical dividers separating side-by-side metrics. Use between stat cards, toolbar groups, or any horizontal layout where you need a visual boundary between sections.',
isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Divider'],
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Divider', 'Card', 'Section', 'Layout', 'Text'],
};
diff --git a/packages/cli/templates/blocks/components/Divider/DividerVertical.tsx b/packages/cli/templates/blocks/components/Divider/DividerVertical.tsx
index 728823324f..c2b072c798 100644
--- a/packages/cli/templates/blocks/components/Divider/DividerVertical.tsx
+++ b/packages/cli/templates/blocks/components/Divider/DividerVertical.tsx
@@ -3,17 +3,37 @@
import {XDSDivider} from '@xds/core/Divider';
import {XDSCard} from '@xds/core/Card';
import {XDSSection} from '@xds/core/Section';
-import {XDSHStack} from '@xds/core/Layout';
+import {XDSHStack, XDSVStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
export default function DividerVertical() {
return (
<XDSSection variant="wash">
- <XDSCard height={200}>
- <XDSHStack gap={4} style={{height: '100%'}}>
- <XDSText type="body">Left content</XDSText>
+ <XDSCard>
+ <XDSHStack gap={4}>
+ <XDSVStack gap={1}>
+ <XDSText type="label">Revenue</XDSText>
+ <XDSText type="label">$24,500</XDSText>
+ <XDSText type="supporting" color="secondary">
+ +12% vs last month
+ </XDSText>
+ </XDSVStack>
<XDSDivider orientation="vertical" />
- <XDSText type="body">Right content</XDSText>
+ <XDSVStack gap={1}>
+ <XDSText type="label">Users</XDSText>
+ <XDSText type="label">1,240</XDSText>
+ <XDSText type="supporting" color="secondary">
+ +8% vs last month
+ </XDSText>
+ </XDSVStack>
+ <XDSDivider orientation="vertical" />
+ <XDSVStack gap={1}>
+ <XDSText type="label">Conversion</XDSText>
+ <XDSText type="label">3.2%</XDSText>
+ <XDSText type="supporting" color="secondary">
+ -0.5% vs last month
+ </XDSText>
+ </XDSVStack>
</XDSHStack>
</XDSCard>
</XDSSection>
diff --git a/packages/cli/templates/blocks/components/Divider/DividerWithLabel.doc.mjs b/packages/cli/templates/blocks/components/Divider/DividerWithLabel.doc.mjs
deleted file mode 100644
index f321796c0e..0000000000
--- a/packages/cli/templates/blocks/components/Divider/DividerWithLabel.doc.mjs
+++ /dev/null
@@ -1,9 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Divider — With Label',
- description: 'Horizontal divider with a centered text label.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Divider'],
-};
diff --git a/packages/cli/templates/blocks/components/Divider/DividerWithLabel.tsx b/packages/cli/templates/blocks/components/Divider/DividerWithLabel.tsx
deleted file mode 100644
index 59d87a1155..0000000000
--- a/packages/cli/templates/blocks/components/Divider/DividerWithLabel.tsx
+++ /dev/null
@@ -1,21 +0,0 @@
-'use client';
-
-import {XDSDivider} from '@xds/core/Divider';
-import {XDSCard} from '@xds/core/Card';
-import {XDSSection} from '@xds/core/Section';
-import {XDSVStack} from '@xds/core/Layout';
-import {XDSText} from '@xds/core/Text';
-
-export default function DividerWithLabel() {
- return (
- <XDSSection variant="wash">
- <XDSCard>
- <XDSVStack gap={3}>
- <XDSText type="body">Content above</XDSText>
- <XDSDivider label="or" />
- <XDSText type="body">Content below</XDSText>
- </XDSVStack>
- </XDSCard>
- </XDSSection>
- );
-}
diff --git a/packages/cli/templates/showcase/Collapsible.tsx b/packages/cli/templates/showcase/Collapsible.tsx
index 3f03f9cf4a..4dc2b44e0a 100644
--- a/packages/cli/templates/showcase/Collapsible.tsx
+++ b/packages/cli/templates/showcase/Collapsible.tsx
@@ -1,13 +1,14 @@
'use client';
import {XDSCollapsible} from '@xds/core/Collapsible';
+import {XDSText} from '@xds/core/Text';
export default function CollapsibleShowcase() {
return (
<XDSCollapsible trigger="Show more details">
- <p style={{margin: 0}}>
+ <XDSText type="body">
This collapsible manages its own state. Click the trigger to toggle.
- </p>
+ </XDSText>
</XDSCollapsible>
);
}
diff --git a/packages/core/src/Collapsible/Collapsible.doc.mjs b/packages/core/src/Collapsible/Collapsible.doc.mjs
index 3d31c47ede..75ec4c409f 100644
--- a/packages/core/src/Collapsible/Collapsible.doc.mjs
+++ b/packages/core/src/Collapsible/Collapsible.doc.mjs
@@ -85,12 +85,20 @@ export const docs = {
},
],
usage: {
- description: 'Collapsible is a content primitive that reveals and hides content on demand via a trigger button. Use it to progressively disclose secondary information in lists, settings, or detail panels.',
+ description: 'Collapsible hides and reveals content behind a trigger button. Use it in settings panels, FAQ pages, or detail views to keep the page scannable while letting users drill into sections they care about. Wrap multiple collapsibles in XDSCollapsibleGroup for accordion behavior.',
bestPractices: [
- { guidance: true, description: 'Use XDSCollapsibleGroup with type="single" for accordion-style patterns where only one section should be open at a time.' },
- { guidance: true, description: 'Start sections open (defaultIsOpen) when the content is likely needed on first view.' },
+ { guidance: true, description: 'Wrap each XDSCollapsible in an XDSCard for visual separation in accordion layouts.' },
+ { guidance: true, description: 'Use XDSCollapsibleGroup with type="single" for settings or FAQ pages where only one section should be open at a time.' },
+ { guidance: true, description: 'Use type="multiple" when users need to compare content across sections, like feature lists or pricing tiers.' },
+ { guidance: true, description: 'Start sections open (defaultIsOpen) when the content is likely needed on first view — don\'t make users click to see essential info.' },
{ guidance: false, description: 'Hide critical or required content behind a collapsible — users may not discover it.' },
- { guidance: false, description: 'Nest collapsibles deeply — more than two levels makes content hard to discover and navigate.' },
+ { guidance: false, description: 'Nest collapsibles more than two levels deep — it makes content hard to find and navigate.' },
+ { guidance: false, description: 'Use a collapsible for a single short paragraph — just show the text directly instead.' },
+ ],
+ anatomy: [
+ { name: 'Trigger', required: true, description: 'The always-visible button that toggles the content. Shows a label and a chevron indicator.' },
+ { name: 'Chevron', required: false, description: 'Animated arrow that rotates to show open or closed state.' },
+ { name: 'Content', required: false, description: 'The area that hides or reveals when the trigger is clicked.' },
],
},
};
@@ -99,12 +107,15 @@ export const docs = {
export const docsZh = {
name: 'Collapsible',
usage: {
- description: 'Collapsible is a content primitive that reveals and hides content on demand via a trigger button. Use it to progressively disclose secondary information in lists, settings, or detail panels.',
+ description: 'Collapsible hides and reveals content behind a trigger button. Use it in settings panels, FAQ pages, or detail views to keep the page scannable while letting users drill into sections they care about. Wrap multiple collapsibles in XDSCollapsibleGroup for accordion behavior.',
bestPractices: [
- { guidance: true, description: 'Use XDSCollapsibleGroup with type="single" for accordion-style patterns where only one section should be open at a time.' },
- { guidance: true, description: 'Start sections open (defaultIsOpen) when the content is likely needed on first view.' },
+ { guidance: true, description: 'Wrap each XDSCollapsible in an XDSCard for visual separation in accordion layouts.' },
+ { guidance: true, description: 'Use XDSCollapsibleGroup with type="single" for settings or FAQ pages where only one section should be open at a time.' },
+ { guidance: true, description: 'Use type="multiple" when users need to compare content across sections, like feature lists or pricing tiers.' },
+ { guidance: true, description: 'Start sections open (defaultIsOpen) when the content is likely needed on first view — don\'t make users click to see essential info.' },
{ guidance: false, description: 'Hide critical or required content behind a collapsible — users may not discover it.' },
- { guidance: false, description: 'Nest collapsibles deeply — more than two levels makes content hard to discover and navigate.' },
+ { guidance: false, description: 'Nest collapsibles more than two levels deep — it makes content hard to find and navigate.' },
+ { guidance: false, description: 'Use a collapsible for a single short paragraph — just show the text directly instead.' },
],
},
theming: {
@@ -143,14 +154,15 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
- description: 'collapsible content primitive + group coordination',
+ description: 'hide/reveal content behind a trigger; group for accordion behavior',
usage: {
- description: 'Collapsible is a content primitive that reveals and hides content on demand via a trigger button. Use it to progressively disclose secondary information in lists, settings, or detail panels.',
+ description: 'Collapsible hides and reveals content behind a trigger button. Use in settings, FAQs, or detail views. Wrap in XDSCollapsibleGroup for accordion behavior.',
bestPractices: [
- { guidance: true, description: 'Use XDSCollapsibleGroup with type="single" for accordion-style patterns where only one section should be open at a time.' },
- { guidance: true, description: 'Start sections open (defaultIsOpen) when the content is likely needed on first view.' },
- { guidance: false, description: 'Hide critical or required content behind a collapsible — users may not discover it.' },
- { guidance: false, description: 'Nest collapsibles deeply — more than two levels makes content hard to discover and navigate.' },
+ { guidance: true, description: 'Wrap in XDSCard for visual separation. Use type="single" for settings/FAQs.' },
+ { guidance: true, description: 'Use type="multiple" when users need to compare across sections.' },
+ { guidance: true, description: 'Start sections open (defaultIsOpen) when content is needed on first view.' },
+ { guidance: false, description: 'Hide critical content behind a collapsible — users may not discover it.' },
+ { guidance: false, description: 'Nest more than two levels deep. Avoid for single short paragraphs.' },
],
},
components: [
diff --git a/packages/core/src/Collapsible/XDSCollapsible.tsx b/packages/core/src/Collapsible/XDSCollapsible.tsx
index 3e55610648..3987e97a37 100644
--- a/packages/core/src/Collapsible/XDSCollapsible.tsx
+++ b/packages/core/src/Collapsible/XDSCollapsible.tsx
@@ -35,6 +35,9 @@ import {xdsClassName, mergeProps} from '../utils';
import type {XDSBaseProps} from '../XDSBaseProps';
const styles = stylex.create({
+ root: {
+ width: '100%',
+ },
// Trigger button — full width, flex row, no browser button styling
trigger: {
all: 'unset',
@@ -187,7 +190,7 @@ export function XDSCollapsible({
ref={ref}
{...mergeProps(
xdsClassName('collapsible'),
- stylex.props(xstyle),
+ stylex.props(styles.root, xstyle),
className,
style,
)}