Skip to content

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

TypeScript

fix(docsite): improve docs article body readability (#3085)

Ernestf94dd07e2268
diff --git a/apps/docsite/src/components/docs/DocPageLayout.tsx b/apps/docsite/src/components/docs/DocPageLayout.tsx
index b18f51523b..e2a917af43 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 f2afdab616..d532fc9c1f 100644
--- a/apps/docsite/src/components/docs/ProseBlock.tsx
+++ b/apps/docsite/src/components/docs/ProseBlock.tsx
@@ -8,9 +8,15 @@ import {renderInlineMarkdown} from './inlineMarkdown';
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}>{renderInlineMarkdown(text)}</Text>;
+ return (
+ <Text as="p" display="block" xstyle={styles.prose}>
+ {renderInlineMarkdown(text)}
+ </Text>
+ );
}
diff --git a/packages/cli/templates/pages/documentation-technical/page.tsx b/packages/cli/templates/pages/documentation-technical/page.tsx
index 1e873d4ce1..c571b4c071 100644
--- a/packages/cli/templates/pages/documentation-technical/page.tsx
+++ b/packages/cli/templates/pages/documentation-technical/page.tsx
@@ -138,9 +138,9 @@ export default function TechnicalDocumentationPage() {
</HStack>
<Text type="body" color="secondary">
Help me get set up with Product Name. Based on my project, do
- the following: 1. Install @astryxdesign/core and the StyleX compiler.
- 2. Wrap my app in ThemeProvider. 3. Replace one existing
- component with an Astryx equivalent.
+ the following: 1. Install @astryxdesign/core and the StyleX
+ compiler. 2. Wrap my app in ThemeProvider. 3. Replace one
+ existing component with an Astryx equivalent.
</Text>
</VStack>
</Card>
@@ -181,8 +181,8 @@ export default function TechnicalDocumentationPage() {
Step 2: Add the StyleX compiler
</Text>
<Text type="body" color="secondary">
- Astryx uses StyleX for styling. Add the compiler plugin to your
- build configuration.
+ Astryx uses StyleX for styling. Add the compiler plugin to
+ your build configuration.
</Text>
<CodeBlock
code="npm install @stylexjs/babel-plugin"