An open source design system that's fully customizable and agent ready
TypeScript
Improve Section docs page and block examples (#1671)
rubyycheung2eec061a2cf0
diff --git a/packages/cli/templates/blocks/components/Section/SectionPageLayout.doc.mjs b/packages/cli/templates/blocks/components/Section/SectionPageLayout.doc.mjsdeleted file mode 100644index 9c24ca5f1b..0000000000--- a/packages/cli/templates/blocks/components/Section/SectionPageLayout.doc.mjs+++ /dev/null@@ -1,10 +0,0 @@-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */-export const doc = {- type: 'block',- name: 'Section — Page Layout',- description:- 'Full page layout inside a section with header, sidebar panel, and main content area.',- isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['Section', 'Layout'],-};diff --git a/packages/cli/templates/blocks/components/Section/SectionPageLayout.tsx b/packages/cli/templates/blocks/components/Section/SectionPageLayout.tsxdeleted file mode 100644index 7fe0e893b5..0000000000--- a/packages/cli/templates/blocks/components/Section/SectionPageLayout.tsx+++ /dev/null@@ -1,45 +0,0 @@-'use client';--import {XDSSection} from '@xds/core/Section';-import {XDSVStack} from '@xds/core/Layout';-import {- XDSLayout,- XDSLayoutHeader,- XDSLayoutContent,- XDSLayoutPanel,-} from '@xds/core/Layout';--export default function SectionPageLayout() {- return (- <XDSSection variant="section" width={600} height={300}>- <XDSLayout- header={- <XDSLayoutHeader hasDivider>- <XDSVStack gap={2}>- <h2 style={{margin: 0}}>Page Header</h2>- <p style={{margin: 0, fontSize: 14, color: 'var(--color-text-secondary)'}}>- Welcome to the application- </p>- </XDSVStack>- </XDSLayoutHeader>- }- start={- <XDSLayoutPanel hasDivider width={150}>- <h3 style={{margin: 0}}>Sidebar</h3>- </XDSLayoutPanel>- }- content={- <XDSLayoutContent>- <XDSVStack gap={2}>- <h3 style={{margin: 0}}>Main Content</h3>- <p style={{margin: 0, fontSize: 14, color: 'var(--color-text-secondary)'}}>- This demonstrates how XDSLayout can be used to create page- layouts with header, sidebar, and content areas.- </p>- </XDSVStack>- </XDSLayoutContent>- }- />- </XDSSection>- );-}diff --git a/packages/cli/templates/blocks/components/Section/SectionShowcase.doc.mjs b/packages/cli/templates/blocks/components/Section/SectionShowcase.doc.mjsdeleted file mode 100644index 901773b375..0000000000--- a/packages/cli/templates/blocks/components/Section/SectionShowcase.doc.mjs+++ /dev/null@@ -1,8 +0,0 @@-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */-export const doc = {- type: 'block',- name: 'Section',- isReady: true,- aspectRatio: 1,- isShowcase: true,-};diff --git a/packages/cli/templates/blocks/components/Section/SectionShowcase.tsx b/packages/cli/templates/blocks/components/Section/SectionShowcase.tsxdeleted file mode 100644index 0a6dd6c27e..0000000000--- a/packages/cli/templates/blocks/components/Section/SectionShowcase.tsx+++ /dev/null@@ -1,14 +0,0 @@-'use client';--import {XDSSection} from '@xds/core/Section';--export default function SectionShowcase() {- return (- <XDSSection variant="section" width={300}>- <p style={{margin: 0}}>- A section with default padding. Sections define distinct areas within a- page.- </p>- </XDSSection>- );-}diff --git a/packages/cli/templates/blocks/components/Section/SectionSimpleContent.doc.mjs b/packages/cli/templates/blocks/components/Section/SectionSimpleContent.doc.mjsdeleted file mode 100644index e53514bfe5..0000000000--- a/packages/cli/templates/blocks/components/Section/SectionSimpleContent.doc.mjs+++ /dev/null@@ -1,10 +0,0 @@-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */-export const doc = {- type: 'block',- name: 'Section — Simple Content',- description:- 'Section with a wash variant containing a title and description using automatic container padding.',- isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['Section', 'VStack'],-};diff --git a/packages/cli/templates/blocks/components/Section/SectionSimpleContent.tsx b/packages/cli/templates/blocks/components/Section/SectionSimpleContent.tsxdeleted file mode 100644index 2803e0baff..0000000000--- a/packages/cli/templates/blocks/components/Section/SectionSimpleContent.tsx+++ /dev/null@@ -1,18 +0,0 @@-'use client';--import {XDSSection} from '@xds/core/Section';-import {XDSVStack} from '@xds/core/Layout';--export default function SectionSimpleContent() {- return (- <XDSSection variant="wash" width={320}>- <XDSVStack gap={2}>- <h3 style={{margin: 0}}>Section Title</h3>- <p style={{margin: 0, fontSize: 14, color: 'var(--color-text-secondary)'}}>- This section contains simple content without an inner layout. The- container padding is applied automatically.- </p>- </XDSVStack>- </XDSSection>- );-}diff --git a/packages/cli/templates/blocks/components/Section/SectionVariants.doc.mjs b/packages/cli/templates/blocks/components/Section/SectionVariants.doc.mjsnew file mode 100644index 0000000000..356d1d04cf--- /dev/null+++ b/packages/cli/templates/blocks/components/Section/SectionVariants.doc.mjs@@ -0,0 +1,11 @@+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */+export const doc = {+ type: 'block',+ name: 'Section — Variants',+ description:+ 'All three background variants stacked — section (default surface), wash (muted), and transparent. A quick visual reference for choosing the right variant.',+ isReady: true,+ isShowcase: true,+ aspectRatio: 16 / 9,+ componentsUsed: ['Section', 'Layout', 'Text'],+};diff --git a/packages/cli/templates/blocks/components/Section/SectionVariants.tsx b/packages/cli/templates/blocks/components/Section/SectionVariants.tsxnew file mode 100644index 0000000000..a865fbb551--- /dev/null+++ b/packages/cli/templates/blocks/components/Section/SectionVariants.tsx@@ -0,0 +1,52 @@+'use client';++import {XDSSection} from '@xds/core/Section';+import {XDSStack} from '@xds/core/Layout';+import {XDSText} from '@xds/core/Text';+import * as stylex from '@stylexjs/stylex';+import {colorVars} from '@xds/core/theme/tokens.stylex';++const styles = stylex.create({+ transparentWrapper: {+ backgroundColor: colorVars['--color-background-blue'],+ },+});++export default function SectionVariants() {+ return (+ <XDSStack direction="vertical" gap={0}>+ <XDSSection variant="section" padding={5}>+ <XDSStack direction="vertical" gap={1}>+ <XDSText type="body" weight="bold">+ Section+ </XDSText>+ <XDSText type="supporting" color="secondary">+ White background.+ </XDSText>+ </XDSStack>+ </XDSSection>+ <XDSSection variant="wash" padding={5}>+ <XDSStack direction="vertical" gap={1}>+ <XDSText type="body" weight="bold">+ Wash+ </XDSText>+ <XDSText type="supporting" color="secondary">+ Gray background.+ </XDSText>+ </XDSStack>+ </XDSSection>+ <XDSStack direction="vertical" xstyle={styles.transparentWrapper}>+ <XDSSection variant="transparent" padding={5}>+ <XDSStack direction="vertical" gap={1}>+ <XDSText type="body" weight="bold">+ Transparent+ </XDSText>+ <XDSText type="supporting" color="secondary">+ No background, shows the color behind it.+ </XDSText>+ </XDSStack>+ </XDSSection>+ </XDSStack>+ </XDSStack>+ );+}diff --git a/packages/cli/templates/blocks/components/Section/SectionWashHighlight.doc.mjs b/packages/cli/templates/blocks/components/Section/SectionWashHighlight.doc.mjsnew file mode 100644index 0000000000..4615ee5838--- /dev/null+++ b/packages/cli/templates/blocks/components/Section/SectionWashHighlight.doc.mjs@@ -0,0 +1,10 @@+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */+export const doc = {+ type: 'block',+ name: 'Section — Default with Wash',+ description:+ 'A default section stacked with a full-width wash section. Shows how wash draws attention to a specific region like an upgrade prompt or banner.',+ isReady: true,+ aspectRatio: 16 / 9,+ componentsUsed: ['Section', 'Layout', 'Text', 'Button', 'Icon'],+};diff --git a/packages/cli/templates/blocks/components/Section/SectionWashHighlight.tsx b/packages/cli/templates/blocks/components/Section/SectionWashHighlight.tsxnew file mode 100644index 0000000000..aabdf97129--- /dev/null+++ b/packages/cli/templates/blocks/components/Section/SectionWashHighlight.tsx@@ -0,0 +1,55 @@+'use client';++import {XDSSection} from '@xds/core/Section';+import {XDSStack} from '@xds/core/Layout';+import {XDSHeading, XDSText} from '@xds/core/Text';+import {XDSButton} from '@xds/core/Button';+import {XDSIcon} from '@xds/core/Icon';+import {CheckIcon} from '@heroicons/react/24/solid';++const FEATURES = [+ '10 team members',+ 'Unlimited projects',+ 'Priority support',+ 'Advanced analytics',+];++export default function SectionDefaultWithWash() {+ return (+ <XDSStack direction="vertical" gap={0}>+ <XDSSection variant="section" padding={5}>+ <XDSStack direction="vertical" gap={3} hAlign="center">+ <XDSStack direction="vertical" gap={1} hAlign="center">+ <XDSText type="display-3">Pro Plan</XDSText>+ <XDSText type="body" color="secondary">+ Everything you need to scale your team.+ </XDSText>+ </XDSStack>+ <XDSStack direction="vertical" gap={2}>+ {FEATURES.map(feature => (+ <XDSStack+ key={feature}+ direction="horizontal"+ gap={2}+ vAlign="center">+ <XDSIcon icon={CheckIcon} size="sm" />+ <XDSText type="body">{feature}</XDSText>+ </XDSStack>+ ))}+ </XDSStack>+ </XDSStack>+ </XDSSection>+ <XDSSection variant="wash" padding={5}>+ <XDSStack direction="vertical" gap={2} hAlign="center">+ <XDSStack direction="horizontal" gap={1} vAlign="end">+ <XDSHeading level={3}>$49</XDSHeading>+ <XDSText type="supporting" color="secondary">+ /month+ </XDSText>+ </XDSStack>+ <XDSButton label="Upgrade" variant="primary" />+ </XDSStack>+ </XDSSection>+ </XDSStack>+ );+}diff --git a/packages/cli/templates/blocks/components/Section/SectionWithDividers.doc.mjs b/packages/cli/templates/blocks/components/Section/SectionWithDividers.doc.mjsnew file mode 100644index 0000000000..71c5649ba4--- /dev/null+++ b/packages/cli/templates/blocks/components/Section/SectionWithDividers.doc.mjs@@ -0,0 +1,10 @@+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */+export const doc = {+ type: 'block',+ name: 'Section — With Dividers',+ description:+ 'Adjacent sections separated by bottom dividers, like a settings page. Use dividers when stacking same-variant sections that need visual separation without a background change.',+ isReady: true,+ aspectRatio: 16 / 9,+ componentsUsed: ['Section', 'Layout', 'Text'],+};diff --git a/packages/cli/templates/blocks/components/Section/SectionWithDividers.tsx b/packages/cli/templates/blocks/components/Section/SectionWithDividers.tsxnew file mode 100644index 0000000000..9b6c5aa772--- /dev/null+++ b/packages/cli/templates/blocks/components/Section/SectionWithDividers.tsx@@ -0,0 +1,36 @@+'use client';++import {XDSSection} from '@xds/core/Section';+import {XDSStack} from '@xds/core/Layout';+import {XDSHeading, XDSText} from '@xds/core/Text';++export default function SectionWithDividers() {+ return (+ <XDSStack direction="vertical" gap={0}>+ <XDSSection variant="section" padding={5} dividers={['bottom']}>+ <XDSStack direction="vertical" gap={1}>+ <XDSHeading level={4}>Account</XDSHeading>+ <XDSText type="body" color="secondary">+ Manage your profile, email, and password.+ </XDSText>+ </XDSStack>+ </XDSSection>+ <XDSSection variant="section" padding={5} dividers={['bottom']}>+ <XDSStack direction="vertical" gap={1}>+ <XDSHeading level={4}>Notifications</XDSHeading>+ <XDSText type="body" color="secondary">+ Choose what updates you receive and how.+ </XDSText>+ </XDSStack>+ </XDSSection>+ <XDSSection variant="section" padding={5}>+ <XDSStack direction="vertical" gap={1}>+ <XDSHeading level={4}>Privacy</XDSHeading>+ <XDSText type="body" color="secondary">+ Control who can see your activity and data.+ </XDSText>+ </XDSStack>+ </XDSSection>+ </XDSStack>+ );+}diff --git a/packages/cli/templates/blocks/components/Section/SectionWithInnerLayout.doc.mjs b/packages/cli/templates/blocks/components/Section/SectionWithInnerLayout.doc.mjsdeleted file mode 100644index 38ab15fa0f..0000000000--- a/packages/cli/templates/blocks/components/Section/SectionWithInnerLayout.doc.mjs+++ /dev/null@@ -1,10 +0,0 @@-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */-export const doc = {- type: 'block',- name: 'Section — With Inner Layout',- description:- 'Section containing an XDSLayout with header, scrollable content, and footer with action button.',- isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['Section', 'Layout', 'Button'],-};diff --git a/packages/cli/templates/blocks/components/Section/SectionWithInnerLayout.tsx b/packages/cli/templates/blocks/components/Section/SectionWithInnerLayout.tsxdeleted file mode 100644index 4db90ec6ca..0000000000--- a/packages/cli/templates/blocks/components/Section/SectionWithInnerLayout.tsx+++ /dev/null@@ -1,42 +0,0 @@-'use client';--import {XDSSection} from '@xds/core/Section';-import {XDSHStack} from '@xds/core/Layout';-import {- XDSLayout,- XDSLayoutHeader,- XDSLayoutContent,- XDSLayoutFooter,-} from '@xds/core/Layout';-import {XDSButton} from '@xds/core/Button';--export default function SectionWithInnerLayout() {- return (- <XDSSection variant="wash" width={350} height={250}>- <XDSLayout- header={- <XDSLayoutHeader hasDivider>- <h3 style={{margin: 0}}>Section with Layout</h3>- </XDSLayoutHeader>- }- content={- <XDSLayoutContent>- <p style={{margin: 0, fontSize: 14, color: 'var(--color-text-secondary)'}}>- When using XDSLayout, the layout manages its own padding- independently from the container padding.- </p>- </XDSLayoutContent>- }- footer={- <XDSLayoutFooter hasDivider>- <XDSHStack gap={2} hAlign="end">- <XDSButton label="Action" variant="primary">- Action- </XDSButton>- </XDSHStack>- </XDSLayoutFooter>- }- />- </XDSSection>- );-}diff --git a/packages/core/src/Section/Section.doc.mjs b/packages/core/src/Section/Section.doc.mjsindex e256b33b1a..327c2d7622 100644--- a/packages/core/src/Section/Section.doc.mjs+++ b/packages/core/src/Section/Section.doc.mjs@@ -65,11 +65,10 @@ export const docs = {},usage: {description:- 'Section is a container with background variants for creating visually distinct regions on a page. It automatically escapes parent padding for edge-to-edge fills. Use sections as the default page structure; reach for cards only when stronger visual distinction is needed.',+ 'Section is a container that is used to create visual separation. Use the default variant for standard content (white), wash to emphasize or group related content (gray), and transparent for no background while still using Section\'s padding and dividers.',bestPractices: [- { guidance: true, description: 'Use dividers to separate adjacent sections when background variants alone do not provide enough visual contrast.' },- { guidance: true, description: 'Default to the section variant for standard content regions; reserve wash for highlighted or grouped areas.' },- { guidance: false, description: 'Wrap content in a Section and a Card together — choose one container type to avoid redundant nesting.' },+ { guidance: true, description: 'Start with the default variant. Use wash only to call attention to a specific region.' },+ { guidance: true, description: 'Add dividers between same-background sections that need separation.' },],},};@@ -139,11 +138,10 @@ export const docsZh = {},usage: {description:- 'Section is a container with background variants for creating visually distinct regions on a page. It automatically escapes parent padding for edge-to-edge fills. Use sections as the default page structure; reach for cards only when stronger visual distinction is needed.',+ 'Section is a container that is used to create visual separation. Use the default variant for standard content (white), wash to emphasize or group related content (gray), and transparent for no background while still using Section\'s padding and dividers.',bestPractices: [- { guidance: true, description: 'Use dividers to separate adjacent sections when background variants alone do not provide enough visual contrast.' },- { guidance: true, description: 'Default to the section variant for standard content regions; reserve wash for highlighted or grouped areas.' },- { guidance: false, description: 'Wrap content in a Section and a Card together — choose one container type to avoid redundant nesting.' },+ { guidance: true, description: 'Start with the default variant. Use wash only to call attention to a specific region.' },+ { guidance: true, description: 'Add dividers between same-background sections that need separation.' },],},};@@ -154,11 +152,10 @@ export const docsDense = {'Container w/ background variants for creating visually distinct regions; auto-escapes parent container padding for edge-to-edge fills.',usage: {description:- 'Section is a container with background variants for creating visually distinct regions on a page. It automatically escapes parent padding for edge-to-edge fills. Use sections as the default page structure; reach for cards only when stronger visual distinction is needed.',+ 'Section is a container that is used to create visual separation. Use the default variant for standard content (white), wash to emphasize or group related content (gray), and transparent for no background while still using Section\'s padding and dividers.',bestPractices: [- { guidance: true, description: 'Use dividers to separate adjacent sections when background variants alone do not provide enough visual contrast.' },- { guidance: true, description: 'Default to the section variant for standard content regions; reserve wash for highlighted or grouped areas.' },- { guidance: false, description: 'Wrap content in a Section and a Card together — choose one container type to avoid redundant nesting.' },+ { guidance: true, description: 'Start with the default variant. Use wash only to call attention to a specific region.' },+ { guidance: true, description: 'Add dividers between same-background sections that need separation.' },],},propDescriptions: {