Skip to content

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

TypeScript

Improve MetadataList docs page and block examples (#1660)

Ted McDonald1dc31ce0983f
diff --git a/packages/cli/templates/blocks/components/MetadataList/MetadataListBasicMetadata.doc.mjs b/packages/cli/templates/blocks/components/MetadataList/MetadataListBasicMetadata.doc.mjs
index 8a7aaa2713..79cdb42e3b 100644
--- a/packages/cli/templates/blocks/components/MetadataList/MetadataListBasicMetadata.doc.mjs
+++ b/packages/cli/templates/blocks/components/MetadataList/MetadataListBasicMetadata.doc.mjs
@@ -2,7 +2,7 @@
export const doc = {
type: 'block',
name: 'MetadataList — Basic',
- description: 'Simple single-column key-value metadata list.',
+ description: 'Single-column key-value metadata list.',
isReady: true,
aspectRatio: 4 / 3,
componentsUsed: ['MetadataList'],
diff --git a/packages/cli/templates/blocks/components/MetadataList/MetadataListCollapsibleMetadata.doc.mjs b/packages/cli/templates/blocks/components/MetadataList/MetadataListCollapsibleMetadata.doc.mjs
index 75692268a2..b124c02f8d 100644
--- a/packages/cli/templates/blocks/components/MetadataList/MetadataListCollapsibleMetadata.doc.mjs
+++ b/packages/cli/templates/blocks/components/MetadataList/MetadataListCollapsibleMetadata.doc.mjs
@@ -3,7 +3,7 @@ export const doc = {
type: 'block',
name: 'MetadataList — Collapsible',
description:
- 'Metadata list that truncates after a set number of items with a show-more toggle.',
+ 'Metadata list with a show-more toggle after a set number of items.',
isReady: true,
aspectRatio: 4 / 3,
componentsUsed: ['MetadataList'],
diff --git a/packages/cli/templates/blocks/components/MetadataList/MetadataListHorizontalMetadata.doc.mjs b/packages/cli/templates/blocks/components/MetadataList/MetadataListHorizontalMetadata.doc.mjs
index 65cafd8b6f..4ec08817b6 100644
--- a/packages/cli/templates/blocks/components/MetadataList/MetadataListHorizontalMetadata.doc.mjs
+++ b/packages/cli/templates/blocks/components/MetadataList/MetadataListHorizontalMetadata.doc.mjs
@@ -3,7 +3,7 @@ export const doc = {
type: 'block',
name: 'MetadataList — Horizontal',
description:
- 'Horizontally-oriented metadata items for compact inline display.',
+ 'Horizontal metadata items for compact inline display.',
isReady: true,
aspectRatio: 4 / 3,
componentsUsed: ['MetadataList'],
diff --git a/packages/cli/templates/blocks/components/MetadataList/MetadataListMultiColumnMetadata.doc.mjs b/packages/cli/templates/blocks/components/MetadataList/MetadataListMultiColumnMetadata.doc.mjs
index a1042134b5..ed19a85b86 100644
--- a/packages/cli/templates/blocks/components/MetadataList/MetadataListMultiColumnMetadata.doc.mjs
+++ b/packages/cli/templates/blocks/components/MetadataList/MetadataListMultiColumnMetadata.doc.mjs
@@ -3,8 +3,8 @@ export const doc = {
type: 'block',
name: 'MetadataList — Multi-Column',
description:
- 'Multi-column metadata grid with token tags for dense information display.',
+ 'Multi-column metadata grid with token tags.',
isReady: true,
aspectRatio: 4 / 3,
- componentsUsed: ['MetadataList', 'Token'],
+ componentsUsed: ['MetadataList', 'Token', 'HStack'],
};
diff --git a/packages/cli/templates/blocks/components/MetadataList/MetadataListMultiColumnMetadata.tsx b/packages/cli/templates/blocks/components/MetadataList/MetadataListMultiColumnMetadata.tsx
index 707b7b1f27..31aa88ff31 100644
--- a/packages/cli/templates/blocks/components/MetadataList/MetadataListMultiColumnMetadata.tsx
+++ b/packages/cli/templates/blocks/components/MetadataList/MetadataListMultiColumnMetadata.tsx
@@ -2,6 +2,7 @@
import {XDSMetadataList, XDSMetadataListItem} from '@xds/core/MetadataList';
import {XDSToken} from '@xds/core/Token';
+import {XDSHStack} from '@xds/core/Layout';
export default function MetadataListMultiColumnMetadata() {
return (
@@ -11,10 +12,10 @@ export default function MetadataListMultiColumnMetadata() {
<XDSMetadataListItem label="Owner">Joey</XDSMetadataListItem>
<XDSMetadataListItem label="Created">Jan 15, 2026</XDSMetadataListItem>
<XDSMetadataListItem label="Tags">
- <span style={{display: 'flex', gap: 4}}>
+ <XDSHStack gap={1}>
<XDSToken label="component" />
<XDSToken label="xds" />
- </span>
+ </XDSHStack>
</XDSMetadataListItem>
<XDSMetadataListItem label="Priority">Tier 1</XDSMetadataListItem>
</XDSMetadataList>
diff --git a/packages/core/src/MetadataList/MetadataList.doc.mjs b/packages/core/src/MetadataList/MetadataList.doc.mjs
index 4e732619f2..3a62e0d17b 100644
--- a/packages/core/src/MetadataList/MetadataList.doc.mjs
+++ b/packages/core/src/MetadataList/MetadataList.doc.mjs
@@ -89,12 +89,12 @@ export const docs = {
],
usage: {
description:
- 'MetadataList displays key-value pairs of metadata using semantic definition list markup. Use it in detail panels, summary sections, or anywhere an object\'s attributes need a structured overview.',
+ 'MetadataList displays key-value pairs for object attributes like quality, condition, and status, in a structured layout. Use it for detail panels, settings summaries, and record information.',
bestPractices: [
- { guidance: true, description: 'Choose label position based on content length — use \'start\' for short values and \'top\' for long or complex values.' },
- { guidance: true, description: 'Use maxNumOfItems to collapse long lists and keep the page scannable.' },
- { guidance: false, description: 'Use MetadataList for tabular data with multiple columns of values — use a table component instead.' },
- { guidance: false, description: 'Mix unrelated metadata items within the same list — group related attributes together.' },
+ { guidance: true, description: 'Choose label position based on content — "start" for short values, "top" for long or complex values.' },
+ { guidance: true, description: 'Collapse long lists with `maxNumOfItems` to keep the page scannable.' },
+ { guidance: false, description: 'Use for extensive form input — use a form layout instead.' },
+ { guidance: false, description: "Use for data that doesn't have a clear key-value structure." },
],
anatomy: [
{name: 'Title', required: false, description: 'Optional title for the metadata list.'},
@@ -133,12 +133,12 @@ export const docsZh = {
],
usage: {
description:
- 'MetadataList displays key-value pairs of metadata using semantic definition list markup. Use it in detail panels, summary sections, or anywhere an object\'s attributes need a structured overview.',
+ 'MetadataList displays key-value pairs for object attributes like quality, condition, and status, in a structured layout. Use it for detail panels, settings summaries, and record information.',
bestPractices: [
- { guidance: true, description: 'Choose label position based on content length — use \'start\' for short values and \'top\' for long or complex values.' },
- { guidance: true, description: 'Use maxNumOfItems to collapse long lists and keep the page scannable.' },
- { guidance: false, description: 'Use MetadataList for tabular data with multiple columns of values — use a table component instead.' },
- { guidance: false, description: 'Mix unrelated metadata items within the same list — group related attributes together.' },
+ { guidance: true, description: 'Choose label position based on content — "start" for short values, "top" for long or complex values.' },
+ { guidance: true, description: 'Collapse long lists with `maxNumOfItems` to keep the page scannable.' },
+ { guidance: false, description: 'Use for extensive form input — use a form layout instead.' },
+ { guidance: false, description: "Use for data that doesn't have a clear key-value structure." },
],
anatomy: [
{name: 'Title', required: false, description: 'Optional title for the metadata list.'},
@@ -154,12 +154,12 @@ export const docsDense = {
description: 'label/value metadata display; column layout, collapse, orientation variants',
usage: {
description:
- 'MetadataList displays key-value pairs of metadata using semantic definition list markup. Use it in detail panels, summary sections, or anywhere an object\'s attributes need a structured overview.',
+ 'MetadataList displays key-value pairs for object attributes like quality, condition, and status, in a structured layout. Use it for detail panels, settings summaries, and record information.',
bestPractices: [
- { guidance: true, description: 'Choose label position based on content length — use \'start\' for short values and \'top\' for long or complex values.' },
- { guidance: true, description: 'Use maxNumOfItems to collapse long lists and keep the page scannable.' },
- { guidance: false, description: 'Use MetadataList for tabular data with multiple columns of values — use a table component instead.' },
- { guidance: false, description: 'Mix unrelated metadata items within the same list — group related attributes together.' },
+ { guidance: true, description: 'Choose label position based on content — "start" for short values, "top" for long or complex values.' },
+ { guidance: true, description: 'Collapse long lists with `maxNumOfItems` to keep the page scannable.' },
+ { guidance: false, description: 'Use for extensive form input — use a form layout instead.' },
+ { guidance: false, description: "Use for data that doesn't have a clear key-value structure." },
],
anatomy: [
{name: 'Title', required: false, description: 'Optional title for the metadata list.'},