Styleguide / MDX examples

[shilman]

Storybook 5.3 will include official MDX support and we should incorporate more of that into the design system. Specifically:

• Introduction - add a kitchen sink example story?
• Styleguide / design tokens
• Convert one component from DocsPage to MDX as an example?

More ideas welcome.

[leerob]

I'm happy to pick this one up with some more details 👍

[domyen]

Great idea, I think there are low hanging fruits that we could use a hand on @leerob. 🙏

Color documentation
Replace color story with MDX docs-only page that features the ColorPalette DocBlock.

Typography documentation
Replace typography story with MDX docs-only page that features the Typeset DocBlock.

Table of Components page
Add a “Table of Components” MDX page that shows component status (inspired by Shopify). The 3 columns we'd have Component, Code, Documentation which indicates the component status. For instance:

Component	Code	Documentation
Avatar	✅Complete(link to component)	✍️In progress
AvatarList	✅Complete(link to component)	Need assistance

Open to different ideas here and co-designing this feature with you. Perhaps it should also include versions?

Create Do's and Don's component
Showcasing how to use and not use components is a frequent part of UI documentation. It would be useful for us to show what not to do. For example, some components feature a11y gotchas that our client apps must consider. The do's and don'ts component should be able to take a code snippet, regular text, or an image. I'm also keen to co-design this feature if you're up for it!

[leerob]

Starting to look into this now. A few questions:

• The image linked above for the colors shows all the different opacity permutations. Those don't appear to used currently in the design system. Should those values be exported for consumers, or just on display in the story? If the former, I would include the hex values. If the latter, maybe the consumer would be using something lighten?
• There are some discrepancies between that image and the current variables in the shared styles.js. For example - tertiary is turquoise there but grey in the design system. Which is the source of truth?

Here's the current status of my WIP:

import { Meta, ColorPalette, ColorItem } from '@storybook/addon-docs/blocks';

import { color } from './shared/styles';

<Meta title="Design System|Colors" />

# Colors

<ColorPalette>
  <ColorItem title="theme.color.primary" subtitle="Coral" colors={[color.primary]} />
  <ColorItem title="theme.color.secondary" subtitle="Blue" colors={[color.secondary]} />
  <ColorItem title="theme.color.tertiary" subtitle="Grey" colors={[color.tertiary]} />
  <ColorItem title="theme.color.positive" subtitle="Green" colors={[color.positive]} />
  <ColorItem title="theme.color.warning" subtitle="Ochre" colors={[color.warning]} />
  <ColorItem title="theme.color.negative" subtitle="Red" colors={[color.negative]} />
  <ColorItem title="theme.color.orange" subtitle="Orange" colors={[color.orange]} />
  <ColorItem title="theme.color.gold" subtitle="Gold" colors={[color.gold]} />
  <ColorItem title="theme.color.seafoam" subtitle="Seafoam" colors={[color.seafoam]} />
  <ColorItem title="theme.color.purple" subtitle="Purple" colors={[color.purple]} />
  <ColorItem title="theme.color.ultraviolet" subtitle="Ultraviolet" colors={[color.ultraviolet]} />
  <ColorItem
    title="Monochrome"
    colors={[
      color.darkest,
      color.darker,
      color.dark,
      color.mediumdark,
      color.medium,
      color.mediumlight,
      color.light,
      color.lighter,
      color.lightest,
    ]}
  />
</ColorPalette>

[domyen]

Hey @leerob, this is awesome! There was a miscommunication error on my part. I sent over the image of the component to show what it looks like not to ask you to achieve the same result. So no worries about being accurate to the image.

We're not intending to ship the shades to design system consumers. The shades are there to show what's possible. Consumers can use polished to lighten the colors but it's not a requirement. In the design the opacity scale is 100%, 80%, 60%, 30%.

As far as names and values go, the code is the source of truth.

Same goes for the type scale:

[leerob]

Gotcha! Thanks for the extra info. I'll get a PR up for the colors/typography.

For the components, we could definitely do an MDX page. However, it could get out of sync quickly.

import { Meta } from '@storybook/addon-docs/blocks';

<Meta title="Design System|Components" />

# Table of Components

| Component  | Code                                                                        | Documentation   |
| ---------- | --------------------------------------------------------------------------- | --------------- |
| Avatar     | ✅Complete ([View Component](/?path=/docs/design-system-avatar--large))     | ✍️In progress   |
| AvatarList | ✅Complete ([View Component](/?path=/docs/design-system-avatarlist--short)) | Need assistance |

A better solution might be:

• Modifying CSF to include this information
• Creating a ComponentStatus DocBlock that would parse the stories loaded

For example, the Button component. Maybe the CSF looks like this:

export default {
  title: 'Design System|Button',
  component: Button,
  codeStatus: COMPLETE,
  docsStatus: IN_PROGRESS
};

There could be an enum with statuses like COMPLETE, IN_PROGRESS, and NEEDS_ASSISTANCE to denote the different states.

The DocBlock could then parse all of the stories and dynamically build the markdown table.

With that being said... that's a lot more work than just putting together a quick MDX file. Should we go forward with that hand-rolled MDX file for now and maybe consider a custom DocBlock if more people would find it valuable?

[shilman]

@leerob I agree with a status doc block longer term, and that short-term the custom MDX is a nice demo of capabilities 👍

I'd like to formalize the notion of a doc block either later in 5.3 or in 5.4, so the status block would be a nice example to use in that conversation.

[domyen]

I think the easier, more manual option is awesome for now!

[bsgreenb]

It would be nice if you could supply names as well as hex codes to each color column. Otherwise to get labeling for each you need to create a new row.