84,621
返回整合

Storybook 設計令牌

Storybook 擴充套件，用於顯示從樣式表和圖示檔案產生的設計令牌文件。

在 Github 上檢視

⚠️ 這是支援 Storybook v7 及更新版本的 v3 文件。請查看 v2 分支以取得支援 Storybook v6 及以下版本的版本。 ⚠️

Storybook 設計令牌擴充套件

Netlify Status

顯示從樣式表和圖示檔案產生的設計令牌文件。在瀏覽器中預覽設計令牌變更。使用自訂 Doc Blocks 將您的設計令牌新增至 Storybook 文件頁面。

展示範例

Teaser image

目錄

開始使用

首先，安裝擴充套件。

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

將擴充套件新增至您的 storybook 擴充套件清單中的 .storybook/main.js

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");'
    }
  }
};

停用擴充套件面板

在某些情況下，您可能只想使用 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 元件可讓您使用自訂呈現器。您可以建立新的呈現器或覆寫現有的呈現器。

覆寫現有 Color 呈現器的範例

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
    網頁元件
標籤
如何安裝擴充套件 建立擴充套件