Storybook Design Token实战教程：构建美观的设计系统文档

Storybook Design Token实战教程：构建美观的设计系统文档

【免费下载链接】storybook-design-tokenDisplay design token documentation generated from your stylesheets and icon files. Preview design token changes in the browser. Add your design tokens to your Storybook Docs pages using the custom Doc Blocks.项目地址: https://gitcode.com/gh_mirrors/st/storybook-design-token

Storybook Design Token是一款强大的Storybook插件，能够从样式表和图标文件中生成设计令牌文档，让你在浏览器中预览设计令牌变更，并通过自定义文档块将设计令牌添加到Storybook Docs页面中，轻松构建专业的设计系统文档。

为什么选择Storybook Design Token？

在现代前端开发中，设计系统的一致性至关重要。Storybook Design Token作为一款优秀的Storybook插件，为设计系统文档提供了全面的解决方案。它支持多种样式文件格式，包括CSS、SCSS、LESS等，能够自动解析其中的设计令牌，并以直观的方式展示出来。

这款插件不仅能够帮助团队更好地管理设计令牌，还能提高设计与开发之间的协作效率。通过Storybook Design Token，设计师和开发人员可以共享同一套设计令牌，确保产品在不同平台和设备上的视觉一致性。

快速开始：安装与基本配置

安装插件

首先，使用npm或yarn安装Storybook Design Token插件：

$ yarn add --dev storybook-design-token # 或 $ npm add --save-dev storybook-design-token

添加到Storybook配置

将插件添加到你的Storybook配置文件.storybook/main.js中：

export default { addons: ['storybook-design-token'] };

标注设计令牌

在样式表中添加特殊的注释块来标注设计令牌的类别和展示器。以下是一个CSS样式表示例，定义了三个类别（"Animations"、"Colors"、"Others"）：

:root { /** * @tokens Animations * @presenter Animation */ --animation-rotate: rotate 1.2s infinite cubic-bezier(0.55, 0, 0.1, 1); /** * @tokens Colors * @presenter Color */ --b100: hsl(240, 100%, 90%); /* Token Description Example @presenter Color */ --b200: hsl(240, 100%, 80%); --b300: hsl(240, 100%, 70%); /** * @tokens Others */ --border-normal: 3px dashed red; /* Token Description Example @presenter BorderRadius */ }

展示器（presenter）控制令牌预览的呈现方式。如果不需要预览或没有适合的展示器，可以省略展示器定义。

探索强大的展示功能

卡片视图与表格视图

Storybook Design Token提供了两种主要的令牌展示方式：卡片视图和表格视图。你可以根据需要在两种视图之间切换，以获得最佳的展示效果。

卡片视图以直观的卡片形式展示每个设计令牌，适合快速浏览和视觉识别。每个卡片显示令牌名称、值和预览效果，让你一目了然地了解每个令牌的外观。

表格视图则以结构化的方式展示令牌信息，适合需要详细查看令牌属性的场景。表格包含令牌名称、值和预览列，便于比较和分析不同令牌之间的关系。

丰富的展示器类型

Storybook Design Token提供了多种展示器，用于不同类型的设计令牌：

• Animation: 展示动画效果
• Border: 展示边框样式
• BorderRadius: 展示边框圆角效果
• Color: 展示颜色预览
• Easing: 展示缓动函数
• FontFamily: 展示字体家族
• FontSize: 展示字体大小
• FontWeight: 展示字体粗细
• LetterSpacing: 展示字母间距
• LineHeight: 展示行高
• Opacity: 展示透明度
• Shadow: 展示阴影效果
• Spacing: 展示间距大小

这些展示器能够根据令牌的类型，以最直观的方式展示其效果，帮助团队成员更好地理解和使用设计令牌。

高级配置：定制你的设计系统文档

默认标签设置

你可以指定插件面板中显示的默认标签，将其设置为相应的类别名称：

// .storybook/preview.js export default { parameters: { designToken: { defaultTab: 'Colors' } } };

可见标签控制

如果你不想显示所有可用标签，可以通过tabs设置指定要在插件面板中显示的标签：

export default { parameters: { designToken: { tabs: ['Colors'] } } };

样式注入

为了注入设计令牌文档所需的样式，可以使用styleInjection参数。一个典型的用例是字体家族令牌所需的网络字体：

// .storybook/preview.js export default { parameters: { designToken: { styleInjection: '@import url("https://fonts.googleapis.com/css2?family=Open+Sans&display=swap");' } } };

自定义令牌文件路径

默认情况下，插件会解析代码库中所有的.css、.scss、.less、.svg、.jpeg、.png和.gif文件，以查找带注释的设计令牌。如果你只想解析特定文件，可以通过DESIGN_TOKEN_GLOB环境变量或main.js中的选项传递一个glob模式：

DESIGN_TOKEN_GLOB=**/*.tokens.{css,scss,less,svg}

设计令牌文档块：打造专业文档

Storybook Design Token附带了一个自定义的Storybook文档块，允许你在文档页面中显示设计令牌文档。

基本用法

// colors.stories.mdx import { DesignTokenDocBlock } from 'storybook-design-token'; <DesignTokenDocBlock categoryName="Colors" maxHeight={600} viewType="card" />;

categoryName参数引用你的令牌类别名称（样式表注释中@tokens后面的部分）。viewType参数可以设置为card或table，以在两种展示方式之间切换。

字体排版文档示例

下面是一个展示字体排版相关令牌的文档块示例：

// typography.stories.mdx import { DesignTokenDocBlock } from 'storybook-design-token'; <DesignTokenDocBlock categoryName="Typography" maxHeight={600} viewType="table" />;

自定义展示器

DesignTokenDocBlock组件允许你使用自定义展示器。你可以创建新的展示器或覆盖现有的展示器：

import React from 'react'; export function CircleColorPresenter({ token }) { return ( <div style={{ width: 30, height: 30, borderRadius: '50%', background: token.value }} ></div> ); }

import { DesignTokenDocBlock } from 'storybook-design-token'; import { CircleColorPresenter } from './CircleColorPresenter'; <DesignTokenDocBlock categoryName="Colors" viewType="card" presenters={{ Color: CircleColorPresenter }} />;

令牌使用地图

你可以为DesignTokenDocBlock组件提供一个usageMap，以显示每个令牌在组件中的使用位置：

<DesignTokenDocBlock categoryName="Colors" usageMap={{ '--b100': ['Button', 'CardHeader'], '--b200': ['Modal'] }} />

当提供usageMap时，用户可以在表格视图中右键单击令牌行，打开一个模态框，显示使用该令牌的组件列表。

总结

Storybook Design Token是构建专业设计系统文档的强大工具。它不仅能够帮助团队更好地管理和展示设计令牌，还能提高设计与开发之间的协作效率。通过本教程，你已经了解了如何安装、配置和使用Storybook Design Token，以及如何利用其高级功能来定制你的设计系统文档。

无论你是设计师还是开发人员，Storybook Design Token都能为你的项目带来巨大的价值。开始使用它，打造出令人印象深刻的设计系统文档吧！

要开始使用Storybook Design Token，只需克隆仓库并按照上述步骤进行配置：

git clone https://gitcode.com/gh_mirrors/st/storybook-design-token

祝你的设计系统文档之旅愉快！ 🚀

【免费下载链接】storybook-design-tokenDisplay design token documentation generated from your stylesheets and icon files. Preview design token changes in the browser. Add your design tokens to your Storybook Docs pages using the custom Doc Blocks.项目地址: https://gitcode.com/gh_mirrors/st/storybook-design-token