Skip to content

feat: small screens and muted-label contrast - #10

Merged
jamesbeedy merged 2 commits into
mainfrom
feat/small-screens
Sep 10, 2026
Merged

jamesbeedy merged 2 commits into
mainfrom
feat/small-screens

Conversation

@wardbryan3

Copy link
Copy Markdown
Contributor

Summary

Two commits, both from the vantage-docs phone and tablet audit (vantagecompute/vantage-docs#136 carries the site-side overrides that this replaces).

fix(css): muted labels and hints clear the text contrast floor

--ink-400 is the ramp's fixed point, #6b7494 in both modes. Measured as text it is 4.46:1 on the light page, 4.24:1 on a light ink-50 surface and 3.68 to 4.10:1 on every dark surface, all under 4.5:1. Every muted label moves to --ink-500 (mirrored per mode, 6.6:1 or better everywhere): sidebar section labels, the TOC label, breadcrumb links, pagination sublabels, guide meta labels, and DocSearch's muted colour, footer labels, key hints and hit-source text. --ink-400 stays for decoration and takes over list markers, which at ink-300 were 2.5:1. The search pill's keyboard hint goes from 70% to 85% white (3.91:1 to 5.1:1). The tokens page documents the numbers.

feat: small screens, from 375px phones to 1199px tablets

  • Search below 1200 is a bare 44px magnifying glass matching a site's Ask AI sparkle. The old 800px icon-only rule lost on specificity to the base rule and never applied; below 997 Docusaurus parks the search container at the right edge, so the 400px pill hung 185px off screen on every phone and tablet page.
  • The logo is no longer hidden at 1024 and below; the lone version badge is hidden where it sat beside the hamburger; the Ask AI item is no longer hidden at 1050.
  • Markdown tables render inside a scroll region via a new MDXComponents override (TableScroll), instead of squeezing to 61px columns on a phone.
  • Tab strips wrap; pagination stacks below 600; the drawer is capped at 360px; hamburger, drawer close, sidebar rows, breadcrumb links and the TOC toggle reach 44px.
  • 997 to 1199: 260px sidebar and the collapsible TOC instead of the right column, so a 1024 tablet gets a 723px article instead of 505 and titles stop wrapping letter by letter.
  • Full-screen search modal on phones: no radius, 16px input (no iOS zoom), 44px Cancel.
  • Dead body.chat-open push rules removed.
  • MIGRATION.md Part 3 lists what a site that fixed these itself must delete, the table wrapper first.

Notes for the release

  • The migration text and docs call this 0.4.9; package.json is not bumped here, following the repo's separate release: commits.
  • A site that already wraps table in its own MDXComponents will wrap every table twice once this ships. vantage-docs has a follow-up PR ready that deletes its wrapper and overrides behind ^0.4.9.

Test plan

  • Overlaid this working tree into vantage-docs's installed package with the site's own overrides disabled; measured at 375, 1024 and 1280: bare 44px search icon beside the 44px sparkle, logo 28px, 8 tables in 8 theme wrappers with 42px rows, muted labels computing to ink-500, band rules active at 1024, desktop layout intact at 1280
  • WCAG ratios computed for every text and UI token pairing in both modes (script in the PR conversation on request)
  • Reviewer: just docs-build after release, and a look at a reference page on a phone

🤖 Generated with Claude Code

Bryan Ward added 2 commits September 9, 2026 12:15
ink-400 is the ramp's fixed point, #6b7494 in both modes. As text it measures 4.46:1 on the light page, 4.24:1 on a light ink-50 surface and 3.68 to 4.10:1 on every dark surface, all under WCAG's 4.5:1 floor. Every muted label moves to ink-500, which is mirrored per mode and clears 6.6:1 everywhere: sidebar section labels, the TOC label, breadcrumb links, pagination sublabels, guide meta labels, and DocSearch's muted colour, footer labels, key hints and hit-source text. ink-400 stays for decoration only and takes over the list markers, which at ink-300 were 2.5:1 against the page. The search pill's keyboard hint goes from 70% to 85% white, 3.91:1 to 5.1:1 on its doubly tinted background. The tokens page documents the numbers.
Below 1200 the search control is a bare 44px magnifying glass matching a site's Ask AI sparkle: the theme's icon-only rule at 800px lost on specificity to its own base rule and never applied, and below 997 Docusaurus parks the search container at the right edge, so the 400px pill hung 185px off screen on every phone and tablet page. The logo is no longer hidden at 1024 and below, the lone version badge is hidden where it sat beside the hamburger, and the Ask AI item is no longer hidden at 1050.

Markdown tables render inside a scroll region (a new MDXComponents override) instead of squeezing to 61px columns; tab strips wrap so every tab is visible; pagination stacks below 600; the drawer is capped at 360px; hamburger, drawer close, sidebar rows, breadcrumb links and the TOC toggle reach touch size. Between 997 and 1199 the sidebar is 260px and the right-hand TOC column gives way to the collapsible one, so a 1024 tablet gets a 723px article instead of 505. The full-screen search modal on phones loses its radius and gets a 16px input. Heading margins tighten below 600. The dead chat-open push rules are gone.

MIGRATION.md Part 3 lists what a site that fixed these itself must delete, the table wrapper first, or every table renders in two scroll regions.

@jamesbeedy jamesbeedy left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1

@jamesbeedy jamesbeedy left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1

@jamesbeedy
jamesbeedy merged commit 52ce37c into main Sep 10, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants