DEV Community

Cover image for Doc blocks for design system documentation
chantastic
chantastic

Posted on • Originally published at chan.dev

Doc blocks for design system documentation

#storybook #systems #coding #webdev

If you document design systems, I'm about to save you a ton of time.
Because Storybook comes with lesser-known components for organizing colors, typography, and icons.

ColorPalette

Display color systems with the ColorPalette component.

Storybook component library showing sample color-system documentation

Import "@storybook/blocks".
Then render a ColorPalette with a single ColorItem inside.

// system/colors.mdx import { ColorPalette, ColorItem } from "@storybook/blocks" <ColorPalette> <ColorItem /> </ColorPalette>
Enter fullscreen mode Exit fullscreen mode

Create an object with a key and color value.
And pass it to the ColorItem component via the color prop.

Both key and value are displayed in the UI.

<ColorItem colors={{ Apple: "#66bf3c" }} />
Enter fullscreen mode Exit fullscreen mode

Describe ColorItems with title and subtitle props.

<ColorItem + title="Apple" + subtitle="A delicious brand color."  colors={{ Apple: "#66bf3c" }} />
Enter fullscreen mode Exit fullscreen mode

Add as many colors to the colors prop as needed.

<ColorItem title="Apple" subtitle="A delicious brand color." colors={{ Apple: "#66bf3c", + AppleDark: "#46991f", + AppleLight: "#83da5a"  }} />
Enter fullscreen mode Exit fullscreen mode

Use any CSS-supported color value.

ColorItem adds gray cross-hatches to indicate translucency — where color functions with non-1 alpha values are used.

<ColorItem title="Apple" subtitle="A delicious brand color." colors={{ + Apple: "rgba(102,191,60,1)", + Apple60: "rgba(102,191,60,.6)", + Apple30: "rgba(102,191,60,.3)",  }} />
Enter fullscreen mode Exit fullscreen mode

See full ColorPalette API reference.

Typeset

Display typography systems with the Typeset component.

Storybook component library showing sample typography documentation

Import the Typeset component from @storybook/blocks.

// system/typography.mdx import { Typeset } from "@storybook/blocks"; <Typeset {/* required props */} />
Enter fullscreen mode Exit fullscreen mode

Typeset requires four props to render: fontSizes, fontWeight, sampleText, and fontFamily.

fontSizes and fontWeight support any supported CSS value (and numbers).

<Typeset + fontSizes={["2.875em", "2em", "1.375em", "1em"]} + fontWeight="900" + sampleText="Lorem ipsum dolor sit amet, consectetur adipiscing elit." + fontFamily='"Nunito Sans", "Helvetica Neue", Helvetica, Arial, sans-serif' />
Enter fullscreen mode Exit fullscreen mode

Create a new Typeset block for every discrete typographical subset.

## Code  <Typeset fontSizes={[16]} fontWeight={400} sampleText="let var = 'const';" fontFamily='ui-monospace, Menlo, Monaco, "Cascadia Mono", "Segoe UI Mono", "Roboto Mono", "Oxygen Mono", "Ubuntu Monospace", "Source Code Pro", "Fira Mono", "Droid Sans Mono", "Courier New", monospace;' />
Enter fullscreen mode Exit fullscreen mode

See full Typeset API reference.

IconGallery

Display icons with the IconGallery component.

Storybook component library showing sample typography documentation

Import "@storybook/blocks".
Then render a IconGallery with a single IconItem inside it.

// system/icons.mdx import { IconGallery, IconItem } from "@storybook/blocks" <IconGallery> <IconItem></IconItem> </IconGallery>
Enter fullscreen mode Exit fullscreen mode

Place an icon inside IconItem.
Then display that icon's name with the name prop.

+ import * as Icons from "@storybook/icons";  <IconGallery> <IconItem name="Accessibility"> + <Icons.Accessibility />  </IconItem> </IconGallery>
Enter fullscreen mode Exit fullscreen mode

Take this further — in React — by dynamically generating all available icons.

## Storybook icons <IconGallery> {Object.entries(Icons) .filter(([name]) => name !== "iconList") .map(([name, Icon]) => ( <IconItem name={name}> <Icon /> </IconItem> ))} </IconGallery>
Enter fullscreen mode Exit fullscreen mode

See full IconGallery API reference.

Learn more…

Find in-depth references for each component on the Storybook docs page and Chromatic YouTube channel.

Top comments (1)

Collapse
 
joevaugh4n profile image
Joe •

i love this idea @chantastic!