Addon-docs: Design token support

[shilman]

Incorporate https://github.com/UX-and-I/storybook-design-token into SB Docs

• file parsers
• presenters
• MDX-embeddable block

[mlegait]

With addon-docs, there is already a bunch of stuff to create a Design System with Storybook. But we still have to document the tokens manually.

Having an auto generated doc for the tokens would be AWESOME! I can't wait to see it implemented 🙇‍♀️

[Sqrrl]

Hey, just wanted to give a little ping as the maintainer of https://github.com/UX-and-I/storybook-design-token. I would love to see it integrated with SB Docs and will assist wherever possible.

[mlegait]

Hi 😄

Any news on this issue? Do we have a chance to see it in the coming releases?

[Sqrrl]

Hey. There are some really interesting efforts to come up with a more standardized specification of design tokens here and here.

While the design token addon does its job right now, I'm not sure if extracting token information from stylesheets and such is the way to go in the future. So I'm unsure of how to proceed here.

[atanasster]

@Sqrrl Since you have been in this space for a while, i would really like to hear what do you think is the way to go in the future. I am just an intrigued observer here

[Sqrrl]

"In this space for a while" is a bit of a stretch. 😉But it sure sounds compelling to have a standardized token format that we can use both in our design tools and to generate and document our styles.

[ryanfitzer]

I think the format that @Sqrrl uses is an excellent way to present design tokens ( I replicate it in my own projects). And agree with him that extracting token information from stylesheets may not be the best route, at least, as the default.

I use Amazon's Style Dictionary to generate the design tokens. One of the many target formats it supports is JSON. I currently use these JSON "property" files to generate the design token stories.

With that said. I think a good way forward would be to:

1. Come to an agreement on a design tokens configuration format for SB to support.
2. Create an addon that supports this format, while also supporting extracting token information from stylesheets.
3. Coordinate with makers of design token tools to add the SB design token format to their tools.
   a. Depending on how open each tool maker is to new formats, these could instead be something that SB provides. It is a trivial level of effort to create custom formats with Style Dictionary and Theo. I expect this same is true for many of the other tools.

One thing I also think is important to discuss is where these tokens are presented. Some may favor them in a panel, as is done with storybook-design-token, but I think there should also be the option to have them as top-level stories, here's an example.

Thoughts?

[shilman]

I’ve been waiting for a proposal from the W3C working group before trying to bring this into core. https://github.com/design-tokens/community-group

But it sounds like that’s a longer term process, so we should push this forward to make more useful addons (or extend the current one— I love what @Sqrrl has done so far!) in the meantime. @ryanfitzer your proposal sounds super reasonable.

For me the top priority is to bring them into Storybook as DocBlocks, which should also be renderable in the Addons panel and also as top level stories (if you’re using Storybook for React, for now). I’ll post more about that soon.

[gossi]

Oh yes please! I just released Theemo, read here about: https://gos.si/blog/say-hello-to-theemo-the-yordle-powered-theme-automator/

Basically the idea with this is theemo already knows about all your tokens. Would like to connect theemo to this. In the end theemo automates everything for you, just one command away.

Let me know how to collaborate.

[shilman]

@gossi @Sqrrl let's tackle this together in 6.1. The 6.0 schedule is slipping and it's going to be a complex release. As soon as it's out the door, I'll start a document that we can iterate together. In the meantime if anybody wants to put together POC's (either as standalone addons or enhancements to storybook-design-token) to help shape the integration into core, I'd be happy to help promote these to the SB community to help get feedback and see how they are being used. Thanks for your patience on this!

[nhoizey]

I use Amazon's Style Dictionary to generate the design tokens. One of the many target formats it supports is JSON. I currently use these JSON "property" files to generate the design token stories.

I started using Style Dictionary for tokens and Storybook for the whole design system, and I'm also looking forward to a standard format for tokens that Storybook could integrate natively.

In the mean time, @ryanfitzer could you share how you generate the design token stories from Style Dictionary's JSON output? Thanks

[nhoizey]

Following my previous comment about using both Style Dictionary and Storybook, here's how I use the former's global JSON output in the later's stories, based on some examples I've seen elsewhere.

For colors:

import { Meta, ColorPalette, ColorItem } from '@storybook/addon-docs/blocks';
import tokens from 'design-tokens/dist/properties.json';

<Meta title="Tokens/Options/Colors" />

# Options for colors

## Brand colors

<ColorPalette>
  {Object.entries(tokens.color.brand).map(([id, data], index) => {
    return (
      <ColorItem
        key={id}
        title={data.path.join('.')}
        subtitle={data.comment}
        colors={[data.value]}
      />
    );
  })}
</ColorPalette>

For typography sizes:

import { Meta, Typeset } from '@storybook/addon-docs/blocks';
import tokens from 'design-tokens/dist/properties.json';

<Meta title="Tokens/Options/Typography" />

# Typography

<Container>
{Object.entries(tokens.size.font).map(([id, data], index) => {
console.log(id);
return (

<Typeset
  fontSizes={[data.value]}
  fontWeight="300"
  sampleText={`${id}: ${data.original.value}`}
  title="test"
  subtitle="test"
/>
); }) }
</Container>

As you can see, I target a fraction of my color tokens (tokens.color.brand) for a section of the color options story. It contains other sections for base colors and complementary colors (split in cold and warm). I also have another story for decision tokens, also with multiple sections.

The result is quite nice:

But there are a few issues:

• I duplicated the code above for each section, I didn't try to refactor to get a simpler syntax yet
• My own properties.json file generated by Style Dictionary will be different from the one from another project, so I don't know if we can automate the listing/creation of stories
• I don't know yet how to create (generate?) and show swatches of variants of each color with different luminosities/saturations. Using https://github.com/adobe/leonardo#readme would be great
• For typography, <Typeset> is not showing the token name in the left as with <ColorItem>

I can't share a link to the full code as it's in a private repo, sorry.

[nhoizey]

There are some nice ideas in this article written by @varya:
https://frontside.com/blog/2021-04-07-helping-designers-and-developers-storybook/

[shilman]

Converting this to a discussion. We’re reserving feature issues for things that are on our short-term roadmap. We’ll check back periodically to see whether this is a good candidate to be added. If this feature would be useful to you, please upvote!