Help us understand the problem. What is going on with this article?

Fractal デザインスタイルガイド 導入

More than 1 year has passed since last update.

Fractalとは

「styledocco」や「sc5-styleguide」などのスタイルガイドジェネレーターの仲間。
スタイルガイドジェネレーターといえば、ドキュメントを作成するためにCSS内にコメントで記述するものが多いですが、fractalはスタイルシート内ではなく、Handlerbarsファイルに記述するようになっています。(設定によりjson yaml pugなどで記述することも可能です)
CSSファイルとは別ファイルで管理できるので、CSSファイルを綺麗に保つことができます。

公式ガイドも比較的わかりやすい記述になってますので、カスタマイズなどしないのであればすぐに利用できると思います。(参考

fractal_logo.png 

画面の説明

各種デザインパーツをまとめていく コンポーネントドキュメント の2つに別れている。
コンポーネントは画面下に HTML View Context Info Notesのタブが表示される。
fractal.jpg

準備

フォルダを作成

% mkdir guide

ターミナルを立ち上げて、上記コマンドを入力

npm initでプロジェクトを開始

% npm init

cd guideでguideフォルダ内に移動し、上記コマンドを入力しpackage.jsonを作成

Fractalをインストール

% npm install --save @frctl/fractal

Fractalをインストールします。--saveのオプションでpackage.jsonにバージョン付きでdependenciesが書き込まれます。(参考

Fractalをグローバルインストール

% npm i -g @frctl/fractal

ターミナルのどこからでもFractalが開始できるように、グローバル領域にFractalをインストールします。

初期設定

ディレクトリ構成

guide
 ├── src
 │    ├── components 
 │    └── docs
 │
 ├── fractal.js
 └── package.json

一旦、上記構成でフォルダを作成。
components ⇒ デザインパーツ(コンポーネンツ)を入れるフォルダ
docs ⇒ ガイドの説明などドキュメントを記載するフォルダ
fractal.js ⇒ fractal内の各種設定を記載

fractal.jsの作成

'use strict';

/* Fractalのインスタンスの作成とエクスポート */
const fractal = module.exports = require('@frctl/fractal').create();

/* プロジェクト・タイトルの設定 */
fractal.set('project.title', 'デザインガイド');

/* componentsディレクトリの指定 */
fractal.components.set('path', __dirname + '/src/components');

/* documentationディレクトリの指定 */
fractal.docs.set('path', __dirname + '/src/docs');

コンポーネントを入れてみる

テキストエディタで header.hbs というファイルを作って先ほどの components ディレクトリに保存します。ファイルには以下のようなHTMLを入れてみてください。

<header>
    <div>タイトル</div>
</header>

Docsのトップページを設置する

Documentationのトップページの内容を追加します。テキストエディタで以下の内容のファイルを作ってdocsディレクトリにindex.mdとして保存します。MarkdownYAML front-matterを使って記述します。

---
title: ドキュメントページ
---
説明を記述します。

ここまでのフォルダ構成

guide
 ├── src
 │    ├── components
 │    │    └── header.hbs
 │    └── docs
 │         └── index.md
 │
 ├── fractal.js
 └── package.json

ローカル環境で確認

% fractal start --sync

ターミナルを立ち上げ上記のコマンドを実行すると、 下記のメッセージが表示されhttp://localhost:3000 にて画面が確認できるようになります。

┌───────────────────────────────────────────┐
│ Fractal web UI server is running!         │
│───────────────────────────────────────────│
│ Local URL:      http://localhost:3000     │
│ Network URL:    http://10.21.180.184:3000 │
│ BrowserSync UI: http://localhost:3002     │
│───────────────────────────────────────────│
│ Use ^C to stop the server.                │
└───────────────────────────────────────────┘

自動でブラウザが立ち上がるようにするには、fractal.jsに下記2行を追加します。(参考

// browsersync設定
fractal.web.set('server.sync', true);
fractal.web.set('server.syncOptions', { open: true});

静的ファイルを書き出し

ローカル環境で確認が済んだら、静的ファイルに書き出します。fractal.jsに下記の記述を追加します。

/* 静的ファイルの書き出し場所 */
fractal.web.set('builder.dest', __dirname + '/dist');

下記コマンドを入力するとdistフォルダが作成されます。

% fractal build

参考記事

公式ガイド
スタイルガイドジェネレーターの「Fractal」がかなり良さそう
Fractalを使ったスタイルガイドの作成(中級編)。このジェネレーターかなりいいですよ

fujihiko
Webデザインおよびフロントエンドエンジニア。
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
No comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
ユーザーは見つかりませんでした