[DX-1527] Typography and spacing enhancements by m-hulbert · Pull Request #3469 · ably/docs

m-hulbert · 2026-07-13T13:57:57Z

Description

This PR implements some new rules for typography and spacing throughout the docs site. Spacing between components, headings and paragraphs should be consistent now that we are no longer inheriting styles from the marketing site.

Overall:

New type scale and text styles
Improved the vertical rhythm across all content so that the spacing is consistent between components, headings and paragraphs.
Aligned tables, admonitions and images with the new scale and rhythm.
Properly indented code blocks within lists to not break the new rhythm.
Examples content updated to match the new normal where possible.
Fixed an issue identified as part of this to keep the 'show more' code block feature consistent.
Fixed the sizing of the AI Transport icon that was noticed as part of this work.

Checklist

Commits have been rebased.
Linting has been run against the changed file(s).
The PR adheres to the writing style guide and contribution guide.

coderabbitai · 2026-07-13T13:58:07Z

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 79726d42-3bd1-4f9d-a375-7ba8a0351161

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch docs-styling-updates

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

Align heading sizes (h1 32, h2 24, h3 20, h4 18, h5 16px), grid-aligned line-heights and graded letter-spacing with the new docs type scale. Set monospace text to medium weight, add a serif ui-text-sub-head style (adopted by the page header intro), and restyle the inline code chip. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Replace the symmetric heading and paragraph margins with an asymmetric rhythm: a larger top margin separates a heading from the preceding content and a smaller bottom margin sets the gap to the following text. Move body copy from p2 to p1 and give code blocks and images 24px of vertical spacing. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Use 24px vertical spacing for tables and admonitions and set table body text to 15px (p2). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Callout body paragraphs were rendering at p1 (16px) because the MDX paragraph mapping overrode the container's intended size. Force body paragraphs to p3 (14px) in both note and USP callouts, keep the USP headline at p1, and reduce the USP vertical padding. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

A paragraph immediately followed by a heading now sets its bottom margin to zero, so the gap is exactly the heading's own top margin instead of the paragraph margin stacking on top of it. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

umair-ably · 2026-07-21T13:03:52Z

Review: Typography and spacing enhancements

87 files, +1,389/−1,294, in two distinct kinds of change:

Design-system changes (10 files): heading/paragraph type scale, line-heights, letter-spacing, and vertical rhythm (margins) in the React components, CSS, and Tailwind config.
Content re-indentation (77 files): <Code>/code-fence blocks re-indented to 4 spaces so they nest inside list items, plus example README fences moved from 2-space → 4-space.

Verdict: The PR meets its objective and the design-system values are internally consistent. All .mdx and README changes are pure whitespace (git diff -w is empty — zero content/code changes), so the risk is confined to rendering. But the "align the whole site" goal isn't fully carried through — a few pages with the same pattern were left behind.

1. Value consistency — 👍 good

Objects all land on a single 24px (my-6) rhythm — MDXWrapper, Admonition, Table, Pre, and the global.css image rule (--spacing-24) all agree, and the global.css comment's stated heading top-margins (h2 48 / h3 32 / h4 28 / h5 24px) exactly match mt-12/8/7/6.
The heading type scale, line-heights, and letter-spacing are applied consistently across both renderers (MarkdownProvider.tsx for docs pages, examples.tsx for example pages).
ui-text-sub-head is newly centralised and used by both PageHeader and examples.tsx.
Body text bumped p2→p1 consistently in both renderers.
The loose-list CSS fix (.ui-ordered-list li > p) correctly reaches docs pages — MarkdownProvider applies .ui-ordered-list/.ui-unordered-list, and examples.tsx was switched to the same classes + an <article> wrapper so the global.css article … rules also apply.

2. Things missed (the "bring the rest of the site into alignment" gap)

A. .mdx pages with the numbered-list + col-0 <Code> pattern — not migrated:

src/pages/docs/api/rest-api.mdx (lines 150, 159) — has a visible symptom: item 1. → col-0 <Code> → item 2. → col-0 <Code>. The col-0 code breaks the list, so step "2." restarts numbering as "1.". This is the exact bug the PR fixes in the getting-started pages.
src/pages/docs/ai-transport/internals/codec-architecture.mdx (line 128) — same pattern; the code sits after the last step, so no numbering break, but it's inconsistent with the new convention.

B. Example README left on a third indentation style:

examples/pub-sub-live-voting/javascript/README.md — the only tracked example README this PR didn't touch. It uses 3-space fences under its numbered steps, whereas every other example README is now 4-space. Renders acceptably but is exactly the inconsistency this PR is meant to remove.

Not misses (checked and deliberately different): 6 pages have bullet-list + col-0 <Code> (auth/token/jwt.mdx, chat/rooms/history.mdx, liveobjects/concepts/objects.mdx, liveobjects/rest-api-usage.mdx, liveobjects/typing.mdx, livesync/postgres/quickstart.mdx). Unlike the 3 authentication.mdx pages migrated here (where the code is the content of a specific bullet ending in ":"), in these the code is a standalone example following the whole list — correctly left at col-0. I'd leave these alone.

3. One internal contradiction to reconcile

In src/templates/examples.tsx the new comment says:

"README fences are indented 2 spaces, short of the 3 needed to nest"

…but this same PR moves those fences to 4 spaces (verified: 4 leading spaces in the shipped files). Per the comment's own "3 needed to nest" logic, 4-space fences would now nest and the list would not split — which would make the start-prop forwarding it justifies unnecessary. Either the comment is stale (should say 4 spaces) or the start-forwarding is now dead code. Worth re-verifying against markdown-to-jsx's actual behaviour and fixing the comment either way.

Recommendation

Solid PR — the design-system work looks good. Before merge, suggest the author:

Fix rest-api.mdx (real numbering bug) and codec-architecture.mdx.
Align pub-sub-live-voting/javascript/README.md to 4-space.
Correct/verify the examples.tsx "2 spaces" comment.

🤖 Reviewed by Claude Opus 4.8 via Claude Code

umair-ably

Latest commit diffs LGTM

Render code fences nested in example list items with indentation, terminal styling (PlainCodeView), and continuous ordered-list numbering. Reindent the example READMEs so fences nest inside their list item. Normalise paragraph spacing inside list items to the 8px list-item rhythm so loose lists (items with code) match tight lists. Excludes the code-styled-headings CSS, which is kept as a separate change. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Re-indent <Code> blocks that belong to a list step so they nest inside the list item, rendering indented and keeping continuous numbering (matching the examples pages). Standalone code under headings is untouched. Pure indentation change. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Use ui-text-h1 for the example title (32px, matching docs pages) and the serif ui-text-sub-head style for the description, replacing the larger ui-text-title and the sans ui-text-sub-header. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Set the label to semibold, switch the disclosure chevron to the solid heroicon at 12px to match the left-rail chevrons, and let the expanded "Show less" pill sit in its own band (no negative margin) so the code content no longer overlaps and clips the pill's top edge. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

The outline and solid AI Transport glyphs were drawn ~87% scale within a 24x24 viewBox, so the mark rendered smaller and thinner than the other product icons. Re-export both in a 20x20 viewBox so the artwork fills the canvas and the stroke weight matches its neighbours. The outline uses currentColor so it adapts to light/dark and active states. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

m-hulbert self-assigned this Jul 13, 2026

m-hulbert added the review-app Create a Heroku review app label Jul 13, 2026

ably-ci temporarily deployed to ably-docs-docs-styling--d7iagd July 13, 2026 13:58 Inactive

m-hulbert force-pushed the docs-styling-updates branch from a515daa to f1f99af Compare July 13, 2026 15:31

ably-ci temporarily deployed to ably-docs-docs-styling--d7iagd July 13, 2026 15:31 Inactive

m-hulbert changed the title ~~Typography and spacing enhancements~~ [DX-1527] Typography and spacing enhancements Jul 13, 2026

m-hulbert marked this pull request as ready for review July 13, 2026 16:43

m-hulbert force-pushed the docs-styling-updates branch from f1f99af to 1857315 Compare July 20, 2026 09:15

m-hulbert temporarily deployed to ably-docs-docs-styling--cel1mv July 20, 2026 16:40 Inactive

m-hulbert and others added 5 commits July 21, 2026 09:43

Align table and admonition spacing with the new type scale

ac23d26

Use 24px vertical spacing for tables and admonitions and set table body text to 15px (p2). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

m-hulbert force-pushed the docs-styling-updates branch from 1857315 to ccf848a Compare July 21, 2026 08:45

m-hulbert temporarily deployed to ably-docs-docs-styling--cel1mv July 21, 2026 08:45 Inactive

m-hulbert temporarily deployed to ably-docs-docs-styling--cel1mv July 21, 2026 10:23 Inactive

m-hulbert temporarily deployed to ably-docs-docs-styling--cel1mv July 21, 2026 14:05 Inactive

umair-ably approved these changes Jul 21, 2026

View reviewed changes

m-hulbert and others added 5 commits July 21, 2026 15:38

m-hulbert force-pushed the docs-styling-updates branch from e4596a9 to 004637a Compare July 21, 2026 14:39

m-hulbert temporarily deployed to ably-docs-docs-styling--cel1mv July 21, 2026 14:39 Inactive

m-hulbert merged commit 6166191 into main Jul 21, 2026
8 checks passed

m-hulbert deleted the docs-styling-updates branch July 21, 2026 14:59

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[DX-1527] Typography and spacing enhancements#3469

[DX-1527] Typography and spacing enhancements#3469
m-hulbert merged 10 commits into
mainfrom
docs-styling-updates

m-hulbert commented Jul 13, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jul 13, 2026 •

edited

Loading

Review skipped

Uh oh!

umair-ably commented Jul 21, 2026

Uh oh!

umair-ably left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

m-hulbert commented Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Uh oh!

coderabbitai Bot commented Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

umair-ably commented Jul 21, 2026

Review: Typography and spacing enhancements

1. Value consistency — 👍 good

2. Things missed (the "bring the rest of the site into alignment" gap)

3. One internal contradiction to reconcile

Recommendation

Uh oh!

umair-ably left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

m-hulbert commented Jul 13, 2026 •

edited

Loading

coderabbitai Bot commented Jul 13, 2026 •

edited

Loading