Skip to content

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

TypeScript

fix(docsite): Documentation pages styling fixes (#2530)

Kenton Quatman6167c8205d15
diff --git a/apps/docsite/src/components/ChangelogView.tsx b/apps/docsite/src/components/ChangelogView.tsx
index 4543d19b9e..3a495a2e96 100644
--- a/apps/docsite/src/components/ChangelogView.tsx
+++ b/apps/docsite/src/components/ChangelogView.tsx
@@ -10,6 +10,7 @@ import {XDSVStack} from '@xds/core/Layout';
import {XDSSection} from '@xds/core/Section';
import {XDSTabList, XDSTab} from '@xds/core/TabList';
import {XDSCarousel} from '@xds/core/Carousel';
+import {spacingVars} from '@xds/core/theme/tokens.stylex';
import {GITHUB_REPO} from '../constants';
function linkifyPRs(markdown: string): string {
@@ -58,12 +59,9 @@ interface ChangelogViewProps {
}
const styles = stylex.create({
- container: {
- maxWidth: 960,
+ section: {
marginInline: 'auto',
- },
- carouselTab: {
- marginBottom: 4,
+ paddingBottom: `calc(${spacingVars['--spacing-12']} * 2)`,
},
});
@@ -75,11 +73,13 @@ export function ChangelogView({
const active = changelogs.find(c => c.pkg === activeTab);
return (
- <XDSSection maxWidth="lg" padding={6} xstyle={styles.container}>
- <XDSVStack gap={6}>
- <XDSVStack gap={2}>
- <XDSHeading level={1}>What&apos;s New</XDSHeading>
- <XDSText type="body" color="secondary">
+ <XDSSection maxWidth={800} padding={6} xstyle={styles.section}>
+ <XDSVStack gap={8}>
+ <XDSVStack gap={4}>
+ <XDSHeading level={1} type="display-1">
+ What&apos;s New
+ </XDSHeading>
+ <XDSText type="large" weight="normal" color="secondary">
Release notes and changelog for all packages.
</XDSText>
</XDSVStack>
@@ -89,12 +89,7 @@ export function ChangelogView({
<XDSTabList value={activeTab} onChange={setActiveTab} hasDivider>
<XDSCarousel gap={0.5} hasSnap={false}>
{changelogs.map(c => (
- <XDSTab
- key={c.pkg}
- value={c.pkg}
- label={c.pkg}
- xstyle={styles.carouselTab}
- />
+ <XDSTab key={c.pkg} value={c.pkg} label={c.pkg} />
))}
</XDSCarousel>
</XDSTabList>
diff --git a/apps/docsite/src/components/DocsShell.tsx b/apps/docsite/src/components/DocsShell.tsx
index cc07e1a377..b3f73734e8 100644
--- a/apps/docsite/src/components/DocsShell.tsx
+++ b/apps/docsite/src/components/DocsShell.tsx
@@ -131,16 +131,12 @@ export function DocsShell({
{!isOnComponentsRoute && (
<>
{/* Getting Started */}
- <XDSSideNavSection title="Getting Started" isHeaderHidden>
+ <XDSSideNavSection title="Documentation" isHeaderHidden>
<XDSSideNavItem
label="Getting Started"
href="/docs/getting-started"
isSelected={pathname === '/docs/getting-started'}
/>
- </XDSSideNavSection>
-
- {/* What's New */}
- <XDSSideNavSection title="Changelog" isHeaderHidden>
<XDSSideNavItem
label="What's New"
href="/changelog"
diff --git a/apps/docsite/src/components/component-detail/BestPractices.tsx b/apps/docsite/src/components/component-detail/BestPractices.tsx
index bd288fa93e..77995ec251 100644
--- a/apps/docsite/src/components/component-detail/BestPractices.tsx
+++ b/apps/docsite/src/components/component-detail/BestPractices.tsx
@@ -17,8 +17,10 @@ export function BestPractices({practices}: BestPracticesProps) {
return (
<XDSSection>
- <XDSVStack gap={2}>
- <XDSHeading level={3}>Best practices</XDSHeading>
+ <XDSVStack gap={4}>
+ <XDSHeading level={2} type="display-3">
+ Best practices
+ </XDSHeading>
<BestPracticesBlock items={practices} />
</XDSVStack>
</XDSSection>
diff --git a/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx b/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx
index 149f74b8a6..3e01deada4 100644
--- a/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx
+++ b/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx
@@ -2,6 +2,7 @@
'use client';
+import * as stylex from '@stylexjs/stylex';
import {Suspense} from 'react';
import {useSearchParams, useRouter, usePathname} from 'next/navigation';
import {XDSHeading, XDSText} from '@xds/core/Text';
@@ -25,6 +26,14 @@ import type {ComponentEntry} from '../../generated/componentRegistry';
import type {BlockEntry} from '../../generated/blockRegistry';
import {showcaseRegistry} from '../../generated/showcaseRegistry';
import {exampleRegistry} from '../../generated/exampleRegistry';
+import {spacingVars} from '@xds/core/theme/tokens.stylex';
+
+const styles = stylex.create({
+ section: {
+ marginInline: 'auto',
+ paddingBottom: `calc(${spacingVars['--spacing-12']} * 2)`,
+ },
+});
interface ComponentDetailClientProps {
comp: ComponentEntry;
@@ -51,13 +60,20 @@ function OverviewContent({
)}
{comp.usage && (
- <XDSVStack gap={6}>
- <XDSHeading level={2}>Usage</XDSHeading>
+ <XDSVStack gap={4}>
+ <XDSHeading level={2} type="display-3">
+ Usage
+ </XDSHeading>
<XDSText type="large" weight="normal">
{comp.usage.description}
</XDSText>
- <XDSCodeBlock code={importPath} language="ts" hasCopyButton />
+ <XDSCodeBlock
+ code={importPath}
+ language="ts"
+ width="100%"
+ hasCopyButton
+ />
{comp.usage.bestPractices && comp.usage.bestPractices.length > 0 && (
<BestPractices practices={comp.usage.bestPractices} />
@@ -72,13 +88,15 @@ function OverviewContent({
{(exampleRegistry[comp.name] || []).length > 0 && (
<>
<XDSDivider />
- <XDSVStack gap={6}>
- <XDSHeading level={2}>Examples</XDSHeading>
+ <XDSVStack gap={4}>
+ <XDSHeading level={2} type="display-3">
+ Examples
+ </XDSHeading>
<XDSText type="large" weight="normal">
Common configurations, variations, and states.
</XDSText>
</XDSVStack>
- <XDSVStack gap={8}>
+ <XDSVStack gap={10}>
{(exampleRegistry[comp.name] || []).map((entry, i) => (
<ExampleBlock key={i} entry={entry} />
))}
@@ -125,9 +143,9 @@ function ComponentDetailInner({
return (
<XDSSection
maxWidth={960}
- padding={4}
+ padding={6}
variant="transparent"
- style={{marginInline: 'auto'}}>
+ xstyle={styles.section}>
<XDSVStack gap={4}>
<XDSVStack gap={2}>
<XDSText type="display-1">{comp.displayName}</XDSText>
diff --git a/apps/docsite/src/components/docs/BestPracticesBlock.tsx b/apps/docsite/src/components/docs/BestPracticesBlock.tsx
index b9142acea3..4f170d5161 100644
--- a/apps/docsite/src/components/docs/BestPracticesBlock.tsx
+++ b/apps/docsite/src/components/docs/BestPracticesBlock.tsx
@@ -3,6 +3,7 @@
'use client';
import {XDSBadge} from '@xds/core/Badge';
+import {XDSCard} from '@xds/core/Card';
import {XDSTable, pixel} from '@xds/core/Table';
interface BestPracticesItem {
@@ -17,24 +18,26 @@ export function BestPracticesBlock({items}: {items: BestPracticesItem[]}) {
})) as Record<string, unknown>[];
return (
- <XDSTable
- data={data}
- columns={[
- {
- key: 'guidance',
- header: 'Guidance',
- width: pixel(100),
- renderCell: (item: Record<string, unknown>) => (
- <XDSBadge
- label={item.guidance ? 'Do' : "Don't"}
- variant={item.guidance ? 'success' : 'error'}
- />
- ),
- },
- {key: 'description', header: 'Practices'},
- ]}
- density="spacious"
- dividers="rows"
- />
+ <XDSCard variant="default">
+ <XDSTable
+ data={data}
+ columns={[
+ {
+ key: 'guidance',
+ header: 'Guidance',
+ width: pixel(100),
+ renderCell: (item: Record<string, unknown>) => (
+ <XDSBadge
+ label={item.guidance ? 'Do' : "Don't"}
+ variant={item.guidance ? 'success' : 'error'}
+ />
+ ),
+ },
+ {key: 'description', header: 'Practices'},
+ ]}
+ density="spacious"
+ dividers="rows"
+ />
+ </XDSCard>
);
}
diff --git a/apps/docsite/src/components/docs/DocPageLayout.tsx b/apps/docsite/src/components/docs/DocPageLayout.tsx
index 22578de076..2f64aed060 100644
--- a/apps/docsite/src/components/docs/DocPageLayout.tsx
+++ b/apps/docsite/src/components/docs/DocPageLayout.tsx
@@ -8,9 +8,19 @@
*/
import type {ReactNode} from 'react';
-import {XDSText} from '@xds/core/Text';
+import * as stylex from '@stylexjs/stylex';
+import {XDSText, XDSHeading} from '@xds/core/Text';
import {XDSVStack} from '@xds/core/Layout';
import {XDSSection} from '@xds/core/Section';
+import {XDSDivider} from '@xds/core/Divider';
+import {spacingVars} from '@xds/core/theme/tokens.stylex';
+
+const styles = stylex.create({
+ section: {
+ marginInline: 'auto',
+ paddingBottom: `calc(${spacingVars['--spacing-12']} * 2)`,
+ },
+});
export function DocPageLayout({
title,
@@ -22,15 +32,18 @@ export function DocPageLayout({
children: ReactNode;
}) {
return (
- <XDSSection maxWidth={800} padding={6} style={{marginInline: 'auto'}}>
- <XDSVStack gap={8}>
- <XDSVStack gap={2}>
- <XDSText type="display-2">{title}</XDSText>
+ <XDSSection maxWidth={800} padding={6} xstyle={styles.section}>
+ <XDSVStack gap={10}>
+ <XDSVStack gap={4}>
+ <XDSHeading level={1} type="display-1">
+ {title}
+ </XDSHeading>
{description ? (
- <XDSText type="body" color="secondary">
+ <XDSText type="large" weight="normal" color="secondary">
{description}
</XDSText>
) : null}
+ <XDSDivider />
</XDSVStack>
{children}
</XDSVStack>
diff --git a/apps/docsite/src/components/docs/ListBlock.tsx b/apps/docsite/src/components/docs/ListBlock.tsx
index 9513941df6..558f114c8e 100644
--- a/apps/docsite/src/components/docs/ListBlock.tsx
+++ b/apps/docsite/src/components/docs/ListBlock.tsx
@@ -2,10 +2,10 @@
'use client';
-import {XDSVStack, XDSHStack} from '@xds/core/Layout';
-import {XDSText} from '@xds/core/Text';
import {XDSBadge} from '@xds/core/Badge';
import {XDSTable} from '@xds/core/Table';
+import {XDSList, XDSListItem} from '@xds/core/List';
+import {renderInlineCode} from './renderInlineCode';
export function ListBlock({
items,
@@ -39,7 +39,12 @@ export function ListBlock({
/>
),
},
- {key: 'text', header: 'Practice'},
+ {
+ key: 'text',
+ header: 'Practice',
+ renderCell: (item: Record<string, unknown>) =>
+ renderInlineCode(item.text as string),
+ },
]}
density="spacious"
dividers="rows"
@@ -47,23 +52,18 @@ export function ListBlock({
);
}
+ const xdsListStyle =
+ listStyle === 'ordered'
+ ? 'decimal'
+ : listStyle === 'unordered'
+ ? 'disc'
+ : 'none';
+
return (
- <XDSVStack gap={1}>
+ <XDSList density="compact" listStyle={xdsListStyle}>
{items.map((item, i) => (
- <XDSHStack key={i} gap={2} vAlign="center">
- {listStyle === 'ordered' && (
- <XDSText type="body" color="secondary">
- {i + 1}.
- </XDSText>
- )}
- {listStyle === 'unordered' && (
- <XDSText type="body" color="secondary">
- •
- </XDSText>
- )}
- <XDSText>{item}</XDSText>
- </XDSHStack>
+ <XDSListItem key={i} label={renderInlineCode(item)} />
))}
- </XDSVStack>
+ </XDSList>
);
}
diff --git a/apps/docsite/src/components/docs/PackageActions.tsx b/apps/docsite/src/components/docs/PackageActions.tsx
index 4f5adcf692..5b9018c826 100644
--- a/apps/docsite/src/components/docs/PackageActions.tsx
+++ b/apps/docsite/src/components/docs/PackageActions.tsx
@@ -43,39 +43,35 @@ export function PackageActions({
];
return (
- <XDSVStack gap={2}>
- {version && (
- <XDSText type="supporting" color="secondary">
- v{version}
- </XDSText>
+ <XDSHStack gap={2}>
+ <XDSPopover
+ width={360}
+ content={
+ <XDSVStack gap={3}>
+ {steps.map((step, i) => (
+ <XDSVStack key={i} gap={1}>
+ <XDSText type="body" weight="bold">
+ {i + 1}. {step.label}
+ </XDSText>
+ <XDSCard padding={0}>
+ <XDSCodeBlock
+ code={step.code}
+ language={step.language ?? 'bash'}
+ hasCopyButton
+ />
+ </XDSCard>
+ </XDSVStack>
+ ))}
+ </XDSVStack>
+ }>
+ <XDSButton
+ label={version ? `Install v${version}` : 'Install'}
+ variant="primary"
+ />
+ </XDSPopover>
+ {cta && (
+ <XDSButton label={cta.label} href={cta.href} variant="secondary" />
)}
- <XDSHStack gap={2}>
- <XDSPopover
- width={360}
- content={
- <XDSVStack gap={3}>
- {steps.map((step, i) => (
- <XDSVStack key={i} gap={1}>
- <XDSText type="body" weight="bold">
- {i + 1}. {step.label}
- </XDSText>
- <XDSCard padding={0}>
- <XDSCodeBlock
- code={step.code}
- language={step.language ?? 'bash'}
- hasCopyButton
- />
- </XDSCard>
- </XDSVStack>
- ))}
- </XDSVStack>
- }>
- <XDSButton label="Install" variant="primary" />
- </XDSPopover>
- {cta && (
- <XDSButton label={cta.label} href={cta.href} variant="secondary" />
- )}
- </XDSHStack>
- </XDSVStack>
+ </XDSHStack>
);
}
diff --git a/apps/docsite/src/components/docs/PackageStubPage.tsx b/apps/docsite/src/components/docs/PackageStubPage.tsx
index d27c62ae18..af40fc7986 100644
--- a/apps/docsite/src/components/docs/PackageStubPage.tsx
+++ b/apps/docsite/src/components/docs/PackageStubPage.tsx
@@ -5,6 +5,7 @@
import {XDSVStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
import {XDSMarkdown} from '@xds/core/Markdown';
+import {XDSDivider} from '@xds/core/Divider';
import {DocPageLayout} from './DocPageLayout';
import {PackageActions, type InstallStep} from './PackageActions';
@@ -57,13 +58,14 @@ export function PackageStubPage({
return (
<DocPageLayout title={name} description={description}>
- <XDSVStack gap={8}>
+ <XDSVStack gap={10}>
<PackageActions
packageName={name}
version={version}
installSteps={installSteps}
cta={cta}
/>
+ <XDSDivider />
{body ? (
<XDSMarkdown headingLevelStart={3} contentWidth={800}>
{body}
diff --git a/apps/docsite/src/components/docs/ProseBlock.tsx b/apps/docsite/src/components/docs/ProseBlock.tsx
index 74a12c3a66..9e26ec5a55 100644
--- a/apps/docsite/src/components/docs/ProseBlock.tsx
+++ b/apps/docsite/src/components/docs/ProseBlock.tsx
@@ -4,11 +4,12 @@
import * as stylex from '@stylexjs/stylex';
import {XDSText} from '@xds/core/Text';
+import {renderInlineCode} from './renderInlineCode';
const styles = stylex.create({
prose: {maxWidth: 800},
});
export function ProseBlock({text}: {text: string}) {
- return <XDSText xstyle={styles.prose}>{text}</XDSText>;
+ return <XDSText xstyle={styles.prose}>{renderInlineCode(text)}</XDSText>;
}
diff --git a/apps/docsite/src/components/docs/ReferenceDocView.tsx b/apps/docsite/src/components/docs/ReferenceDocView.tsx
index da4a002c01..a2c4f03c9e 100644
--- a/apps/docsite/src/components/docs/ReferenceDocView.tsx
+++ b/apps/docsite/src/components/docs/ReferenceDocView.tsx
@@ -2,9 +2,8 @@
'use client';
-import {XDSText} from '@xds/core/Text';
+import {XDSHeading} from '@xds/core/Text';
import {XDSVStack} from '@xds/core/Layout';
-import {XDSSection} from '@xds/core/Section';
import {ContentBlockRenderer} from './ContentBlockRenderer';
import {BestPracticesBlock} from './BestPracticesBlock';
import {DocPageLayout} from './DocPageLayout';
@@ -37,7 +36,9 @@ function BestPracticesSection({section}: {section: DocSection}) {
}
return (
<XDSVStack gap={4}>
- <XDSText type="display-3">{section.title}</XDSText>
+ <XDSHeading level={2} type="display-3">
+ {section.title}
+ </XDSHeading>
<BestPracticesBlock items={items} />
</XDSVStack>
);
@@ -59,20 +60,22 @@ export function ReferenceDocView({
{sections.map(section => {
const override = sectionOverrides?.[section.title];
return (
- <XDSSection key={section.title}>
+ <XDSVStack gap={4} key={section.title}>
{override ? (
override(section)
) : isBestPracticesSection(section) ? (
<BestPracticesSection section={section} />
) : (
- <XDSVStack gap={4}>
- <XDSText type="display-3">{section.title}</XDSText>
+ <>
+ <XDSHeading level={2} type="display-3">
+ {section.title}
+ </XDSHeading>
{section.content.map((block, i) => (
<ContentBlockRenderer key={i} block={block} />
))}
- </XDSVStack>
+ </>
)}
- </XDSSection>
+ </XDSVStack>
);
})}
</DocPageLayout>
diff --git a/apps/docsite/src/components/docs/TableBlock.tsx b/apps/docsite/src/components/docs/TableBlock.tsx
index 06be51326a..3adc5ef267 100644
--- a/apps/docsite/src/components/docs/TableBlock.tsx
+++ b/apps/docsite/src/components/docs/TableBlock.tsx
@@ -4,6 +4,8 @@
import {XDSText} from '@xds/core/Text';
import {XDSTable} from '@xds/core/Table';
+import {XDSCard} from '@xds/core/Card';
+import {renderInlineCode} from './renderInlineCode';
export function TableBlock({
headers,
@@ -24,17 +26,19 @@ export function TableBlock({
key: h,
header: h,
renderCell: (item: Record<string, unknown>) => (
- <XDSText>{item[h] as string}</XDSText>
+ <XDSText>{renderInlineCode(item[h] as string)}</XDSText>
),
}));
return (
- <XDSTable
- data={data}
- columns={columns}
- density="spacious"
- dividers="rows"
- hasHover
- />
+ <XDSCard>
+ <XDSTable
+ data={data}
+ columns={columns}
+ density="spacious"
+ dividers="rows"
+ hasHover
+ />
+ </XDSCard>
);
}
diff --git a/apps/docsite/src/components/docs/TokensDocView.tsx b/apps/docsite/src/components/docs/TokensDocView.tsx
index b2203ac873..12c21b8bbf 100644
--- a/apps/docsite/src/components/docs/TokensDocView.tsx
+++ b/apps/docsite/src/components/docs/TokensDocView.tsx
@@ -2,8 +2,9 @@
'use client';
+import {XDSCard} from '@xds/core/Card';
import {XDSVStack} from '@xds/core/Layout';
-import {XDSText} from '@xds/core/Text';
+import {XDSHeading} from '@xds/core/Text';
import {useXDSTheme} from '@xds/core/theme';
import {
ColorTokenTable,
@@ -89,11 +90,15 @@ function TokenSection({
const prose = section.content.filter(block => block.type !== 'table');
return (
<XDSVStack gap={4}>
- <XDSText type="display-3">{section.title}</XDSText>
+ <XDSHeading level={3} type="display-3">
+ {section.title}
+ </XDSHeading>
{prose.map((block, i) => (
<ContentBlockRenderer key={i} block={block} />
))}
- <Table theme={theme} />
+ <XDSCard>
+ <Table theme={theme} />
+ </XDSCard>
</XDSVStack>
);
}
diff --git a/apps/docsite/src/components/docs/renderInlineCode.tsx b/apps/docsite/src/components/docs/renderInlineCode.tsx
new file mode 100644
index 0000000000..d66d878b7d
--- /dev/null
+++ b/apps/docsite/src/components/docs/renderInlineCode.tsx
@@ -0,0 +1,26 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {Fragment} from 'react';
+import {XDSCode} from '@xds/core/CodeBlock';
+
+const INLINE_CODE = /`([^`]+)`/g;
+
+// Render backtick-delimited spans as inline code, leaving other text as-is.
+export function renderInlineCode(text: string) {
+ const nodes = [];
+ let lastIndex = 0;
+ let match;
+ while ((match = INLINE_CODE.exec(text)) !== null) {
+ if (match.index > lastIndex) {
+ nodes.push(text.slice(lastIndex, match.index));
+ }
+ nodes.push(<XDSCode key={match.index}>{match[1]}</XDSCode>);
+ lastIndex = match.index + match[0].length;
+ }
+ if (lastIndex < text.length) {
+ nodes.push(text.slice(lastIndex));
+ }
+ return nodes.map((node, i) => <Fragment key={i}>{node}</Fragment>);
+}