plume-uiの開発について

plume-uiを開発するときに知っておきたい、コマンドや設計の方針についてです。

コマンド

主要なコマンドです。他のものはnpm scriptsを確認してください。

開発

以下のコマンドでwatch buildとドキュメントのサーバーを同時に起動します

$ npm run dev

ビルド

以下のコマンドで変更をwatchしながらビルドします

$ npm start

以下のコマンドで単純にビルドします

$ npm run build

ドキュメント

Doczでドキュメントを書いています。

mdxというファイル形式で、markdownの中にJSXをimportしてコンポーネントを描画することができます。

少しクセのあるツールですが、人に向けたドキュメントと、リビングドキュメントとしてのコンポーネントを一つのページ内に書けて強力です。VSCodeならmdxを編集するためのプラグインがあります。

リリース

package.jsonの version を更新してmasterブランチにpushするとGithub Actionで自動的にpublishされます。

フォーマット

$ yarn fmt

構成

• ディレクトリレイアウト

ルートには各種設定ファイルなどがあり、src以下にコードがあります。

index.ts / index.scssがそれぞれTS / Sassのエントリーファイルで、新しいコンポーネントを追加する際はそれぞれのファイルからimport / exportします。

componentsディレクトリがコンポーネントのルートです。 stylesは色変数など、コンポーネントでないスタイル関連のコードです。 internalはフレームワーク内部で使用するコンポーネントです。

> tree -L 1 ./src
./src
├── components
├── index.scss
├── index.ts
├── internal
└── styles

コンポーネントディレクトリ以下には、コンポーネントのtsxファイル、スタイルのscssファイル、ドキュメントのmdxファイルを配置します。

❯ tree -L 2 ./src/components
./src/components
└── Tag
    ├── _Tag.scss
    └── Tag.tsx
    └── Tag.mdx

設計方針

plume-uiはアプリケーションを開発する上で、使いやすく拡張しやすいことを目指します。

具体的には以下の点を重視して開発します。

• 上述のmodifierやコンポーネントのプロパティ名が一貫していてAPI・使い方が想像しやすく、ドキュメントを見ればコピーして使えるという使いやすさ。
• コンポーネントが使われるユースケースによって細かい修正を加えたり、少しだけスタイルを変えたりというケースもあり、その全てをUIフレームワークが吸収するのは得策ではないので、利用する側が柔軟に拡張・コントロールできるという拡張しやすさ

命名規則

plume-uiでは一貫した命名規則を守ることで、コンポーネントを利用する際に想像しやすいようにします。

サイズ

コンポーネントやヘルパーでサイズを指定する際には、以下の分類を使います。

normalが基準であり、何も指定していない場合のサイズにします。

詳細な分類が必要ない場合はnormal small largeのみを用意し、必要に応じてmediumやextra largeを追加します。

• extra small
• small
• normal
• medium
• large
• extra large

CSSでは下記のmodifierとしてis-largeのようなクラス名を用意し、Reactコンポーネントではsize='large'のようなpropsを提供します。

CSS

prefix

cssのクラス名に関しては、コンポーネントと対応するものに関しては他のCSSとコンフリクトしないように、pl-というprefixをつけています。

例えばタグのコンポーネントに利用するクラス名に関してはpl-tagと命名します。

modifierについて

pl-tagのようなコンポーネントの基本となるクラスに対して、色やサイズに関してはis-lightやis-mediumという修飾するためのクラス（= modifier）でスタイルを当てます。

<span className="pl-tag is-light is-medium" >example</span>

React

Baseコンポーネント

plume-uiの全てのコンポーネントは、利用する側でコントロール・拡張しやすいようにaspropでHTMLタグを変化したり、スタイルを当てられるようにしています。

詳細はBaseコンポーネントのドキュメントを参照してください。