Using MDX with Storybook

[00:00:00]
>> We're gonna take a little bit of a side quest because this is great and wonderful, but the more you can document your design system, and how you use it, right? And what the appropriate thing and this is a shared thing too, yeah, there's rules and if you look at Twilio paste, a lot of these design systems will be, this is when you use this thing.

[00:00:20]
And that is definitely meant for the designers as the audience, right? My job is to then take those segments and make them a website thing, but again, it becomes a collaboration piece, right? Because for most of these things, it could be the designers deciding what the rules and when you should use this kind of button versus that kind of button.

[00:00:38]
But when we saw Microsoft's design system, Atlassian design system, Twilio designs, all the designs as they're all in storybook. So it becomes again, that collaboration between development and design. And there's some really, really powerful features that also help you as a developer. So we will look at those real quick, and then we'll kinda go and look at that call out component when we have a full picture of all the things that we can do.

[00:01:02]
So, predominantly, most of our work today has been in a stories.tsx file, and that's pretty cool. But what happens, I keep going to badge cuz it starts with a b, let's close that, there we go, much better. All right, so let's go here and say, button.mdx, and I'm just gonna write some mark down.

[00:01:26]
Hello world! I am a button, sure. I'm just gonna say that, so mark down, nothing special. Let's go back into my story book, cool, over here, I have a button and here's my markdown. Okay, great, that's fine. We're all nodding but it's not that impressive. What we wanna do is actually then make this the documentation for our button.

[00:01:59]
And so storybook has these things called docs blocks. I'm just gonna say blocks from this point forward because there's no way I'm gonna repeatedly say docs blocks, and not stumble over my words. mdx is basically a variant, overloaded word, pun unintended, marked down syntax over there, that also supports a certain amount of JavaScript/JSX.

[00:02:29]
I mentioned this at the beginning of the workshop, but I'll mention it now cuz it's important, which is MDX you can write JSX also known as React. You can do this even if you are Svelte, Vue, whatever, right? It's not important, but it is React, right? You don't need to have React installed as a dependency as a version eight, if you have seven yet and you do.

[00:02:53]
But version eight, they bundle it in there, but it is React syntax. So if you try to then just write Svelte or Vue you will be sad but it's pretty easy to deal with. I will mention just real quick, the MDX file got picked up because that is in the settings and that is by default unless you went out of your way to change it.

[00:03:15]
You're like, I don't know what this is and removed it then it won't work, but if you didn't change that, it will totally work as well, and that's how it got picked up in that case. So at the very simple level, I can do something like this inside of markdown, which is I could say import button from button, and then anywhere I want in here, I can do button, I am a button.

[00:03:43]
And if we go back to that page, look, we have a button in our markdown file, and you can do all sorts of crazy stuff. My website where we have the core stuff is spelt but directly I use a Svelte variant of this. Again, and it's kinda cool to be able to embed components in there, but then what becomes a lot more powerful is there are a lot of these components that Storybook gives you for free.

[00:04:12]
So let's pull in some of them. We're gonna pull in import, and we're gonna say Meta, which is just like, what is this? We'll start with just that one, what is this? Storybook, I think it's just blocks, yeah. And we'll pull in the import ButtonStories, you know how in this stories, I'll just look at it real quick.

[00:04:43]
We exported as default the meta about this set of stories and everything you need to know, which is the title of it, what the args are, what component we're describing, right? That is the default export from button.stories. So we'll pull that in from, Button.stories as well, and now we'll watch as, I'll show you real quick just for compare and contrast.

[00:05:15]
They're kinda not connected to each other right now. What we can do instead of saying will say, Meta of ButtonStories, which is just saying like this document is describing the button. Which did move it over here, and so now it is docs along with all of my button stories in this case, right?

[00:05:43]
And so this is where you might, again, nobody wants to watch me write a bunch of prose describing a button. But theoretically, let's look at an example, this is kind of like it in practice, from Twilio's, right? Here's the guidelines, here's about the account switcher. Let's go look at their button just for context, right?

[00:05:59]
And we'll do some of this momentarily. But it's the guidelines, when to use a button, a button versus an anchor link, so on and so forth. So we've got that and there's just some other little helpful ones in here as well, so we could do stuff like Title.

[00:06:18]
Where we'll say Title is most of that is just some helpful styling as well. But where this becomes a little bit more interesting is we could say, let's go with the primary, is not necessarily the one you called primary, it is the first story that is exported cuz ESM keeps the order.

[00:06:42]
So if you called it default or whatever, it is whatever the first story that you had in that export of the stories is considered the primary story. So now what I can do is I can say primary, and I could write a bunch of prose, like (Here is notes on how to use a button), put it in parentheses.

[00:07:08]
Cool, so we've got that here as well. And it's a JSX, so you gonna have the closing tag. Wrong tab, there we go. And now you can see there is my primary story in here as well, along with the prose on how to like use a button. And this is just one of the stories, there's also stories plural.

[00:07:33]
And if you just like the default components, and you're like, I don't need this, then ignore it. But there are some powerful pieces around, so we can just use stories. And we can say, show me all the stories here, I gotta put that slash, and that's like here's primary, here's secondary, so they're all in one page.

[00:07:53]
So you can see all of the buttons in this case, and you can write your own code and all of those things as well. The other cool thing is, on just a usage level and documentation, it shows you the syntax for this component like, you want a button that looks like this.

[00:08:07]
And these are simple, but you can see a world where on a more complicated case, right? We can see all the pieces in here. And there's a whole bunch of other ones in here for various different uses you show a particular story. The other one that I think is useful in a lot of cases is this controls which are those controls that we saw earlier.

[00:08:30]
So I can say, let's put the, will say, Other variations here, and we'll put controls. And that meta is what's hooking it all up, if you don't have this it's could be like I don't know what you want controls up and what you wanna story off, so, it gets confused.

[00:08:49]
But now, you can say, okay, cool, these are all the props that it takes, this is what type it takes, here's the default value. And a lot of that it acquiesced from the typescript types. And what's even kinda cooler is, we didn't write our own types anymore. You know what I mean?

[00:09:10]
We use that class variance authority to generate our types, which then generated annotations on our controls, which then also showed us how to use this component. Which I think is super useful as well, and again, you change anything here and changes that primary story, like the way we have up here.

[00:09:29]
So if you like the default layout, you can use that if you find yourself wanting to have different opinions and you can use the docs blocks in here. You can also write your own presentational things. You can do all JavaScript works in here, any component you have works.

[00:09:46]
If you have strong opinions on how you wanna communicate and standardize on communicating your design system, all of that is fair game in here, right? And that's obviously of course going to be, unique to what you're doing, and it's in there as well. There are one or two special use cases I do wanna show you, you can choose to use them, you can choose to not use them.

[00:10:08]
These are some of the ones I think are super helpful, and they are kind of somewhat agnostic to any given component. So I can put him in tokens, I'm gonna put them in the top level because I don't know what else to do. So I can do colors.mdx, and this is kinda a useful one.

[00:10:31]
That is definitely I think, helpful, yeah, in that collaboration with design. So we can do something like, will do import, let's do, we'll grab Meta, and we'll say ColorPalette, you can guess where we're going here, and ColorItem from storybook/blocks. Great, great, great, and we'll say in this case we're not actually tying it to a given set of stories.

[00:11:01]
So we'll just say the Meta title is Colors. Awesome, and now we can take that ColorPalette component and you could write this yourself if you wanted to, right? This is just one they gave you for free. If you need something special, it's just JSX, you can totally write it.

[00:11:24]
I don't even know how to spell palette anymore. You'd think I'd got good at this at some point, but no. Cool, and then what we'll do is we could say something like, we'll start with something basic, we'll say ColorItem, and we'll say title is Blue. We'll switch this out in a second.

[00:11:50]
Our brand because every brand is blue. Sweet, and we'll say that the colors are, I'll just start with the, Xcode, if we flip over. All right, what did I waste time? All right, when am I gonna close myself closing tags nobody knows. Can I spell ColorPalette right? ColorPalette has one l and two ts, for those keeping track at home.

[00:12:28]
The only bad part about MDX is the IntelliSense is not nearly as good as if you're writing a JavaScript file. And you can see how much I rely on IntelliSense, by the fact that I don't know how to spell at all. And so here's a color swatch and that's cool or whatever, but let's take this to its natural conclusion.

[00:12:49]
We can import those colors from ./tokens/colors, and here we can just do map over that where we've entries called name, value, I'm not sure that totally works. Yes, name and value, what's angry about value for? Colors, ColourItem, it's title, it's name, title, colors is, what you angry about?

[00:13:29]
Probably not closing this. So I imported that JSON file with the object of colors and this is why in my code base you saw that I had an object of colors because I am very lazy and I don't want to implement this by hand. So the workflow is we've got those CSS variables and Figma, you can export that as either CSS variables or the Tailwind theme is just a JavaScript object.

[00:13:51]
So even if you don't use Tailwind you use that, and that is all our key values. So now we have our ColorPalette by name, and if I wanted to I could include additional things about when to use what color, I'm just mapping over an object. It's just a regular object you can kinda generate a ColorPalette.

[00:14:11]
I will save this as an exercise to the reader because we're not using them too much today. There is one for our typeset which is useful for typography, and one for an icon set which is incredibly useful, cuz then you can just have a page of the icons.

[00:14:25]
They're basically just pretty ways to display these things, if you'd hate this ColorPalette, then you don't have to use Storybooks, there's just helpful blocks. You can write your own ColorPalette, and you can use that instead, and you can feel productive for the day cuz you did that. But these are available to kind of begin to build out and document that design system and communicate, which is both helpful for designers communicating with each other.

[00:14:46]
And then also for you just to be able on a second screen stare at all the icons so you don't necessarily need to remember what icons are there, what their names are as well. And so those are all there, I've got those in the course website. Those are document on how to do those, because it's not the most pertinent thing for what we're doing right now, I will kind of leave that as kind of an extension if you're interested in this is something that speaks to you as well