Docs site theme switching & live token modification #1785

forrestbaer · 2022-05-02T16:05:28Z

forrestbaer
May 2, 2022
Maintainer

Did some more thinking on theme switching and theme modification from within the upcoming Gatsby doc site. Let me know what you think, is this valuable? I wanted to get ahead of the request if it might be forthcoming at some point.

For both options:

Export sass with css references to themselves from tokens:
```
  $token-reference: var(--token_reference);
  ...
```
Import typescript theme file directly with gatsby-source-filesystem and transform keys to css variables:
```
themes: {
  themeName: {
    '--token_reference': 'token_value',
    ...
  }
}
```
Create the :root {} css descriptor at build time with Gatsby store of current theme (core, unified??, etc..) using GraphQL, each theme would have it's own data-theme reference to make switching themes as easy as updating the html element with the new data attribute.

For live theme modification

Init function pushes the themedata to localstorage on reset theme, reset variable or first view
Notify user local storage is required to mess with theme modification
A couple options for how to then structure the page
- Make a button under the component listing that pulls all css vars out of the css of the rendered element and parses them into a temporary object which will update the localstorage reference when modified, this way each component could be modified in-page and with a popup or drawer including inputs for each theme item. quite a bit of work likely but a really nice effect as only the current component would be modified.
- Create a single page which pulls all theme variables from localstorage, assign all values to a dropdown or several inputs similar to the bootstrap page here, thanks Sarah :) on change/save, write modified values to local storage and refresh values that changed. Refreshing could be a matter of setting a hook for themeModified to override updated variables when they have changed.
Write an exporter to write current localstorage theme variables to new TS theme file.

For switching pre-defined themes / dark mode

Switching themes would be easy, just a matter of updating the current <html data-theme="themeName"> attribute, if there is no need to modify the current styles, localstorage wouldn't be needed.

zarahzachz · 2022-05-05T19:31:26Z

zarahzachz
May 5, 2022
Maintainer

I like this! CSS properties are incredibly flexible, so I love seeing them come into play here!

I'm partial to the one-pager Bootstrap idea myself, but also wonder how complex our theming will actually get. If we're just focusing on colors, maybe something as simple as allowing users to input a palette of colors and us mapping those colors (with us adjusting saturation and lightness as needed) to the site is an appropriate solution? Not sure how complex that would get though... 😵

Also, supporting light/dark mode might be a simpler than outright theming (at least when it comes to implementation).

You can do this with a meta tag in the HTML, a media query, or applying color-scheme to :root.

I think these rules automatically adhere to the OS color scheme settings, but need to explore that.

3 replies

forrestbaer May 6, 2022
Maintainer Author

Interesting I didn't know about color-scheme or it's availability as a media query.. good to know and thanks for the feedback!

zarahzachz May 6, 2022
Maintainer

Adam Argyle has a good theming example using his version of design tokens for reference (it's under "4 Color Schemes").

pwolfert May 12, 2022
Maintainer

😮 whoa, that open-props.style library is pretty cool

pwolfert · 2022-05-13T22:58:55Z

pwolfert
May 13, 2022
Maintainer

If I understand this correctly, we will export a special kind of theme SCSS file from our token exporter that will look something like

$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);

Then we will import into our doc site the full suite of design-system styles that make use of these variables, like we are doing here. (We wouldn't be importing it from a child design system. We'd always import from the core package because it happens once at build time for our one unified doc site.)

We then we will also use our token exporter to generate three CSS files that define the actual values for those CSS vars but under specific selectors, like

/* core-vars.css */
[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;
}

/* healthcare-vars.css */
[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;
}

/* medicare-vars.css */
/* ...etc */

And load them all into the document?

(Or possibly that first selector is more like :root { ... } because it is the default?)

If I'm in the ballpark about how we'd be doing theme switching (with selectors), the only thing I can think of that this wouldn't handle is the brand-specific CSS that exists in places like https://github.com/CMSgov/design-system/blob/master/packages/ds-healthcare-gov/src/styles/components/_Logo.scss. We could import these files directly into Gatsby since each brand shouldn't be using rules that conflict with each other, but that feels like a lot of manual work.

17 replies

pwolfert May 18, 2022
Maintainer

But if we include it in our doc site under patterns, it still does exist in our codebase somewhere. Why not make it consumable?

line47 May 18, 2022

We certainly could. I wonder where we draw the line on micro components? How might we decide to make a micro component instead of using the props of a pre-existing component? I don't have the answer and am thinking about future use cases...

forrestbaer May 18, 2022
Maintainer Author

pwolfert May 18, 2022
Maintainer

An alternative to a component that would still capture this content in the design system package would be to ask users to access it through our translation function. It'd be something like

<HelpDrawer
  footerTitle={t('healthcare.drawer.footerTitle')}
  footerBody={t('healthcare.drawer.footerBody')}
  ...

babsdenney May 19, 2022

I like idea E as well and the mini component idea is good too. It seems similar to discussions I've seen on slack about adding more form fields that are pattern specific.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs site theme switching & live token modification #1785

{{title}}

Replies: 2 comments 20 replies

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{title}}

{{title}}

Select a reply

Docs site theme switching & live token modification #1785

forrestbaer May 2, 2022 Maintainer

For both options:

For live theme modification

For switching pre-defined themes / dark mode

Replies: 2 comments · 20 replies

zarahzachz May 5, 2022 Maintainer

forrestbaer May 6, 2022 Maintainer Author

zarahzachz May 6, 2022 Maintainer

pwolfert May 12, 2022 Maintainer

pwolfert May 13, 2022 Maintainer

pwolfert May 18, 2022 Maintainer

line47 May 18, 2022

forrestbaer May 18, 2022 Maintainer Author

pwolfert May 18, 2022 Maintainer

babsdenney May 19, 2022

forrestbaer
May 2, 2022
Maintainer

Replies: 2 comments 20 replies

zarahzachz
May 5, 2022
Maintainer

forrestbaer May 6, 2022
Maintainer Author

zarahzachz May 6, 2022
Maintainer

pwolfert May 12, 2022
Maintainer

pwolfert
May 13, 2022
Maintainer

pwolfert May 18, 2022
Maintainer

forrestbaer May 18, 2022
Maintainer Author

pwolfert May 18, 2022
Maintainer