Skip to content

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

TypeScript

feat(markdown): expose per-block spacing to theming via astryx-markdown-* targets (#4669)

freddymeta3d4860ab9a67
diff --git a/.changeset/markdown-block-spacing-theme-targets.md b/.changeset/markdown-block-spacing-theme-targets.md
new file mode 100644
index 0000000000..125a529f20
--- /dev/null
+++ b/.changeset/markdown-block-spacing-theme-targets.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] Markdown: expose per-block spacing to theming. Every block type now renders a stable theme target — `astryx-markdown-heading`, `-paragraph`, `-list`, `-codeblock`, `-blockquote`, `-table`, `-hr`, and `-image` — so a theme can tune the gap around any block (`marginBlockStart`/`marginBlockEnd`) via `defineTheme` instead of overriding global spacing tokens or reaching for fragile `[role="paragraph"]`-style descendant selectors. Each target reflects `data-density` (so spacing can differ per `default`/`compact`), and the heading target additionally reflects `data-level` (1–6) for per-level spacing. Targets apply only to the default render path — a custom `components.heading`/`code`/`blockquote`/`hr`/`image` continues to own its own styling. Purely additive — default rendering is unchanged.
+
+@freddymeta
diff --git a/packages/core/src/Markdown/Markdown.doc.mjs b/packages/core/src/Markdown/Markdown.doc.mjs
index 6a3762e80f..52dd698804 100644
--- a/packages/core/src/Markdown/Markdown.doc.mjs
+++ b/packages/core/src/Markdown/Markdown.doc.mjs
@@ -128,6 +128,38 @@ export const docs = {
theming: {
targets: [
{className: 'astryx-markdown', visualProps: ['density']},
+ {
+ className: 'astryx-markdown-heading',
+ visualProps: ['density', 'level'],
+ },
+ {
+ className: 'astryx-markdown-paragraph',
+ visualProps: ['density'],
+ },
+ {
+ className: 'astryx-markdown-list',
+ visualProps: ['density'],
+ },
+ {
+ className: 'astryx-markdown-codeblock',
+ visualProps: ['density'],
+ },
+ {
+ className: 'astryx-markdown-blockquote',
+ visualProps: ['density'],
+ },
+ {
+ className: 'astryx-markdown-table',
+ visualProps: ['density'],
+ },
+ {
+ className: 'astryx-markdown-hr',
+ visualProps: ['density'],
+ },
+ {
+ className: 'astryx-markdown-image',
+ visualProps: ['density'],
+ },
],
},
usage: {
@@ -292,6 +324,54 @@ export const docsZh = {
theming: {
targets: [
{className: 'astryx-markdown', visualProps: ['density']},
+ {
+ className: 'astryx-markdown-heading',
+ visualProps: ['density', 'level'],
+ description:
+ '每个渲染的标题块(h1–h6)。覆盖 marginBlockStart/marginBlockEnd 可调整标题周围的间距;反映 data-density 和 data-level,因此主题可按密度和标题层级设置间距。仅适用于默认标题渲染——自定义的 components.heading 拥有自己的样式。',
+ },
+ {
+ className: 'astryx-markdown-paragraph',
+ visualProps: ['density'],
+ description:
+ '每个渲染的段落块。覆盖 marginBlockStart/marginBlockEnd 可调整段落之间的间距。反映 data-density,因此主题可以为不同密度设置不同的间距。',
+ },
+ {
+ className: 'astryx-markdown-list',
+ visualProps: ['density'],
+ description:
+ '每个渲染的列表块(有序、无序和任务列表)。覆盖 marginBlockStart/marginBlockEnd 可调整列表周围的间距;反映 data-density。',
+ },
+ {
+ className: 'astryx-markdown-codeblock',
+ visualProps: ['density'],
+ description:
+ '每个渲染的代码块外层容器。覆盖 marginBlockStart/marginBlockEnd 可调整代码块周围的间距;反映 data-density。仅适用于默认渲染——自定义的 components.code 拥有自己的样式。',
+ },
+ {
+ className: 'astryx-markdown-blockquote',
+ visualProps: ['density'],
+ description:
+ '每个渲染的引用块(与 astryx-blockquote 目标共用同一元素)。覆盖 marginBlockStart/marginBlockEnd 可调整引用块周围的间距;反映 data-density。仅适用于默认渲染——自定义的 components.blockquote 拥有自己的样式。',
+ },
+ {
+ className: 'astryx-markdown-table',
+ visualProps: ['density'],
+ description:
+ '每个渲染的表格外层容器。覆盖 marginBlockStart/marginBlockEnd 可调整表格周围的间距;反映 data-density。',
+ },
+ {
+ className: 'astryx-markdown-hr',
+ visualProps: ['density'],
+ description:
+ '每个渲染的水平分隔线。覆盖 marginBlockStart/marginBlockEnd 可调整分隔线周围的间距;反映 data-density。仅适用于默认渲染——自定义的 components.hr 拥有自己的样式。',
+ },
+ {
+ className: 'astryx-markdown-image',
+ visualProps: ['density'],
+ description:
+ '每个渲染的块级图片外层容器(以及损坏图片的占位符)。覆盖 marginBlockStart/marginBlockEnd 可调整图片周围的间距;反映 data-density。仅适用于默认渲染——自定义的 components.image 拥有自己的样式。',
+ },
],
},
usage: {
diff --git a/packages/core/src/Markdown/Markdown.test.tsx b/packages/core/src/Markdown/Markdown.test.tsx
index 1720be73bf..1a36daf0c5 100644
--- a/packages/core/src/Markdown/Markdown.test.tsx
+++ b/packages/core/src/Markdown/Markdown.test.tsx
@@ -2,6 +2,7 @@
import {describe, it, expect, vi} from 'vitest';
import {render, screen, fireEvent} from '@testing-library/react';
+import type {ReactNode} from 'react';
import {Markdown} from './Markdown';
import type {MarkdownInlinePlugin} from './Markdown';
@@ -34,6 +35,97 @@ describe('Markdown', () => {
expect(para).toHaveAttribute('role', 'paragraph');
});
+ it('renders the astryx-markdown-paragraph theme target on each paragraph', () => {
+ render(<Markdown>{'First para\n\nSecond para'}</Markdown>);
+ const first = screen.getByText('First para');
+ const second = screen.getByText('Second para');
+ // Stable theme-target class lets a theme adjust the inter-paragraph gap
+ // (marginBlockStart/marginBlockEnd) via defineTheme without reaching for
+ // fragile descendant selectors or global spacing tokens.
+ expect(first.className).toContain('astryx-markdown-paragraph');
+ expect(second.className).toContain('astryx-markdown-paragraph');
+ });
+
+ describe('block spacing theme targets', () => {
+ // Every block type renders a stable astryx-markdown-<block> class so a
+ // theme can tune the gap around it (marginBlockStart/marginBlockEnd) via
+ // defineTheme — the whole prose rhythm is themeable, not just paragraphs.
+ it('renders a stable theme-target class on every block type', () => {
+ const {container} = render(
+ <Markdown>
+ {[
+ '# Heading',
+ 'Paragraph text',
+ '- item one',
+ '```\ncode\n```',
+ '> quoted',
+ '| a | b |\n| - | - |\n| 1 | 2 |',
+ '---',
+ '![alt](https://example.com/x.png)',
+ ].join('\n\n')}
+ </Markdown>,
+ );
+ for (const cls of [
+ 'astryx-markdown-heading',
+ 'astryx-markdown-paragraph',
+ 'astryx-markdown-list',
+ 'astryx-markdown-codeblock',
+ 'astryx-markdown-blockquote',
+ 'astryx-markdown-table',
+ 'astryx-markdown-hr',
+ 'astryx-markdown-image',
+ ]) {
+ expect(
+ container.querySelector(`.${cls}`),
+ `expected a .${cls} element`,
+ ).not.toBeNull();
+ }
+ });
+
+ it('renders the theme target on task lists too', () => {
+ const {container} = render(<Markdown>{'- [ ] todo'}</Markdown>);
+ expect(container.querySelector('.astryx-markdown-list')).not.toBeNull();
+ });
+
+ it('reflects density on block targets as data-density', () => {
+ const {rerender} = render(<Markdown>{'Hello world'}</Markdown>);
+ // Default density is reflected so themes can tune spacing per density.
+ expect(screen.getByText('Hello world')).toHaveAttribute(
+ 'data-density',
+ 'default',
+ );
+ rerender(<Markdown density="compact">{'Hello world'}</Markdown>);
+ expect(screen.getByText('Hello world')).toHaveAttribute(
+ 'data-density',
+ 'compact',
+ );
+ });
+
+ it('reflects the heading level on the heading target as data-level', () => {
+ render(<Markdown>{'## Section'}</Markdown>);
+ const heading = screen.getByText('Section');
+ expect(heading.className).toContain('astryx-markdown-heading');
+ expect(heading).toHaveAttribute('data-level', '2');
+ });
+
+ it('does not apply the theme target when a custom block component is provided', () => {
+ const {container} = render(
+ <Markdown
+ components={{
+ heading: ({children}: {children: ReactNode}) => (
+ <h2 data-custom>{children}</h2>
+ ),
+ }}>
+ {'# Custom heading'}
+ </Markdown>,
+ );
+ // Custom components own their own styling — the default target is not
+ // imposed on them.
+ expect(container.querySelector('.astryx-markdown-heading')).toBeNull();
+ expect(container.querySelector('[data-custom]')).not.toBeNull();
+ });
+ });
+
it('renders inline display without block wrappers', () => {
const {container} = render(
<Markdown display="inline">{'Use `code` and **bold**'}</Markdown>,
diff --git a/packages/core/src/Markdown/Markdown.tsx b/packages/core/src/Markdown/Markdown.tsx
index 0b5b0b99fc..a6f850b7e2 100644
--- a/packages/core/src/Markdown/Markdown.tsx
+++ b/packages/core/src/Markdown/Markdown.tsx
@@ -1083,18 +1083,21 @@ function renderBlock(
return (
<Tag
key={index}
- {...stylex.props(
- styles.headingBase,
- headingStyles[level],
- spacing,
- contentWidthValue != null
- ? dynamicStyles.proseWidth(contentWidthValue)
- : null,
- contentAlign !== 'start'
- ? dynamicStyles.proseAlign(ALIGN_MARGIN[contentAlign])
- : null,
- isFirst && styles.noMarginBlockStart,
- isLast && styles.noMarginBlockEnd,
+ {...mergeProps(
+ themeProps('markdown-heading', {density, level}),
+ stylex.props(
+ styles.headingBase,
+ headingStyles[level],
+ spacing,
+ contentWidthValue != null
+ ? dynamicStyles.proseWidth(contentWidthValue)
+ : null,
+ contentAlign !== 'start'
+ ? dynamicStyles.proseAlign(ALIGN_MARGIN[contentAlign])
+ : null,
+ isFirst && styles.noMarginBlockStart,
+ isLast && styles.noMarginBlockEnd,
+ ),
)}>
{headingChildren}
</Tag>
@@ -1130,16 +1133,19 @@ function renderBlock(
<div
key={index}
role="paragraph"
- {...stylex.props(
- spacing,
- contentWidthValue != null
- ? dynamicStyles.proseWidth(contentWidthValue)
- : null,
- contentAlign !== 'start'
- ? dynamicStyles.proseAlign(ALIGN_MARGIN[contentAlign])
- : null,
- isFirst && styles.noMarginBlockStart,
- isLast && styles.noMarginBlockEnd,
+ {...mergeProps(
+ themeProps('markdown-paragraph', {density}),
+ stylex.props(
+ spacing,
+ contentWidthValue != null
+ ? dynamicStyles.proseWidth(contentWidthValue)
+ : null,
+ contentAlign !== 'start'
+ ? dynamicStyles.proseAlign(ALIGN_MARGIN[contentAlign])
+ : null,
+ isFirst && styles.noMarginBlockStart,
+ isLast && styles.noMarginBlockEnd,
+ ),
)}>
{paraChildren}
</div>
@@ -1161,11 +1167,14 @@ function renderBlock(
return (
<div
key={index}
- {...stylex.props(
- spacing,
- styles.codeBlockWrapper,
- isFirst && styles.noMarginBlockStart,
- isLast && styles.noMarginBlockEnd,
+ {...mergeProps(
+ themeProps('markdown-codeblock', {density}),
+ stylex.props(
+ spacing,
+ styles.codeBlockWrapper,
+ isFirst && styles.noMarginBlockStart,
+ isLast && styles.noMarginBlockEnd,
+ ),
)}>
<CodeBlock
code={node.content}
@@ -1207,6 +1216,7 @@ function renderBlock(
return (
<Blockquote
key={index}
+ {...themeProps('markdown-blockquote', {density})}
xstyle={[
spacing,
contentWidthValue != null
@@ -1254,10 +1264,13 @@ function renderBlock(
return (
<div
key={index}
- {...stylex.props(
- spacing,
- isFirst && styles.noMarginBlockStart,
- isLast && styles.noMarginBlockEnd,
+ {...mergeProps(
+ themeProps('markdown-list', {density}),
+ stylex.props(
+ spacing,
+ isFirst && styles.noMarginBlockStart,
+ isLast && styles.noMarginBlockEnd,
+ ),
)}>
<CheckboxList
label={t('@astryx.markdown.taskList')}
@@ -1327,16 +1340,19 @@ function renderBlock(
return (
<div
key={index}
- {...stylex.props(
- spacing,
- contentWidthValue != null
- ? dynamicStyles.proseWidth(contentWidthValue)
- : null,
- contentAlign !== 'start'
- ? dynamicStyles.proseAlign(ALIGN_MARGIN[contentAlign])
- : null,
- isFirst && styles.noMarginBlockStart,
- isLast && styles.noMarginBlockEnd,
+ {...mergeProps(
+ themeProps('markdown-list', {density}),
+ stylex.props(
+ spacing,
+ contentWidthValue != null
+ ? dynamicStyles.proseWidth(contentWidthValue)
+ : null,
+ contentAlign !== 'start'
+ ? dynamicStyles.proseAlign(ALIGN_MARGIN[contentAlign])
+ : null,
+ isFirst && styles.noMarginBlockStart,
+ isLast && styles.noMarginBlockEnd,
+ ),
)}>
<List
listStyle={node.ordered ? 'decimal' : 'disc'}
@@ -1414,17 +1430,20 @@ function renderBlock(
tabIndex={0}
role="group"
aria-label={t('@astryx.markdown.table')}
- {...stylex.props(
- styles.tableWrapper,
- spacing,
- contentWidthValue != null
- ? dynamicStyles.blockWidth(contentWidthValue)
- : null,
- BLOCK_ALIGN_MARGIN[contentAlign] != null
- ? dynamicStyles.blockAlign(BLOCK_ALIGN_MARGIN[contentAlign])
- : null,
- isFirst && styles.noMarginBlockStart,
- isLast && styles.noMarginBlockEnd,
+ {...mergeProps(
+ themeProps('markdown-table', {density}),
+ stylex.props(
+ styles.tableWrapper,
+ spacing,
+ contentWidthValue != null
+ ? dynamicStyles.blockWidth(contentWidthValue)
+ : null,
+ BLOCK_ALIGN_MARGIN[contentAlign] != null
+ ? dynamicStyles.blockAlign(BLOCK_ALIGN_MARGIN[contentAlign])
+ : null,
+ isFirst && styles.noMarginBlockStart,
+ isLast && styles.noMarginBlockEnd,
+ ),
)}>
<Table dividers="rows" textOverflow="wrap">
<TableHeader>
@@ -1499,11 +1518,14 @@ function renderBlock(
return (
<hr
key={index}
- {...stylex.props(
- styles.hr,
- spacing,
- isFirst && styles.noMarginBlockStart,
- isLast && styles.noMarginBlockEnd,
+ {...mergeProps(
+ themeProps('markdown-hr', {density}),
+ stylex.props(
+ styles.hr,
+ spacing,
+ isFirst && styles.noMarginBlockStart,
+ isLast && styles.noMarginBlockEnd,
+ ),
)}
/>
);
@@ -1514,10 +1536,13 @@ function renderBlock(
return (
<div
key={index}
- {...stylex.props(
- spacing,
- isFirst && styles.noMarginBlockStart,
- isLast && styles.noMarginBlockEnd,
+ {...mergeProps(
+ themeProps('markdown-image', {density}),
+ stylex.props(
+ spacing,
+ isFirst && styles.noMarginBlockStart,
+ isLast && styles.noMarginBlockEnd,
+ ),
)}>
[{node.alt}]
</div>
@@ -1530,10 +1555,13 @@ function renderBlock(
return (
<div
key={index}
- {...stylex.props(
- spacing,
- isFirst && styles.noMarginBlockStart,
- isLast && styles.noMarginBlockEnd,
+ {...mergeProps(
+ themeProps('markdown-image', {density}),
+ stylex.props(
+ spacing,
+ isFirst && styles.noMarginBlockStart,
+ isLast && styles.noMarginBlockEnd,
+ ),
)}>
<img src={safeSrc} alt={node.alt} {...stylex.props(styles.image)} />
</div>