Open shilman opened 5 years ago
I'm happy to pick this one up with some more details 👍
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!
Starting to look into this now. A few questions:
lighten
?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>
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:
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:
ComponentStatus
DocBlock that would parse the stories loadedFor 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?
@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.
I think the easier, more manual option is awesome for now!
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.
Storybook 5.3 will include official MDX support and we should incorporate more of that into the design system. Specifically:
More ideas welcome.