84,621
返回集成

Storybook 设计令牌

用于显示从样式表和图标文件中生成的“设计令牌”文档的 Storybook 附加组件。

在 Github 上查看

⚠️ 这是支持 Storybook v7 及更高版本的 v3 的文档。请查看支持 Storybook v6 及更低版本的 v2 分支。 ⚠️

Storybook 设计令牌附加组件

Netlify Status

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

给我演示

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 样式表的示例。它对 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");'
    }
  }
};

禁用附加组件面板

在某些情况下，您可能只想使用文档块并隐藏附加组件面板。您可以通过设置 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
    }
  }
};

为您的令牌文件指定自定义通配符

默认情况下，附加组件会解析代码库中所有 .css、.scss、.less、.svg、.jpeg、.png 和 .gif 文件，以查找带注释的“设计令牌”。如果您只想解析特定文件，则可以通过 DESIGN_TOKEN_GLOB 环境变量或 main.js 中的选项传递 通配符。

例如

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

设计令牌文档块

此附加组件附带一个自定义 Storybook 文档块，允许您在文档页面中显示“设计令牌”文档。

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

查看 演示文件 以获取使用示例。

浏览器支持

  • 所有现代浏览器
  • Internet Explorer 11
由以下人员制作
  • psiekmann
    psiekmann
适用于
    Angular
    Ember
    HTML
    Preact
    React
    Svelte
    Vue
    Web Components
标签
如何安装附加组件 创建附加组件