Playground-local stylesheets

Hey 👋

I’m migrating the docs from Vanilla Form, my form state/validation management library. Currently I’m using Styleguidist, so migrating to Docz is pretty easy as all documentation and examples are already in Markdown.

Background

As the documentation examples are using plain HTML elements, I’ve used Styleguidist’s require configuration option to apply Milligram styles for better-looking components in playground. This basically requires applies Milligram globally in the docs page.

For the Docz migration I followed the same idea, but using the CSS plugin to achieve it. I could make it work and all playground examples now have Milligram styles, but as a side-effect, Docz theme is completely screwed up, as Milligram uses global CSS.

Playground Isolation

I like a lot that both Styleguidist and Docz render playgrounds inline (no funky iframes), even understanding that conflicts ranging from HTML IDs to CSS could happen. On the other hand, I’ve come to believe that having at least styles isolation inside playgrounds is an important thing, because not all libraries are using fancy CSS systems (emotion, styled, css-modules, …), so their styles could interfere with Docz’s own theme.

Possible solution

Trying to avoid using iframe, it seems that Shadow DOM could be a thing here. By Shadow DOM-ing playground’s preview and injecting style tags inside the playground we could get the desired styles isolation.

EDIT:: After some tinkering, I came with this component to Shadow DOM the example. The only downside is that it breaks HTML preview (for obvious reasons):

import React from 'react'
import ShadowDOM from 'react-shadow'
import marx from 'marx-css/css/marx.css'

const Themed = ({children}) =>
  <ShadowDOM include={[marx]}><div>{children}</div></ShadowDOM>

export default Themed

I had to match \.css$ and use file-loader in the pipeline to achieve the desired effect.

Even if this is already sufficient for me, having to repeat the theme wrapper every demo makes the demos clunky.

[giulianok]

You can do the following in case you don’t want to commit .docz (since has tmp folders)

import fs from "fs";

export default {
  typescript: true,
  htmlContext: {
    head: {
      raw: `<style>${fs.readFileSync(
        process.cwd() + "/src/assets/demo.css"
      )}</style>`
    }
  }
};

[donifer]

@pedronauck I believe the issue he is mentioning is applying the css only to the previewer.

I could make it work and all playground examples now have Milligram styles, but as a side-effect, Docz theme is completely screwed up, as Milligram uses global CSS.

So he is able to load the styles globally but it messes up the Docz theme itself. Is there a workaround for that?