[RFC] Allow styles targeted at individual viewports

[jasonsperske]

Summary

A proposal to add an attribute allowing style properties beyond height/width to be defined on a per-viewport basis.

Problem Statement

In my application, I use Storybook to test components for four different clients. Each client has its own dimensions and global style (in our case, padding and font size impact layout). Currently, Storybook doesn't provide a way to define these viewport styles without targeting all viewports.

Non-goals

This proposal is not seeking to provide a more extensive API to the addon-viewport (this might cover our specific use case but wouldn't scale to others).

Implementation

We would introduce a small bit of code that adds the viewport.id to the outer body element inside the preview iframe with a data attribute named data-storybook-viewport-id. This would allow people to write CSS that targets a specific viewport. Using the viewports that come with Storybook by default, this might look like this:

#storybook-root {
  padding: 12px;
}
body[data-storybook-viewport-id="mobile1"] #storybook-root {
  padding: 8px;
}
body[data-storybook-viewport-id="mobile2"] #storybook-root {
  padding: 16px;
}

By using the viewport ID we maintain consistency with configuration of viewports.

Prior Art

Projects already target the preview viewport in CSS, so this solution feels consistent with that approach (adding just an extra layer of information). Also, the approach is similar to how the addon-viewport implements the height/width settings in

<Global
  styles={{
    [`iframe[data-is-storybook="true"]`]: {
      ...(styles || {
        width: '100%',
        height: '100%',
      }),
    },
  }}
/>

https://github.com/storybookjs/storybook/blob/next/code/addons/viewport/src/Tool.tsx#L203-L210.

Deliverables

1. Add code to code/addons/viewport/src/Tool.tsx to attach data attribute
2. Add documentation to docs/essentials/viewport.md with information how target specific viewports in CSS

Risks

1. The code to modify the iframe's inner body element assumes a specific structure to the preview page. I believe this assumption is safe because all previews will appear inside of iframe elements and those iframe.
2. This code will create targeted styles bound to viewport id. In projects with complex viewports this may add to the complexity by spreading the style properties from the peramaters.viewports

Unresolved Questions

• Is this approach consistent with the overall design of configuring addons
• Is this approach too brittle for future redesigns of the preview view

Alternatives considered / Abandoned Ideas

It is also possible to define the interface of ViewportStyles (found in code/addons/viewport/src/models/Viewport.ts) as like this:

export interface ViewportStyles extends Partial<CSSStyleDeclaration> {}

This would allow all CSS styles to be defined in the parameters. However this would require more downstream changes to support.

[yannbf]

Thank you so much for elaborating this RFC. We are currently working hard on the Storybook 8 beta, so it might take some time to check this in detail, so we appreciate your patience! @cdedreuille would you be interested in leading this since you had ideas regarding the viewports addon?

[cdedreuille]

Thanks @jasonsperske for this RFC. You're touching a subject that I would love to work very soon. One of the restriction we face today is that the viewport is an addon, therefore quite restrictive on how we can transform the iFrame. One thing we could explore is to move this functionality in the manager directly. I would love to explore some ideas after the launch of Storybook 8.

Just to give some perspective, here are the first designs I've done before Christmas.

• Multiple viewports in a single view
• Modify with handles each viewport directly
• Edit sizes manually

[jasonsperske]

That looks really slick! Need any help? I've been reading through the code for the addon and picking up a bit of context

[cdedreuille]

This can't be done on the addon itself. We have bake it inside the manager since addons can't control the iFrame. I'm not sure when this would be prioritised on our side so yes I could use any help I could take to make it happen.

[jasonsperske]

Would a separate RFC for something like a PreviewManager that can spawn and control iframes be a good starting point?

[cdedreuille]

That would be really great indeed @jasonsperske