pixiv · fsubal · Mar 22, 2022 · Mar 8, 2022 · Mar 8, 2022 · Mar 8, 2022
diff --git a/docs/.nojekyll b/docs/.nojekyll
diff --git a/docs/_coverpage.md b/docs/_coverpage.md
@@ -1,13 +1,12 @@
-![logo](images/logo.svg)
-
 # Charcoal
 
-> Utility-first & layered design system
+> Design system library by pixiv
 
-- ☑ Supports both CSS-in-JS and CSS
-- ☑ Optimized for gradual adoption
-- ☑ Helps you write your components
+- ユーティリティファーストな設計
+- CSS-in-JS と CSS 両方で使える
+- 既存のプロジェクトに導入がしやすい
- ユーティリティファーストな設計
- CSS-in-JS と CSS 両方で使える
- 既存のプロジェクトに導入がしやすい
- ユーティリティファーストな設計
- CSS-in-JS と CSS 両方で使える
- 既存のプロジェクトに導入がしやすい
 
-[Get Started](#docsify)
+[GitHub](https://github.com/pixiv/charcoal/)
+[Get Started](#main)
 
-![](images/logo.svg)
+![color](#ffffff)
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
@@ -1,23 +1,25 @@
-- はじめに
-
-  - [ライブラリを選択する](pages/choose.md)
-
-- 定数集
+- 定数
 
   - [🏛 @charcoal/foundation](pages/constants/foundation.md)
   - [🎨 @charcoal/theme](pages/constants/theme.md)
   - [🖌️ @charcoal/pixiv-theme](pages/constants/pixiv-theme.md)
 
 - ユーテリティ
 
-  - [❓ ユーティリティとはなにか？](pages/utilities/what.md)
   - [💅 @charcoal/styled](pages/utilities/styled.md)
-  - [🍃 @charcoal/tailwind](pages/utilities/tailwind.md)
+  - [🍃 @charcoal/tailwind-config](pages/utilities/tailwind-config.md)
 
 - コンポーネント
 
   - [⚛️ @charcoal/react](pages/components/react.md)
+  - [⏳ @charcoal/react-sandbox](pages/components/react-sandbox.md)
   - [⭐ @charcoal/icons](pages/components/icons.md)
 
-- [コントリビュートしたい方へ](pages/contribution.md)
-- [Changelog](pages/changelog.md)
+- その他
+
+  - [♻️ @charcoal/icons-cli](pages/misc/icons-cli.md)
+  - [👀 @charcoal/tailwind-diff-cli](pages/misc/tailwind-diff-cli.md)
+  - [🔨 @charcoal/utils](pages/misc/utils.md)
+
+- [Storybook](https://pixiv.github.io/charcoal)
+- [Changelogs](https://github.com/pixiv/charcoal/releases)
diff --git a/docs/images/favicon.ico b/docs/images/favicon.ico
diff --git a/docs/images/flowchart.png b/docs/images/flowchart.png
diff --git a/docs/images/layers.png b/docs/images/layers.png
diff --git a/docs/images/logo.svg b/docs/images/logo.svg
diff --git a/docs/index.html b/docs/index.html
@@ -2,8 +2,9 @@
 <html lang="ja">
   <head>
     <meta charset="UTF-8" />
-    <title>Charcoal</title>
+    <title>Charcoal - Design system for content platforms</title>
     <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
+    <link rel="shortcut icon" href="./images/favicon.ico" type="image/x-icon">
     <meta name="description" content="Description" />
     <meta
       name="viewport"
@@ -13,14 +14,7 @@
       rel="stylesheet"
       href="https://cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css"
     />
-    <style>
-      html,
-      body {
-        font-family: system-ui, -apple-system, 'Segoe UI', Roboto, Ubuntu,
-          Cantarell, 'Noto Sans', 'Hiragino Kaku Gothic ProN', Meiryo,
-          sans-serif;
-      }
-    </style>
+    <link rel="stylesheet" href="./theme/docsify.charcoal.css">
   </head>
   <body>
     <div id="app"></div>

diff --git a/docs/pages/choose.md b/docs/pages/choose.md
diff --git a/docs/pages/components/icons.md b/docs/pages/components/icons.md
@@ -1,22 +1,27 @@
-# `@pixiv-elements/icons`
+# `@charcoal/icons`
 
-ピクシブのすべてのプロダクトで利用可能なアイコンライブラリです。中身
-は[Custom Element](https://developer.mozilla.org/ja/docs/Web/Web_Components/Using_custom_elements)と
-して実装されています。
+SVG アイコンを [Custom Elements](https://developer.mozilla.org/ja/docs/Web/Web_Components/Using_custom_elements)として利用できるライブラリです。
 
 ### インストール
 
+npm
+
+```bash
+npm i --save-dev @charcoal/icons
 ```
-$ yarn add @pixiv-elements/icons
+
+yarn
+
+```bash
+yarn add -D @charcoal/icons
 ```
 
 ### 使い方
 
-アプリケーションのエントリポイントで `import` します。 Storybook の場合は `preview.(js|ts)` に書くと
-良いでしょう。
+アプリケーションのエントリポイントで `import` します。 Storybook の場合は `preview.(js|ts)` に書くと良いでしょう。
 
 ```ts
-import '@pixiv-elements/icons'
+import '@charcoal/icons'
 ```
 
 これだけで、 `<pixiv-icon>` という HTML タグが利用可能になります。
@@ -46,7 +51,7 @@ TypeScript 環境下では、`KnownIconType` という型を拡張すること
 くようになります。
 
 ```ts
-import PixivIcon from '@pixiv-elements/icons'
+import PixivIcon from '@charcoal/icons'
 import NewFeature from './NewFeature.svg'
 
 PixivIcon.extend({
@@ -55,7 +60,7 @@ PixivIcon.extend({
   '32/NewFeature': NewFeature,
 })
 
-declare module '@pixiv-elements/icons' {
+declare module '@charcoal/icons' {
   export interface KnownIconType {
     '16/NewFeature': unknown
     '24/NewFeature': unknown
@@ -70,11 +75,10 @@ Custom Element は **`className` という props を受け取ることが通常
 
 https://ja.reactjs.org/docs/web-components.html#using-web-components-in-react
 
-もし `styled-components` などを使っていて `className` を渡せないと困るケースでは、ラッパーコンポーネ
-ントを作ってください。
+もし `styled-components` などを使っていて `className` を渡せないと困るケースでは、ラッパーコンポーネントを作ってください。
 
 ```tsx
-import { Props as IconProps } from '@pixiv-elements/icons'
+import { Props as IconProps } from '@charcoal/icons'
 
 interface Props extends Omit<IconProps, 'class'> {
   className?: string
@@ -84,3 +88,7 @@ export const Icon: React.FC<Props> = ({ className, ...props }) => (
   <pixiv-icon class={className} {...props} />
 )
 ```
+
+### 収録アイコン
+
+[Storybook](https://pixiv.github.io/charcoal?path=/story/icons-pixivicon-pixiv-icon--default) をご覧ください
diff --git a/docs/pages/components/react-sandbox.md b/docs/pages/components/react-sandbox.md
@@ -0,0 +1,23 @@
+# `@charcoal/react-sandbox`
+
+charcoal デザインシステムに則った React コンポーネントを試験的に公開しているパッケージです。
+
+`@charcoal/react` と比較して破壊的な変更が頻繁に行われる可能性があります。
+
+## インストール
+
+npm
+
+```bash
+npm i @charcoal/react-sandbox
+```
+
+yarn
+
+```bash
+yarn add @charcoal/react-sandbox
+```
+
+## コンポーネント
+
+[Storybook](https://pixiv.github.io/charcoal) をご覧ください
diff --git a/docs/pages/components/react.md b/docs/pages/components/react.md
@@ -0,0 +1,21 @@
+# `@charcoal/react`
+
+charcoal デザインシステムに則った React コンポーネントを提供します。
+
+## インストール
+
+npm
+
+```bash
+npm i @charcoal/react
+```
+
+yarn
+
+```bash
+yarn add @charcoal/react
+```
+
+## コンポーネント
+
+[Storybook](https://pixiv.github.io/charcoal) をご覧ください
diff --git a/docs/pages/constants/foundation.md b/docs/pages/constants/foundation.md
@@ -0,0 +1,17 @@
+# `@charcoal/foundation`
+
+charcoal デザインシステムで利用されるプリミティブな型定義や値を提供します。
+
+## インストール
+
+npm
+
+```bash
+npm i @charcoal/foundation
+```
+
+yarn
+
+```bash
+yarn add @charcoal/foundation
+```
diff --git a/docs/pages/constants/pixiv-theme.md b/docs/pages/constants/pixiv-theme.md
@@ -0,0 +1,17 @@
+# `@charcoal/pixiv-theme`
+
+TODO
+
+## インストール
+
+npm
+
+```bash
+npm i @charcoal/pixiv-theme
+```
+
+yarn
+
+```bash
+yarn add @charcoal/pixiv-theme
+```
diff --git a/docs/pages/constants/theme.md b/docs/pages/constants/theme.md
@@ -0,0 +1,17 @@
+# `@charcoal/theme`
+
+charcoal 全体で制約されるテーマ構造の型を提供します。
+
+## インストール
+
+npm
+
+```bash
+npm i --save-dev @charcoal/theme
+```
+
+yarn
+
+```bash
+yarn add -D @charcoal/theme
+```
diff --git a/docs/pages/index.md b/docs/pages/index.md
@@ -1,24 +1,31 @@
-# @charcoal ― PIXIV Design System monorepo
+# charcoal について
 
-This is the monorepo for the `@charcoal` packages by pixiv.
+charcoal はピクシブ株式会社のデザインシステムです。ここでは特に、Web フロントエンドの実装に用いる npm パッケージ集のことを言います。
 
-# Development
+## charcoal という名前
 
-## Setup
+「charcoal（木炭）」とはデッサンの道具であり、線を引く、表現の基礎となる素材の一つです。また創作物を主役とするサービスの基盤として、それ自体は色を持たないモノクロの素材である、というニュアンスも含みます。
 
-Requires `yarn` and `nodenv`.
+## 設計思想
 
-```sh
-nodenv install `cat .node-version`
-yarn install
-yarn lerna bootstrap
-yarn build
-```
+charcoal はいわゆるコンポーネント実装も含みますが、それ以外にも UI の実装に必要なパッケージを多数収録しています。charcoal の設計思想は「定数」「ユーティリティ」「コンポーネント」の三層構造として説明されます。
 
-You should build all the packages first so that each package can import another `@charcoal/*`
-package.
+![デザインシステムの3層構造を説明する図](../images/layers.png)
 
-## Commit
+- 定数（constants）: デザインシステム上にどういう色やスペーシングのルールがあるかを表す。デザイントークン。
+- ユーティリティ（utilities）: 定数の値を CSS の表現に落とし込み、マークアップに使えるようにしたもの。
+- コンポーネント（components）: 見た目と挙動が一体になった、それ単体で利用可能な UI の部品。
 
-`@charcoal` is using [commintlint](https://github.com/conventional-changelog/commitlint) and
-following the [Conventional Commits](https://www.conventionalcommits.org/ja/v1.0.0/) rules.
+## charcoal のはじめ方
+
+charcoal を導入する場合、最初にまず自分たちの技術スタックに適した「ユーティリティ」を選択します。
+
+以下のフローチャートに従って、`tailwind-config` か `styled` を選択してください。
+
+![ユーティリティを決めるためのフローチャート](../images/flowchart.png)
+
+- **Q. React を使用しているか？**
+  - No → [tailwind-config](pages/utilities/tailwind-config.md) を使用する
+  - Yes → **Q. styled-components を使用しているか？**
+    - No → [tailwind-config](pages/utilities/tailwind-config.md) を使用する
+    - Yes → [styled](pages/utilities/styled.md) を使用する
diff --git a/docs/pages/misc/icons-cli.md b/docs/pages/misc/icons-cli.md
@@ -0,0 +1,78 @@
+# `@charcoal/icons-cli`
+
+Figma からアイコンの SVG をダウンロードし、GitHub に自動で更新の Pull Request を作成します。
+
+GitLab にも対応しています。
+
+## インストール
+
+npm
+
+```bash
+npm i --save-dev @charcoal/icons-cli
+```
+
+yarn
+
+```bash
+yarn add -D @charcoal/icons-cli
+```
+
+## 使い方
+
+### Figma からアイコンをダウンロードする
+
+```bash
+yarn icons-cli figma:export
+```
+
+必要な環境変数は以下です。
+
+| 名前            | 必須 | 説明                                                         |
+| --------------- | ---- | ------------------------------------------------------------ |
+| FIGMA_FILE_URL  | yes  | Figma の URL です。node-id は含んでいても良いです            |
+| FIGMA_TOKEN     | yes  | Figma API のアクセストークンです                             |
+| OUTPUT_ROOT_DIR | yes  | svg をダウンロードするディレクトリ（ 例: `packages/icons` ） |
+
+Figma 内のコンポーネントは以下の命名規則に従います（ 例: `16/Add` `Inline/Add` ）。
+
+- `/` を含む
+- `/` の前は数字あるいは `Inline`
+
+### SVG ファイルにアイコン向けの変換をかける
+
+```bash
+yarn icons-cli svg:optimize --file path/to/file --color "#000"
+```
+
+ダウンロードしたファイルに SVGO による最適化をかけつつ、指定した色を `currentColor` に置換します。
+
+### GitHub に Pull Request を作成する
+
+```bash
+yarn icons-cli github:pr
+```
+
+必要な環境変数は以下です。
+
+| 名前                  | 必須 | 説明                                             |
+| --------------------- | ---- | ------------------------------------------------ |
+| GITHUB_ACCESS_TOKEN   | yes  | GitHub のアクセストークンです                    |
+| GITHUB_REPO_OWNER     | no   | リポジトリの owner です（ 例: pixiv ）           |
+| GITHUB_REPO_NAME      | no   | リポジトリ名です（ 例: charcoal ）               |
+| GITHUB_DEFAULT_BRANCH | no   | リポジトリのデフォルトブランチです（ 例: main ） |
+
+### GitLab に Pull Request を作成する
+
+```bash
+yarn icons-cli gitlab:mr
+```
+
+必要な環境変数は以下です。
+
+| 名前                  | 必須 | 説明                                                                          |
+| --------------------- | ---- | ----------------------------------------------------------------------------- |
+| GITLAB_PROJECT_ID     | yes  | GitLab のプロジェクト ID（数値）です                                          |
+| GITLAB_ACCESS_TOKEN   | yes  | GitLab のアクセストークンです                                                 |
+| GITLAB_HOST           | no   | GitLab のホスト名（セルフホスティング版の場合は自身のサーバーのホスト名）です |
+| GITLAB_DEFAULT_BRANCH | no   | リポジトリのデフォルトブランチです（ 例: main ）                              |