加入直播会话：美国东部时间周四上午 11 点，Storybook 9 发布及 AMA
86,718
返回集成页面

Storybook 设计令牌

Storybook 插件，用于显示从样式表和图标文件生成的設計令牌文档。

在 Github 上查看

⚠️ 这是 v3 的文档，支持 Storybook v7 及更高版本。请查看 v2 分支以获取支持 Storybook v6 及以下版本的发布。 ⚠️

Storybook 设计令牌插件

Netlify Status

显示从样式表和图标文件生成的设计令牌文档。在浏览器中预览设计令牌的更改。使用自定义 Doc Blocks 将设计令牌添加到 Storybook Docs 页面。

查看演示

Teaser image

目录

入门

首先，安装插件。

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

将插件添加到 .storybook/main.js 中的 Storybook 插件列表里

module.exports = {
  addons: ['storybook-design-token']
};

最后一步是使用类别名称和展示器来标注设计令牌。你可以通过在样式表中添加特殊的注释块来完成此操作。下面是一个 CSS 样式表示例，它定义了三个类别（"Animations", "Colors", "Others"）。对于 scss 和 less 文件，工作方式相同。

: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 */
}

展示器控制令牌预览的渲染方式。请参阅下一节以获取可用展示器的完整列表。如果你不想渲染预览或者没有展示器适用于你的令牌，则可以省略展示器定义。

默认情况下，令牌类别以下一个类别的注释块结束。如果你想在下一个类别注释之前结束一个类别块，可以插入一个特殊注释提前结束该块

/**
  * @tokens-end
  */

为了列出你的 SVG 图标，插件会解析你的 SVG 文件并搜索 SVG 元素。重要提示：只有带有 id 或 data-token-name 属性的 SVG 元素才会添加到令牌列表。 你可以使用（可选的）属性 data-token-description 和 data-token-category 为你的图标提供描述和类别名称。

可用展示器

请查看 演示 以查看展示器的实际效果。

  • 动画
  • 边框
  • 边框半径
  • 颜色
  • 缓动
  • 字体族
  • 字体大小
  • 字体粗细
  • 字母间距
  • 行高
  • 不透明度
  • 阴影
  • 间距

高级配置

默认选项卡

你可以指定插件面板中显示的默认选项卡。将其设置为对应的类别名称。

.storybook/preview.js

export default {
  parameters: {
    designToken: {
      defaultTab: 'Colors'
    }
  }
};

可见选项卡

如果你不想显示所有可用选项卡，可以通过 tabs 设置指定在插件面板中应显示哪些选项卡。

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

样式注入

要注入设计令牌文档所需的样式，请使用 styleInjection 参数。一个典型的用例是你的字体族令牌所需的网络字体。请注意，styleInjection 参数仅适用于有效的 CSS。

.storybook/preview.js

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

禁用插件面板

在某些情况下，你可能只想使用 Doc Blocks 而隐藏插件面板。你可以通过设置 disable 参数来做到这一点

export default {
  parameters: {
    designToken: {
      disable: true
    }
  }
};

令牌搜索可见性

在某些情况下，你可能不需要搜索字段可见。你可以通过设置 showSearch 参数来控制其可见性

export default {
  parameters: {
    designToken: {
      showSearch: false
    }
  }
};

分页

默认情况下，卡片视图的 pageSize 为 50 项。你可以通过设置 pageSize 参数来配置它

export default {
  parameters: {
    designToken: {
      pageSize: 10
    }
  }
};

你可以通过以下方式禁用分页

export default {
  parameters: {
    designToken: {
      // specify max value to disable pagination
      pageSize: Number.MAX_VALUE
    }
  }
};

为令牌文件指定自定义 glob

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

例如

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

保留 CSS 变量

默认情况下，插件在构建时提取 CSS 变量的值。因此，展示器在运行时使用固定值。此行为在某些场景下可能会带来限制

  • 包含 CSS 变量的样式表与令牌分开加载
  • 主题在运行时替换，并加载新的 CSS 变量值

如果你想在展示器中保留 CSS 变量，请在 main.js 文件中启用 preserveCSSVars 选项

module.exports = {
  stories: [
    // stories
  ],
  addons: [
    { name: 'storybook-design-token', options: { preserveCSSVars: true } }
  ]
  // other options
};

设计令牌 Doc Block

此插件附带一个自定义的 Storybook Doc Block，允许你在文档页面中显示设计令牌文档。

// colors.stories.mdx

import { DesignTokenDocBlock } from 'storybook-design-token';

<DesignTokenDocBlock categoryName="Colors" maxHeight={600} viewType="card" />;

categoryName 参数引用你的令牌类别名称（样式表标注中 @tokens 之后的部分）。viewType 参数可以设置为 card 或 table 以切换两种展示方式。在某些情况下，你可能想隐藏令牌值。你可以通过传递 showValueColumn={false} 来做到这一点。查看 演示文件 获取使用示例。

自定义展示器

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 }}
/>;

自定义过滤器

filterNames prop 允许你按变量名过滤在 DesignTokenDocBlock 中显示的设计令牌。使用此功能可以在 Storybook 文档中专注于令牌的子集。

// colors.stories.mdx

import { DesignTokenDocBlock } from 'storybook-design-token';

<DesignTokenDocBlock
  filterNames={['--b100']}
  categoryName="Colors"
  viewType="card"
/>;

你还可以向 DesignTokenDocBlock 组件传递一个主题。当你有两个主题具有相同的变量名，但只想显示当前主题的变量时，这会很有用。只需传递 theme 属性即可完成此操作。

浏览器支持

  • 所有现代浏览器
  • Internet Explorer 11
创建者
  • psiekmann
    psiekmann
兼容
    Angular
    Ember
    HTML
    Preact
    React
    Svelte
    Vue
    Web Components
标签
如何安装插件 创建插件