diff --git a/packages-proprietary/tokens/src/components/ams/table.tokens.json b/packages-proprietary/tokens/src/components/ams/table.tokens.json
index f3cbbdc6aff..f2282048cb8 100644
--- a/packages-proprietary/tokens/src/components/ams/table.tokens.json
+++ b/packages-proprietary/tokens/src/components/ams/table.tokens.json
@@ -35,8 +35,13 @@
"caption": {
"font-weight": {
"$value": "{ams.typography.body-text.bold.font-weight}",
+ "$type": "fontWeight"
+ },
+ "margin-block-end": {
+ "$value": "{ams.space.s}",
+ "$type": "dimension",
"$extensions": {
- "nl.amsterdam.type": "fontWeight"
+ "nl.amsterdam.subtype": "space"
}
}
},
diff --git a/packages/css/src/components/table/README.md b/packages/css/src/components/table/README.md
index 953d22cb8d3..42928d7d33b 100644
--- a/packages/css/src/components/table/README.md
+++ b/packages/css/src/components/table/README.md
@@ -6,6 +6,6 @@ Structures data in rows and columns to help users work with large amounts of inf
## Guidelines
-- Add a caption to help users find, navigate and understand the table.
-- Include a [Heading](https://designsystem.amsterdam/?path=/docs/components-text-heading--docs) in the Table Caption,
- unless the table is in a [Figure](https://designsystem.amsterdam/?path=/docs/components-media-figure--docs) which has a Figure Caption.
+- Add a caption so users can find and understand the table without reading its data.
+- Use a [Heading](https://designsystem.amsterdam/?path=/docs/components-text-heading--docs) in the caption, at the level that fits the document outline.
+ It becomes the table’s accessible name, announced by screen readers on every encounter.
diff --git a/packages/css/src/components/table/table.scss b/packages/css/src/components/table/table.scss
index bfc3ecf3461..283e270d634 100644
--- a/packages/css/src/components/table/table.scss
+++ b/packages/css/src/components/table/table.scss
@@ -19,6 +19,7 @@
.ams-table__caption {
font-weight: var(--ams-table-caption-font-weight);
+ margin-block-end: var(--ams-table-caption-margin-block-end);
text-align: start;
}
diff --git a/storybook/src/components/Table/Table.docs.mdx b/storybook/src/components/Table/Table.docs.mdx
index c21a790a659..cd6f03495ce 100644
--- a/storybook/src/components/Table/Table.docs.mdx
+++ b/storybook/src/components/Table/Table.docs.mdx
@@ -24,6 +24,14 @@ Use `Table.Footer` for a summary row.
+### With description in caption
+
+Add a description to the caption to provide context like a source, date, or reading instructions.
+Use a small [Paragraph](/docs/components-text-paragraph--docs).
+Set `aria-labelledby` to keep only the heading as the table’s accessible name, or screen readers will read out the entire text.
+
+
+
## Design tokens