addon-docs: "escape-hatch" styling for MDX Blocks in DocPages #8502

mcpatten · 2019-10-21T17:01:48Z

Is your feature request related to a problem? Please describe.
It is difficult to customize MDX/DocPage stories using the @storybook/theming setup [v5.2.4]. Customizing individual blocks is difficult, as they only render with minified/hashed css classnames.

Describe the solution you'd like
An intermediary solution similar to #8061 would be great in the short term.

Describe alternatives you've considered
Updating the ThemeVars interface seems like the more appropriate long-term solution, but I imagine this would be more complex of a change that could take a while to ship.

If you do have plans for an update on the theming implementation, it would be great to have something to work with in the meantime.

Are you able to assist bring the feature to reality?
With the appropriate guidance/support.

The text was updated successfully, but these errors were encountered:

github-actions · 2019-10-21T23:37:19Z

Automention: Hey @ndelangen @patricklafrance, you've been tagged! Can you give a hand here?

shilman · 2019-10-21T23:37:52Z

This was an oversight in our escape hatching. Should be pretty easy to add -- anybody want to pick it up? cc @domyen

domyen · 2019-10-22T15:20:32Z

👍I support adding CSS escape hatches for further theming. A naming scheme like
className="sbdocs sbdocs-<docBlockName>" would be appropriate.

Jeremie-Chauvel · 2020-07-22T12:28:10Z

Interested in tackling this issue, I will look into it

Jeremie-Chauvel · 2020-07-30T11:57:11Z

Hi @shilman
I was able to cover most component with the exception of <Props>, the lib/components/src/blocks/PropsTable/PropsTable.tsx being difficult to update correctly.

That said, being unable to use yarn dev without running into the error Error: EMFILE: too many open files, makes for a long time debugging using yarn bootstrap --core + yarn start.

If I find how to reliably have a dev server for --core on storybook v5, I will wrap up the pr, else I can push part of the solution.

shilman · 2020-07-30T13:25:39Z

Hi @Jeremie-Chauvel that's great news! You should base off next which is v6. If you have that, you can run:

yarn build components addon-docs --watch

And it should be much more efficient than yarn dev thanks to @yannbf. If you edit other packages you can just add them to the list.

timbomckay · 2021-08-16T21:44:35Z

It seems like the escape hatches require additional specificity due to the current cascade in the <head>.

As of version 6.3.1, our custom styles (main.123abc.css) are imported before the storybook component styles.

<link href="main.123abc.css" rel="stylesheet">
<style>#root[hidden], #docs-root[hidden] {
        display: none !important;
}</style>
<style data-emotion="css-global">
  html.os-html,html.os-html > .os-host {
    display:block;
    ...
  }
</style>
<style data-emotion="css-global"></style>
<style data-emotion="css-global"></style>
<style data-emotion="css-global"></style>
<style data-emotion="css-global"></style>
<style data-emotion="css-global"></style>
...

Our preview.js file imports styles.scss where our component & utility classes are provided. We're also wrapping any custom sbdocs styles like so for the specificity concern.

.sbdocs {
  // doubling up to compile .sbdocs.sbdocs-content
  // this increases the specificity since Storybook Docs styles lower in the cascade
  &.sbdocs {
    &-content {
      max-width: 84ch;
    }
  }
  ...
}

It seems like all elements have storybook classes assigned because even a <span> won't allow me to assign utility classes. Same with paragraphs via:

/* Storybook Docs Paragraph Styles */
.css-19sr785 {
    font-family: "Nunito Sans",-apple-system,".SFNSText-Regular","San Francisco",BlinkMacSystemFont,"Segoe UI","Helvetica Neue",Helvetica,Arial,sans-serif;
    font-size: 16px; /* First font-size declaration */
    margin: 0;
    -webkit-font-smoothing: antialiased;
    -moz-osx-font-smoothing: grayscale;
    -webkit-tap-highlight-color: rgba(0,0,0,0);
    -webkit-overflow-scrolling: touch;
    margin: 16px 0;
    font-size: 14px; /* Second font-size declaration, overwriting the one above */
    line-height: 24px;
    color: #15191b;
}

Is there a way to ensure our custom styles load at the bottom of <head> or top of <body> to respect our styles in the cascade without increasing specificity? Such as:

<style>#root[hidden], #docs-root[hidden] {
        display: none !important;
}</style>
<style data-emotion="css-global"></style>
<style data-emotion="css-global"></style>
...
<link href="main.123abc.css" rel="stylesheet">

This would allow us to easily assign a utility class without increasing its specificity. Such as updating the background:

<Preview className="bg-blue">
  ...
</Preview>

Note: I do realize Preview will allow us to use utility classes without the extra specificity, but we don't always want the bordered, preview section, or the code snippet displayed, and we don't use react so the markup is incorrect with className="" instead of class="". We get an error if we simply use class, though it does work ¯_(ツ)_/¯.

Is this by design? To require us to provide .sbdocs in front of the desired escape hatch? If so, it might be necessary to specify so in the documentation. Though I'd say this increased specificity requirement contradicts "The Storybook theme API is narrow by design" statement as mentioned in the escape hatches documentation.

Please let me know if I'm missing something, if there's a configuration setting I'm missing to correct the cascade structure. Hoping this is just an oversight on one of our ends.

Thanks

domyen · 2021-08-18T23:13:32Z

Not sure why your previous implementation doesn't work with 6.3.1 e.g., .sbdocs.sbdocs-h1. I'm not aware of any changes to how the DOM elements render in Docs in this release. Emotion doesn't override the styles provided in your CSS files, and increased specificity will override any less specific styles by virtue of the cascade.

timbomckay · 2021-08-19T00:48:06Z

Emotion definitely overrides our styles provided in the CSS, and increased specificity overrides less specific selectors despite the cascade. The current implementation of increased specificity (.sbdocs.sbdocs-h1) is working where defined but it prevents the simple application of a utility class without being duplicated or nested within .sbdocs.

My interpretation of "narrow by design" was assuming you trusted in the power of the cascade by importing our custom css after Storybook's, allowing the cascade to be respected first. However, this isn't the case as previously noted, thus returning to the age old game of specificity wars.

With the current CSS structure:

<link href="main.123abc.css" rel="stylesheet">
<style data-emotion="css-global"></style>
<style data-emotion="css-global"></style>
...

the cascade would be similar to:

// Custom CSS loaded first via main.css 
.sbdocs.sbdocs-h1 {
  font-size: 123px;
}

// Emotion CSS inserted last
.css-abc123 { // equivalent to sbdocs-h1
  font-size: 321px;
}

The custom CSS selector (.sbdocs.sbdocs-h1) is respected because it has higher specificity, not because it's lower in the cascade. If you were to swap the import/insertion order it'd reduce the increased specificity requirement.

// Emotion CSS inserted first
.css-abc123 { // equivalent to sbdocs-h1
  font-size: 321px;
}

// Custom CSS loaded last via main.css 
.sbdocs-h1 {
  font-size: 123px;
}

If the official position is to require increasing specificity then "narrow by design" is meaningless in my opinion. You're still having to determine amount of specificity, whether it's two classes or eight. It's fine if it is your standard but I'd recommend updating the documentation for more clarity and understand it causes the cascade to favor Emotion/Storybook and not our custom CSS.

domyen · 2021-08-19T14:28:15Z

Got it, thanks for the clarification. This is how it's intended to work.

As for specificity and the interpretation of "narrow by design", the official theme API is narrow by design. It has few properties you can customize (intentionally). Why? Every new property adds maintenance cost that prevents us from shipping features and fixing bugs.

CSS escape hatches are not a part of the theme API. Which is why they're called "escape hatches" and have a "use at your own risk" message in the docs. Our intention is to provide other unofficial ways to customize that are outside of the official theme API. But even this level of customization and ergonomics might not be suitable for everyone (perhaps that's the case here).

If you're looking for a fully custom docs site, I'd recommend using a static site generator like Gatsby, Nuxt, Hexo, etc and importing/embedding stories there. That offers ultimate flexibility and fine-grained control over when things load and where, the tradeoff is you have to maintain it yourself.

Thanks for the docs suggestion. Would you submit a PR with what you'd like to see?

shilman added addon: docs theming labels Oct 21, 2019

shilman added this to the 5.3.0 milestone Oct 21, 2019

shilman added help wanted good first issue bug labels Oct 21, 2019

shilman modified the milestones: 5.3.0, 5.3.x Jan 11, 2020

shilman removed this from the 5.3.x milestone Jul 30, 2020

Jeremie-Chauvel mentioned this issue Aug 3, 2020

Addon-docs: add escape hatch css classes in docpages #11775

Closed

timbomckay mentioned this issue Aug 17, 2021

Emotion CSS overriding element styles in MDX Preview #10817

Closed

ndelangen closed this as completed Jan 17, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

addon-docs: "escape-hatch" styling for MDX Blocks in DocPages #8502

addon-docs: "escape-hatch" styling for MDX Blocks in DocPages #8502

mcpatten commented Oct 21, 2019 •

edited

Loading

github-actions bot commented Oct 21, 2019 •

edited

Loading

shilman commented Oct 21, 2019

domyen commented Oct 22, 2019

Jeremie-Chauvel commented Jul 22, 2020

Jeremie-Chauvel commented Jul 30, 2020

shilman commented Jul 30, 2020 •

edited

Loading

timbomckay commented Aug 16, 2021

domyen commented Aug 18, 2021

timbomckay commented Aug 19, 2021 •

edited

Loading

domyen commented Aug 19, 2021

addon-docs: "escape-hatch" styling for MDX Blocks in DocPages #8502

addon-docs: "escape-hatch" styling for MDX Blocks in DocPages #8502

Comments

mcpatten commented Oct 21, 2019 • edited Loading

github-actions bot commented Oct 21, 2019 • edited Loading

shilman commented Oct 21, 2019

domyen commented Oct 22, 2019

Jeremie-Chauvel commented Jul 22, 2020

Jeremie-Chauvel commented Jul 30, 2020

shilman commented Jul 30, 2020 • edited Loading

timbomckay commented Aug 16, 2021

domyen commented Aug 18, 2021

timbomckay commented Aug 19, 2021 • edited Loading

domyen commented Aug 19, 2021

mcpatten commented Oct 21, 2019 •

edited

Loading

github-actions bot commented Oct 21, 2019 •

edited

Loading

shilman commented Jul 30, 2020 •

edited

Loading

timbomckay commented Aug 19, 2021 •

edited

Loading