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.mjsindex 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.mjsindex 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.mjsdeleted file mode 100644index 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.tsxdeleted file mode 100644index 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.mjsindex 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.mjsindex 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.tsxindex 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.mjsindex 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.mjsindex 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.mjsdeleted file mode 100644index 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.tsxdeleted file mode 100644index 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.mjsindex 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.tsxindex 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.mjsindex 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: [