Pattern page width (scaling live preview)

[jesstelford]

(forked from #7948): "Narrow page with to match figma prototype"

tl;dr: There's a mismatch between the page sizes used in Figma vs the actual website which have significant impact on how examples render.

The final rendered width of an example on a detail page on the docs site has a bunch of inputs:

1. The main column (including ToC) has a max width of 1240px (including 128px of padding, so content can only be 1112px).
2. The nav column has a hard-coded width of 288px*.
3. The Table of Contents (ToC) has a hard-coded width of 336px**. The ToC can be disabled on a per-page basis with showTOC: true/false
4. What breakpoint currently matches? This effects visibility of both the nav and the ToC.
5. The examples have a 1px border + 64px of padding.

^{* Including the padding
** Including the padding and gap separating it from the main column}

To put it a different way, let's list out all the possible widths with the relevant breakpoints to determine how wide the content area can ever be:

With showTOC: true

Screen width	Content width	Example render width
hitting the max-width: 1240px ie; >= 1528	1240[maxw] - 128[pad] - 336[toc] = 776px	776 - 64[pad] - 2[border] = 710px
thinnest before ToC media query ie; > 1400	1401[scr] - 288[nav] - 128[pad] - 336[toc] = 649px	649 - 64[pad] - 2[border] = 583px

With showTOC: false

Screen width	Content width	Example render width
hitting the max-width: 1240px ie; >= 1528	1240[maxw] - 128[pad] = 1112px	1112 - 64[pad] - 2[border] = 1046px
thinnest before ToC media query ie; > 1400	1401[scr] - 288[nav] - 128[pad] = 985px	985 - 64[pad] - 2[border] = 919px

ToC always hidden by media query

Screen width	Content width	Example render width
ToC hidden by media query ie; = 1400	1400[scr] - 288[nav] - 128[pad] = 984px	984 - 64[pad] - 2[border] = 918px
thinnest while nav still visible ie; > 769	769[scr] - 288[nav] - 128[pad] = 353px	353 - 64[pad] - 2[border] = 287px
Nav hidden by media query ie; = 768	768[scr] - 128[pad] = 640px	640 - 64[pad] - 2[border] = 574px

The Figma designs are currently using a screen resolution of 1540px, which puts them firmly in the "hitting the max-width: 1240px" row, BUT... it uses different padding:

This padding is defined site-wide, so couldn't/shouldn't be changed without serious consideration and work.

Another thing to consider is how the site behaves on common screen widths. Interestingly, on my personal 13" MacBook Air, the ToC is automatically hidden (because the screen is slightly smaller), which results in more physical space for the text and demo, making it a better experience using the docs site!

It also means that on my 14" with ToC open, the live code preview width is thinner, pushing it just under the threshold for a smaller breakpoint size, meaning on my 14" I see a different (mobile) rendered preview than I do on my 13" (tablet) 😱
See these photos of the laptops side-by-side (13" in front, 14" behind).

One final point is thinking about how the rendered examples behave with respect to breakpoints: anything above our two smallest breakpoints (320px & 490px) will never be fully visible without horizontally scrolling (the next breakpoint up is 768px - never visible when the ToC is rendered above 1400px).

Suggested actions

1. Update the Figma designs to use the correct padding
2. Consider the above tables of information with respect to how much width each example has to render when the ToC is visible / at different screen sizes

[SeanyB]

on my 14" with ToC open, the live code preview width is thinner, pushing it just under the threshold for a smaller breakpoint size, meaning on my 14" I see a different (mobile) rendered preview than I do on my 13".

I think this is the main crux of the decision around the page width and ToC. As we have patterns with large UX examples (e.g. Settings page layout), we should definitely be able to show a representative desktop UI, not a mobile responsive one, in our live code preview.

[SeanyB]

The issue that raised my concern that the Pattern details page on staging was too wide is the size of the Useful to know images, relative to the rest of the page content - especially the annotations to the left of them.

Given that these are usually zoomed-in portions of UI, I think we need these to be smaller.

However, we could come up with a UX that makes these smaller without it being directly linked to the overall page width.

[jesstelford]

Definitely need to work on that - the images are gigantic! 😅 Let's shift that discussion back to the original issue to flesh out the details.

[SeanyB]

I'd like to hold off on changing page widths or ToC behaviour in the Patterns pages for now (unless a change is needed to align them with the rest of the Polaris site).

These sorts of changes need to be made across our documentation consistently, and that means bringing Component and other documentation into designing a better experience. I don't think we should do this in the context of the Patterns project. We may have larger site-wide documentation changes in the future and we should include this as consideration into it.

[jesstelford]

I've reverted all custom padding & widths on the Patterns page to match the rest of the pages on Polaris docs: #7994

This has re-introduced the issue of rendering the Tablet breakpoint in our live code example.

From #7938:

At the moment (likely due to the re-addition of the TOC) the example width on the pattern page is an awkward 758px (just below small desktop screen size), so we get this awkward large tablet look.

[johanstromqvist]

Moving a conversation here from #7938

👉 The problem is that the content width forces live previews to default to tablet size and desktop width can only be seen in the sandbox.

My comment from the other issue:

The whole [App settings layout] pattern page is focused on a two column layout, which makes defaulting to a single-column tablet width in the preview problematic. It reveals a bigger root problem which is our general desktop-first focus in both product and product documentation. That root problem is too big for us to solve right now, so I'm wondering if there's a way to show a small desktop view despite the lack of available width.

• Could we perhaps adjust the scale in the iframe?
• Or potentially have a fixed width inside the frame and have overflow-x scrollable?

Not sure how it would affect DX, but could be worth looking into if the fixes are feasible.

Pinging @martenbjork because this topic may have been considered in the component previews.

Here are a few scrappy visualizations:

1. Fixed zoom level
2. User choose zoom level (like chrome inspector)
3. Fixed width div inside iframe, and scrollable overflow

Just exploring options. Happy to hear if there are any smarter solutions out there?

[martenbjork]

Pinging @martenbjork because this topic may have been considered in the component previews.

I've been considering the same solution as you! :) Users can select zoom level, just like in Chrome's dev tools. We then use a transform: scale(n) to adjust the scale of the previewed page.

[SeanyB]

My long-term suggestion (not well researched) would be to widen the default page width of our Polaris documentation so that UI renderings always get the admin's "normal width" size. Essentially, the subject of our UI documentation should dictate the space that we allocate for rendering it.

In the short-term, I'd prefer either option 1 (fixed zoom that we decide) or option 2 (variable zoom, with us making a default choice per pattern/component). The scrolling behaviour feels clunkier.