Generic styles for documentation

[bashmish]

We need to improve the default styles for our documentation to prevent the need to create own styles or the need to create them fully from scratch by giving good defaults and customisation options.

Use-cases

• style MDJS and JSX code blocks in Markdown
  • provide DS styles to the live demo
  • style a wrapper for live demo and live editor
  • code highlighting
• style typography tags (h1-h6, p...)

Current solutions

1. For JSX we have a dockit-react package with <Playground> and <ShadowPlayground>

   • the shell is styled internally via JSX inline style
     • doesn't allow to override styles
   • <Playground> live demo relies on global styles
     • requires 1 LOC on top of each MDX file to import a <Playground> and then using it for each code block explicitly
     • is fragile since all styles are global and can easily break DS styles
   • <ShadowPlayground> introduces a Shadow DOM boundary and API to style live demo using a stylesheet passed as a property
     • requires 1 LOC on top of each MDX file to import a <ShadowPlayground> and then using it for each code block explicitly
     • requires creating a wrapper component with a predefined stylesheet

2. MDJS live demo and live editor is a set of normal HTML tags

   • can be styled via global styles using tag selectors and imported in a Markdown file using import './styles.css';
     • requires 1 LOC on top of each Markdown file to import a default layout and export it

3. Typography tags

   • by default they are just normal HTML tags and can be styled via global styles using tag selectors and imported in a Markdown file using import './styles.css';
     • requires 1 LOC on top of each Markdown file to import a default layout and export it
   • in MDX they can be styled using a layout component which can define MDXProvider and pass a different set of typography tag implementations
     • requires 2 LOC on top of each MDX file to import a default layout and export it
     • 2 LOC is not a problem though given the layout is used not just for styling, but for actual layout purpose (logo, navigation, etc...)

4. ... not 100% sure what we have for Vue, Angular, Svelte, but I assume they have similar solutions

Improvement points

• good looking docs and demos from start
• reduce boilerplate and repetition
• reduce maintenance costs
• prevent global styles leak into DS demos
• provide customisation options
• prevent technology specific solutions (e.g. MDX has it's own way right now)
• rely on standard HTML and CSS where possible

Proposal outline

• all live demos should be encapsulated
• Markdown native HTML-tags or JSX code in MDX should be encapsulated too (things like <TailwindShowcases>)
• we need a global config to define a DS stylesheet to be automatically included in each encapsulated DOM containing a live demo or code like <TailwindShowcases>
• we need to encapsulate only the custom code, but all shell components should remain in Light DOM for simple styling (e.g. typography tags, <details>, <summary> etc...)
• we need a global config to define a "Shell" stylesheet to be automatically included globally in each Markdown doc page (for doc styles like typography tags, live demo/editor wrapper, code highlighting)
• we need good default styles which will look nice in Light and Dark theme, but will allow extending or complete overwrite if needed

[jorenbroekema]

To add on top of the proposal, a possible concrete approach:

In the DS, opt-into getting the default docs styles:
package.json or studio.config.json:

{
  "bkl": {
    "docs": {
      "default": true,
      "styles": "./path/to/styles.css",
      "prismTheme": "vsc-dark-plus"
    }
  }
}

For new design systems we could provide a default config out of the box, for current design system they can opt-in so we don't break the looks of their docs when we release this.

If you supply styles, it allows adding custom CSS to further enhance the docs styles. If you turn off default by setting it to false, it will only use your own styles. By default, docs object is empty and nothing happens. prismTheme would be the theme for code highlighting using PrismJS. We would need to find a way to conditionally fetch the right theme url and insert it in the story-component, could be done with <link> element inside. Theoretically that could clash with the design system if they use the same classes, but I think the chances are quite slim as PrismJS always targets token class plus another class, and the selectors always look like .token.foo. If really needed, we can introduce another shadow boundary to wrap the <pre> element inside of

User writes (without the \):

\```js preview-story
<simba-checkbox-group>...</simba-checkbox-group>
\```

Resulting DOM for docs preview-story:

<mdjs-preview-story>
  #shadow-root
    <link rel="stylesheet" href="https://gitcdn.link/repo/PrismJS/prism-themes/master/themes/prism-vsc-dark-plus.css">
    <style>/* if enabled, BKL provided styles */</style>
    <style>/* if passed, user provided styles */</style>
    <div class="story__container">
      <simba-checkbox-group>...</simba-checkbox-group>
    </div>
    <details>
      <summary>
        ::marker
        Code
      </summary>
      <pre class="language-js">
        <code class="language-js">
          ...
        </code>
      </pre>
    </details>
</mdjs-preview-story>

Which would look like this:

Implementation-wise, I don't know exactly what the feasibility is because I don't know the ins and outs of MDJS, how customizable it is, or what BKL's implementation of MDJS is like, but this would be an API that I would personally be quite happy with as a design system creator.

[bashmish]

thanks for taking your time for a detailed answer!

I came to the conclusion that we should not isolate Mdjs tags and should instead isolate live demos only, but code will speak for itself below

CAUTION: I show jsx story below for JSX block, but actually jsx should be a well-formed JS file with JSX in between which is not the case right now, including how props are passed to JSX tags... I need to think a bit more about how to do it, but the point is clear: I don't want to write actual JS when it comes to using <TailwindShowcases>

Configuration

Fist let's start with the config:

// markdown.config.js
export default {
  defaultMdjsStyles: true, // boolean, default: false, so BKL won't style `.story`, `.story details`...
  customMdjsStyles: "~/layout/my-custom-styles-for-mdjs.css", // string, default: undefined
  storyStyles: "~/design-system/tailwind.css", // string, default: undefined, this is where DS styles should be specified
}

MDX scoping for JSX code blocks

Some JSX dockit components

• require DS styles
• should be isolated from other styles (BKL defaults, custom layout styles or whatever else developers use for styling docs)

<!-- MDX file for documenting Tailwind tokens -->

# Tokens

## Font Family

<!-- 1. JSX with explicit wrapping -->
\```jsx story
<TailwindShowcases theme={theme} showcaseKey="fontFamily" />
\```

<!-- 2. JSX without explicit wrapping (no change, just direct JSX usage in MDX files like now) -->
<TailwindShowcases theme={theme} showcaseKey="fontFamily" />

transforms into

<style>/* defaultMdjsStyles */</style>
<style>/* customMdjsStyles */</style>

<div class="story">
  <mdjs-story class="story__container">
    #shadow-root
      <style>/* storyStyles */</style>
      <div id="root"></div>
  </mdjs-story>
</div>

<script>
// somewhere in our compiler we need to generate code like this
ReactDOM.render(
  <TailwindShowcases theme={theme} showcaseKey="fontFamily" />,
  $mdjsStoryRenderRoot // <div id="root"></div> inside <mdjs-story> Shadow DOM
);
</script>

The second source code 2. JSX without explicit wrapping should be working only if the user enables a configuration for it, e.g.

// markdown.config.js
export default {
  ...
  mdx: { isolateJSXBlocks: true } // super naive first draft
}

But at the same time I'm doubting it's a good idea. Maybe everything should be explicit, so only option 1.

Playground

Thanks to such behavior, we don't need <Playground> or <ShadowPlayground> anymore:

<!-- MDX file for documenting the "button" component -->

# Button

## Usage

<!-- 1. JSX with explicit wrapping -->
\```jsx preview-story
<Button variant="primary">Primary</Button>
<Button variant="secondary">Secondary</Button>
\```

<!-- 2. JSX without explicit wrapping (no change, just direct JSX usage in MDX files like now) -->
<!-- not possible, because I want ti display code and live code editor which requires meta information like "jsx preview-story" -->

transforms into

<style>/* defaultMdjsStyles */</style>
<style>/* customMdjsStyles */</style>
<link rel="stylesheet" href="https://gitcdn.link/repo/PrismJS/prism-themes/master/themes/prism-vsc-dark-plus.css">
<!-- we can have another config for this, or instead we can make all 3 styles to be configured just like normal tags in the default layout -->

<div class="story">
  <mdjs-story class="story__container">
    #shadow-root
      <style>/* storyStyles */</style>
      <div id="root"></div>
  </mdjs-story>
  <details>
    <summary>
      ::marker
      Code
    </summary>
    <pre class="language-jsx">
      <code class="language-jsx">
        ...
      </code>
    </pre>
  </details>
</div>

<script>
// somewhere in our compiler we need to generate code like this
ReactDOM.render(
  <>
    <Button variant="primary">Primary</Button>
    <Button variant="secondary">Secondary</Button>
  </>,
  $mdjsStoryRenderRoot // <div id="root"></div> inside <mdjs-story> Shadow DOM
);
</script>

[jorenbroekema]

Meeting divriots reusable docs - 13 Aug 2021

Main places where discussion is happening:

• Generic styles for documentation #6 (here)

• https://github.com/divriots/webcomponents-editor/pull/2498

• mdjs.config.js / markdown.config.js --> @muryoh working on it already, renderer, layout etc., we discussed some changes to API.

• (Kinda off-topic) Maybe for html story blocks, configuring the renderer is redundant as it is "just html" string, if you were going to use a renderer + bindings etc. you should just use js story blocks for "advanced" demos. Lots of demos in some design systems are just html strings though so html story blocks covers a lot of use cases.

• We might need to use studio.config.json instead, and actually make it studio.config.js instead json for configuring doc layouts

• Page Layout renders the HTML string (from .md) inside a wrapper which is configured by the user. We expose a default wrapper with default backlight styles, but users can override of course. Configuring this property = opting in. This can also cover for the most part the looks of your demo, e.g. how the <details>, <summary> element of the code preview look, putting some border around the demo, etc.

• Story layout needs a boundary to prevent leaks, can be Shadow boundary or iframe boundary (useful for custom viewport demos, prefers-color-theme, prefers-reduced-motion emulation). We need to be able to support users passing DS styles (e.g. global stylesheet) through this boundary. Not fully clear yet how we will do this technically, Storybook format compatibility was briefly mentioned. In ING we do render to iframes for emulating conditions like viewport, we can organise a meeting with Thomas Allmer to get his input on this.

• pageLayout covers most things for now, so we start there