Storybook: 各要素に対する説明文を入れる

Storybook を html で作り直すかなどはまだ検討している段階と思われますが、
コンポーネントと各要素に対して簡易的な説明文が有ればより良くなるのではと思いました。

文字だけでは伝わらないと思うので、うちの Storybook のスクショを例に貼っておきます。
（※ このStorybook は Basis2 のプロジェクトとは全く別のものなのでそのままできるかは不明）

確か、Storybook の html 版（と言うやつ？）でも、attr や class に対して説明文など設定できるのがあったはずなので、data-layoutなどの要素の各説明を書けるはず。なので、同様な感じで各説明文を表示できるはず。
これ、上手く記述すれば結構分かりやすくできると思うんで、現時点で一度どうするか決めておいた方が良いと思ってます。コンポーネント増えたりした後からやると結構地獄です。

現状は Basis 同様に実際のソースコードを調べないと使いにくい状態になってる部分もあるので、
リファレンスがサンプルデザインを見るだけの存在になってしまっているのに問題を感じています。

[inc2734]

下のテーブルの Description のところですかね？ 今は CSS var の名前だけ入れているので何がなにやら状態ですよね…。ここはちゃんと書かないとですね。

タイトル下の概要文的なのも入れたいなとは思っているのですが、これはこのレイアウトはどう説明したら良いのだ？というところで引っかかるので放置しています^^;

確か、Storybook の html 版（と言うやつ？）でも、

これ調べてたのですが、HTML 版にすると（僕の技術力的に）メンテナンス性がめちゃくちゃ落ちそうなので、現状の React 版のままで、Canvas には HTML コードを表示するプラグインを追加、Docs のプレビューのところにはコードは表示しない、という形で進めはじめてます。

下のテーブルの Description のところですかね？

そこです。
うちの形で申し訳ないですが…一応、サンプルコードを出しときます。

export default {
  title: 'Components/LinkCard/LinkCardView',
  component: LinkCardView,
  argTypes: {
    pageUrl: {
      type: { name: 'string', required: true },
      description: 'ページの URL',
    },
  },
  args: {
    pageUrl: 'https://example.com',
  },
  parameters: {
    docs: {
      description: {
        component:
          '`LinkCardView` は、対象の URL 情報を元にカード形式でリンクを表示するコンポーネントです。',
      },
    },
  },
} as ComponentMeta<typeof LinkCardView>

こんな感じで type に対して name と required を分けて書くと、必須項目やら説明やらに分解されて表示できるので…必須要素みたいなのに required を入れると良いかもです。

また、

    imageUrl: {
name: 'aaaaaaa',
      type: { name: 'string', required: true },
      description: '画像の URL',
    },

みたいに name をパラメータに別で入れると別の名前を割り当てられたりしますので、
Code を出さずに html を出させるなら、それで data-ホニャララ みたいな要素名を書くようにしても良い気がしました。（ちょっとメンテ性が解りにくくなるか…）

コンポーネントの説明ですが、 parameters に docs... 云々でネストさせて書くとコンポーネントの説明を書けます。

import {
  Description,
} from '@storybook/addon-docs'

でやった場合は <Description /> で好きな部分に出せるはず。

とは言え、React版でやるなら @storybook/addon-docs をラッパーなり拡張なりさせた React Component を作って、それで独自の注意書きとかカスタマイズ表示させる方が楽かも。
標準のは、自由度が足りないですからね。

HTML 版にすると（僕の技術力的に）メンテナンス性がめちゃくちゃ落ちそう

確実に落ちるかと。
html版だと使えない Storybook 用のプラグインもあるので、私はどうあっても使いませんね。
React のまま進めた方が良いかも。