Auto-visualizing Tailwind Tokens and Documenting Design Systems Props with Blast

We've recently added some new features to Blast to help document your design system. In Blast 1.4, one of our community members submitted an update to enable Storybook's extended documentation for component props and in Blast 1.5 we added the ability to automatically generate stories to visualize your Tailwind configuration.

The auto-generated stories are built in a way that allows you to configure which areas of your Tailwind config is generated and then, because the stories are published to your Laravel application, you can extend them with additional notes.

In this guide I'll walk you through the new features and show how to take your design system from no documentation to fully documented and use some of Blast's features to streamline adding documentation to your components.

If you're new to Blast consider reading our other guide which introduces you to Blast and guides you through the initial setup and features.

What does it do and why do I need it?

Documentation is a crucial part of any design system. It guides every single team member on how to use and extend the system.

At AREA 17, whenever we create a Storybook for clients, we like to include as much documentation for the design tokens as possible, from colors, to the layout grid, spacing tokens, breakpoints, etc. There isn't an out-of-the-box way to do this with Storybook so we have to manually create components to handle this.

As of Blast 1.5, this process is no longer manual. We can run one task and it parses our Tailwind config and generates the stories needed to visualize all of the system's design tokens. Out of the box it supports the main Tailwind core elements as well as some of our own plugins we developed to make developing column based layouts, type sets, etc easier with Tailwind.

How to Auto Generate Documentation

Before you can run the command to create the documentation stories you need to set the location of the tailwind.config.js in your application's config/blast.php. Look for the tailwind_config_path item and check that the path is correct, it defaults to the project root.

Now that you've confirmed the location of our Tailwind config file you can run the following command from your Laravel application directory:

php artisan blast:generate-docs

You'll be prompted to give your documentation section a name. Enter a name or hit return to use the default 'UI Documentation' name. If stories already exist in that location you will be prompted to override them.

Blast will now parse your Tailwind config, copy the story blade files to your application, generate the stories and update the Storybook UI. Once complete, your Storybook should look something like this:

Click through the items in the sidebar to see each section of your Tailwind config visualized. Some of the sections like Color and Transitions have Storybook controls so you can interact with the stories and filter background colors or change transition properties.

Configuring Auto-documentation

There may be times when you don't want to generate documentation for every part of your Tailwind config, you just want to show the colors or spacing values. You can do this by adding/removing items from the auto_documentation item in your application's config/blast.php. All of the content types are enabled by default, these are:

border-radius
border-width
colors
font-size
font-weight
height
layout (requires a17-tailwind-plugins)
letter-spacing
line-height
max-height
max-width
min-height
min-width
opacity
shadows
spacing
transition
typesets (requires a17-tailwind-plugins)
width

Extending the Stories

As these documentation stories are published to your application and are built in the same format as all of your other stories, you are free to edit them as you wish.

By default they use the DocsPage component shipped with Blast along with the component used to visualize the Tailwind config within it.

You can add notes around the inner components to give further context to your design tokens, add a README.md to the UI Docs story directory to add documentation to the Docs tab in the Storybook UI, use the @storybook directive to create controls. Anything you can do in your component stories, is available to you in these documentation stories.

But that's not all...

All of the data from your parsed Tailwind config is stored in what we call the UIDataStore. This is available within your stories (we use it in the Transitions stories - see views/stories/data/ui-docs.php) so if you need to visualize something that Blast doesn't support, the data is already there for you to create a component and visualize it.

If you find yourself using this feature to create stories for plugins or other Tailwind features Blast doesn't currently support, please submit a PR to Blast so we can include it!

Updating Data

If you've created your UI Documentation and then changed something in your Tailwind config, you'll need to update the data for the stories. If you run php artisan blast:generate-docs you will be prompted to override the current stories which we may not always want to do.

In this case you can use the --update-data option and this will re-parse your Tailwind config, skip the copying stage and regenerate the stories.

php artisan blast:generate-docs --update-data

Documenting Component Props

As of Blast 1.4 you have been able to add more detailed documentation to component props using Storybook's expanded controls.

This allows you to add a description and the default default value to your controls table which appears beneath your component canvas and also on the Docs page.

This feature is enabled by default but should you need to disable it, you can do so by setting storybook_expanded_controls to false in config/blast.php.

You can define this additional documentation in the argTypes array within the @storybook directive in your story blade files. For example:

@storybook([
    'args' => [
        'label' => 'Label',
        'href' => ''
    ],
    'argTypes' => [
        'label' => [
            'description' => 'Plain text used within the button',
            'defaultValue' => ['summary' => ''],
        ],
        'href' => [
            'description' => 'The `href` string to use on an `a` element. If this prop is set to `falsey` value the component will render as a `button`.',
            'defaultValue' => ['summary' => ''],
        ]
    ]
])

will render as the following in your component's 'Controls' tab:

Reusing Prop Documentation

You can also define this documentation in a data/[something].php file and use it across multiple components via the preset data in the @storybook directive.

For example, if you have primary and secondary button components which both share the same props you can create a stories/data/button.php file containing the following:

return [
    'base' => [
        'args' => [
            'label' => 'Label',
            'href' => ''
        ],
        'argTypes' => [
            'label' => [
                'description' => 'Plain text used within the button',
                'defaultValue' => ['summary' => ''],
            ],
            'href' => [
                'description' => 'The `href` string to use on an `a` element. If this prop is set to `falsey` value the component will render as a `button`.',
                'defaultValue' => ['summary' => ''],
            ]
        ]
    ]
];

and then in your story blade files you can use:

// stories/button/primary.blade.php
@storybook([
    'preset' => 'button.base'
])

// stories/button/secondary.blade.php
@storybook([
    'preset' => 'button.base',
    'args' => [
        'label' => 'Secondary'
    ]
])

This will reuse everything from the preset and allow you to override anything within from your story blade file.

Conclusion

That covers all of the latest documentation features in Blast. The folks over at Storybook also wrote an awesome article about writing documentation in Storybook.

We're working on adding support for more frameworks to the auto-documention feature, Storybook 6.4 support, more customization options, and lots of other new features so watch this space.

If you have any questions or ideas, please head over to our Github and submit Issues, PRs, etc or join the Twill CMS Discord and head to the Blast channel.