Skip to content

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

TypeScript

fix(richtext): render documents with Markdown's typography, block spacing, and measure (#6997)

Cindy Zhangb45853314f84
diff --git a/packages/richtext/src/__tests__/MarkdownParitySandbox.a11y.chromium.spec.ts b/packages/richtext/src/__tests__/MarkdownParitySandbox.a11y.chromium.spec.ts
index 3e98c837d5..829d5811d6 100644
--- a/packages/richtext/src/__tests__/MarkdownParitySandbox.a11y.chromium.spec.ts
+++ b/packages/richtext/src/__tests__/MarkdownParitySandbox.a11y.chromium.spec.ts
@@ -417,6 +417,105 @@ for (const viewport of [PHONE, {width: 1280, height: 900}] as const) {
}
}
+// spec:AST-061 FR2–FR4: the same blocks use the same type scale, spacing,
+// and measure on both surfaces. Geometry still differs where structure does
+// (lists, code, rules); these blocks already share their structure.
+test('side by side: shared blocks match core Markdown typography, spacing, and measure', async ({
+ page,
+}) => {
+ const errors = await openStory(page, STORY.sideBySide, DESKTOP);
+ await waitForDocument(page, MARKDOWN);
+ await waitForDocument(page, RICH_TEXT);
+ const read = (surface: string) =>
+ page.evaluate(selector => {
+ const properties = [
+ 'fontFamily',
+ 'fontSize',
+ 'lineHeight',
+ 'fontWeight',
+ 'marginTop',
+ 'marginBottom',
+ 'maxWidth',
+ 'paddingLeft',
+ 'borderLeftWidth',
+ ] as const;
+ const styleOf = (element: Element | null | undefined) => {
+ if (element == null) {
+ return null;
+ }
+ const computed = getComputedStyle(element);
+ return Object.fromEntries(
+ properties.map(property => [property, computed[property]]),
+ );
+ };
+ const block = (key: string, inner?: string) => {
+ const element = document.querySelector(
+ `${selector} [data-parity-block="${key}"]`,
+ );
+ if (inner == null || element?.matches(inner)) {
+ return element;
+ }
+ return element?.querySelector(inner);
+ };
+ // RichText draws the inline-code chip on the text inside <code>.
+ const code = block('paragraph-inline')?.querySelector('code');
+ return {
+ heading1: styleOf(block('heading-1', 'h1')),
+ heading2: styleOf(block('heading-2', 'h2')),
+ heading3: styleOf(block('heading-3', 'h3')),
+ heading4: styleOf(block('heading-4', 'h4')),
+ paragraph: styleOf(block('paragraph-escapes', 'p, div')),
+ lastParagraph: styleOf(block('paragraph-final', 'p, div')),
+ blockquote: styleOf(block('blockquote', 'blockquote')),
+ strong: getComputedStyle(
+ block('paragraph-inline')?.querySelector('strong') as Element,
+ ).fontWeight,
+ inlineCode: styleOf(code?.firstElementChild ?? code),
+ // The text inside a header cell, where each surface draws it.
+ tableHeader: (() => {
+ const cell = block('table', 'table')?.querySelector('th');
+ const text = cell?.querySelector('p') ?? cell;
+ return text == null
+ ? null
+ : [getComputedStyle(text).fontWeight, getComputedStyle(text).color];
+ })(),
+ };
+ }, surface);
+ const markdown = await read(MARKDOWN);
+ const richText = await read(RICH_TEXT);
+ for (const key of [
+ 'heading1',
+ 'heading2',
+ 'heading3',
+ 'heading4',
+ 'paragraph',
+ 'lastParagraph',
+ ] as const) {
+ expect(richText[key], key).toEqual(markdown[key]);
+ }
+ for (const property of [
+ 'marginTop',
+ 'marginBottom',
+ 'maxWidth',
+ 'paddingLeft',
+ 'borderLeftWidth',
+ ] as const) {
+ expect(richText.blockquote?.[property], `blockquote ${property}`).toBe(
+ markdown.blockquote?.[property],
+ );
+ }
+ expect(richText.strong).toBe(markdown.strong);
+ expect(richText.tableHeader, 'table header text').toEqual(
+ markdown.tableHeader,
+ );
+ for (const property of ['fontSize', 'lineHeight', 'paddingLeft'] as const) {
+ expect(richText.inlineCode?.[property], `inline code ${property}`).toBe(
+ markdown.inlineCode?.[property],
+ );
+ }
+ expect(errors).toEqual([]);
+});
+
test('side by side: one fixture renders on both surfaces', async ({page}) => {
const errors = await openStory(page, STORY.sideBySide, DESKTOP);
await waitForDocument(page, MARKDOWN);
diff --git a/packages/richtext/src/editorTheme.ts b/packages/richtext/src/editorTheme.ts
index 7fc313bf6f..8372812e12 100644
--- a/packages/richtext/src/editorTheme.ts
+++ b/packages/richtext/src/editorTheme.ts
@@ -4,8 +4,8 @@
* @file editorTheme.ts
* @input Uses StyleX + Astryx design tokens
* @output Exports sharedEditorTheme(), which builds a Lexical EditorThemeClasses
- * object mapping Lexical's theme slots to StyleX-generated class names and
- * normalizes paragraph spacing for editor/view alignment.
+ * object mapping Lexical's theme slots to StyleX-generated class names, with
+ * document blocks styled like core Markdown (spec:AST-061 FR2–FR4).
* @position Shared by RichTextEditor.tsx and RichTextView.tsx so editor and
* read-only view render identically.
*
@@ -23,49 +23,172 @@ import {
} from '@astryxdesign/core/theme/tokens.stylex';
import type {EditorThemeClasses} from 'lexical';
+// Document blocks follow core Markdown's typography, spacing, and measure
+// (spec:AST-061 FR2–FR4): type-scale tokens for text, one block spacing table
+// with no margin before the first block or after the last, and prose capped
+// at Markdown's default content width while code and tables span the editor.
+const PROSE_MEASURE = '680px';
+
+// Block margins wrap their spacing tokens in calc(). The value is unique to
+// these rules, so its atomic class never matches a margin declared by other
+// code; a stylesheet in a later cascade layer therefore cannot outrank the
+// :first-child and :last-child rules that remove the outer margins.
+const MAJOR_HEADING_BEFORE = `calc(${spacingVars['--spacing-6']})`;
+const MAJOR_HEADING_AFTER = `calc(${spacingVars['--spacing-3']})`;
+const MINOR_HEADING_BEFORE = `calc(${spacingVars['--spacing-4']})`;
+const MINOR_HEADING_AFTER = `calc(${spacingVars['--spacing-2']})`;
+const TEXT_BLOCK_SPACE = `calc(${spacingVars['--spacing-3']})`;
+const WIDE_BLOCK_SPACE = `calc(${spacingVars['--spacing-4']})`;
+
const editorTheme = stylex.create({
paragraph: {
- // A leading margin collapses through Lexical's wrapper and stacks with the
- // input inset. Keep the same between-paragraph rhythm on the end edge so
+ // The first block's leading margin would stack with the input inset, so
// the first line aligns with TextArea and the empty-editor placeholder.
- marginBlockStart: spacingVars['--spacing-0'],
- marginBlockEnd: spacingVars['--spacing-1'],
+ marginBlockStart: {
+ default: TEXT_BLOCK_SPACE,
+ ':first-child': spacingVars['--spacing-0'],
+ },
+ marginBlockEnd: {
+ default: TEXT_BLOCK_SPACE,
+ ':last-child': spacingVars['--spacing-0'],
+ },
+ maxWidth: PROSE_MEASURE,
+ // The base reset gives every <p> body weight and primary color; a
+ // paragraph inside a table header cell takes the cell's instead.
+ fontWeight: 'inherit',
+ color: 'inherit',
},
h1: {
fontFamily: typographyVars['--font-family-heading'],
- fontSize: '1.5rem',
- fontWeight: fontWeightVars['--font-weight-semibold'],
- marginBlock: spacingVars['--spacing-2'],
+ fontSize: typeScaleVars['--text-heading-1-size'],
+ fontWeight: typeScaleVars['--text-heading-1-weight'],
+ lineHeight: typeScaleVars['--text-heading-1-leading'],
+ marginBlockStart: {
+ default: MAJOR_HEADING_BEFORE,
+ ':first-child': spacingVars['--spacing-0'],
+ },
+ marginBlockEnd: {
+ default: MAJOR_HEADING_AFTER,
+ ':last-child': spacingVars['--spacing-0'],
+ },
+ maxWidth: PROSE_MEASURE,
},
h2: {
fontFamily: typographyVars['--font-family-heading'],
- fontSize: '1.25rem',
- fontWeight: fontWeightVars['--font-weight-semibold'],
- marginBlock: spacingVars['--spacing-2'],
+ fontSize: typeScaleVars['--text-heading-2-size'],
+ fontWeight: typeScaleVars['--text-heading-2-weight'],
+ lineHeight: typeScaleVars['--text-heading-2-leading'],
+ marginBlockStart: {
+ default: MAJOR_HEADING_BEFORE,
+ ':first-child': spacingVars['--spacing-0'],
+ },
+ marginBlockEnd: {
+ default: MAJOR_HEADING_AFTER,
+ ':last-child': spacingVars['--spacing-0'],
+ },
+ maxWidth: PROSE_MEASURE,
},
h3: {
fontFamily: typographyVars['--font-family-heading'],
- fontSize: '1.125rem',
- fontWeight: fontWeightVars['--font-weight-semibold'],
- marginBlock: spacingVars['--spacing-1'],
+ fontSize: typeScaleVars['--text-heading-3-size'],
+ fontWeight: typeScaleVars['--text-heading-3-weight'],
+ lineHeight: typeScaleVars['--text-heading-3-leading'],
+ marginBlockStart: {
+ default: MAJOR_HEADING_BEFORE,
+ ':first-child': spacingVars['--spacing-0'],
+ },
+ marginBlockEnd: {
+ default: MAJOR_HEADING_AFTER,
+ ':last-child': spacingVars['--spacing-0'],
+ },
+ maxWidth: PROSE_MEASURE,
+ },
+ h4: {
+ fontFamily: typographyVars['--font-family-heading'],
+ fontSize: typeScaleVars['--text-heading-4-size'],
+ fontWeight: typeScaleVars['--text-heading-4-weight'],
+ lineHeight: typeScaleVars['--text-heading-4-leading'],
+ marginBlockStart: {
+ default: MINOR_HEADING_BEFORE,
+ ':first-child': spacingVars['--spacing-0'],
+ },
+ marginBlockEnd: {
+ default: MINOR_HEADING_AFTER,
+ ':last-child': spacingVars['--spacing-0'],
+ },
+ maxWidth: PROSE_MEASURE,
+ },
+ h5: {
+ fontFamily: typographyVars['--font-family-heading'],
+ fontSize: typeScaleVars['--text-heading-5-size'],
+ fontWeight: typeScaleVars['--text-heading-5-weight'],
+ lineHeight: typeScaleVars['--text-heading-5-leading'],
+ marginBlockStart: {
+ default: MINOR_HEADING_BEFORE,
+ ':first-child': spacingVars['--spacing-0'],
+ },
+ marginBlockEnd: {
+ default: MINOR_HEADING_AFTER,
+ ':last-child': spacingVars['--spacing-0'],
+ },
+ maxWidth: PROSE_MEASURE,
+ },
+ h6: {
+ fontFamily: typographyVars['--font-family-heading'],
+ fontSize: typeScaleVars['--text-heading-6-size'],
+ fontWeight: typeScaleVars['--text-heading-6-weight'],
+ lineHeight: typeScaleVars['--text-heading-6-leading'],
+ marginBlockStart: {
+ default: MINOR_HEADING_BEFORE,
+ ':first-child': spacingVars['--spacing-0'],
+ },
+ marginBlockEnd: {
+ default: MINOR_HEADING_AFTER,
+ ':last-child': spacingVars['--spacing-0'],
+ },
+ maxWidth: PROSE_MEASURE,
},
quote: {
- marginBlock: spacingVars['--spacing-2'],
+ marginBlockStart: {
+ default: WIDE_BLOCK_SPACE,
+ ':first-child': spacingVars['--spacing-0'],
+ },
+ marginBlockEnd: {
+ default: WIDE_BLOCK_SPACE,
+ ':last-child': spacingVars['--spacing-0'],
+ },
marginInline: 0,
- paddingInlineStart: spacingVars['--spacing-3'],
- borderInlineStartWidth: '3px',
+ maxWidth: PROSE_MEASURE,
+ paddingInlineStart: spacingVars['--spacing-4'],
+ borderInlineStartWidth: '2px',
borderInlineStartStyle: 'solid',
borderInlineStartColor: colorVars['--color-border-emphasized'],
color: colorVars['--color-text-secondary'],
},
ul: {
- marginBlock: spacingVars['--spacing-1'],
+ marginBlockStart: {
+ default: TEXT_BLOCK_SPACE,
+ ':first-child': spacingVars['--spacing-0'],
+ },
+ marginBlockEnd: {
+ default: TEXT_BLOCK_SPACE,
+ ':last-child': spacingVars['--spacing-0'],
+ },
+ maxWidth: PROSE_MEASURE,
paddingInlineStart: spacingVars['--spacing-6'],
listStyleType: 'disc',
listStylePosition: 'outside',
},
ol: {
- marginBlock: spacingVars['--spacing-1'],
+ marginBlockStart: {
+ default: TEXT_BLOCK_SPACE,
+ ':first-child': spacingVars['--spacing-0'],
+ },
+ marginBlockEnd: {
+ default: TEXT_BLOCK_SPACE,
+ ':last-child': spacingVars['--spacing-0'],
+ },
+ maxWidth: PROSE_MEASURE,
paddingInlineStart: spacingVars['--spacing-6'],
listStyleType: 'decimal',
listStylePosition: 'outside',
@@ -75,7 +198,8 @@ const editorTheme = stylex.create({
// `depth % array.length`, so three entries give three distinct levels that
// then repeat — matching the browser default disc → circle → square cycle.
ulNested: {
- marginBlock: 0,
+ marginBlockStart: 0,
+ marginBlockEnd: 0,
},
ulDepth2: {
listStyleType: 'circle',
@@ -84,7 +208,8 @@ const editorTheme = stylex.create({
listStyleType: 'square',
},
olNested: {
- marginBlock: 0,
+ marginBlockStart: 0,
+ marginBlockEnd: 0,
},
olDepth2: {
listStyleType: 'lower-alpha',
@@ -108,7 +233,7 @@ const editorTheme = stylex.create({
textDecoration: 'underline',
cursor: 'pointer',
},
- textBold: {fontWeight: fontWeightVars['--font-weight-bold']},
+ textBold: {fontWeight: fontWeightVars['--font-weight-semibold']},
textItalic: {fontStyle: 'italic'},
textUnderline: {textDecoration: 'underline'},
textStrikethrough: {textDecoration: 'line-through'},
@@ -116,9 +241,7 @@ const editorTheme = stylex.create({
fontFamily: typographyVars['--font-family-code'],
backgroundColor: colorVars['--color-background-muted'],
paddingInline: spacingVars['--spacing-1'],
- paddingBlock: spacingVars['--spacing-0-5'],
borderRadius: radiusVars['--radius-inner'],
- fontSize: '0.9em',
},
// GFM tables, styled like core Markdown's table: semibold secondary header
// text, a divider under every row but the last, and a wide table that
@@ -132,11 +255,18 @@ const editorTheme = stylex.create({
// sizes to the table's natural width.
display: 'grid',
gridTemplateColumns: 'minmax(0, 1fr)',
+ marginBlockStart: {
+ default: WIDE_BLOCK_SPACE,
+ ':first-child': spacingVars['--spacing-0'],
+ },
+ marginBlockEnd: {
+ default: WIDE_BLOCK_SPACE,
+ ':last-child': spacingVars['--spacing-0'],
+ },
},
table: {
borderCollapse: 'collapse',
width: '100%',
- marginBlock: spacingVars['--spacing-4'],
},
tableRow: {
borderBottomWidth: '1px',
@@ -164,7 +294,14 @@ const editorTheme = stylex.create({
padding: spacingVars['--spacing-3'],
borderRadius: radiusVars['--radius-inner'],
fontSize: typeScaleVars['--text-supporting-size'],
- marginBlock: spacingVars['--spacing-2'],
+ marginBlockStart: {
+ default: WIDE_BLOCK_SPACE,
+ ':first-child': spacingVars['--spacing-0'],
+ },
+ marginBlockEnd: {
+ default: WIDE_BLOCK_SPACE,
+ ':last-child': spacingVars['--spacing-0'],
+ },
whiteSpace: 'pre-wrap',
},
});
@@ -194,6 +331,9 @@ export function sharedEditorTheme(): EditorThemeClasses {
h1: stylex.props(editorTheme.h1).className,
h2: stylex.props(editorTheme.h2).className,
h3: stylex.props(editorTheme.h3).className,
+ h4: stylex.props(editorTheme.h4).className,
+ h5: stylex.props(editorTheme.h5).className,
+ h6: stylex.props(editorTheme.h6).className,
},
quote: stylex.props(editorTheme.quote).className,
list: {