Doc site theme switcher

[pwolfert]

Doc site theme switcher

Our new doc site is going to be one doc site with an option to switch between themes rather than separate documentation sites for all three of our primary design systems. This is an exploration of the ways we could implement this theme switcher.

Here is an outline of three general ways our theme switcher could behave and how they'd be implemented:

1. Only the Storybook examples change their theme - This is its own option because it would be simpler to implement. We build three static Storybooks and switch between the instances that our example iframes point to. We wouldn't need to dynamically change any stylesheets in the doc site page
2. All the examples change their theme - This is similar to the first without any of the benefits of simplicity. The only reason we'd go with this one over the third option is if we want the doc site itself to always be a consistent theme for design reasons
3. The whole site theme changes - The whole look and feel of the doc site changes to match the theme that is selected

1. Only storybook examples change

Right now when we build the new doc site, we build a static version of Storybook using the core theme. When we transition to having all three design systems on our doc site, we'll need to build static Storybook instances for all three themes. We are going to need to change where the embedded stories' iframes point to dynamically based on the chosen theme no matter what option we choose, so in this case we'd simply stop there. We might want to change some of our other embedded examples into Storybook stories so they pick up the theming changes, but there wouldn't have to be any dynamic CSS changes for the doc site itself.

2. All the examples change

The difference between this and the first option is that we do dynamically swap the theme of the doc site itself so that the embedded, non-Storybook examples update to match the theme. The difference between this and the third option is that we would actively avoid changing the style of the outer doc site and only target the examples for theme matching with specific CSS selectors. The reason we might go with this one is if we want to maintain a consistent look and feel on the site regardless of which theme is selected.

3. The whole site theme changes

This option requires the dynamic Storybook-instance swapping of the first option plus dynamically changing the CSS rules or the stylesheets applied to the doc site itself in order to make the look and feel match the theme selected.

Dynamically swapping out the styles

This discussion by Forrest outlines how we can use design tokens to dynamically change the theme used in our CSS without activating and deactivating whole stylesheets and without statically building three different versions of our complete design-system CSS. Using this method, we can minimize the total amount of CSS used and downloaded by our site's visitors and also minimize any thrashing that they might otherwise experience while switching themes.

Notes about brand-specific documentation

Some child design systems (brands) have components that are unique to them. While we want to move towards having all components represented in the core design system and minimizing or eliminating brand-unique components, we recognize that there will likely always be brand-specific customizations or implementations of components that need to be documented. The documentation site will always show all available pages of documentation, regardless of which theme is currently active. This will make the experience more intuitive and help us move toward a unified design system by making the brand differences more apparent.

The following is how we've decided to organize the brand-specific documentation in the first iteration of our new doc site's information architecture:

├── Components
│   ├── Alert
│   ├── Footer
│   │   ├── Healthcare.gov
│   │   └── Medicare.gov
│   ├── Text field
│   └── Card (M.gov)
│
├── Patterns

In the organizational pattern above, brand-specific extensions to a component's documentation would exist as sub-pages to that core component page, and brand-unique components would exist in the root of the Components category but with a brand tag next to it.

Conclusion

The best experience will come from options 2 and 3. Option 1 would only be appropriate for a bare-bones MVP. Whether we change the theme of the whole site or restrict it to the examples and tables will come down to a design decision.

[line47]

Interesting implementation here https://nordhealth.design/components/banner/ the theme switcher is next to all interactive component sections and it remembers your selection between pages. This could be an interesting idea 🤔

[pwolfert]

Oh yeah, that's a different idea that we could consider. They've got an interesting drag bar, too, for resizing the iframes.

[pwolfert]

This doc site is full of patterns I haven't seen. Here's another one:

[pwolfert]

Their color tokens page also shows these little markers of different background colors and the contrast against that color. I think that's a pretty neat idea.

[pwolfert]

Doc site theme switcher implementation

Context: The choice we selected from the original discussion post was the third option, where we change the entire theme of the site.

Problem

The intended behavior of the new doc site theme switcher is to change the look-and-feel of the site overall as well as for the examples. This means we will want to implement theme-switching logic at two levels:

1. At the doc-site CSS level
2. At the Storybook-example level

Additionally, the solution must take into account that in the unified site all pages will be viewable at any time, no matter what theme is selected. This means that even if a component only exists in one of the child design systems, its documentation page needs to not crash when one of the other two themes are active.

1. At the doc-site CSS level

The old doc-site generator creates entirely separate instances of the doc site based on the currently selected design-system package (core, healthcare, or medicare). At build time the Sass for that design system is loaded along with the doc-site Sass, and the design-system variables affect the doc-site's look-and-feel. This results in a statically generated CSS file for the doc site that is specific to that design system. Because we now have one doc site for multiple design systems (or themes of the same design system), we must find a way to dynamically change the theme of the site for our users on the client side as they wish.

On the new doc site, there will be a theme dropdown that controls the theme of the site. It needs to be able to change the CSS for the doc site in some way so the site matches the chosen theme. It should also save that preference in the query parameters so sharing links are theme-specific.

2. At the Storybook-example level

The CSS that styles the doc site is separate from the CSS that styles the embedded Storybook examples. We need to also change the Storybook examples dynamically so that they match the chosen theme. This will involve dynamically setting the iframe URLs, whether that is to switch between Storybook instances entirely or to send a theme identifier through query parameters.

Solution

1. At the doc-site CSS level

Based on #1785, we can use CSS vars and our token exporter to dynamically change design token values in our CSS rather than swapping out entire stylesheets.

Our token tooling will be updated to be able to export special token SCSS files for the doc site which replace the literal values of SCSS variables with references to corresponding CSS vars. We will then place the real values for those tokens in a theme-namespaced rules.

To illustrate, the Sass variables would look something like this:

$alert__background-color: var(--alert__background-color);
$alert__background-color--error: var(--alert__background-color--error);
$alert__background-color--lightweight: var(--alert__background-color--lightweight);
$alert__background-color--success: var(--alert__background-color--success);
$alert__background-color--warn: var(--alert__background-color--warn);

And the CSS-var definitions would look something like this:

[data-theme="core"] {
  --alert__background-color: #e6f9fd;
  --alert__background-color--error: #fce8ec;
  --alert__background-color--lightweight: #ffffff;
  --alert__background-color--success: #e7f3e7;
  --alert__background-color--warn: #fef9e9;
}

[data-theme="healthcare"] {
  --alert__background-color: #eaf8fe;
  --alert__background-color--error: #fce8ec;
  --alert__background-color--lightweight: #ffffff;
  --alert__background-color--success: #e7f3e7;
  --alert__background-color--warn: #fef9e9;
}

[data-theme="medicare"] {
  /* ... */
}

In this way, the theme can be switched by changing the data-theme attribute on the root element.

Because we would need to import all styles used in all design systems—without duplicates—we need to cherry-pick the files that we include from the child design systems rather than importing their root index files. The Sass imports might look something like the following:

@import '@cmsgov/design-system/src/styles/index';
@import '@cmsgov/ds-healthcare-gov/src/styles/components/index';
@import '@cmsgov/ds-medicare-gov/src/styles/components/index';

// Load medicare-specific typography overrides, but only apply them if that theme is selected
[data-theme="medicare"] {
  @import '@cmsgov/ds-medicare-gov/src/styles/base/override.typography';
}

In the future, it would be ideal for these design-system-specific style overrides not to exist and for all customization of the core rules to be done through design tokens. That is just not the reality at the moment, however, so our solution must address them.

2. At the Storybook-example level

There are two options for implementing this. One involves modifying our Storybook setup to consolidate our three Storybook instances into one, and the other leaves the Storybook instances alone and simply switches between instances by changing the URL of our example iframes dynamically.

If we go the route of consolidating our Storybook instances and dynamically switching the theme, the dynamic CSS logic will look very similar to the doc-site-level logic. Storybook keeps its global settings in query parameters, so that works perfectly for being able to control it from the URL in an iframe. See the implementation plan for the doc-site-level for details.

It is my recommendation that we try to update our Storybook setup to consolidate into a single instance and fall back to the other solution if it becomes unreasonably difficult.

[pwolfert]

@scheul93 and @forrestbaer, could you look at this rough implementation plan and give feedback? I'd like to start creating tickets about this work

[scheul93]

Only thing that stands out to me is the "consolidate storybook into one instance" I like it in theory but how do brand-specific components work in this consolidated model?

For example, Hgov has an hgov-specific header component. We can have a story for that component that is always present, but when we switch to the mgov theme in storybook, what happens? The component won't be styled correctly (or maybe at all?). What kind of notification or error handling would we need to look into to address components like these?

And for clarity, I'm not worried about showing these brand specific components on the doc site, I'm more concerned if someone follows an "Open in Storybook" link from the doc site and they are navigating around the storybook instance.

[line47]

For example, Hgov has an hgov-specific header component. We can have a story for that component that is always present, but when we switch to the mgov theme in storybook, what happens?

I've been thinking about this a bit and it could work like this. If we have all design system components mapped to theme-tokens and they use something like color-primary then if we switch the theme for the HCgov header to Medicare - we should then see the HCgov header component with the Medicare theme applied.

[ghost]

This all sounds good, regarding the brand specific components, I'm wondering if we should move those stories to a new namespace with their own heading.. so

Components:
Button
etc..

Medicare:
Header
MgovLogo

[scheul93]

Converted this discussion point to Jira tickets 🙂