Skip to content

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

TypeScript

feat(docsite): guide + foundation doc pages with block renderers (#1956)

Cindy Zhang11619155c1f7
diff --git a/apps/docsite/scripts/generate-data.mjs b/apps/docsite/scripts/generate-data.mjs
index 77f048d71b..fcf00bc61a 100644
--- a/apps/docsite/scripts/generate-data.mjs
+++ b/apps/docsite/scripts/generate-data.mjs
@@ -458,23 +458,46 @@ async function generateDocsRegistry() {
let title = '';
let description = '';
let category = '';
+ let sections = [];
try {
const mod = await import(`file://${docPath}`);
title = mod.docs?.title || '';
description = mod.docs?.description || '';
category = mod.docs?.category || '';
+ sections = mod.docs?.sections || [];
} catch {
const meta = readDocMeta(docPath);
description = meta.description;
}
- docTopics.push({topic, title: title || topic, description, category: category || null});
+ docTopics.push({topic, title: title || topic, description, category: category || null, sections});
}
docTopics.sort((a, b) => a.topic.localeCompare(b.topic));
const content = `// Auto-generated by scripts/generate-data.mjs — do not edit
+export interface ContentBlock {
+ type: string;
+ text?: string;
+ code?: string;
+ lang?: string;
+ label?: string;
+ headers?: string[];
+ rows?: string[][];
+ items?: string[];
+ style?: string;
+ topic?: string;
+ section?: string;
+}
+
+export interface DocSection {
+ title: string;
+ content: ContentBlock[];
+ previewType?: string;
+ category?: string;
+}
+
export interface DocTopic {
/** URL-friendly slug derived from filename (e.g. 'getting-started') */
topic: string;
@@ -484,6 +507,8 @@ export interface DocTopic {
description: string;
/** Navigation category: 'guide' | 'foundations' | null */
category: string | null;
+ /** Full doc sections with content blocks */
+ sections: DocSection[];
}
export const docTopics: DocTopic[] = ${JSON.stringify(docTopics, null, 2)};
diff --git a/apps/docsite/src/app/docs/[topic]/page.tsx b/apps/docsite/src/app/docs/[topic]/page.tsx
index c16704cfd2..0f32fe432c 100644
--- a/apps/docsite/src/app/docs/[topic]/page.tsx
+++ b/apps/docsite/src/app/docs/[topic]/page.tsx
@@ -1,15 +1,13 @@
/**
* Page type: long-form-doc
- * Renders documentation topics from CLI docs/*.doc.mjs.
- * Used for: getting-started, typography, color, spacing, shape, icons,
- * elevation, motion, principles, styling, tokens, theme.
+ * Renders guide and foundation docs from the pipeline.
+ * Content blocks (prose, code, table, list) rendered via ContentBlockRenderer.
*/
import {notFound} from 'next/navigation';
-import {XDSHeading, XDSText} from '@xds/core/Text';
-import {XDSVStack} from '@xds/core/Layout';
import {XDSSection} from '@xds/core/Section';
import {docTopics} from '../../../generated/docsRegistry';
+import {ReferenceDocView} from '../../../components/docs/ReferenceDocView';
export function generateStaticParams() {
return docTopics.map(d => ({topic: d.topic}));
@@ -25,14 +23,12 @@ export default async function DocPage({
if (!topic) notFound();
return (
- <XDSSection maxWidth="md" padding={6}>
- <XDSVStack gap={4}>
- <XDSHeading level={1}>{topic.title}</XDSHeading>
- <XDSText type="body" color="secondary">
- {topic.description}
- </XDSText>
- {/* TODO: render full doc sections from pipeline */}
- </XDSVStack>
+ <XDSSection maxWidth="lg" padding={6}>
+ <ReferenceDocView
+ title={topic.title}
+ description={topic.description}
+ sections={topic.sections}
+ />
</XDSSection>
);
}
diff --git a/apps/docsite/src/components/docs/BestPracticesBlock.tsx b/apps/docsite/src/components/docs/BestPracticesBlock.tsx
new file mode 100644
index 0000000000..8c5a2be283
--- /dev/null
+++ b/apps/docsite/src/components/docs/BestPracticesBlock.tsx
@@ -0,0 +1,38 @@
+'use client';
+
+import {XDSBadge} from '@xds/core/Badge';
+import {XDSTable, pixel} from '@xds/core/Table';
+
+interface BestPracticesItem {
+ guidance: boolean;
+ description: string;
+}
+
+export function BestPracticesBlock({items}: {items: BestPracticesItem[]}) {
+ const data = items.map(item => ({
+ guidance: item.guidance as unknown,
+ description: item.description as unknown,
+ })) 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"
+ />
+ );
+}
diff --git a/apps/docsite/src/components/docs/CodeBlock.tsx b/apps/docsite/src/components/docs/CodeBlock.tsx
new file mode 100644
index 0000000000..3096963f87
--- /dev/null
+++ b/apps/docsite/src/components/docs/CodeBlock.tsx
@@ -0,0 +1,44 @@
+'use client';
+
+import * as stylex from '@stylexjs/stylex';
+import {XDSVStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+import {XDSCodeBlock} from '@xds/core/CodeBlock';
+import {XDSCard} from '@xds/core/Card';
+
+const styles = stylex.create({
+ root: {width: '100%'},
+});
+
+export function CodeBlockRenderer({
+ lang,
+ code,
+ label,
+}: {
+ lang: string;
+ code: string;
+ label?: string;
+}) {
+ return (
+ <XDSVStack gap={1}>
+ {label && (
+ <XDSText type="supporting" color="secondary">
+ {label}
+ </XDSText>
+ )}
+ <XDSCard variant="muted" xstyle={styles.root}>
+ <XDSCodeBlock
+ code={code}
+ language={lang}
+ hasCopyButton
+ style={
+ {
+ '--color-syntax-background': 'transparent',
+ width: '100%',
+ } as React.CSSProperties
+ }
+ />
+ </XDSCard>
+ </XDSVStack>
+ );
+}
diff --git a/apps/docsite/src/components/docs/ContentBlockRenderer.tsx b/apps/docsite/src/components/docs/ContentBlockRenderer.tsx
new file mode 100644
index 0000000000..a3f5dad6a5
--- /dev/null
+++ b/apps/docsite/src/components/docs/ContentBlockRenderer.tsx
@@ -0,0 +1,30 @@
+'use client';
+
+import {ProseBlock} from './ProseBlock';
+import {CodeBlockRenderer} from './CodeBlock';
+import {TableBlock} from './TableBlock';
+import {ListBlock} from './ListBlock';
+import type {ContentBlock} from '../../generated/docsRegistry';
+
+export function ContentBlockRenderer({block}: {block: ContentBlock}) {
+ switch (block.type) {
+ case 'prose':
+ return <ProseBlock text={block.text ?? ''} />;
+ case 'code':
+ return (
+ <CodeBlockRenderer
+ lang={block.lang ?? 'text'}
+ code={block.code ?? ''}
+ label={block.label}
+ />
+ );
+ case 'table':
+ return (
+ <TableBlock headers={block.headers ?? []} rows={block.rows ?? []} />
+ );
+ case 'list':
+ return <ListBlock items={block.items ?? []} listStyle={block.style} />;
+ default:
+ return null;
+ }
+}
diff --git a/apps/docsite/src/components/docs/ListBlock.tsx b/apps/docsite/src/components/docs/ListBlock.tsx
new file mode 100644
index 0000000000..bf76c277ec
--- /dev/null
+++ b/apps/docsite/src/components/docs/ListBlock.tsx
@@ -0,0 +1,67 @@
+'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';
+
+export function ListBlock({
+ items,
+ listStyle,
+}: {
+ items: string[];
+ listStyle?: string;
+}) {
+ if (listStyle === 'do-dont-merged') {
+ const data = items.map((item, i) => {
+ const isDo = item.startsWith('do:');
+ return {
+ _idx: i,
+ guidance: isDo ? 'Do' : "Don't",
+ isDo,
+ text: item.replace(/^(do|dont):/, ''),
+ };
+ });
+
+ return (
+ <XDSTable
+ data={data as Record<string, unknown>[]}
+ columns={[
+ {
+ key: 'guidance',
+ header: 'Guidance',
+ renderCell: (item: Record<string, unknown>) => (
+ <XDSBadge
+ label={item.guidance as string}
+ variant={(item.isDo as boolean) ? 'success' : 'error'}
+ />
+ ),
+ },
+ {key: 'text', header: 'Practice'},
+ ]}
+ density="spacious"
+ dividers="rows"
+ />
+ );
+ }
+
+ return (
+ <XDSVStack gap={1}>
+ {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>
+ ))}
+ </XDSVStack>
+ );
+}
diff --git a/apps/docsite/src/components/docs/ProseBlock.tsx b/apps/docsite/src/components/docs/ProseBlock.tsx
new file mode 100644
index 0000000000..39aee4dba7
--- /dev/null
+++ b/apps/docsite/src/components/docs/ProseBlock.tsx
@@ -0,0 +1,12 @@
+'use client';
+
+import * as stylex from '@stylexjs/stylex';
+import {XDSText} from '@xds/core/Text';
+
+const styles = stylex.create({
+ prose: {maxWidth: 800},
+});
+
+export function ProseBlock({text}: {text: string}) {
+ return <XDSText xstyle={styles.prose}>{text}</XDSText>;
+}
diff --git a/apps/docsite/src/components/docs/ReferenceDocView.tsx b/apps/docsite/src/components/docs/ReferenceDocView.tsx
new file mode 100644
index 0000000000..d227318d7e
--- /dev/null
+++ b/apps/docsite/src/components/docs/ReferenceDocView.tsx
@@ -0,0 +1,89 @@
+'use client';
+
+import * as stylex from '@stylexjs/stylex';
+import {XDSText} 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 type {DocSection} from '../../generated/docsRegistry';
+import type {ReactNode} from 'react';
+
+const styles = stylex.create({
+ container: {maxWidth: 1200, marginInline: 'auto'},
+ prose: {maxWidth: 800},
+});
+
+export type SectionOverrides = Record<
+ string,
+ (section: DocSection) => ReactNode
+>;
+
+function isBestPracticesSection(section: DocSection): boolean {
+ return section.content.every(
+ b => b.type === 'list' && (b.style === 'do' || b.style === 'dont'),
+ );
+}
+
+function BestPracticesSection({section}: {section: DocSection}) {
+ const items: {guidance: boolean; description: string}[] = [];
+ for (const block of section.content) {
+ if (
+ block.type === 'list' &&
+ (block.style === 'do' || block.style === 'dont')
+ ) {
+ const isDo = block.style === 'do';
+ for (const item of block.items ?? []) {
+ items.push({guidance: isDo, description: item});
+ }
+ }
+ }
+ return (
+ <XDSVStack gap={4}>
+ <XDSText type="display-3">{section.title}</XDSText>
+ <BestPracticesBlock items={items} />
+ </XDSVStack>
+ );
+}
+
+export function ReferenceDocView({
+ title,
+ description,
+ sections,
+ sectionOverrides,
+}: {
+ title: string;
+ description: string;
+ sections: DocSection[];
+ sectionOverrides?: SectionOverrides;
+}) {
+ return (
+ <XDSVStack gap={8} xstyle={styles.container}>
+ <XDSVStack gap={2}>
+ <XDSText type="display-2">{title}</XDSText>
+ <XDSText type="body" color="secondary" xstyle={styles.prose}>
+ {description}
+ </XDSText>
+ </XDSVStack>
+ {sections.map(section => {
+ const override = sectionOverrides?.[section.title];
+ return (
+ <XDSSection key={section.title}>
+ {override ? (
+ override(section)
+ ) : isBestPracticesSection(section) ? (
+ <BestPracticesSection section={section} />
+ ) : (
+ <XDSVStack gap={4}>
+ <XDSText type="display-3">{section.title}</XDSText>
+ {section.content.map((block, i) => (
+ <ContentBlockRenderer key={i} block={block} />
+ ))}
+ </XDSVStack>
+ )}
+ </XDSSection>
+ );
+ })}
+ </XDSVStack>
+ );
+}
diff --git a/apps/docsite/src/components/docs/TableBlock.tsx b/apps/docsite/src/components/docs/TableBlock.tsx
new file mode 100644
index 0000000000..cd30efdf6a
--- /dev/null
+++ b/apps/docsite/src/components/docs/TableBlock.tsx
@@ -0,0 +1,38 @@
+'use client';
+
+import {XDSText} from '@xds/core/Text';
+import {XDSTable} from '@xds/core/Table';
+
+export function TableBlock({
+ headers,
+ rows,
+}: {
+ headers: string[];
+ rows: string[][];
+}) {
+ const data = rows.map((row, i) => {
+ const obj: Record<string, unknown> = {_idx: i};
+ headers.forEach((h, j) => {
+ obj[h] = row[j] ?? '';
+ });
+ return obj;
+ });
+
+ const columns = headers.map(h => ({
+ key: h,
+ header: h,
+ renderCell: (item: Record<string, unknown>) => (
+ <XDSText>{item[h] as string}</XDSText>
+ ),
+ }));
+
+ return (
+ <XDSTable
+ data={data}
+ columns={columns}
+ density="spacious"
+ dividers="rows"
+ hasHover
+ />
+ );
+}