[WK3-W] Storybook mdx - Collapsible text, global css, iframe Figma

1 Waking up

I was really gonna hit the gym today, so I had my alarm set at 6am. I did wake up at 6am, but the story goes that I slept right away till 8:30. Nice!

 

2 What did I do?

Yeah I'm being a little bit lazy these days, not filling these daily entries out everyday, but that's as expected. Some days you are super motivated, and some days you just can't be bothered. It doesn't matter, as long as I get back to it somewhat frequently enough. 

 

Today, I was just comparing some design systems that were built through Storybook. There are quite a few companies that are kind enough to give Storybook links to their storybooks for demonstration purposes. Some of them make much less use of Storybook features than even ours, and some goes way beyond what we did (like their custom theming goes above the roof).

 

Here's rough document of the findings from looking at the examples:

I think at this point, I TA'ed most of the main features of Storybook. So it's the matter of studying, how do we effectively use it?

 

For example, Atlassian makes such a good documentation on their components, and that on its own renders itself to be one of the best design systems out there. So it's not just matter of 'we have technology to write markdown documentation', it's more about whether we can leverage the tool to the best it can be. Everyone can use CSS, but not everyone is a good designer nor is able to leverage its features to make a pleasant enough component. Likewise, documentation can really make a design system shine if it is used well. 

3 Making design system comprehensive, easy to navigate, and pretty

Here's the end product I got to after manouvering with it for about a day:

Whereas before, it looked like:

Which is fine, but like you can already see a level of complexity in the second one, whereas the first one is very easy to eyes and it's clear what each sections will be about. 

 

These links definitely gave me some inspirations.

Codeacademy Gamut Storybook

Atlassian Design System - Component

 

What I learnt through doing these 'exercises' (though they are just my tasks) is an importance of conscious and focused effort of making things to be nice and usable as possible. To do that, it's often easy and a good starting point to look at what has been done so far that people call 'good'. Imitation really is important.

 

Also, knowing CSS really helped me too when it came to styling some weird contingencies (like headings being too close to the actual paragraph) and applying custom styles (like status bar and the round border around each section).

 

4 How I implemented that markdown

There were mainly 4 things that I've done differently from other time

 

4.1 Used <details> and <summary> tags to make collapsible markdown

<details className={"details"}>
  <summary className={"summary"}><h2 className={"summary-text"}>Examples</h2></summary>

	// markdown to be collapsed by 'Examples' goes here

</details>

4.2 Separated mdx files so that they it's less cluttered

 

Here's carousel.stories.mdx

import { Meta, Canvas, Story, ArgsTable } from '@storybook/addon-docs/blocks';
// ... some more imports
// then mdx imports:
import Title from './title.mdx';
import Code from './code.mdx';
import Usage from './usage.mdx';
import GlobalFooter from '../GLOBALMDX/globalfooter.mdx';

// Meta tag and stuff ...

<Title />

// stuffs in between (story definitions)

<Code />
<Usage />
<GlobalFooter />

Here's code.mdx (you can think of it as a 'refactored mdx'). I'm showing this as an example for how you could make an MDX that references into multiple MDX files. 

import { Meta, Canvas, Story, ArgsTable } from '@storybook/addon-docs/blocks';

<details className={'details'}>
  <summary className={'summary'}>
    <h2 className={'summary-text'}>Code</h2>
  </summary>

### Changelog

#### 1.0.1

- Updated dependencies

<ArgsTable story="Default Carousel" />

```js
import React from 'react';

import Carousel from '@dfd/ui-components';

args = {
  hideNavButtons: false,
  autoPlay: false,
  overlapIndicators: false,
};

const children = // children to be used in Carousel

const CarouselExample = () => <Carousel {...args}>{children}</Carousel>;

export default CarouselExample;
```

</details>

 

Two things to note:

- You can reference ArgsTable defined in carousel.stories.mdx from other mdx

- MDX files referenced from carousel.stories.mdx can have just markdowns

 

3. Applied CSS

To set global CSS that applies to all the mdx files (remember, mdx is superset of markdown, which supports html and css):

1. Create index.css (doesn't matter what the name is actually), then go to preview.js

2. import index.css from preview.js

//... other imports
import './index.css'

That's literally it! I actually styled the collapsible text by adding class name to details and summary then defining styles for them in index.css - so now we have single point of styling for all the details and summaries.

// carousel.stories.mdx

<details className={"details"}>
  <summary className={"summary"}><h2 className={"summary-text"}>Examples</h2></summary>

	// markdown to be collapsed by 'Examples' goes here

</details>

/* index.css */

.summary {
  margin-bottom: 20px;
  padding: 10px;
  cursor: pointer;
}
.summary-text {
  display: inline;
  cursor: pointer;
}

.details {
  border: 1px #000 solid;
  border-radius: 10px;
  padding: 20px;
  margin-bottom: 20px;
}

Also, I just created div and styled it similarly for status:

Lastly, you can add style for each mdx by just adding this tag to that particular markdown you want to style

<style>{`
	.some-style{
    	color: black;
        border: 1px solid red;
    }

`}</style>

 

4. iframe for Figma within markdown

mdx supports html, including iframe. So you can do something like this to embed figma (go to Share on figma and get the link for the frame you wish to share)

<div className={'center-child some-padding'}>
  <iframe
    width={'800'}
    height={'450'}
    src={
      'https://www.figma.com/embed?embed_host=share&url=https%3A%2F%2Fwww.figma.com%2Ffile%2Fjv6SPNFNR2BQ4brcUlCQ6g%2FApproved-Designs_DFD-Ontario%3Fnode-id%3D1%253A11535'
    }
    allowFullScreen
  />
</div>

5 What to do tomorrow?

I'll probably make some good title pages, both for getting started and atoms/molecules/templates.

Then I'll latex up some good presentations for sesh with the team.

That's it! I'm bit exhausted somewhat, but should be fine. I really should hit gym too.