エンジニアの副業は週1からでも可能？副業の例や探し方も解説
- ITエンジニア
- 副業
コードの効率やUIの一貫性など多くの利点があることから、人気が集まっている『CSSスタイルガイド』の考え方。
今回はスタイルガイド作成ツールの『DocumentCSS』を使って、CSSスタイルガイドの作り方をチュートリアル形式で解説します。
意思疎通をより強固にする”CSSスタイルガイド”とは？
海外では「リビングスタイルガイド」とも呼ばれています。CSSスタイルガイドは、標準的なスタイルガイドと同じように、アプリケーションの作成のために必要な共通認識や結束力を醸成するためのものです。
しかし標準的なスタイルガイドの目的はあくまでグラフィックとデザインの誤用を防ぐ所にあります。一方でCSSスタイルガイドには、通常のスタイルガイドに加えて次の要素が付加されています。
- ドキュメント化されたエレメントのリスト（下図左「Elements」）
- コードスニペットとインタラクティブUIデモンストレーションによる簡潔なドキュメンテーション（下図右「Documentation」）
CSSスタイルガイドはソースコードから多くの情報を直接得ることができ、アプリケーションの進捗を容易かつ効率的に反映できるという点において、一般的なスタイルガイドに優っているのです。
今回ご紹介する『DocumentCSS』では、スタイルガイドジェネレーターによって考案されたCSSを自動でドキュメント化できたり。Git Hubで公開できたりと、シェアもしやすいです。
『DocumentCSS』を使用してCSSスタイルガイドを作成する方法をご紹介しますが、Bitoviによって作られたこのオープンソースツールは、CSSだけでなくLessやSASSなどのプリプロセッサもサポートしています。『DocumentCSS』はDocumentJSのサブセットなので、Javascriptなどの言語に興味があるかたにもおすすめです。
『DocumentCSS』を使った、CSSスタイルガイドの作り方
1.スタイルガイドの計画を立てよう
CSSスタイルガイドの作成に入る前に、まず内容を決める必要があります。優れたWebサイトと同じように、情報アーキテクチャをうまく構築することがキーポイントです。まずは「Vintage Shop」というサンプルアプリケーションのデザインを使って、UIのエレメントをみてみましょう。
まずはナビゲーション、カート、フォームなど、大きなエレメントのグループからはじめましょう。たとえばステップインジケータ、ミニカート、カート内の製品の三つのグループにデザインをわけます。
これらの大きなグループのエレメントからはじめることによって、ディテールを掘り下げて「スタイル」を見分けることができます。たとえば文字は、見出し、小見出し、リンク、通常のテキストといった種類によってわかれています。これはボタンの色についても同じです。
これらを踏まえて、ダイアグラムを作ってみましょう。
これらのグループを詳しくみてみると、改善の余地があることがわかります。
まず、「Elements」という表記はあらゆるHTMLエレメントとして捉えられる曖昧な言葉なので、「Compornents」や「Modules」という名前がより適切です。これらは依然として幅広い意味を持っていますが、「Elements」よりは具体的であるといえます。また、「Primary vs Secondary」のボタンは「Base Elements」の一部なので、色については「Color Palette」のカテゴリーに入れることができます。
さらに、スタイルガイドに関するより一般的な情報のためのカテゴリも設ける必要があります。スタイルガイドについて説明する「Guides」、または設計と実装にあたって留意すべきガイドラインを含む「Branding」というセクションを作ってみましょう。
このように適切なダイアグラムを作ることによって、CSSスタイルガイドを作成する際に設計図のようにして使用することができます。
次に、デザインについて考えてみましょう。サイトマップを書くときに気をつけたいのが、将来的に必要になるであろうカテゴリーをできるだけたくさん書き出しておくということです。スタイルガイドの例を探して参考にするのもおすすめです。
2. CSSスタイルガイドでページを作ってみよう
CSSスタイルガイドドキュメントの多くはソースコードに追加した特別なコメントに基づいていますが、ほかのタイプのコンテンツをホストできるスタンドアローンのページを作ることもできます。『DocumentCSS』では、ドキュメントをCSSスタイルガイドで集中管理できるという利点があります。
CSSスタイルガイドは「ゲームのルール」のようなものです。「ルール」の中には、ゲームの「遊びかた」に必要な全ての情報、すなわちブロックを作るためのルールが書かれている必要があります。これはチームのメンバーにとって、維持をする際の手助けにもなります。
これらを念頭において、このチュートリアルで使用するサンプルアプリケーションをインストールしてみましょう。
サンプルアプリケーションをインストールする方法
3つのステップでインストールをおこないます。
(1)Node.jsをインストールする
まずNode.jsを.インストールしておきましょう。少なくともバージョン6が必要です。
(2)アプリをインストールする
次に、sgdd-tutorial.zipをデスクトップにダウンロードして解凍します。ほかの場所にインストールするとファイルが壊れてしまう可能性があるので、かならずデスクトップにダウンロードするようにしてください。
解凍できたら、ターミナルをあけて以下のコマンドを入力します。
cd ~/Desktop/vintage-shop-sgdd-tutorial && npm install
数秒すると、アプリがインストールされるはずです。
(3)アプリを起動する
インストールが完了したら、以下のコマンドを入力します
- npm run develop
- npm run document（新しいタブに入力）
以下で細かく内容をみてみましょう。
npm run develop
サーバを起動すると、http://localhost:8080からアプリケーションが動作しているのを確認できます。ターミナルは以下のようになります。
ブラウザ上では以下のように表示されます
rpm run document
http://localhost:8080/styleguideでCSSスタイルガイドを作ります。このコマンドにフラグ「– -w」を追加することによってコードの変更をウォッチし、更新することができます。
npm run document — -w
ブラウザ上では以下のように表示されます。
生成されたCSSスタイルガイドでは『DocumentCSS』を使用しています。どのように機能するのかみてみましょう。
『DocumentCSS』はどのように機能する？
『DocumentCSS』はコード内で特別にフォーマットされたコメントを探し、静的Webサイトを作成する静的サイトジェネレーターです。「静的」と呼ばれているのは、コマンド（この場合はdocumentjs）が再び実行されるまでは変更されないためです。スタイルシートを変更すると静的サイトも変更されるため、このワークフローはCSSスタイルガイドを生成するのに適しているといえます。
『DocumentCSS』は以下のようなプロセスでCSSスタイルガイドを構築します。
- 設定で指定されたファイルを読み込む（この記事においては.lessと.md）
- @page、@stylesheetなど特別な「タグ」を使用するコメントを探す
- HTMLファイルを生成し、それらを接続してサイトを構築する
これを覚えたら、『DocumentCSS』を使ってCSSスタイルガイドに新しいページを作ってみましょう。
4. ページを作ってみよう
まず、コードエディタでサンプルアプリケーションを開きます。以下のようなファイル構造が表示されるはずです。
SRCにドリルダウンし、base/markdownを探します。スタイルガイドに既存のページがあるので、新しいマークダウンファイルを作成し、名前を「about」（拡張子は.md）にします。すると、ファイル構造は以下のようになります。
この新しいファイルの中に、@pageタグとaboutを追加します。
@page about about
以下で細かく内容をみてみましょう。
@page
この@pageというタグはファイルをページとして宣言し、このファイル内の情報をページとして表示する必要があることをDocumentCSSに知らせる役割を果たします。これにより、スタイルシート、Javascript、ドキュメント内のほかのタイプのファイルと区別されます。
@about
ページの名前で、ほかのタグへの参照として使用されます。ページのURLとして使用されるので、短くシンプルにしておきます。この記事においては、新しいページのURLはhttp://localhost:8080/styleguide/about.htmlとなります。
@About
生成されたサイトで表示するために使用されるページのタイトルです。スペースやその他の文字を含む、複数の単語を使用することができます。
新しく作成されたページを表示するためには、ターミナルでdocumentjsをもう一度実行する必要があります。続いて、http://localhost:8080/styleguide/about.htmlにアクセスして新しいページを表示します。
次に、ファイルに二つめのラインを追加することによって、ナビゲーションにページを追加します。
@page about About@parent index
この@parentタグはドキュメントの「親」を指定できます。この記事では「About」ページをホームセクションの下に表示させるのが目的です。以下のようなページが確認できたでしょうか。
左上に表示されている「Welcome」をクリックすると、スタートページにアクセスするはずです。
MarkdownやHTMLを使ってこのページにコンテンツを追加してみましょう。今回は以下のダミーコンテンツを追加してみます。
<code class=" language-markdown">@page about About
@parent index
## Hello World!
This is the first page of my style guide. Here I can add any type of content that shouldn’t live with the code. Like who are the main contributors of the style guide or contact info.
For example here's an animated gif inside of an `iframe`:
<iframe class="giphy-embed" src="https://giphy.com/embed/3o7TKMt1VVNkHV2PaE" width="480" height="480" frameborder="0" allowfullscreen="allowfullscreen"></iframe> </code>
アウトプットは以下のようになります。
5. CSSスタイルガイドでのスタイルシートのドキュメント化
CSSスタイルガイドを作成するにあたって重要なのは、ドキュメントをソースコードに適切に配置することです。すでにこれを実行できているなら、スタイルガイドジェネレーターを使って次のレベルにチャレンジしてみましょう。
スタイルシートのドキュメント化
スタイルシートのドキュメント化は、ページをドキュメント化するのと似ていますが、この場合はコードのすぐ隣にあるコメントの中にドキュメントが入ります。
まず、buttons-custom.lessを開きます。
このファイルのコメントブロックの中に、@stylesheetタグと二つの文字列を追加します。
<code class=" language-css"><span class="token comment" spellcheck="true">/**
@stylesheet buttons.less Buttons
*/</span>
</code>
ドキュメントのコメントは、パーサー（この場合はJSDoc）が認識するために/**ではじまる必要があることを覚えておきましょう。
以下で細かい内容をみていきます。
@stylesheet
この@stylesheetタグはファイルをスタイルシートとして宣言し、このファイルの情報をスタイルガイドに表示するように指示する役割を果たしています。ページやコンポーネントなど、ほかのタイプのドキュメントとの差別化に役立っています。
buttons.less
スタイルシートの名前で、ほかのタグへの参照として使用されます。任意の名前を使用できますが、ドキュメントを参照するときにファイルを見つけやすくなるので、スタイルシートファイルの名前を使用することをおすすめします。また、この名前はドキュメントのURLにも影響します。
Buttons
生成されたサイトで表示するために使用されるページのタイトルです。スペースやその他の文字を含む、複数の単語を使用することができます。
作成したページを表示するには、以下のコマンドを実行します。
documentjs
@parentタグを使ってページを作成した時と同じように、この新しいドキュメントをナビゲーションに追加してみましょう。
<code class=” language-css”><span class=”token comment” spellcheck=”true”>/**
* @stylesheet buttons.less Buttons
* @parent styles.base
*/</span></code>
このケースでは、.base を追加することにより、このページをサイドバーに表示されるグループ「Baseline」の下に表示するように指定しています。
ドキュメントを再実行してページを更新すると、以下のようになります。
ドキュメント化することで、スタイルガイドに次の3つを追加できます。
- ドキュメントの包括的な説明を追加
- MarkdownとHTMLの両方を使ってさまざまなコンテンツを追加
- コードのデモを追加
以下で簡単な説明とデモを追加します。
<code class=” language-css”><span class=”token comment” spellcheck=”true”>/**
* @stylesheet buttons.less Buttons
* @parent styles.base
* @description
* Global style definitions for all button elements.
* @iframe src/base/bootstrap-custom/buttons/buttons-custom.html
*/</span></code>
ドキュメントを再実行してみましょう。
このように、@iframeタグはデモ付きのiframeをドキュメントに追加することを可能にしてくれます。このデモは、アプリケーションにCSSをインポートするスクリプトタグ付きのシンプルなHTMLファイルです。
buttons-custom.htmlのデモをみてみましょう。
コードは以下のようになっています。
<code class=" language-html"><span class="token tag"><span class="token punctuation"><</span>script <span class="token attr-name">src</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>/node_modules/steal/steal.js<span class="token punctuation">"</span></span> <span class="token attr-name">main</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>can/view/autorender/<span class="token punctuation">"</span></span><span class="token punctuation">></span></span><span class="token script language-javascript">
<span class="token operator"><</span><span class="token keyword">import</span> <span class="token string">"vintage-shop/styles.less"</span><span class="token punctuation">;</span>
</span><span class="token tag"><span class="token punctuation"></</span>script<span class="token punctuation">></span></span> <span class="token tag"><span class="token punctuation"><</span>a <span class="token attr-name">class</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>btn btn-default<span class="token punctuation">"</span></span> <span class="token attr-name">href</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>#<span class="token punctuation">"</span></span> <span class="token attr-name">role</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>button<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Link<span class="token tag"><span class="token punctuation"></</span>a<span class="token punctuation">></span></span><span class="token tag"><span class="token punctuation"><</span>button <span class="token attr-name">class</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>btn btn-default<span class="token punctuation">"</span></span> <span class="token attr-name">type</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>submit<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Button<span class="token tag"><span class="token punctuation"></</span>button<span class="token punctuation">></span></span>
<span class="token tag"><span class="token punctuation"><</span>input <span class="token attr-name">class</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>btn btn-default<span class="token punctuation">"</span></span> <span class="token attr-name">type</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>button<span class="token punctuation">"</span></span> <span class="token attr-name">value</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>Input<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token punctuation"><</span>input <span class="token attr-name">class</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>btn btn-default<span class="token punctuation">"</span></span> <span class="token attr-name">type</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>submit<span class="token punctuation">"</span></span> <span class="token attr-name">value</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>Submit<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token punctuation"><</span>hr <span class="token punctuation">/></span></span>
<span class="token tag"><span class="token punctuation"><</span>button <span class="token attr-name">type</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>button<span class="token punctuation">"</span></span> <span class="token attr-name">class</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>btn btn-default<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Default<span class="token tag"><span class="token punctuation"></</span>button<span class="token punctuation">></span></span>
<span class="token tag"><span class="token punctuation"><</span>button <span class="token attr-name">type</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>button<span class="token punctuation">"</span></span> <span class="token attr-name">class</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>btn btn-primary btn-checkout<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Primary<span class="token tag"><span class="token punctuation"></</span>button<span class="token punctuation">></span></span>
<span class="token tag"><span class="token punctuation"><</span>button <span class="token attr-name">type</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>button<span class="token punctuation">"</span></span> <span class="token attr-name">class</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>btn btn-success<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Success<span class="token tag"><span class="token punctuation"></</span>button<span class="token punctuation">></span></span>
<span class="token tag"><span class="token punctuation"><</span>button <span class="token attr-name">type</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>button<span class="token punctuation">"</span></span> <span class="token attr-name">class</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>btn btn-info<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Info<span class="token tag"><span class="token punctuation"></</span>button<span class="token punctuation">></span></span>
<span class="token tag"><span class="token punctuation"><</span>button <span class="token attr-name">type</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>button<span class="token punctuation">"</span></span> <span class="token attr-name">class</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>btn btn-warning<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Warning<span class="token tag"><span class="token punctuation"></</span>button<span class="token punctuation">></span></span>
<span class="token tag"><span class="token punctuation"><</span>button <span class="token attr-name">type</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>button<span class="token punctuation">"</span></span> <span class="token attr-name">class</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>btn btn-danger<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Danger<span class="token tag"><span class="token punctuation"></</span>button<span class="token punctuation">></span></span>
<span class="token tag"><span class="token punctuation"><</span>button <span class="token attr-name">type</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>button<span class="token punctuation">"</span></span> <span class="token attr-name">class</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>btn btn-link<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Link<span class="token tag"><span class="token punctuation"></</span>button<span class="token punctuation">></span></span></code>
このファイルに必要なのはスクリプトタグだけで、このタグはアプリケーションで作成したデモと同じでなければいけません。残りのコードはデモで表示したいスタイルのマークアップです。
さらに、@demoタグを使用して使用されているコードのスニペットを以下のように表示することもできます。
<code class=" language-html">/**
* @stylesheet buttons.less Buttons
* @parent styles.base
*
* @description
* Global style definitions for all button elements.
* @demo src/base/bootstrap-custom/buttons/buttons-custom.html
*/</code>
アウトプットは以下のようになります。
6. スタイルシートセクションの作成
スタイルセクションの作成には@stylesタグを使用します。このタグは、スタイルシートのドキュメントをわかやすいグループに分けることができる便利なタグです。たとえば今回については、色の定義と、使用されるマークアップに関係なくボタンを定義するためのスタイルがあります（<button/>もしくは<a/>のタグ）。
@stylesのタグを使用することによって、色の定義を独自のセクションに分け、なおかつそのセクションに直接ハイパーリンクを設定することが可能です。
同じbutton-custom.lessにおいて、スタイルの最初のブロックのうしろ、色の変数の前に@stylesというタグを追加すると、以下のようになります。
<code class=” language-css”> <span class=”token comment” spellcheck=”true”>/** * @stylesheet buttons.less Buttons * @parent styles.base * * @description * Global style definitions for all button elements. * @demo src/base/bootstrap-custom/buttons/buttons-types.html */</span> <span class=”token selector”>.btn</span> <span class=”token punctuation”>{</span> <span class=”token property”>display</span><span class=”token punctuation”>:</span> inline-block<span class=”token punctuation”>;</span> …<span class=”token punctuation”>}</span> <span class=”token comment” spellcheck=”true”>/** * @styles buttons-colors Button Colors * * @description * Buttons can be displayed in the following colors: * @demo src/base/bootstrap-custom/buttons/buttons-color.html */</span> <span class=”token atrule”><span class=”token rule”>@btn-default-color</span><span class=”token punctuation”>:</span> #333<span class=”token punctuation”>;</span></span></code>
ここでのポイントは二つです。ひとつは最初のデモを更新して、ボタンタイプだけを表示するようにしたということ。もうひとつは、@stylesタグを使って新しいコメントブロックを追加したこと。button-colorsという名前とButton Colorsというタイトルを付け、@descriptionと@demoを追加してボタンの色だけを表示するようにしました。
アウトプットは以下のようになります。
新しいコメントブロックが「Button」ドキュメント内のセクションになりました。このURLから直接アクセスをすることも可能です。
これによって人にスタイルガイドの特定のセクションを伝える際「このページの中の、このセクションをスクロールして……」という面倒な説明をするかわりに、リンクを送るだけで情報を共有することができるようになります。
7. スタイルシートのグループの作成
これに加えて、スタイルガイドのサイドバーにセクションまたはグループを作成することも可能です。以下のようにMarkdownディレクトリにあるstyles.mdファイルを開きます。
@groupというタグがあるのに気がつくはずです。
<code class=” language-markdown”>@page styles Styles @group styles.theme 0 Theme @group styles.base 1 Baseline The styles shown in this section show how elements are styles with definitions from the Bootstrap framework, in addition to any customizations made for this specific project. Therefore they will be available for use in any part of the application.</code>
二行目を細かくみてみましょう。
@group
@groupタグを使用すると、親セクションの下に表示されるサイドバーにセクションを作成することができます。たとえば、「Theme」と「Baseline」のグループは、「Styles」の親セクションの下に表示されます。
styles.theme
グループの名前です。ここでは親セクションの名前を使用することをおすすめします。この場合は「Styles」が採用されています。このように、同じ名前のグループを別のセクションに作成する場合、グループの名前はそのままになります。
０
グループが表示される順序で、0からはじまります。順序が割り当てられていない場合は、グループのリストはアルファベット順に表示されます。
Theme
サイドバーに表示される名前なので、スペースやその他の文字を含む、複数の単語を使用することができます。
実際のグループを確認するには、以下のように新しいグループを作成してみましょう。
<code class=" language-markdown">@page styles Styles
@group styles.theme 0 Theme
@group styles.base 1 Baseline
@group styles.forms 2 Forms
The styles shown in this section show how elements are styles with definitions from the Bootstrap framework, in addition to any customizations made for this specific project. Therefore they will be available for use in any part of the application.</code>
最後に、この新しいセクションの下に既存のドキュメントを追加してみましょう。forms-custom.lessを開きます。
三行目のstyles.baseをstyles.formsに置き換えます。
<code class=" language-less">/**
* @stylesheet forms-custom.less Form Elements
* @parent styles.forms
**/</code>
ドキュメントを実行してブラウザをリフレッシュさせましょう。サイドバーの「Forms」の下に「Form Elements」が表示されているはずです。
おわりに
『DocumentCSS』の使い方をご紹介しました。
一貫性のあるUIデザインを作成するためのツールであるCSSスタイルガイドは、Style Guide Driven Development（SDGG）やモジュールデザインにおいて活用できます。
ぜひ使ってみてください。
（翻訳：Asuka Nakajima）
人気のフリーランス・副業求人
IoTの開発プロジェクト！ヘルスケア・医療データの処理、分析、解析、データマイニングを得意とするインフラエンジニア募集！
- #スタートアップ
職種：バックエンドエンジニア
時給：2,500円 〜
働き方：どちらでも可
エリア：東京都
Web制作をリードするフロントエンド構築、WordPress実装が可能なエンジニア募集！
職種：フロントエンドエンジニア
時給：2,500円 〜
働き方：リモート希望
エリア：東京都
【リモート可】音楽、エンタメ × ITでイノベーションを！API開発をするサーバーサイドエンジニア募集！
- #土日週末OK
- #急募
職種：バックエンドエンジニア
時給：4,000円 〜
働き方：どちらでも可
エリア：東京都
From interviews with the biggest names on the web, to free downloads of incredible assets; from the latest trends, to the coolest code; WebdesignerDepot strives to give you the competitive edge in your design career.
この記事はWebdesignerDepotからの転載です。配信元または著者とコンテンツ契約を結び配信しています。
HOW TO CREATE A LIVING STYLE GUIDE
