Skip to content

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

TypeScript

docs: say what four block templates are for (#7963)

Joeyb33622e504c6
diff --git a/.changeset/block-descriptions-what-its-for.md b/.changeset/block-descriptions-what-its-for.md
new file mode 100644
index 0000000000..089822878f
--- /dev/null
+++ b/.changeset/block-descriptions-what-its-for.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[docs] Four block templates (`MetadataListItemBasic`, `SegmentedControlItemBasic`, `VisuallyHiddenSupplementaryContext`, `ItemWithMetadata`) now describe what each one shows and when to use it, written from what the block renders.
+
+@josephfarina
diff --git a/packages/cli/assets/templates/blocks/components/Item/ItemWithMetadata.doc.mjs b/packages/cli/assets/templates/blocks/components/Item/ItemWithMetadata.doc.mjs
index 5bb52a3c83..59336619c7 100644
--- a/packages/cli/assets/templates/blocks/components/Item/ItemWithMetadata.doc.mjs
+++ b/packages/cli/assets/templates/blocks/components/Item/ItemWithMetadata.doc.mjs
@@ -7,7 +7,7 @@ export const doc = {
name: 'Item — Metadata',
displayName: 'Item — Metadata',
description:
- 'Items with end-aligned metadata and badges. Use the endContent slot for counts, status, timestamps, and other secondary row information.',
+ 'Status rows with an icon, a title, a short description, and end-aligned metadata such as a timestamp or a status badge, here build, memory, and sync events. Use the endContent slot for counts, status, timestamps, and other secondary row information.',
isReady: true,
aspectRatio: 16 / 9,
componentsUsed: ['Item', 'Badge', 'Icon', 'Text', 'Layout'],
diff --git a/packages/cli/assets/templates/blocks/components/MetadataListItem/MetadataListItemBasic.doc.mjs b/packages/cli/assets/templates/blocks/components/MetadataListItem/MetadataListItemBasic.doc.mjs
index 9a4da295be..529f88baea 100644
--- a/packages/cli/assets/templates/blocks/components/MetadataListItem/MetadataListItemBasic.doc.mjs
+++ b/packages/cli/assets/templates/blocks/components/MetadataListItem/MetadataListItemBasic.doc.mjs
@@ -7,7 +7,7 @@ export const doc = {
name: 'MetadataListItem — Basic',
displayName: 'MetadataListItem — Basic',
description:
- 'Labeled key-value rows inside a MetadataList. Values accept any content, from plain text to components like Badge.',
+ 'A titled section of label and value rows for one record, here a deployment\'s environment, health status badge, version, and last deploy date. Values take plain text or a component such as a Badge.',
isReady: true,
aspectRatio: 16 / 9,
componentsUsed: ['MetadataList', 'MetadataListItem', 'Badge'],
diff --git a/packages/cli/assets/templates/blocks/components/SegmentedControlItem/SegmentedControlItemBasic.doc.mjs b/packages/cli/assets/templates/blocks/components/SegmentedControlItem/SegmentedControlItemBasic.doc.mjs
index 53d443ae91..484debe88a 100644
--- a/packages/cli/assets/templates/blocks/components/SegmentedControlItem/SegmentedControlItemBasic.doc.mjs
+++ b/packages/cli/assets/templates/blocks/components/SegmentedControlItem/SegmentedControlItemBasic.doc.mjs
@@ -7,7 +7,7 @@ export const doc = {
name: 'SegmentedControlItem — Basic',
displayName: 'SegmentedControlItem — Basic',
description:
- 'Label-only options inside a SegmentedControl. Each item declares a value; the parent control holds the selected value and change handler.',
+ 'A row of label-only options that switches between a few views, here Board, List, and Timeline. Each item declares a value; the parent control holds the selected value and change handler.',
isReady: true,
aspectRatio: 16 / 9,
componentsUsed: ['SegmentedControl', 'SegmentedControlItem'],
diff --git a/packages/cli/assets/templates/blocks/components/VisuallyHidden/VisuallyHiddenSupplementaryContext.doc.mjs b/packages/cli/assets/templates/blocks/components/VisuallyHidden/VisuallyHiddenSupplementaryContext.doc.mjs
index 966fb7f4db..d4e7b89fe3 100644
--- a/packages/cli/assets/templates/blocks/components/VisuallyHidden/VisuallyHiddenSupplementaryContext.doc.mjs
+++ b/packages/cli/assets/templates/blocks/components/VisuallyHidden/VisuallyHiddenSupplementaryContext.doc.mjs
@@ -7,7 +7,7 @@ export const doc = {
name: 'VisuallyHidden — Supplementary Context',
displayName: 'VisuallyHidden — Supplementary Context',
description:
- 'Add screen-reader-only context to terse visual data, like spelling out what a trend arrow means.',
+ 'Stat cards whose trend arrows get screen-reader-only text, so a change like +12% is read as an increase from last month. Use to make terse visual data accessible.',
isReady: true,
aspectRatio: 4 / 3,
componentsUsed: [