Skip to content

[DX-1527] Typography and spacing enhancements #3469

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
m-hulbert wants to merge 3 commits into
base: main
Choose a base branch
from
Open

[DX-1527] Typography and spacing enhancements #3469

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
dca4780
Update docs type scale and text styles
m-hulbert Jul 13, 2026
9b381ae
Apply new vertical rhythm to MDX content
m-hulbert Jul 13, 2026
f1f99af
Align table and admonition spacing with the new type scale
m-hulbert Jul 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/components/Layout/MDXWrapper.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -199,7 +199,7 @@ const WrappedCodeSnippet: React.FC<{ activePage: ActivePage } & CodeSnippetProps
lang={languageOverride || activePage.language}
sdk={detectedSdkType || sdk}
onChange={handleLanguageChange}
className={cn(props.className, 'mb-5')}
className={cn(props.className, 'my-6')}
languageOrdering={
activePage.product && languageData[activePage.product] ? Object.keys(languageData[activePage.product]) : []
}
Expand Down
4 changes: 2 additions & 2 deletions src/components/Layout/mdx/Admonition.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ const Admonition: React.FC<AdmonitionProps> = ({ 'data-type': dataType = 'note',
{...rest}
data-type={dataType}
className={cn(
'border-l px-6 py-3.5 my-4 rounded-r-lg text-neutral-1000 dark:text-neutral-300',
'border-l px-6 py-3.5 my-6 rounded-r-lg text-neutral-1000 dark:text-neutral-300',
borderColor,
backgroundColor,
className,
Expand All @@ -84,7 +84,7 @@ const Admonition: React.FC<AdmonitionProps> = ({ 'data-type': dataType = 'note',
{...rest}
data-type={dataType}
className={cn(
'border-l px-6 py-4 my-4 rounded-r-lg text-neutral-1000 dark:text-neutral-300',
'border-l px-6 py-4 my-6 rounded-r-lg text-neutral-1000 dark:text-neutral-300',
borderColor,
backgroundColor,
className,
Expand Down
6 changes: 1 addition & 5 deletions src/components/Layout/mdx/PageHeader.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,7 @@ export const PageHeader: React.FC<PageHeaderProps> = ({ title, intro }) => {
return (
<div className="my-8 border-b border-neutral-300 dark:border-neutral-1000 pb-8">
<h1 className={cn('ui-text-h1', intro ? 'mb-4' : 'mb-0')}>{title}</h1>
{intro && (
<p className="text-neutral-800 dark:text-neutral-500 font-serif italic tracking-tight text-lg leading-normal mb-0">
{intro}
</p>
)}
{intro && <p className="ui-text-sub-head mb-0">{intro}</p>}
</div>
);
};
4 changes: 2 additions & 2 deletions src/components/Layout/mdx/Table.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@ export interface TableRootProps extends React.HTMLAttributes<HTMLDivElement> {

const TableRoot: React.FC<TableRootProps> = ({ children, className, ...props }) => {
return (
<div className={cn('overflow-x-auto my-4 rounded-lg overflow-hidden', className)} {...props}>
<table className="w-full border-separate border-spacing-0 text-left text-sm">{children}</table>
<div className={cn('overflow-x-auto my-6 rounded-lg overflow-hidden', className)} {...props}>
<table className="w-full border-separate border-spacing-0 text-left text-p2">{children}</table>
</div>
);
};
Expand Down
24 changes: 16 additions & 8 deletions src/components/Markdown/MarkdownProvider.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,38 +6,46 @@ import Link from 'src/components/Link';
import { CodeBlock } from './CodeBlock';
import { checkLinkIsInternal } from 'src/utilities/link-checks';

/**
* Vertical rhythm (Figma "Docs Site SSoT" > Vertical spacing).
* Asymmetric heading margins: a large margin-top separates a heading from the
* preceding content, and a smaller margin-bottom (baking in the 8px paragraph
* lead-in) sets the gap to the following text. Objects (code, tables, asides)
* carry 24px. Adjacent margins collapse, so e.g. a paragraph's 12px bottom and
* a heading's 48px top resolve to 48px.
*/
const H1: FC<JSX.IntrinsicElements['h1']> = ({ children, ...props }) => (
<h1 className="ui-text-h1 my-10" {...props}>
<h1 className="ui-text-h1 mb-6" {...props}>
{children}
</h1>
);

const H2: FC<JSX.IntrinsicElements['h2']> = ({ children, ...props }) => (
<h2 className="ui-text-h2 my-8" {...props}>
<h2 className="ui-text-h2 mt-12 mb-6" {...props}>
{children}
</h2>
);

const H3: FC<JSX.IntrinsicElements['h3']> = ({ children, ...props }) => (
<h3 className="ui-text-h3 my-5" {...props}>
<h3 className="ui-text-h3 mt-8 mb-5" {...props}>
{children}
</h3>
);

const H4: FC<JSX.IntrinsicElements['h4']> = ({ children, ...props }) => (
<h4 className="ui-text-h4 my-5" {...props}>
<h4 className="ui-text-h4 mt-7 mb-4" {...props}>
{children}
</h4>
);

const H5: FC<JSX.IntrinsicElements['h5']> = ({ children, ...props }) => (
<h5 className="ui-text-h5 my-5" {...props}>
<h5 className="ui-text-h5 mt-6 mb-3" {...props}>
{children}
</h5>
);

const Paragraph: FC<JSX.IntrinsicElements['p']> = ({ children, ...props }) => (
<p className="ui-text-p2 mb-5" {...props}>
<p className="ui-text-p1 mb-3" {...props}>
{children}
</p>
);
Expand Down Expand Up @@ -113,7 +121,7 @@ const Ul: FC<JSX.IntrinsicElements['ul']> = ({ children, ...props }) => (
);

const Li: FC<JSX.IntrinsicElements['li']> = ({ children, ...props }) => (
<li className="ui-text-p2 mb-2" {...props}>
<li className="ui-text-p1 mb-2" {...props}>
{children}
</li>
);
Expand All @@ -128,7 +136,7 @@ const Pre: FC<JSX.IntrinsicElements['pre']> = ({ children }) => {
const lang = (children as React.ReactElement)?.props?.className?.replace('language-', '');

return (
<div className="mb-5">
<div className="my-6">
<CodeBlock language={lang || 'javascript'}>{children}</CodeBlock>
</div>
);
Expand Down
10 changes: 10 additions & 0 deletions src/styles/global.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,3 +108,13 @@
* optimo.ch
*/
}

/* MDX content images (gatsby-remark-images) join the object vertical rhythm
with 24px above and below. Kept outside @layer so it is not purged — the
wrapper class is injected at build time and never appears in scanned source.
The wrapper is display:block inside its paragraph, so the margins collapse
through to sit 24px from the surrounding content. */
article .gatsby-resp-image-wrapper {
margin-top: var(--spacing-24);
margin-bottom: var(--spacing-24);
}
10 changes: 5 additions & 5 deletions src/styles/ui/core/styles/properties.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -172,16 +172,16 @@
--fs-title: 2.75rem;
--fs-title-xs: 2.5rem;
--fs-h1-xl: 2.5rem;
--fs-h1: 2.25rem;
--fs-h1: 2rem; /* 32px — docs content heading scale */
--fs-h1-xs: 2rem;

--fs-h2-xl: 2.125rem;
--fs-h2: 2rem;
--fs-h2: 1.5rem; /* 24px */
--fs-h2-xs: 1.75rem;

--fs-h3: 1.5rem;
--fs-h4: 1.25rem;
--fs-h5: 1rem;
--fs-h3: 1.25rem; /* 20px */
--fs-h4: 1.125rem; /* 18px */
--fs-h5: 1rem; /* 16px */

--fs-p1: 1rem;
--fs-p2: 0.938rem;
Expand Down
34 changes: 20 additions & 14 deletions src/styles/ui/core/styles/text.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,48 +7,48 @@

.ui-text-h1 {
@apply font-sans font-bold text-cool-black;
@apply text-h1-xs xs:text-h1 xl:text-h1-xl;
@apply tracking-[-0.0125em] xs:tracking-[-0.015em];
@apply text-h1;
@apply tracking-[-0.02em];
}

.ui-text-h2 {
@apply font-sans font-bold text-cool-black;
@apply text-h2-xs xs:text-h2 xl:text-h2-xl;
@apply tracking-[-0.015em] xs:tracking-[-0.01em];
@apply text-h2;
@apply tracking-[-0.0175em];
}

.ui-text-h3 {
@apply font-sans font-bold text-cool-black;
@apply text-h3;
@apply tracking-[-0.005em];
@apply tracking-[-0.015em];
}

.ui-text-h4 {
@apply font-sans font-bold text-cool-black;
@apply text-h4;
@apply tracking-[-0.0015em];
@apply tracking-[-0.0125em];
}

.ui-text-h5 {
@apply font-sans font-bold text-cool-black;
@apply text-h5;
@apply tracking-[-0.0025em];
@apply tracking-[-0.01em];
}

.ui-text-p1 {
@apply font-sans font-medium text-charcoal-grey text-p1;
@apply font-sans font-medium text-charcoal-grey text-p1 tracking-[-0.01em];
}

.ui-text-p2 {
@apply font-sans font-medium text-charcoal-grey text-p2;
@apply font-sans font-medium text-charcoal-grey text-p2 tracking-[-0.0075em];
}

.ui-text-p3 {
@apply font-sans font-medium text-charcoal-grey text-p3;
@apply font-sans font-medium text-charcoal-grey text-p3 tracking-[-0.005em];
}

.ui-text-p4 {
@apply font-sans font-medium text-charcoal-grey text-p4;
@apply font-sans font-medium text-charcoal-grey text-p4 tracking-[-0.0025em];
}

.ui-text-standfirst {
Expand All @@ -68,6 +68,12 @@
@apply text-sub-header-xs xs:text-sub-header leading-normal;
}

/* Decorative serif sub-head (docs page intro / standfirst). Figma: text-sub-head */
.ui-text-sub-head {
@apply font-serif font-normal italic text-neutral-800 dark:text-neutral-500;
@apply text-sub-header leading-relaxed tracking-[-0.0125em];
}

.ui-text-overline1 {
@apply font-mono font-medium text-active-orange uppercase;
@apply text-overline1 leading-normal;
Expand Down Expand Up @@ -104,15 +110,15 @@
}

.ui-text-code {
@apply font-mono font-normal text-code;
@apply font-mono font-medium text-code;
}

.ui-text-code2 {
@apply font-mono font-normal text-code2;
@apply font-mono font-medium text-code2;
}

.ui-text-code-inline {
@apply inline-flex font-mono px-[0.1875rem] py-1 text-code text-neutral-1000 font-medium bg-neutral-200 border border-neutral-400 rounded-md;
@apply inline-flex items-center font-mono px-1 py-0.5 text-code text-neutral-1000 font-medium bg-neutral-100 border-[0.5px] border-neutral-500 rounded-[4px];
}

.dark .ui-text-code-inline {
Expand Down
10 changes: 5 additions & 5 deletions tailwind.config.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -169,15 +169,15 @@ module.exports = {
title: ['var(--fs-title)', 'var(--lh-min-normal)'],
'title-xl': ['var(--fs-title-xl)', 'var(--lh-min-normal)'],
'title-xs': ['var(--fs-title-xs)', 'var(--lh-min-normal)'],
h1: ['var(--fs-h1)', 'var(--lh-dense)'],
h1: ['var(--fs-h1)', '1.25'],
'h1-xl': ['var(--fs-h1-xl)', 'var(--lh-min-normal)'],
'h1-xs': ['var(--fs-h1-xs)', 'var(--lh-min-normal)'],
h2: ['var(--fs-h2)', 'var(--lh-min-normal)'],
h2: ['var(--fs-h2)', '1.33'],
'h2-xl': ['var(--fs-h2-xl)', 'var(--lh-min-normal)'],
'h2-xs': ['var(--fs-h2-xs)', 'var(--lh-min-normal)'],
h3: ['var(--fs-h3)', 'var(--lh-min-normal)'],
h4: ['var(--fs-h4)', 'var(--lh-min-normal)'],
h5: ['var(--fs-h5)', 'var(--lh-min-normal)'],
h3: ['var(--fs-h3)', '1.4'],
h4: ['var(--fs-h4)', '1.44'],
h5: ['var(--fs-h5)', '1.5'],
p1: ['var(--fs-p1)', 'var(--lh-relaxed)'],
p2: ['var(--fs-p2)', 'var(--lh-relaxed)'],
p3: ['var(--fs-p3)', 'var(--lh-relaxed)'],
Expand Down