Fractalを使ったスタイルガイドの作成（中級編）。このジェネレーターかなりいいですよ

コンポーネントの作成と詳細設定

Fractalでコンポーネントを追加するにはcomponentsフォルダ内にテンプレートファイルを追加します。たとえばheadings.hbsというファイルを作ってcomponentsフォルダに保存すると、ウェブUIのメニューにHeadingsが表示されます。

この辺の基礎については、初級編の「スタイルガイドジェネレーターの『Fractal』がかなり良さそう」をご覧ください。

ファイルの命名ルール

テンプレートのファイル名がメニューや他のページから参照する際に使われるハンドルとして使われます。たとえば、ファイル名をresponsive-web.hbsにするとナビゲーションではResponsive Webとして表示されます。ちなみに、ファイル名に使える文字は以下の通りです。

ウェブUIのナビゲーションで日本語を使いたい場合などで違うラベルを設定したい場合は、後ほど説明する設定ファイルで指定が可能です。

その他の詳しいルールは以下のページ（英語）に書いてあります。

• Naming & referencing

メニューでの表示順の指定

メニューでの表示順を変えるには、ファイル名の最初に「01」「02」といったように番号を振ります。

01-title.hbs
02-headings.hbs
03-paragraph-styles.hbs

上のようにファイル名をすると、ウェブUIのナビゲーションでは以下のように表示されます。

Title
Headings
Paragraph Styles

設定ファイルの設置

コンポーネントやドキュメントに対して、設定ファイルを設置することができます。たとえば、headings.hbsの設定ファイルはheadings.config.jsonになります。CommonJS、JSON、またはYAMLのいずれかで記述できるようになっています。

たとえば以下の設定や指定ができます：

• ページタイトル
• ナビゲーションのラベル
• コンポーネントのステータス（Ready、WIPなど）
• コンテキスト・データ（Context Data）

ステータスについて

ステータスはページの右上に表示されるやつで（キャプチャ参照）、デフォルトではPrototype、WIP、Readyから選べるようになっています。ちなみに「WIP」はWork in Progressの略で作業中を意味します。

コンテキスト・データについて

プレビューに表示するHTMLで、データを動的に表示させるために指定するデータです。設定ファイルに書き込んだり、APIを利用したりして他の場所から読み込むことが可能です。Handlebarsで指定した変数に合わせてデータを記述します。

たとえば、下の設定ファイルの例の場合だと「variants」の中にある「context」のところで、動的に使用されるデータをしています。サンプルのスタイルガイドではこのページでコンテキスト・データを使っています。「Context」タブをクリックしてみてください。

設定ファイルの例

{
    "title": "Title",
    "preview": "@preview-title",
    "context": {
      "titleText": "デフォルトのタイトル"
    },
    "variants": [
        {
            "name": "responsive web",
            "label": "レスポンシブWeb",
            "context": {
              "category": "cat-item-108",
              "titleText": "レスポンシブWebデザイン・カテゴリのタイトル"
            }
        },
        {
            "name": "development",
            "context": {
              "category": "cat-item-4",
              "titleText": "ウェブ制作・運営ノウハウ・カテゴリのタイトル"
            }
        }
    ]
}

設定ファイルの書き方などの詳細は下のドキュメントページにまとめられています。

• Configuration files

コンポーネントに追加設定をする方法

コンポーネントにノートやアセットを追加したい場合、コンポーネントを「コンパウンド・コンポーネント」にする必要があります。コンパウンド（compound）とは「混合物、合成物、複合物」といった意味なので、「複合コンポーネント」とでも呼べばいいでしょうか？

といってもフォルダを作って関連ファイルを入れるだけなんですけどね。

たとえば、さっきのheadings.hbsをコンパウンド・コンポーネントにするには、headingsというフォルダを作って、そこに関連ファイルを入れます。たとえば、以下のようになります。

src
├── components
│   └── headings
│       ├── headings.hbs
│       ├── headings.config.json
│       ├── README.md
│       ├── script.js
│       └── style.scss
└── docs

• README.mdがNotesタブに表示されます
• このフォルダに保存した画像ファイル、.jsや.scssファイルはAssetsタブに表示されます

コンポーネントをグルーピングする方法

複数のコンポーネントをグルーピングしてウェブUIのメニューで一緒のドロップダウンに表示させたり、共通の設定ファイルを持たせることも可能です。サンプルのスタイルガイドではbodyというグループを作って、記事本文に使用するスタイルをひとまとめにしてみました。

コンポーネントにバリエーション（変形型）を追加する方法

さらに、コンポーネントにはバリエーションを持たせることができます。サンプルのスタイルガイドではListとTitleでバリエーションを作ったのですが、それぞれ違う方法で設定しています。

ファイルでバリエーションを作る方法

Listの方は、以下のように複数のファイルを作ってバリエーションを作っています。

src
├── components
│   └── list
│       ├── list.hbs
│       ├── list--decorated.hbs
│       ├── list--link.hbs
│       └── list--ordered.hbs
└── docs

設定ファイルでバリエーションを作る方法

一方、Titleの方は設定ファイルを使ってバリエーションを作っています。さっきの設定ファイルの例なんですけど、「variants」以下でResponsive WebとDevelopmentの2つのバリエーションを作っています。

{
    "title": "Title",
    "preview": "@preview-title",
    "context": {
      "titleText": "デフォルトのタイトル"
    },
    "variants": [
        {
            "name": "responsive web",
            "label": "レスポンシブWeb",
            "context": {
              "category": "cat-item-108",
              "titleText": "レスポンシブWebデザイン・カテゴリのタイトル"
            }
        },
        {
            "name": "development",
            "context": {
              "category": "cat-item-4",
              "titleText": "ウェブ制作・運営ノウハウ・カテゴリのタイトル"
            }
        }
    ]
}

コンポーネントをメニューから隠す方法

コンポーネントをウェブUIのメニューから隠すにはファイル名の最初にアンダースコア「_」をつけます。

src
├── components
│   └── _hidden-style.hbs
└── docs

隠したコンポーネントでも他のコンポーネントから参照できるので、メニューには表示したくないけど、ページのテンプレートに組み込みたい場合などに有効に使えそうです。この辺の使用方法については、もう少し検証が必要ですけど。