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.

[johanstromqvist]

Ah, that parity is clever Sean! I'll make a separate issue for the backlog.

Let's roll with popular option 2 then! Does that make sense for you @jesstelford? And is this is the only outstanding task in this issue?

[jesstelford]

Zooming could work - I'd have to double check how that interacts with the iframe, but I'm sure we could figure something out.

with us making a default choice per pattern/component

This option comes with the side-effect of inconsistencies across patterns. Ie; a user might copy-paste a pattern that's 100%, and everything looks good. Then they copy-paste a pattern that's 80% without realizing it was zoomed, and now their codebase looks different to the pattern, and unless they happen to know / see the "zoom" option, they're possibly going to spin off chasing a red herring rabbit hole (what a mix of metaphors!) wondering why their code makes everything look so much bigger than the examples on the website.

And none of this takes into account if the user has a smaller laptop (see my 13" vs 14" image), or have resized their browser window for whatever unrelated reasons...

---

If I were to take a step back, I'd describe our core challenge as: the user doesn't know what breakpoint they are viewing.

With that in mind, I think it's more important that we convey the currently rendered breakpoint instead of allowing a zoom system. The user can then experiment with making their window thinner to see mobile breakpoints which is nice.

The only problem we're left with is handling thinner screens and trying to see breakpoints that are larger than their screen can fit.

This can be broken into two categories IMO:

1. The width of the content column isn't wide enough.
   • Fix: Have an "expand" option to make the example container wider than the column.
2. The width of the screen isn't wide enough (ie; even clicking "expand" isn't enough).
   • Fix: Horizontal scroll.

Tailwind Awesome shows the current breakpoint (without the horizontal scroll) and it works really well!

Here's a hacky attempt at what it might look like in our docs site (click the thumbnail to see the big version):

• Default view shows which breakpoint is currently matching (desktop in this case) with an "expand" button next to it:
  
• A thinner window with the default view shows the tablet breakpoint matches in this case:
  
• Clicking the expand icon pops the preview out into a modal which is (almost) full page width. In this case, it can now show desktop breakpoint even though the page is still thin. At any time, the user can click the "un-expand" button to go back to the default view:
  
• Clicking any of the other breakpoint buttons changes the width of the modal. In this case; mobile width:
  
• Finally, when the page is thinner than the breakpoint the user wants to view, they can click the appropriate button which will trigger a horizontal scrollbar. Here, the page is mobile width, but the preview is expanded and "Desktop" is selected, so there's a horizontal scroll to see it all:
  

[johanstromqvist]

Thanks for the thoughtful breakdown and suggestion @jesstelford! The general direction is interesting. My one concern is if all guidance is focused on desktop width while the live preview defaults to tablet size. For example, in App settings layout we show and discuss the value of a two-column layout, but the live preview would show a single-column layout. That's the one thing that makes a scaling iframe approach appealing to me. From a dev POV, what do you think is the better tradeoff?

Zooming out... The main constraint for a nice long term solution is the narrow container width. We want to fix that in the future, but it's unclear when. We will need a short term solution that makes the page viable, but we don't want to invest in it as if it was a long term solution. In other words, I think it's ok if the MVP is a bit wonky as long as it works ok. With that in mind, would it make sense to choose the solution that is the easiest to build?

Visual example of the desktop + tablet size concern

[johanstromqvist]

I had a sync with @SeanyB and here's our suggested path forward:

Short term
Go with what's easiest to build and has the least implications on the general page experience. Our bet is that this is the zoomable iframe solution. This approach is hacky and does come with UX tradeoffs. We think we can mitigate and accept some of those in the short term, given that we revisit the purpose and design of the site/page/code feature later.

Long term
Revisit this problem when we have learned more about different pattern needs in general and the code feature specifically. When we do revisit it, we should probably address the width of the content column, which is a site-wide root problem, and take a critical look at the nav and ToC. The Tailwind Awesome demo is an amazing reference, and imo the most interesting direction. It's just a matter of timing.

Unless there are any objections, I will close this issue shortly, log the decision, and create a new one speccing what needs to be done. Hope this sounds good. Always open to hear other POVs!

[johanstromqvist]

Closing this and moving the viewport issue to here: #8248