# Spindle UI
Spindle (Ameba Design System) UI Components
 
Spindle UIは、Amebaのデザインシステム「Spindle」で定義されたコンポーネントを配布するライブラリです。様々なタイプのプロジェクトに導入できるように設計されています。
## インストール
```
npm install @openameba/spindle-ui
```
```
pnpm add @openameba/spindle-ui
```
## 利用方法
Spindle UIは以下のように利用できます。
```JavaScript
import React from 'react';
import ReactDOM from 'react-dom';
import { Button } from '@openameba/spindle-ui';
// Tree Shakingされない環境下では個別にインポートすることを推奨します
// 例）`import { Button } from '@openameba/spindle-ui/Button';`
// コンポーネントを利用する際には対応するCSSも読み込みます
import '@openameba/spindle-ui/Button/Button.css';
function App() {
return ;
}
ReactDOM.render(, document.querySelector('#app'));
```
Spindle UIはmodule版の配信もしています。利用する際には、[導入ガイド](https://github.com/openameba/spindle/pull/175)を参考にしてください。
さらなる詳細は[コンポーネント一覧](#コンポーネント一覧)を参照してください。
> **_NOTE:_** アイコン利用時は[Spindle IconsのReactコンポーネント](/packages/spindle-icons#react)を読み、注意点を確認してください。
## コンポーネント一覧
利用可能なコンポーネントは、[Storybook](https://ameba-spindle.web.app/)で公開されています。各コンポーネントの開発状況は[Spindleサイトのコンポーネントステータスページ](https://spindle.ameba.design/components/status/)をご覧ください。
## スタイリング
Spindle UIのスタイルは、名前空間(`spui`)をもったCSSとして定義されています。これはスタイルを利用時に再定義する必要がないほか、コンポーネント志向のアプリケーションだけでなく、HTMLを中心としたWebページでも利用可能にするためです。
スタイルは以下の方法で利用できます。
### 必要なスタイルのみをビルド (推奨)
[webpack](https://webpack.js.org/)や[PostCSS](https://postcss.org/)、[Sass](https://sass-lang.com/)などを利用してアプリケーションに必要なスタイルのみをビルドします。生成したファイルは各アプリケーションで利用しているサーバから配信します。
この方法ではCSSファイルのサイズが最小限になり、配信サーバの品質も管理可能なため、できる限りこの方法での利用を推奨します。
### CDNから読み込み
簡易的にSpindle UIのスタイルを試す場合には、CDNから読み込むと便利です。Webページの読み込み速度がそこまで重要でない場合、例えば開発環境や一部のランディングページなどで利用できます。
```HTML
```
ただし、CSSファイルサイズやファイル数が不必要に大きくなり、CDNサーバが遅延の原因になる可能性があるため**本番Webアプリケーションでの利用は推奨していません**。
## ブラウザサポート
Spindle UIはGoogle Chrome最新版で動作確認しています。それ以外のブラウザでは[Amebaの推奨環境](https://helps.ameba.jp/faq/others/5510/top_08.html)に基づき表示・動作に問題がある場合は対応していきます。
## 開発方法
```
pnpm install --frozen-lockfile
pnpm dev # storybookが起動します
```
NOTE: 事前に [spindle-hooks](https://github.com/openameba/spindle/tree/main/packages/spindle-hooks) を以下のようにbuildしておく必要があります。
```
cd ../spindle-hooks
pnpm build
cd -
```
新規コンポーネントを作成する際にはgenerateコマンドが便利です。推奨されるフローは、まずDesign Docを作成しPull Requestします。レビューが終わったらマージし、コンポーネント実装を進めます。
```
pnpm generate
? Please select a document. (Use arrow keys)
❯ design doc
? Please select the output destination directory. (Use arrow keys or type to search)
❯ src/
? Please enter a component name. NewComponent
🐶 Generated 1 files!
✔ src/NewComponent/design-doc.md
```
```
pnpm generate
? Please select a document. (Use arrow keys)
❯ component
? Please select the output destination directory. (Use arrow keys or type to search)
❯ src/
? Please enter a component name. NewComponent
🐶 Generated 7 files!
✔ src/NewComponent/index.ts
✔ src/NewComponent/NewComponent.tsx
✔ src/NewComponent/NewComponent.css
✔ src/NewComponent/NewComponent.stories.mdx
✔ src/NewComponent/NewComponent.test.tsx
✔ src/index.ts
✔ src/index.css
```
## 開発ガイドライン
### アニメーション
Spindleでは、[Amebaらしさ](https://spindle.ameba.design/principles/design/)を表現するためにできる限りアニメーションを付与したいと考えています。ただしプラットフォームでの実装難易度による開発コスト(短期的には開発時間、中長期的には変更のしにくさ、テストのしにくさ、予期せぬ問題の発生)を考慮し、アニメーション対応のガイドラインを作成しました。アニメーションを付与する際には以下のフローにそって判断してください。わからない場合には都度開発メンバーにヒアリングしてください。
- 機能的にアニメーションが必須な場合 (1)
- まず標準的な方法で実装します。それが難しい場合にはハック的な方法を使って実装します (1.1)
- 機能的にアニメーションが必須ではない場合 (2)
- 標準的な方法で実装できる場合は実装します (2.1)
- ハック的な方法が必要な場合は、アニメーション実装をしません (2.2)
## ライセンス
Spindle UIはMITライセンスで公開されています。ただし、アイコンは[Spindle Icons](https://github.com/openameba/spindle/tree/main/packages/spindle-icons#%E3%83%A9%E3%82%A4%E3%82%BB%E3%83%B3%E3%82%B9)に準じて、Creative Commons BY-NC-ND 4.0ライセンスで公開されています。
## 関連ドキュメント
- [Design Doc](docs/design-doc.md)