コンポーネント用スタイルガイドジェネレーター (Atomic Lab.)を作りました。

  • 26
    いいね
  • 0
    コメント

スクリーンショット

Screen Shot 2016-09-29 at 11.24.50 PM.png

考案・開発: steelydylan
UIデザイン: okajax

なぜつくったか

  • HTMLベースのスタイルガイドジェネレーターを作りたかったから。
  • JSONファイルのみでスタイルガイドに表示する内容を制御したかったから。
  • React、Polymerなどのコンポーネント系のライブラリをつかおうが、、CMSを使ってコンポーネント化しようが、どんな制作環境でも表示できるスタイルガイドを作りたかったから。
  • スタイルガイドジェネレーターを使った時に静的HTMLファイルが大量にできるのが好きじゃないから。

デモページ

以下のページより実際にどんなスタイルガイドかを確認できます。さらにHTML,CSSのソースコードを直接ブラウザで変更し、変更結果をプレビューで確認することも可能です。

http://steelydylan.github.io/atomic-lab/

GitHub

https://github.com/steelydylan/atomic-lab

何ができるの?

コンポーネント単位でスタイルガイドを生成できます。
今までのスタイルガイドジェネレーターと違い、HTMLベースでスタイルガイドを生成します。また、オンライン上で直接、HTMLとCSSを編集してプレビューを確認することが可能です。
また、コンポーネントをAtom Molecule Organism Template に分類できるのも特徴です。

プレビューの表示

Atomic Labでは、HTMLに下記のようなコメントタグを記述して、プレビュー結果を出力します。

<!--@preview
<main-visual image="http://www.civillink.net/fsozaip/phote/fukei3l.jpg" text="steelaxe"></main-visual>
-->

ノートの表示

以下のようなコメントタグでくくり、中にマークダウンを書くことでそのコンポーネントに対する説明を記述することができます。また、cssやhtmlなどのソースコードは自動的にハイライトされます。

<!--@note
## grid system
```scss
@include make-grid(mod,col,12);
``
## clearfix
```scss
@include clearfix();
`` 
-->

Screen Shot 2016-09-29 at 11.37.19 PM.png

独自タグの定義

また、ReactやPolymer,Riotなど独自タグを定義できるライブラリが増えてきていますので、Atomic Labでも独自にタグを定義してプレビュー画面に表示するしくみを提供しています。

テンプレートの定義

<!--@template -->
code here
<!--@/template -->

デフォルト変数の定義

<!--@template text="hoge" -->
<p>{text}</p>
<!--@/template -->

コンポーネントの読み込み及び、使用

<!--@import parts="main-visual" -->
<main-visual image="hoge.png"></main-visual>

さまざまな言語に対応

また、さまざまなメタ言語に対応しています。
- EJS,Jade,Hamlに対応
- Sass,Less,Stylusに対応

作ったプロジェクトのシェア

また作ったプロジェクトをTwitterやSlackなどでシェアすることも可能です。

シェアされたプロジェクトの例

Screen Shot 2016-09-29 at 11.55.18 PM.png

Zipファイルとしてダウンロード

また、左上のダウンロードアイコンよりプロジェクトをZipファイルとして、ダウンロードすることも可能です。その際に、そのプロジェクトをbuildするためのgulpfile.jsやpackage.jsonまた、コンポーネントの情報をjson化したファイル、また、HTMLやCSSなどを一式ダウンロードできます。
Screen_Shot_2016-09-30_at_12_08_06_AM.png

必要な環境

このスタイルガイドを案件等で利用するにはNode.jsの環境が必要です。というのも、このスタイルガイドジェネレーターは、表示する内容をJSONから読み込む仕組みだからです。
手作業で、JSONファイルを作成するわけにもいきませんので、HTMLなどを保存した際に自動でJSONファイルを生成するためのgulpなどの環境が必要となってきます。

Screen Shot 2016-09-30 at 10.50.30 PM.png

始めよう

1. まずはローカル環境にnpmでインストール

$ npm install atomic-lab

2. プロジェクトの初期化

$ $(npm bin)/atomic-lab init
Options:
  --src Theme/Components directory (this directory will be compiled to the dist directory) [string]
  --dist The directory Where Atomic Lab page will be created [string]
  --sample Whether You want to get some sample components or not [boolean]

3. プロジェクトのビルド

コマンドラインから
$ $(npm bin)/atomic-lab build
Options:
  --src Theme/Components directory (this directory will be compiled to the dist directory) [string]
  --dist The directory Where Atomic Lab page will be created [string]
  --markup You can choose from html/ejs/jade/haml [string]
gulpを使ったビルド
var gulp = require('gulp');
var atomic = require('atomic-lab');
var bs = require('browser-sync').create();

gulp.task('atomic', function(){
        atomic.build({
            src:"./components",
            dist:"./atomic-lab/resources/setting.json",
            markup:"ejs"//html jade hamlなど
        }).then(bs.reload());
});

gulp.task('default', function () {
    bs.init({
        server: "./atomic-lab/"
    });
    gulp.watch('components/**',['atomic']);
});

なお、atomic.build()を実行したい際に、そのファイルをJSONへの取り込み対象にするには、下記のようなスタイルでコメントを記述する必要があります。

<!--@doc
# @category molecule
# @name main-visual
# @css ./main-visual.sass
-->
  • category: atom molecule organism templateから選択
  • name : Atomic Labに表示したい名前
  • css : このHTMLファイルから該当するCSSファイルへの相対パス

4. 最終的に以下のような構成でスタイルガイドを設置します。

以下はあくまで例になります。

Your Project/
├── atomic-lab/
│   └── resource/
│       └── setting.json
│
├── themes or components here (HTMLなどをここに設置します)/
│   └── ** (ここをWatchします)

設定の変更

また、制作環境に合わせて、設定を変更することも可能です。

config.js
var config = {
    title:"Atomic Lab.",
    /*
        read data from jsonfile
        instead of localstorage
    */
    read_from_local_file:true,
    /*
    */
    local_file_path:"./resources/setting.json",
    /*
        run js on preview mode
    */
    run_script:true,
    /*
        used for Google URL shortener
    */
    use_url_shortener:true,
    key:"AIzaSyDNu-_s700JSm7SXzLWVt3Rku5ZwbpaQZA",
    css_dependencies:[

    ],
    markup:"ejs",//html,ejs,jade,haml
    styling:"sass",//css,sass,less,stylus
    parser:{
        preview:{
            start:/<!--@preview/g,
            end:/-->/g,
            body:/<!--@preview(([\n\r\t]|.)*?)-->/g
        },
        note:{
            start:/<!--@note/g,
            end:/-->/g,
            body:/<!--@note(([\n\r\t]|.)*?)-->/g
        },
        template:{
            start:/<!--@template(.*?)-->/g,
            end:/<!--@\/template(.*?)-->/g,
            body:/<!--@template(.*?)-->(([\n\r\t]|.)*?)<!--@\/template(.*?)-->/g
        },
        import:{
            body:/<!--@import parts="(.*?)" -->/
        },
        variable:{
            mark:/{(.*?)}/g
        }
    }
}

例えば、コメントをHTMLではなく、ReactなどのJSXに記述したいということもあると思います。その際は、Parserを例えば以下のようにJavaScript用のコメントに書き換えてください。

parser:{
    preview:{
        start:/\/\*\*@preview/g,
        end:/\*\*\//g,
        body:/\/\*\*@preview(([\n\r\t]|.)*?)\*\*\//g
    },
    note:{
        start:/\/\*\*@note/g,
        end:/\*\*\//g,
        body:/\/\*\*@note(([\n\r\t]|.)*?)\*\*\//g
    },
    template:{
        start:/\/\*\*@template(.*?)\*\*\//g,
        end:/\/\*\*@\/template(.*?)\*\*\//g,
        body:/\/\*\*@template(.*?)\*\*\/(([\n\r\t]|.)*?)\/\*\*@\/template(.*?)\*\*\//g
    },
    import:{
        body:/\/\*\*@import parts="(.*?)" \*\*\//
    },
    variable:{
        mark:/{(.*?)}/g
    }
}