asteroid/bibi/wardrobe/README-Dress_ja/02_Customize.md

ドレス作成・運用ガイド　２．カスタマイズ編
================================================================================================================================

この README では、テンプレートからのカスタマイズでオリジナルのドレスを作る人に向けて、ソースフォルダに含まれる各ファイルの役目を概説します。
先に「ドレス作成・運用ガイド（１）はじめに」（01_Introduction.md）を読んでおいてください。




ドレス開発環境の起動
--------------------------------------------------------------------------------------------------------------------------------

「はじめに」（01_Introduction.md）では、次のコマンドでドレスファイルの生成を確認しました。

```
npm run build
```

カスタマイズ後も最終的にはこのコマンドでドレスファイルを生成するのですが、カスタマイズの最中は、次の開発用コマンドのほうが便利です。

```
npm start
```

この開発用コマンドを実行すると、ローカルでサーバが立ち上がり、ブラウザでビビが開かれます。
この状態でドレスのソースファイルを編集すると、その成果は、ブラウザをリロードしなくとも自動的に画面に反映されます。※1※2

最後までドレス開発が終わったら、開発用コマンドで実行されている処理を止めたうえで、改めて `npm run build` を実行し、サーバ設置用のドレスファイルを生成するのを忘れないようにしてください。

開発用コマンドの実行中にもドレスファイルは仮生成されていますが、これは、開発時の詳細な確認には適しているものの最終的には不要なコードが大量に含まれており、容量的にも記述内容的にも非常に重いファイルです。
これをそのままサーバに設置して使用するのは避けてください（表面上は問題なく使用できてしまいますが、実用に向かず、閲覧者やネットワークにも迷惑をかけてしまいます）。

　＊

※1 - ソースファイルを編集してもブラウザ上にスタイルの変更内容が自動反映されないときは、__src/bibi/index.html 内の記述がカスタマイズ中のドレスファイルを使うようになっているか、確認してください
※2 - もし `npm start` 後に dresses.js を編集した場合、`npm start` し直すまでその成果は反映されません。






ドレスのソースフォルダ内の構成
--------------------------------------------------------------------------------------------------------------------------------

「はじめに」に引き続き、あたらしく作成するドレスの名前は仮に cocktail であるとしておきます。

次のファイル構成図は、_template フォルダを複製・リネームして作った cocktail フォルダ（cocktail ドレスのソースフォルダ）内から、編集対象となるファイルのみを挙げたものです。
構成図に挙がっていないファイルは、生成処理が利用するためのものなので、編集しないでください。

```
+ dev-bib/
  + i/
    + res/
      + styles/
        + wardrobe/
          + cocktail/
            - _arrows.scss
            - _help.scss
            - _icons.scss
            - _main.scss
            - _menu.scss
            - _nomble.scss
            - _notifier.scss
            - _panel.scss
            - _slider.scss
            - _spinner.scss
            - _stage.scss
            - _subpanels.scss
            - _veil.scss
            - bibi.dress.scss
```

説明と理解の双方の便宜上、この構成図どおりのアルファベット順ではなく、次の順で説明していきます。
これを目次として、順次読んでいってください。

1. bibi.dress.scss … すべてが集約される基幹ファイル（より独自性の強いカスタマイズもここで）
2. _stage.scss … ビビ全体に関わるスタイルや、他の細部に継承される大元のスタイル
3. _main.scss … 本の表示部分のスタイル
4. _menu.scss … 画面上部に固定されている **Menu** UI（メニューバー）のスタイル
5. _slider.scss … 画面下部（縦スクロール時は右）にあり、画面中央タップ／クリックで拡張される **Slider** UI のスタイル
6. _notifier.scss … 画面上部にあらわれる **Notifier**（通知）UI のスタイル
7. _veil.scss … 本が開かれる前に画面全体を覆っている **Veil** UI のスタイル
8. _help.scss … UI にマウスカーソルを合わせたときに画面下部にあらわれる **Help** UI のスタイル
9. _panel.scss … 左上アイコンから開かれる、目次・ナビゲーション・書誌情報をまとめた **Panel** UI のスタイル
10. _subpanels.scss … メニューバーのアイコンから具体的なメニューリストとして開かれる **Subpanel** UI のスタイル
11. _icons.scss … メニューバーと Subpanel 内のアイコンそれぞれのスタイル
12. _spinner.scss … 時間のかかる処理中に画面中央に表示される **Spinner** UI のスタイル
13. _nombre.scss … Slider UI の側に現れる現在の表示位置・ページ数を示す **Nombre**（ノンブル）UI のスタイル
14. _arrows.scss … 画面左右端（縦スクロール時は上下端）にあらわれる **Arrow** UI のスタイル

　＊

なお、具体的なカスタマイズの際には、各ファイル内の個々の変数・ミックスインが具体的に何を司るのかが重要ですが、できるかぎり名前でそれが自明となるように努めてあります。
とはいえ、わかりづらそうなものを中心に、いくつかの変数・ミックスインには、各ファイル中でそれぞれの側にコメントを添えてあります。
変数・ミックスインには命名規則があり、理解しておくとカスタマイズの助けになると思いますので、このドキュメント末尾の「参考）変数とミックスインの命名規則について」を参考にしてください。






bibi.dress.scss … すべてが集約される基幹ファイル（より独自性の強いカスタマイズもここで）
--------------------------------------------------------------------------------------------------------------------------------

最終的にはすべてのソースファイルのカスタマイズ成果がこのファイルに集約され、生成結果に出力されます。

```
@import "@";
```

ファイル中にあるこの１行によって、他のソースファイルの読み込みや、それに基づく実際のスタイルの生成など、すべての処理を呼び込んでいます。

したがって、

1. この１行を消去しない限りは、基本的に自由に編集できます。
2. もし必要であれば、この１行の前で、何度も使う独自の変数やミックスインを定義しておいて、他のソースファイル内で使うこともできます。
3. もし必要であれば、この１行の後に、ドレスのカバー範囲を超える内容のスタイルを自由に記述することができます。           

@import 文前後に可能な自由記述では、たとえば、@import 文で任意の Sass モジュールファイルを読み込むこともできます。
また、冒頭にある複数行コメントは、削除しても構いませんし、ドレス作成者の情報などを記述するために使うこともできます。

　＊

なお、この「唯一の @import 文ですべてのスタイルを生成する。したがってその前後に自由記述ができる」という仕様は、将来のバージョンにわたって堅持するつもりでいます。
つまり、ドレスに予め用意された仕組みを超えてスタイルを拡張したい場合は、上のルールに沿って、この bibi.dress.scss 内に記述したり、ここを起点に @import したりして編集するのが安全です。そうしておけば、ドレス機能のバージョンアップ時にも各ドレスをそれに併せて更新しやすい状態が維持されます。

また、今後ドレス機能自体のアップデートがあった場合、ソースフォルダ中の各ソースファイルに用意されたカスタマイズ可能な変数は、増えたり減ったりする可能性があります。
そうした場合も、独自拡張を bibi.dress.scss に集約しておけば、他の各ソースファイルを新しいバージョンのテンプレートに基づく内容へと更新しやすいはずです。

もしドレス機能のバージョンアップで新しく設定可能な変数が増え、そのバージョンのビビで古いドレスを生成処理にかけた場合も、あらたな変数による設定値にはデフォルトが使用されるだけで、問題なくドレスファイルが生成される見込みです。
そしてもちろん、新規追加変数の値は、テンプレートに倣ってドレスソースフォルダ内に追加定義すればカスタマイズ可能となります。

ちなみに変数が減る場合というのは、そこがカスタマイズ可能ではなくなったり、カスタマイズ対象がなくなったりする場合に考えられます。その場合も、仮になくなった変数の定義がドレスに残っていたとしても、生成処理で無視されるだけで、エラーなどは生じません。




_stage.scss … ビビ全体に関わるスタイルや、他の細部に継承される大元のスタイル
--------------------------------------------------------------------------------------------------------------------------------

ビビ全体に関わるスタイルが定義されています。

現在、全体のフォント指定のみが存在していますが、今後増えるかもしれません。




_main.scss … 本の表示部分のスタイル
--------------------------------------------------------------------------------------------------------------------------------

書籍を表示する部分全体の背景色や、読み込み中アイテムの背景色や「Loading...」表示などをカスタマイズできます。

「Loading...」文字列は疑似要素の content で実装されており、これは画像に変えたりすることも可能です。




_menu.scss … 画面上部に固定されている **Menu** UI（メニューバー）のスタイル
--------------------------------------------------------------------------------------------------------------------------------

メニューバーの高さや閲覧者の操作状況ごとの背景色、内部のアイコンのサイズと閲覧者の操作状況ごとの色、その他構成要素の各スタイルがカスタマイズできます。

メニューバーは、様々な状況に応じて背景色や透明度を変化させることで、普段は閲覧者の読書を邪魔せず、設定変更したいときにはそれに応えられるようになっています。
カスタマイズする場合は、UI としての挙動に一貫性を保ち、閲覧者が快適に読書・操作できるように気をつけてください。

また、デフォルトでは、これ以降に紹介するいくつかのソースファイル内でメニューバーの高さ設定である $Menu_Height を参照し、様々な要素のレイアウトをメニューバーの高さに揃えています。
それぞれの場所で別々の値を上書き指定することもできるようになっていますが、基本的にはメニューバーの高さに合わせたままにしておくことをお勧めします。

アイコンの、基本サイズと色以外のスタイルは、後述の _icons.scss で、これも後述の Subpanel UI 内に現れるアイコンと統一して行うようにしてあります。
_icons.scss 内では、デフォルトのデザインが利用しているのとは異なるアイコンフォントを利用したり、フォントではなくそれぞれ任意の画像に変更したり、抜本的で深いカスタマイズも可能です。




_slider.scss … 画面下部（縦スクロール時は右）にあり、画面中央タップ／クリックで拡張される **Slider** UI のスタイル
--------------------------------------------------------------------------------------------------------------------------------

Slider は、平常時はスクロールバーを模しており、画面中央のタップ／クリック時には大きくなってデザインを変える UI です。
_slider.scss では、それぞれの状態の各パーツの色や大きさ、余白取りなどなど、様々なカスタマイズが可能です。

Slider は閲覧者の頻繁な操作が想定される繊細な UI なので、様々な操作に矛盾なく応えられるデザインになるよう、とくに細かく注意を払ってください。




_notifier.scss … 画面上部にあらわれる **Notifier**（通知）UI のスタイル
--------------------------------------------------------------------------------------------------------------------------------

最初のローディング時に進捗を表示したり、表示設定の変更時やエラー発生時に通知を行う Notifier の文字色や背景色をカスタマイズできます。

デフォルトでは _menu.scss 内でメニューバーの高さを指定する変数を参照し、高さをメニューバーに揃えてあります。
変更することもできますが、メニューバーと同じかそれ以上の高さを持たせておくことをお勧めします。




_veil.scss … 本が開かれる前に画面全体を覆っている **Veil** UI のスタイル
--------------------------------------------------------------------------------------------------------------------------------

読み込み中や、埋め込み状態などでクリック／タップで開かれるのを待っているとき、あるいはドラッグ＆ドロップを待機しているとき、または非対応環境に表示するメッセージなど、本が開かれる前の段階で画面全体を覆っているのが Veil UI です。その表示をカスタマイズできます。

自動的に本が開かれる設定で使用している場合、Veil は、EPUB に表紙が定義されてあればそれを、なければ簡単な書誌情報を表示してローディング中の画面を覆いますが、そのごく短い間に１度だけ現れます。この背景色などがカスタマイズできます（EPUB に表紙が定義されていない場合に書誌情報に添えて表示されるアイコンは、現在のところ変更できません）。

また、埋め込み状態など、設定によってクリック／タップで開かれるのを待っている場合は、動画再生アイコンに似たアイコンを表示しています。このアイコンなどもカスタマイズできます。

設定によってドラッグ＆ドロップによるローカル EPUB ファイルのオープンを許可している場合は、枠線やアイコンが表示されます。この線の色などもカスタマイズ可能です（本のかたちのアイコンは、現在の所変更できません）。




_help.scss … UI にマウスカーソルを合わせたときに画面下部にあらわれる **Help** UI のスタイル
--------------------------------------------------------------------------------------------------------------------------------

メニュー項目にカーソルを合わせたときなどに画面下部に現れる Help UI の、文字色や背景色をカスタマイズできます。

なお、そもそも Help UI を使用するかどうかはプリセットファイルで選択可能です。




_panel.scss … 左上アイコンから開かれる、目次・ナビゲーション・書誌情報をまとめた **Panel** UI のスタイル
--------------------------------------------------------------------------------------------------------------------------------

Panel 内にある目次の文字色や、表紙画像の側の区切り線の色などがカスタマイズできます。

なお、書字方向を横書きに固定するなどの制御は、プリセットファイルで可能です。




_subpanels.scss … メニューバーのアイコンから具体的なメニューリストとして開かれる **Subpanel** UI のスタイル
--------------------------------------------------------------------------------------------------------------------------------

メニュー各項目の文字色などが、閲覧者による設定のオン／オフなどの状況ごとにカスタマイズ可能です。
アイコンや文字の色は、UI としての統一性が求められる箇所なので、デフォルトでは、最初に設定できるキーカラーを利用するように記述してあります。
文字色などはキーカラー設定を無視して個別に定義し直すこともできますが、その場合はアイコンのデザインとの不統一が閲覧者を混乱させないよう、充分に注意してください。

Subpanel 内のアイコンも、基本サイズと色以外のスタイルは、メニューバー内のアイコンと同様、デザインの一貫性を保ちやすいよう、次項の _icons.scss 内に記述されています。
メニューバー内のアイコン同様、アイコンフォントを変更したりフォントを使わず任意の画像に変更したり、抜本的なカスタマイズが可能になっています。




_icons.scss … メニューバーと Subpanel 内のアイコンそれぞれのスタイル
--------------------------------------------------------------------------------------------------------------------------------

アプリケーションの UI には、利用者が違和感なく利用でき、納得あるフィードバックを得られるような、一貫したマナーに基づくインタラクションが求められます。
とくに、閲覧者の捜査結果を反映して外見を変えることも多いボタンや、そこにあしらわれるアイコンでは、この点が非常に重要です。

したがって、アイコンの現れる場所はメニューバー内であったり Subpanel 内であったりと個別に異なりますが、基本的なスタイルはここでまとめて指定できるようになっています。

多くのアイコンは、デフォルトでは Material Icons アイコンフォントを利用しています。
これを別のアイコンフォントにしたり、あるいはフォントを使用せずに任意の画像に変更したりといった深いカスタマイズにも対応しています（それぞれ、変数ではなく、変更可能な部分に絞った mixin を用意してあります）。

_menu.scss や _subpanels.scss と行き来して、見て美しく操作して気持ちのよいデザインを作ってください。




_nombre.scss … Slider UI の側に現れる現在の表示位置・ページ数を示す **Nombre**（ノンブル）UI のスタイル
--------------------------------------------------------------------------------------------------------------------------------

背景色と文字色のカスタマイズが可能です。

なお、画面中央をタップしたとき（Slider が大きくなっているとき）以外は表示しない、あるいはそもそも Nombre を利用しない、といった制御はプリセットファイルで可能です。




_arrows.scss … 画面左右端（縦スクロール時は上下端）にあらわれる **Arrow** UI のスタイル
--------------------------------------------------------------------------------------------------------------------------------

アイコンの色や大きさを、閲覧者の操作状況ごとにカスタマイズできます。

Arrow の各アイコンも、他のアイコン系要素同様、デフォルトのアイコンフォント利用をやめて画像にするなどの深いカスタマイズが可能です。




_spinner.scss … 時間のかかる処理中に画面中央に表示される **Spinner** UI のスタイル
--------------------------------------------------------------------------------------------------------------------------------

やや特殊な内容になっています。

大きな mixin 内の CSS を自由に編集可能とすることで、たとえば１枚のアニメーション GIF 画像にしてしまうなど、デフォルトのデザインにとらわない自由なデザインのスピナーが利用できるようにしました。

ビビのデフォルトでは混み入った CSS で特殊なスピナーを構築してあり、それがテンプレート中の mixin の内容ですが、この特殊なスピナー各部の色や形状をカスタマイズできるようにするよりも、独自のスピナーに置き換えられるほうが需要に合うだろう、という判断からです。

たとえば独自のアニメーション GIF 画像に置き換える場合は、span 要素の display を none にして、:before, :after 各疑似要素は用いず、mixin 直下に背景画像でアニメーション GIF を使用するなどの方法が考えられます（:before 疑似要素の content に画像を入れる方法も考えられます）。

そうした場合は @keyframes の定義は不要になりますので、コメントアウトしてください（削除しても構いません）。




参考）変数とミックスインの命名規則について
--------------------------------------------------------------------------------------------------------------------------------

変数定義は、原則として `$[対象要素]_[対象スタイル]: [設定値];` という書式になっています（言い換えると `$[この要素の]_[このスタイルを]: [この値に];` です）。
ミックスインの場合は `$[対象要素] { [対象スタイル]: [設定値]; }` です。

`[対象要素]` 内では、ハイフン繋ぎで要素の親子関係を示している場合があります。

`[対象スタイル]` は、原則的には CSS プロパティをパスカルケース（アッパーキャメルケース）で表記したものです。
いくつかの例外もありますが、その場合も要素の「なんのスタイルか」を示すことには違いありません。各変数に添えられたコメントを参考にしてください。

`[対象スタイル]` に続けて `__[バリエーション]` が加わる場合があります（`$[対象要素]_[対象スタイル]__[バリエーション]: [設定値];`）。
OS の違い、ホバーなどのカーソルアクションの状況の違い、設定変更によるビビの表示状態の違い、などなど、状況を限定する条件を示しています。

`[設定値]` は、ほとんどすべての場合 CSS プロパティに対する設定値です。先行して設定しておいた変数を参照することもできます。

````````````````````````````````````````````````````````````````````````````````````````````````
// ex.)

$Subpanel-Button_BackgroundColor: white;
// 対象要素： Subpanel-Button（Subpanel 内のボタン）
// 対象スタイル： BackgroundColor（background-color プロパティ＝背景色）
// 設定値： white

$Subpanel-Button_BackgroundColor__Active: $Subpanel-Button_BackgroundColor;
// 対象要素： Subpanel-Button（Subpanel 内のボタン）
// 対象スタイル： BackgroundColor（background-color プロパティ＝背景色）
// バリエーション： Active（ボタンがアクティブなとき＝クリック／タップ時・トグル／ラジオボタンの有効表示時）
// 設定値： $Subpanel-Button_BackgroundColor（先に設定した値と同値にする目的で参照している＝white）
````````````````````````````````````````````````````````````````````````````````````````````````

ほか、先頭に `DEFAULT__` の付されたミックスインがいくつか存在しています。
これは、複数のドレスソースファイルで使用されることを前提に用意された変数で、基本的には _stage.scss 内で定義されています。