スタイルガイドジェネレータの「Fractal」を使ってみる

2019.03.18

HTML・CSS

スタイルガイド

スタイルガイドジェネレータの「Fractal」を使う機会があったので、使用までの流れと使い方をメモ。

インストール

まずはFractalを使用するディレクトリへ移動します。

cd 【プロジェクトディレクトリ】

以下のコマンドでpackage.jsonを生成します。

npm init

Fractalをプロジェクトディレクトリにインストールします。

npm install --save @frctl/fractal

今回はFractal単体で使用するため、グローバルにも同様にインストールします。

npm i -g @frctl/fractal

これでインストールは一通り完了しました。
　

設定

プロジェクトディレクトリ内に、以下の構造でフォルダを作成します。

src
- components
- docs
package.json

プロジェクトディレクトリ直下に、fractalfile.jsというファイル名でファイルを作成します。
今回は以下のような内容で記述します。

'use strict';

// fractalインスタンスを作成してエクスポート
const fractal = module.exports = require('@frctl/fractal').create();
// プロジェクト関連のメタデータ設定
fractal.set('project.title', 'cly7796.net');
fractal.set('project.author', 'cly7796');
// コンポーネントの設定
fractal.components.set('path', __dirname + '/src/components');
// ドキュメントページの設定
fractal.docs.set('path', __dirname + '/src/docs');

公式のドキュメントだとfractal.jsというファイル名で生成するようになっていますが、Windows環境だとfractal.jsというファイル名でうまくいかないようなので、fractalfile.jsとしています。

package.jsonに以下を追記します。

"fractal": {
	"main": "fractalfile.js"
}

サンプルでコンポーネントを追加してみます。
先ほど作成したcomponentsディレクトリ内にalert.hbsというファイル名で以下のように記述します。

<!-- src/components/alert.hbs -->
<div class="alert">This is an alert!</div>

スタイルガイドのトップページの内容を追加します。
docsのディレクトリ内にindex.mdというファイルを作成して、以下のように記述します。

---
title: cly7796 Fractal sample
---
Fractal sample page.

これで一通り準備完了なので、実際に使ってみます。
以下のコマンドを実行します。

fractal start --sync

「Fractal web UI server is running!」と表示されていればOKです。
記載されているURLにアクセスすると、以下のように表示されました。

左ナビのAlertをクリックすると以下のように表示されます。

ここまでのディレクトリ構造は以下のようになっています。

src
- components
  - alert.hbs
- docs
  - index.md
fractalfile.js
package.json

CSSの適用

今のままだとコンポーネントのプレビューにスタイルが当たっていない状態なので、CSSを適用してみます。
このプレビュー部分はiframeで読み込む形になっているので、このiframe内のテンプレートを用意します。

プロジェクトディレクトリ直下にpublicというフォルダを作成、さらにその中でcssというフォルダを作成して、style.cssというファイル名で以下のCSSファイルを設置します。

.alert {
	color: red;
	font-weight: bold;
}

fractalfile.jsの内容を以下に変更します。

'use strict';

// fractalインスタンスを作成してエクスポート
const fractal = module.exports = require('@frctl/fractal').create();
// プロジェクト関連のメタデータ設定
fractal.set('project.title', 'cly7796.net');
fractal.set('project.author', 'cly7796');
// コンポーネントの設定
fractal.components.set('path', __dirname + '/src/components');
// ドキュメントページの設定
fractal.docs.set('path', __dirname + '/src/docs');
// 静的ファイルの設定
fractal.web.set('static.path', __dirname + '/public');

12～13行目に静的ファイルの読み込みファイルを追加していて、これでpublicディレクトリ内をルートとして扱えるようになりました。

componentsディレクトリ内に_preview.hbsというファイル名で以下のように記述します。

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<link media="all" rel="stylesheet" href="{{ path '/css/style.css' }}">
<title>Preview Layout</title>
</head>
<body>
{{{ yield }}}
</body>
</html>

CSSのパスは{{ path ‘/css/style.css’ }}で指定していて、{{{ yield }}}の部分にコンポーネントが追加されます。
これでコンポーネントのプレビューにスタイルを当てることができました。

ここまでのディレクトリ構造は以下のようになっています。

public
- css
  - style.css
src
- components
  - _preview.hbs
  - alert.hbs
- docs
  - index.md
fractalfile.js
package.json

コンポーネントの設定

設定ファイルの追加

設定ファイルは同じディレクトリに同じコンポーネント名で作成する必要があり、ファイル形式はjson,js,ymlのいずれかで作成できます。
例えば先ほどのalert.hbsの設定ファイルをjson形式で作成する場合、componentsディレクトリ内に「alert.config.json」という名前でファイルを作成します。
ファイルの内容を以下のようにしてみます。

{
	"title": "アラート"
}

コンポーネントページのタイトルを変更することができました。

設定ファイルでデータを管理することもできます。
例えば、alert.hbsのテキスト部分を以下のように変更してみます。

<!-- src/components/alert.hbs -->
<div class="alert">{{text}}</div>

先ほど作成したalert.config.jsonに以下のように追加します。

{
	"title": "アラート",
	"context": {
		"text": "alert.config.jsonから設定"
	}
}

これで設定ファイルからデータを渡すことができました。

別パターンのコンポーネントを作成

variants(BEMで言うところのモディファイア)を作成してみます。
componentsディレクトリ内にalert–caution.hbsというファイルを作成して、以下の内容を記述します。

<div class="alert alert--caution">{{text}}</div>

/public/css/style.cssにもスタイルを追加します。

.alert--caution {
	color: yellow;
}

左ナビの表示が「Default」と「Caution」になり、別パターンのコンポーネントを追加できました。

先ほど追加した「alert.config.json」にvariantsの設定も追加できます。
以下のように変更します。

{
	"title": "アラート",
	"context": {
		"text": "alert.config.jsonから設定"
	},
	"variants": [
		{
			"name": "caution",
			"title": "アラートの別パターン",
			"context": {
				"text": "variants内で別途設定"
			}
		}
	]
}

ページタイトルとコンポーネントのテキストを変更できました。

グループ化

ここまでcomponentsディレクトリ直下にファイルを設置してきましたが、さらにその中でフォルダ分けすることでグループ分けすることもできます。
例として、componentsディレクトリ内にgroupというフォルダを作成して、alert.hbsとalert–caution.hbsとalert.config.jsonをフォルダ内に移動します。
さらにgroupディレクトリ内にbtn.hbsというコンポーネントを以下の内容で追加します。

<button class="btn">Button</button>

/public/css/style.cssにスタイルを追加します。

.btn {
	-webkit-appearance: none;
	-moz-appearance: none;
	appearance: none;
	padding: 0;
	border: none;
	outline: none;
	color: #000;
	font-size: 14px;
	font-family: "ヒラギノ角ゴ ProN W3", "Hiragino Kaku Gothic ProN", "メイリオ", Meiryo, sans-serif;
	background: transparent;
	cursor: pointer;

	border: #000 1px solid;
	border-radius: 3px;
	padding: 5px 10px;
}

左ナビを「Group」という括りでまとめることができました。

インクルード

他のコンポーネントの内容をインクルードして使用することもできます。
以下の内容でcomponentsディレクトリ内にsearch.hbsを作成します。

<input type="search" name="keywords">
{{> @btn }}

{{> @btn }}で先ほど追加したbtn.hbsをインクルードしています。

ここまでのディレクトリ構造は以下のようになっています。

public
- css
  - style.css
src
- components
  - group
    - alert.config.json
    - alert.hbs
    - alert–caution.hbs
    - btn.hbs
  - _preview.hbs
  - search.hbs
- docs
  - index.md
fractalfile.js
package.json

テーマの変更

全体のテーマのカラーがいくつか用意されているようなので設定してみます。
fractalfile.jsを以下のように変更します。

'use strict';

// fractalインスタンスを作成してエクスポート
const fractal = module.exports = require('@frctl/fractal').create();
// プロジェクト関連のメタデータ設定
fractal.set('project.title', 'cly7796.net');
fractal.set('project.author', 'cly7796');
// コンポーネントの設定
fractal.components.set('path', __dirname + '/src/components');
// ドキュメントページの設定
fractal.docs.set('path', __dirname + '/src/docs');
// 静的ファイルの設定
fractal.web.set('static.path', __dirname + '/public');
// テーマの設定
const mandelbrot = require('@frctl/mandelbrot');
const myCustomisedTheme = mandelbrot({
	skin: "olive"
});
fractal.web.theme(myCustomisedTheme);

カラーを変更できました。

用意されているテーマではなく、CSS読み込みの変更もできます。
今回はデフォルトのテーマの後にCSSを追加で読み込み、上書きするようにしてみます。

'use strict';

// fractalインスタンスを作成してエクスポート
const fractal = module.exports = require('@frctl/fractal').create();
// プロジェクト関連のメタデータ設定
fractal.set('project.title', 'cly7796.net');
fractal.set('project.author', 'cly7796');
// コンポーネントの設定
fractal.components.set('path', __dirname + '/src/components');
// ドキュメントページの設定
fractal.docs.set('path', __dirname + '/src/docs');
// 静的ファイルの設定
fractal.web.set('static.path', __dirname + '/public');
// テーマの設定
const mandelbrot = require('@frctl/mandelbrot');
const myCustomisedTheme = mandelbrot({
	"styles": [
		"default",
		"/css/styleguide.css"
	]
});
fractal.web.theme(myCustomisedTheme);

/public/css/にstyleguide.cssを作成して、以下のように記述します。

.Header {
	background: black;
}

ヘッダーの色を変更できました。

エクスポート

静的なHTMLにエクスポートするオプションも用意されています。
fractalfile.jsを以下のように変更します。

'use strict';

// fractalインスタンスを作成してエクスポート
const fractal = module.exports = require('@frctl/fractal').create();
// プロジェクト関連のメタデータ設定
fractal.set('project.title', 'cly7796.net');
fractal.set('project.author', 'cly7796');
// コンポーネントの設定
fractal.components.set('path', __dirname + '/src/components');
// ドキュメントページの設定
fractal.docs.set('path', __dirname + '/src/docs');
// 静的ファイルの設定
fractal.web.set('static.path', __dirname + '/public');
// テーマの設定
const mandelbrot = require('@frctl/mandelbrot');
const myCustomisedTheme = mandelbrot({
	"styles": [
		"default",
		"/css/styleguide.css"
	]
});
fractal.web.theme(myCustomisedTheme);
// HTMLの生成
fractal.web.set('builder.dest', __dirname + '/build');

これで/build/に静的HTMLの状態でスタイルガイドが生成されるようになりました。
以下のコマンドでビルドを行います。

fractal build

「Build finished with no errors.」と表示されればOKです。
以下のように生成することができました。
スタイルガイドのデモページ
　

【参考サイト】

Overview | Fractal

日	月	火	水	木	金	土
	1	2	3	4	5	6
7	8	9	10	11	12	13
14	15	16	17	18	19	20
21	22	23	24	25	26	27
28	29	30

スタイルガイドジェネレータの「Fractal」を使ってみる

インストール

設定

CSSの適用

コンポーネントの設定

設定ファイルの追加

別パターンのコンポーネントを作成

グループ化

インクルード

テーマの変更

エクスポート

コメントを残すコメントをキャンセル

Category

Tag

Recent

スタイルガイドジェネレータの「Fractal」を使ってみる

インストール

設定

CSSの適用

コンポーネントの設定

設定ファイルの追加

別パターンのコンポーネントを作成

グループ化

インクルード

テーマの変更

エクスポート

関連記事

StorybookでHTMLを表示するアドオンを試してみる

Storybookで参照するディレクトリとビルドするディレクトリを変更する

Storybookを使ってみる

スタイルガイドジェネレーターの「Fractal」でpugを使用する

スタイルガイドジェネレーターの「Fractal」をgulpで使ってみる

コメントを残す コメントをキャンセル

Category

Tag

Recent

コメントを残すコメントをキャンセル