Stop the docs chrome running off a narrow screen

Andrew Dunnrequested to merge
docs/chrome-phone-fixes-r2 into main

What does this MR do and why?

I want the docs chrome to fit a phone and a tablet, because at a 390px viewport every page of the reference measured wider than the screen, from 721px to 1010px the header nav ran past its box, and the heading an anchor names sat under the sticky header. Consumer sites carry local patches for the nav and the tables. The fixes are in design/chrome/docs/, plus one grid in the compliance page. What changes at each width:

Viewport Header Nav Tables Inline code
720px and below static, --header-h 0 own row, links wrap (flex-basis: 100%) scroll in their own box overflow-wrap: anywhere
721px to 1151px sticky, 57px, one row scrolls sideways in its own box, 6rem scroll-padding-inline, 2rem fade at the edge that hides links as before overflow-wrap: break-word
1152px and up as before as before as before overflow-wrap: break-word
  • Nav. On main the 720px block set width: 100% beside flex: 1, and the 0 flex basis outranks the width, so the nav sat between the brand and the actions with its links clipped; at 721px to 1151px the reference's eight links ran past their box and over the actions. Below 721px it now takes flex-basis: 100%. From 721px to 1151px it keeps its row and scrolls inside its own box, the scroll-padding-inline makes tabbing to a link in the cut-off end scroll it into view, and the padding with a matching negative margin keeps the focus ring inside the box.
  • Fade. A scroll-driven animation on the nav's own inline scroll timeline sizes a 2rem mask gradient through two registered lengths: the trailing edge fades while links are hidden past it, the leading edge fades once the reader has scrolled away from the start. A nav that does not overflow has an inactive timeline, so its lengths stay 0px and its pixels do not change. It sits in @supports (animation-timeline: scroll()), so a browser without it shows no fade. No script, button or markup.
  • Grid and tables. The 900px collapse set the grid to 1fr and the wide layout 240px 1fr; the minimum of 1fr is the content, so one wide table or one unbroken line of code set the column wider than the viewport. Both are minmax(0, 1fr). Neither site wraps a table: the reference renders standards through marked with no table renderer, and the docs template writes each <table> in its pages. So at 720px and below a bare table.standards-table, .token-table or article table is display: block; overflow-x: auto. The compliance matrix is left out because .compliance-scroll already holds it. Chromium reports the same table, row, cell and header roles for the block-level table and reaches it with Tab; Safari was not tested.
  • Inline code and stats. :not(pre) > code wraps a long unbroken string such as the renovate standard's 219-character regex, and a pre keeps its own scroll. The compliance page's four-column stat grid becomes repeat(auto-fit, minmax(8rem, 1fr)) so it stops at the viewport.
  • Anchors. Headings, details and figure with an id take scroll-margin-top: calc(var(--header-h) + 1.5rem), and tokens.css sets --header-h to 57px, the 56px .header-inner minimum plus its 1px rule. This replaces .md-heading:target { scroll-margin-top: 5rem }, which named one class and a literal; at 1280px the landing offset is 81px where it was 80px.

References

design/chrome/docs/chrome.css lines 42, 296-325, 336, 424 and 457; design/chrome/docs/tokens.css line 90; site/src/pages/compliance/index.astro line 441.

Standards affected

None. standards/design asserts neither the header nor table behavior, and no assertion, tier or status changes.

Exemption implications

None.

Test plan

  • just ship passes: 21 standard(s) passed, 0 exempt, 0 failed.

  • Built the reference site and the docs template with its placeholders filled and its chrome links pointed at the working tree. Loaded every page in an iframe at each width and read document.documentElement.scrollWidth. Pages wider than the viewport, main to this branch, and the header's height where it is sticky:

    Viewport Reference (61 pages) Template (7 pages) Header
    390px 61 to 0 3 to 0 static
    720px 27 to 0 1 to 0 static
    721px 61 to 0 1 to 0 57px, one row
    800px 61 to 0 1 to 0 57px, one row
    1010px 61 to 0 1 to 0 57px, one row
    1151px 7 to 0 0 to 0 57px, one row
    1152px 7 to 0 0 to 0 57px, one row
    1280px 1 to 0 0 to 0 57px, one row

    The widest page on main was standards/renovate/, 1853px at 390px and 2133px at 1010px.

  • Fade, read from the computed --fade-start and --fade-end on the reference as the nav scrolls. At 721px and 800px the nav starts at 0px and 32px, holds 32px and 32px from 32px of scroll, and ends at 32px and 0px. At 1010px the range is 149px and the values are the same. At 1151px only 8px of nav is hidden, so the fades are 8px or less. The renders show "Principles" fading at 721px and "Doctrine" at 800px, and "Templates" fading on the leading edge once the nav is scrolled to its end.

  • At 721px, 1010px and 1151px all eight nav links take focus from Tab and end inside the nav box, with the focus ring inside the box and the link clear of both fades.

  • The docs template filled with a short name has three links that fit the row. Against the previous revision of this branch, without the fade, all 7 pages are byte for byte the same at 721px, 1010px and 1151px. Against main, all 7 are the same at 1151px and 6 at 721px and 1010px; reference/example/ differs because on main its code block pushed the content column past its track, 725px wide at 721px and a 705px column against 690px at 1010px.

  • At 1280px, 13 of 14 sampled reference pages render byte for byte the same as on main; the 14th, standards/renovate/, was 2133px wide.

  • After an anchor jump the heading lands 81px below the top at 1280px, under the 57px header, and 24px below it at 720px and below, where the header has scrolled away.

  • Exhibits that link this chrome unpinned. exhibits/bulkhead at 3cbe1d89ef72, built locally with the chrome swapped, pages over the viewport out of 4: 390px 4 to 0, 768px 1 to 0, 1010px 2 to 0. exhibits/the-firebreak at 280181ccb081, which carries its own override for this defect, renders the same 11 pages byte for byte with and without this chrome at 390px, 768px and 1010px, and none is over the viewport.

  • Not tested: Safari with a block-level table, and any browser without animation-timeline, where the nav scrolls with no fade.

An AI tool wrote this change and ran the checks above.

Merge request reports