Skip to content

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

TypeScript

docs: rewrite CodeBlock & Code usage docs and consolidate blocks (#1565)

rubyycheungfa9fe3122ad0
diff --git a/packages/cli/templates/blocks/components/Code/CodeAcrossTextSizes.doc.mjs b/packages/cli/templates/blocks/components/Code/CodeAcrossTextSizes.doc.mjs
index 8c396e6516..de9933a8a8 100644
--- a/packages/cli/templates/blocks/components/Code/CodeAcrossTextSizes.doc.mjs
+++ b/packages/cli/templates/blocks/components/Code/CodeAcrossTextSizes.doc.mjs
@@ -1,10 +1,10 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'Code — Across Text Sizes',
+ name: 'Code — Text Sizes',
description:
- 'Inline code rendered inside heading, body, detail, and label text to show size adaptation.',
+ 'Inline code rendered inside heading, body, supporting, and label text. XDSCode automatically matches the font size of its parent text element.',
isReady: true,
- aspectRatio: 4 / 3,
+ aspectRatio: 16 / 9,
componentsUsed: ['Code', 'Text', 'Stack'],
};
diff --git a/packages/cli/templates/blocks/components/Code/CodeInlineInParagraph.doc.mjs b/packages/cli/templates/blocks/components/Code/CodeInlineInParagraph.doc.mjs
index cadbb7edf5..d3828d517d 100644
--- a/packages/cli/templates/blocks/components/Code/CodeInlineInParagraph.doc.mjs
+++ b/packages/cli/templates/blocks/components/Code/CodeInlineInParagraph.doc.mjs
@@ -1,10 +1,10 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'Code — Inline In Paragraph',
+ name: 'Code — Inline',
description:
- 'Inline code snippets mixed within a paragraph of body text.',
+ 'Inline code references mixed within a paragraph of body text. Use XDSCode to mark up function names, hooks, or API terms so they stand out from surrounding prose.',
isReady: true,
- aspectRatio: 4 / 3,
+ aspectRatio: 16 / 9,
componentsUsed: ['Code', 'Text'],
};
diff --git a/packages/cli/templates/blocks/components/Code/CodeInstructionalText.doc.mjs b/packages/cli/templates/blocks/components/Code/CodeInstructionalText.doc.mjs
deleted file mode 100644
index 65e46b0dd3..0000000000
--- a/packages/cli/templates/blocks/components/Code/CodeInstructionalText.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Code — Instructional Text',
- description:
- 'Step-by-step instructions with inline code for installation and usage.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Code', 'Text', 'Stack'],
-};
diff --git a/packages/cli/templates/blocks/components/Code/CodeInstructionalText.tsx b/packages/cli/templates/blocks/components/Code/CodeInstructionalText.tsx
deleted file mode 100644
index d635fa234c..0000000000
--- a/packages/cli/templates/blocks/components/Code/CodeInstructionalText.tsx
+++ /dev/null
@@ -1,21 +0,0 @@
-'use client';
-
-import {XDSCode} from '@xds/core/CodeBlock';
-import {XDSText} from '@xds/core/Text';
-import {XDSVStack} from '@xds/core/Stack';
-
-export default function CodeInstructionalText() {
- return (
- <XDSVStack gap={4}>
- <XDSText type="body">
- Install the package with <XDSCode>npm install @xds/core</XDSCode>, then
- import the component:
- </XDSText>
- <XDSText type="body">
- Add <XDSCode>{'<XDSButton label="Save">Save</XDSButton>'}</XDSCode> to
- your JSX. The <XDSCode>label</XDSCode> prop is required for
- accessibility.
- </XDSText>
- </XDSVStack>
- );
-}
diff --git a/packages/cli/templates/blocks/components/Code/CodeVariousContent.doc.mjs b/packages/cli/templates/blocks/components/Code/CodeVariousContent.doc.mjs
index 4316efe089..874200eee1 100644
--- a/packages/cli/templates/blocks/components/Code/CodeVariousContent.doc.mjs
+++ b/packages/cli/templates/blocks/components/Code/CodeVariousContent.doc.mjs
@@ -1,10 +1,10 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'Code — Various Content Types',
+ name: 'Code — Content Types',
description:
- 'Inline code used for variables, commands, CSS properties, file paths, and keyboard shortcuts.',
+ 'Inline code used for variables, terminal commands, CSS properties, file paths, and keyboard shortcuts. Shows how XDSCode adapts to different kinds of technical content.',
isReady: true,
- aspectRatio: 4 / 3,
+ aspectRatio: 16 / 9,
componentsUsed: ['Code', 'Text', 'Stack'],
};
diff --git a/packages/cli/templates/blocks/components/CodeBlock/CodeBlockBashCommand.doc.mjs b/packages/cli/templates/blocks/components/CodeBlock/CodeBlockBashCommand.doc.mjs
index 6ff34315dc..e7d529031d 100644
--- a/packages/cli/templates/blocks/components/CodeBlock/CodeBlockBashCommand.doc.mjs
+++ b/packages/cli/templates/blocks/components/CodeBlock/CodeBlockBashCommand.doc.mjs
@@ -1,10 +1,10 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'CodeBlock — Bash Command',
+ name: 'Code — Snippet',
description:
- 'Minimal single-line bash command with a copy button.',
+ 'Short terminal commands with a copy button and no line numbers. Use for install instructions or one-liner commands that readers will paste directly.',
isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['CodeBlock'],
+ aspectRatio: 16 / 9,
+ componentsUsed: ['CodeBlock', 'Stack'],
};
diff --git a/packages/cli/templates/blocks/components/CodeBlock/CodeBlockBashCommand.tsx b/packages/cli/templates/blocks/components/CodeBlock/CodeBlockBashCommand.tsx
index c4a57b8d15..285389d9b0 100644
--- a/packages/cli/templates/blocks/components/CodeBlock/CodeBlockBashCommand.tsx
+++ b/packages/cli/templates/blocks/components/CodeBlock/CodeBlockBashCommand.tsx
@@ -1,13 +1,21 @@
'use client';
import {XDSCodeBlock} from '@xds/core/CodeBlock';
+import {XDSVStack} from '@xds/core/Stack';
export default function CodeBlockBashCommand() {
return (
- <XDSCodeBlock
- code="npm install @xds/core"
- language="bash"
- hasCopyButton
- />
+ <XDSVStack gap={4}>
+ <XDSCodeBlock
+ code="npm install @xds/core @stylexjs/stylex"
+ language="bash"
+ hasCopyButton
+ />
+ <XDSCodeBlock
+ code={`curl -s https://api.example.com/status | jq '.services[] | select(.healthy == false)'`}
+ language="bash"
+ hasCopyButton
+ />
+ </XDSVStack>
);
}
diff --git a/packages/cli/templates/blocks/components/CodeBlock/CodeBlockHighlightedLines.doc.mjs b/packages/cli/templates/blocks/components/CodeBlock/CodeBlockHighlightedLines.doc.mjs
index 6d954c3f15..f9a0933d39 100644
--- a/packages/cli/templates/blocks/components/CodeBlock/CodeBlockHighlightedLines.doc.mjs
+++ b/packages/cli/templates/blocks/components/CodeBlock/CodeBlockHighlightedLines.doc.mjs
@@ -1,10 +1,10 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'CodeBlock — Highlighted Lines',
+ name: 'Code — Highlighted',
description:
- 'Code block with specific lines highlighted to draw attention to a function.',
+ 'TypeScript code with specific lines highlighted to draw attention to a key section. Use highlightLines to call out new or important code in tutorials and changelogs.',
isReady: true,
- aspectRatio: 4 / 3,
+ aspectRatio: 16 / 9,
componentsUsed: ['CodeBlock'],
};
diff --git a/packages/cli/templates/blocks/components/CodeBlock/CodeBlockJSONConfig.doc.mjs b/packages/cli/templates/blocks/components/CodeBlock/CodeBlockJSONConfig.doc.mjs
index d159d8ae80..8cad84c4fa 100644
--- a/packages/cli/templates/blocks/components/CodeBlock/CodeBlockJSONConfig.doc.mjs
+++ b/packages/cli/templates/blocks/components/CodeBlock/CodeBlockJSONConfig.doc.mjs
@@ -1,10 +1,10 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'CodeBlock — JSON Configuration',
+ name: 'Code — Config',
description:
- 'Code block displaying a JSON configuration file with line numbers.',
+ 'A JSON configuration file with a title bar and line numbers. The title prop adds a filename label in the header so readers know which file the code belongs to.',
isReady: true,
- aspectRatio: 4 / 3,
+ aspectRatio: 16 / 9,
componentsUsed: ['CodeBlock'],
};
diff --git a/packages/cli/templates/blocks/components/CodeBlock/CodeBlockPythonScript.doc.mjs b/packages/cli/templates/blocks/components/CodeBlock/CodeBlockPythonScript.doc.mjs
deleted file mode 100644
index d3111c6122..0000000000
--- a/packages/cli/templates/blocks/components/CodeBlock/CodeBlockPythonScript.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'CodeBlock — Python Script',
- description:
- 'Python code block with highlighted dataclass definition and line numbers.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['CodeBlock'],
-};
diff --git a/packages/cli/templates/blocks/components/CodeBlock/CodeBlockPythonScript.tsx b/packages/cli/templates/blocks/components/CodeBlock/CodeBlockPythonScript.tsx
deleted file mode 100644
index 12e9535e48..0000000000
--- a/packages/cli/templates/blocks/components/CodeBlock/CodeBlockPythonScript.tsx
+++ /dev/null
@@ -1,37 +0,0 @@
-'use client';
-
-import {XDSCodeBlock} from '@xds/core/CodeBlock';
-
-const code = `#!/usr/bin/env python3
-"""Data processing pipeline."""
-
-from dataclasses import dataclass
-from typing import List, Optional
-
-@dataclass
-class Config:
- input_path: str
- output_path: str
- batch_size: int = 100
-
-def process(config: Config) -> None:
- """Process data according to config."""
- print(f"Processing {config.input_path}")
- # TODO: implement pipeline
- pass
-
-if __name__ == "__main__":
- cfg = Config("input.csv", "output.csv")
- process(cfg)`;
-
-export default function CodeBlockPythonScript() {
- return (
- <XDSCodeBlock
- code={code}
- language="python"
- title="pipeline.py"
- hasLineNumbers
- highlightLines={[7, 8, 9, 10, 11]}
- />
- );
-}
diff --git a/packages/cli/templates/blocks/components/CodeBlock/CodeBlockScrollableBlock.doc.mjs b/packages/cli/templates/blocks/components/CodeBlock/CodeBlockScrollableBlock.doc.mjs
index ec4c670ef8..a90ab59b0d 100644
--- a/packages/cli/templates/blocks/components/CodeBlock/CodeBlockScrollableBlock.doc.mjs
+++ b/packages/cli/templates/blocks/components/CodeBlock/CodeBlockScrollableBlock.doc.mjs
@@ -1,10 +1,10 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'CodeBlock — Scrollable Block',
+ name: 'Code — Scrollable',
description:
- 'Code block with a max height constraint that enables vertical scrolling.',
+ 'A long code block with a max height that enables vertical scrolling. Use maxHeight to keep the block from dominating the page when displaying large files.',
isReady: true,
- aspectRatio: 4 / 3,
+ aspectRatio: 16 / 9,
componentsUsed: ['CodeBlock'],
};
diff --git a/packages/cli/templates/blocks/components/CodeBlock/CodeBlockScrollableBlock.tsx b/packages/cli/templates/blocks/components/CodeBlock/CodeBlockScrollableBlock.tsx
index d987788566..0818be020f 100644
--- a/packages/cli/templates/blocks/components/CodeBlock/CodeBlockScrollableBlock.tsx
+++ b/packages/cli/templates/blocks/components/CodeBlock/CodeBlockScrollableBlock.tsx
@@ -14,7 +14,7 @@ export default function CodeBlockScrollableBlock() {
language="typescript"
title="many-lines.ts"
hasLineNumbers
- maxHeight={200}
+ maxHeight="100%"
/>
);
}
diff --git a/packages/core/src/CodeBlock/XDSCodeBlock.doc.mjs b/packages/core/src/CodeBlock/XDSCodeBlock.doc.mjs
index 9b00f8516b..72ee320301 100644
--- a/packages/core/src/CodeBlock/XDSCodeBlock.doc.mjs
+++ b/packages/core/src/CodeBlock/XDSCodeBlock.doc.mjs
@@ -49,12 +49,20 @@ export const docs = {
],
},
usage: {
- description: 'CodeBlock displays syntax-highlighted code snippets with optional line numbers, copy button, and collapsible sections. Use XDSCodeBlock for fenced multi-line code and XDSCode for inline code within prose.',
+ description: 'CodeBlock renders syntax-highlighted code with line numbers, a copy button, and optional collapsible sections. Use XDSCodeBlock for multi-line snippets like source files, terminal commands, and configuration examples. Use XDSCode for inline references to function names, variables, or CLI flags within body text.',
bestPractices: [
- { guidance: true, description: 'Set the language prop to enable syntax highlighting — use "plaintext" when the language is unknown or not supported.' },
- { guidance: true, description: 'Use XDSCode for short inline code references within body text, and XDSCodeBlock for standalone multi-line snippets.' },
- { guidance: false, description: 'Enable line numbers for short snippets where they add visual noise without aiding comprehension.' },
- { guidance: false, description: 'Wrap code blocks in a scrollable container when isWrapped or maxHeight already handles overflow.' },
+ {guidance: true, description: 'Set the language prop to match the code content so syntax highlighting is accurate. Use "plaintext" when the language is unknown.'},
+ {guidance: true, description: 'Add a title when the code represents a file — it gives readers context and appears in the header bar alongside the copy button.'},
+ {guidance: true, description: 'Use XDSCode for short inline references like function names or CLI flags, and XDSCodeBlock for standalone multi-line snippets.'},
+ {guidance: false, description: 'Enable line numbers on short snippets (under 5 lines) where they add clutter without helping navigation.'},
+ {guidance: false, description: 'Nest a code block inside a scrollable container — use the maxHeight prop instead, which handles overflow natively.'},
+ ],
+ anatomy: [
+ {name: 'Header Bar', required: false, description: 'Shows the title, language label, and copy button. Appears when any of these props are set.'},
+ {name: 'Line Numbers', required: false, description: 'Numbered gutter along the left edge. Enable with hasLineNumbers.'},
+ {name: 'Code Body', required: true, description: 'The syntax-highlighted code content.'},
+ {name: 'Highlighted Lines', required: false, description: 'Background accent on specific lines to draw attention.'},
+ {name: 'Copy Button', required: false, description: 'Copies the code string to the clipboard. Shown by default.'},
],
},
};
@@ -113,12 +121,13 @@ export const docsZh = {
export const docsDense = {
description: 'syntax-highlighted code block via CSS Custom Highlight API (0-DOM overhead); span-based fallback; XDSCode for inline code in prose',
usage: {
- description: 'CodeBlock displays syntax-highlighted code snippets with optional line numbers, copy button, and collapsible sections. Use XDSCodeBlock for fenced multi-line code and XDSCode for inline code within prose.',
+ description: 'CodeBlock renders syntax-highlighted code with line numbers, a copy button, and optional collapsible sections. Use XDSCodeBlock for multi-line snippets like source files, terminal commands, and configuration examples. Use XDSCode for inline references to function names, variables, or CLI flags within body text.',
bestPractices: [
- { guidance: true, description: 'Set the language prop to enable syntax highlighting — use "plaintext" when the language is unknown or not supported.' },
- { guidance: true, description: 'Use XDSCode for short inline code references within body text, and XDSCodeBlock for standalone multi-line snippets.' },
- { guidance: false, description: 'Enable line numbers for short snippets where they add visual noise without aiding comprehension.' },
- { guidance: false, description: 'Wrap code blocks in a scrollable container when isWrapped or maxHeight already handles overflow.' },
+ {guidance: true, description: 'Set the language prop to match the code content so syntax highlighting is accurate. Use "plaintext" when the language is unknown.'},
+ {guidance: true, description: 'Add a title when the code represents a file — it gives readers context and appears in the header bar alongside the copy button.'},
+ {guidance: true, description: 'Use XDSCode for short inline references like function names or CLI flags, and XDSCodeBlock for standalone multi-line snippets.'},
+ {guidance: false, description: 'Enable line numbers on short snippets (under 5 lines) where they add clutter without helping navigation.'},
+ {guidance: false, description: 'Nest a code block inside a scrollable container — use the maxHeight prop instead, which handles overflow natively.'},
],
},
components: [