From 1ddcfd4ee2119b617791e32f8aa019a2aa83fc96 Mon Sep 17 00:00:00 2001
From: Ernest Tien <ernesttien@meta.com>
Date: Wed, 24 Jun 2026 15:00:08 -0700
Subject: [PATCH] fix(docsite): improve docs article body readability

Bump article body text to 16px with a 1.75 line-height (type-scale
consistent: a 4px-grid-snapped 28px line box) and render paragraphs as
<p> instead of <span>. Scoped to the article container via the body
size/leading tokens, so headings, subtitle, and site chrome are
unaffected.

Addresses reader feedback:
https://fb.workplace.com/groups/xdsfyi/posts/2426457761173540/?comment_id=2427223827763600&reply_comment_id=2427226201096696

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../src/components/docs/DocPageLayout.tsx      | 18 +++++++++++++++++-
 .../docsite/src/components/docs/ProseBlock.tsx | 10 ++++++++--
 2 files changed, 25 insertions(+), 3 deletions(-)

diff --git a/apps/docsite/src/components/docs/DocPageLayout.tsx b/apps/docsite/src/components/docs/DocPageLayout.tsx
index b18f51523b29..e2a917af43d4 100644
--- a/apps/docsite/src/components/docs/DocPageLayout.tsx
+++ b/apps/docsite/src/components/docs/DocPageLayout.tsx
@@ -13,11 +13,24 @@ import {Text, Heading} from '@astryxdesign/core/Text';
 import {VStack} from '@astryxdesign/core/Layout';
 import {Section} from '@astryxdesign/core/Section';
 import {Divider} from '@astryxdesign/core/Divider';
+import {typeScaleVars} from '@astryxdesign/core/theme/tokens.stylex';
 import {layout} from '../../layout.stylex';
 
 const styles = stylex.create({
   section: {
     marginInline: 'auto',
+    // Article body text reads larger and airier than the app default
+    // (body = 14px / 1.43). Re-assigning the body size/leading tokens here
+    // scopes the change to body-typed Text *inside* an article only: the
+    // title (display-1) and subtitle (large) use different tokens, and the
+    // sidebar/top-nav live in a different subtree, so nothing else shifts.
+    //
+    // Leading follows the type scale's convention (unitless ratio = a
+    // 4px-grid-snapped line box ÷ font size, per expandTypeScale's
+    // computeLeading). The grid-snapped value closest to the requested ~1.7
+    // at 16px is 28px ÷ 16px = 1.75.
+    [typeScaleVars['--text-body-size']]: '1rem', // 16px
+    [typeScaleVars['--text-body-leading']]: '1.75', // 28px line box
   },
 });
 
@@ -31,7 +44,10 @@ export function DocPageLayout({
   children: ReactNode;
 }) {
   return (
-    <Section maxWidth={layout.proseMaxWidth} padding={6} xstyle={styles.section}>
+    <Section
+      maxWidth={layout.proseMaxWidth}
+      padding={6}
+      xstyle={styles.section}>
       <VStack gap={10}>
         <VStack gap={4}>
           <Heading level={1} type="display-1">
diff --git a/apps/docsite/src/components/docs/ProseBlock.tsx b/apps/docsite/src/components/docs/ProseBlock.tsx
index 804838074492..0a9cc4446762 100644
--- a/apps/docsite/src/components/docs/ProseBlock.tsx
+++ b/apps/docsite/src/components/docs/ProseBlock.tsx
@@ -8,9 +8,15 @@ import {renderInlineCode} from './renderInlineCode';
 import {layout} from '../../layout.stylex';
 
 const styles = stylex.create({
-  prose: {maxWidth: layout.proseMaxWidth},
+  // marginBlock: 0 — the <p> UA margin would otherwise double up with the
+  // VStack gap that already spaces blocks apart.
+  prose: {maxWidth: layout.proseMaxWidth, marginBlock: 0},
 });
 
 export function ProseBlock({text}: {text: string}) {
-  return <Text xstyle={styles.prose}>{renderInlineCode(text)}</Text>;
+  return (
+    <Text as="p" display="block" xstyle={styles.prose}>
+      {renderInlineCode(text)}
+    </Text>
+  );
 }