Doc blocks for design system documentation
Tags: storybook, systems, coding, webdev
Published: 2023-08-10 04:09:59

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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/n06x6y1tl70ke2fw5281.png)

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

```jsx
// system/colors.mdx
import { ColorPalette, ColorItem } from "@storybook/blocks"

<ColorPalette>
  <ColorItem />
</ColorPalette>
```
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._

```jsx
<ColorItem colors={{ Apple: "#66bf3c" }} />
```
Describe `ColorItems` with `title` and `subtitle` props.

```diff
<ColorItem
+  title="Apple"
+  subtitle="A delicious brand color."
  colors={{ Apple: "#66bf3c" }}
/>
```
Add as many colors to the `colors` prop as needed.

```diff
<ColorItem
  title="Apple"
  subtitle="A delicious brand color."
  colors={{
    Apple: "#66bf3c",
+    AppleDark: "#46991f",
+    AppleLight: "#83da5a"
  }}
/>
```
Use any CSS-supported color value.  
`ColorItem` adds gray cross-hatches to indicate translucency — where color functions with non-`1` alpha values are used.

```diff
<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)",
  }}
/>
```
See full [`ColorPalette` API reference](https://storybook.js.org/docs/react/api/doc-block-colorpalette).

## Typeset

Display typography systems with the `Typeset` component.

![Storybook component library showing sample typography documentation](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/1uhs8nrbue4dagnauv11.png)

Import the `Typeset` component from `@storybook/blocks`.

```jsx
// system/typography.mdx
import { Typeset } from "@storybook/blocks";

<Typeset {/* required props */} />
```
`Typeset` requires four props to render: `fontSizes`, `fontWeight`, `sampleText`, and `fontFamily`.

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

```diff
<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'
/>
```
Create a new `Typeset` block for every discrete typographical subset.

```diff
## 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;'
/>
```
See full [`Typeset` API reference](https://storybook.js.org/docs/react/api/doc-block-typeset).

## IconGallery

Display icons with the `IconGallery` component.

![Storybook component library showing sample typography documentation](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/3kefnnz6opatt77kyq4u.png)

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

```jsx
// system/icons.mdx
import { IconGallery, IconItem } from "@storybook/blocks"

<IconGallery>
  <IconItem></IconItem>
</IconGallery>
```
Place an icon inside `IconItem`.
Then display that icon's name with the `name` prop.

```diff
+ import * as Icons from "@storybook/icons";

<IconGallery>
  <IconItem name="Accessibility">
+    <Icons.Accessibility />
  </IconItem>
</IconGallery>
```
Take this further — in React — by dynamically generating all available icons.

```mdx
## Storybook icons

<IconGallery>
  {Object.entries(Icons)
    .filter(([name]) => name !== "iconList")
    .map(([name, Icon]) => (
      <IconItem name={name}>
        <Icon />
      </IconItem>
    ))}
</IconGallery>
```
See full [`IconGallery` API reference](https://storybook.js.org/docs/react/api/doc-block-icongallery).

## Learn more…

Find in-depth references for each component on the [Storybook docs page](https://storybook.js.org/docs/) and [Chromatic YouTube channel](https://www.youtube.com/@chromaticui).