Merge pull request #340 from pixiv/mimo/tailwind-config-documents

tailwind-configのdocs追加準備
pixiv · Dec 22, 2023 · d95aeef · d95aeef
2 parents ab67ff6 + 7e75a0b
commit d95aeef
Show file tree

Hide file tree

Showing 8 changed files with 2,119 additions and 515 deletions.
diff --git a/docs/package.json b/docs/package.json
@@ -26,8 +26,11 @@
     "@types/react": "18.0.27",
     "@types/react-dom": "18.0.10",
     "@types/styled-components": "^5.1.26",
+    "autoprefixer": "^10.4.16",
     "eslint": "8.33.0",
     "eslint-config-next": "13.1.6",
+    "postcss": "^8.4.32",
+    "tailwindcss": "^3.3.6",
     "typescript": "^5.0.4"
   },
   "resolutions": {

diff --git a/docs/postcss.config.js b/docs/postcss.config.js
@@ -0,0 +1,6 @@
+module.exports = {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+}
diff --git a/docs/src/components/NavList.tsx b/docs/src/components/NavList.tsx
@@ -90,6 +90,17 @@ const iconsList: ListItem[] = [
   },
 ]
 
+const tailwindConfigList: ListItem[] = [
+  {
+    text: 'クイックスタート',
+    href: '/@charcoal-ui/tailwind-config/quickstart',
+  },
+  {
+    text: 'カスタマイズする',
+    href: '/@charcoal-ui/tailwind-config/customize',
+  },
+]
+
 const tailwindDiffList: ListItem[] = [
   {
     text: 'クイックスタート',
@@ -190,6 +201,8 @@ export const NavList: FC<{ className?: string }> = (props) => {
       {reactList.map(renderListItem)}
       <ListItemHeader>@charcoal-ui/icons</ListItemHeader>
       {iconsList.map(renderListItem)}
+      <ListItemHeader>@charcoal-ui/tailwind-config</ListItemHeader>
+      {tailwindConfigList.map(renderListItem)}
       <ListItemHeader>@charcoal-ui/tailwind-diff</ListItemHeader>
       {tailwindDiffList.map(renderListItem)}
       <ListItemHeader>@charcoal-ui/foundation</ListItemHeader>

diff --git a/docs/src/pages/@charcoal-ui/tailwind-config/customize.page.tsx b/docs/src/pages/@charcoal-ui/tailwind-config/customize.page.tsx
@@ -0,0 +1,180 @@
+import { ContentRoot } from '../../../components/ContentRoot'
+import { InlineCode } from '../../../components/InlineCode'
+import { SSRHighlight } from '../../../components/SSRHighlight'
+import { Table } from '../../../components/Table'
+import { dedent } from '../../../utils/string'
+
+export default function CustomizeTailwindConfig() {
+  return (
+    <ContentRoot>
+      <h1>カスタマイズする</h1>
+      <p>
+        <InlineCode>createTailwindConfig()</InlineCode>
+        を利用することでお使いの環境、色などに適応させることができます。
+      </p>
+
+      <SSRHighlight
+        code={dedent`
+            const { light, dark } = require('@charcoal-ui/theme')
+            const { createTailwindConfig } = require('@charcoal-ui/tailwind-config')
+            
+            /**
+             * @type {import('tailwindcss/tailwind-config').TailwindConfig}
+                */
+            module.exports = {
+                darkMode: false,
+                content: ['./src/**/*.tsx', './src/**/*.html'],
+                presets: [
+                createTailwindConfig({
+                    version: 'v3',
+                    theme: {
+                    ':root': light,
+                    '@media (prefers-color-scheme: dark)': dark,
+                    },
+                }),
+                ],
+            }
+        `}
+        lang="javascript"
+      />
+      <p>
+        <InlineCode>createTailwindConfig</InlineCode>
+        には以下のオプションを渡すことができます。
+      </p>
+      <Table data={options} />
+
+      <h2>ThemaMap について</h2>
+      <p>
+        charcoal は Tailwind.css の通常のダークモード（
+        <InlineCode>dark:〇〇</InlineCode> 系のクラス ）をサポートしません。
+        <br />
+        なぜなら charcoal における「色」は、同じ名前でも light テーマと dark
+        テーマで違うカラーコードであり得るからです。
+        <br />
+        これを表現するために
+        <InlineCode>@charcoal-ui/tailwind-config</InlineCode> では
+        <InlineCode>theme</InlineCode> というオプションを受け取ります。
+        <br />
+      </p>
+      <p>
+        以下の例は <InlineCode>:root</InlineCode>（つまり通常ケース）では light
+        テーマを、システムの設定がダークモードである場合は dark
+        テーマを使用するものです。 <br />
+      </p>
+      <SSRHighlight
+        code={dedent`
+            createTailwindConfig({
+                version: 'v3',
+                theme: {
+                    ':root': light,
+                    '@media (prefers-color-scheme: dark)': dark,
+                },
+            })
+            `}
+        lang="javascript"
+      />
+      <p>
+        <InlineCode>theme</InlineCode>
+        オプションを設定する場合、ダークテーマ対応を行わないサービスであっても
+        <InlineCode>:root</InlineCode>
+        に必ず自身のプロダクトのカラーテーマを渡す必要があります。
+      </p>
+      <p>
+        <InlineCode>theme</InlineCode> をこのように書くと、 このような CSS
+        Variables を生成します。
+      </p>
+      <SSRHighlight
+        lang="css"
+        code={dedent`
+            /* 以下はイメージです */
+
+            :root {
+              --tailwind-color-background1: #fff;
+              --tailwind-color-background2: #f5f5f5;
+              /* ... */
+            }
+            
+            @media (prefers-color-scheme: dark) {
+              :root {
+                --tailwind-color-background1: #1f1f1f;
+                --tailwind-color-background2: #000000;
+                /* ... */
+              }
+            }
+        `}
+      />
+      <p>
+        このとき、以下のように書く必要はありません。
+        <br />
+        キーが <InlineCode>@media</InlineCode> で始まる場合はビルド時に
+        <InlineCode>:root</InlineCode> が補われます。
+      </p>
+      <SSRHighlight
+        lang="javascript"
+        code={dedent`
+                {
+                    theme: {
+                        // これは間違い！！
+                        '@media (prefers-color-scheme: dark)': {
+                            ':root': dark
+                        },
+                
+                        // 正しくはこう
+                        '@media (prefers-color-scheme: dark)': dark
+                    }
+                }
+            `}
+      />
+      <p>
+        <InlineCode>theme</InlineCode>
+        のキーとして通常のセレクタを指定することもできます。
+        <br />
+        これによりダークモードの切り替えがDOMの状態に依存するケースにも対応します。
+        <InlineCode>localStorage</InlineCode> などで JS
+        での切り替えを実装しているアプリケーションはこのような手法が好ましいでしょう。
+      </p>
+      <SSRHighlight
+        lang="javascript"
+        code={dedent`
+            createTailwindConfig({
+                version: 'v3',
+                theme: {
+                    ':root': light,
+                    'html[data-theme="dark"]': dark,
+                },
+            })
+        `}
+      />
+      <SSRHighlight
+        lang="css"
+        code={dedent`
+            /* 以下はイメージです */
+
+            :root {
+              --tailwind-color-background1: #fff;
+              --tailwind-color-background2: #f5f5f5;
+              /* ... */
+            }
+            
+            html[data-theme='dark'] {
+              --tailwind-color-background1: #1f1f1f;
+              --tailwind-color-background2: #000000;
+              /* ... */
+            }
+        `}
+      />
+    </ContentRoot>
+  )
+}
+const options = {
+  version: {
+    type: 'v1 | v2 | v3',
+    description:
+      'Tailwind.cssのバージョン系統を指定します。色のキー名に使われる DEFAULT と default などの違いを内部で吸収します。',
+  },
+  theme: {
+    type: 'Record<string, Theme>',
+    description:
+      '条件ごとの色の値のマッピングを渡します。 :root は必須のキーです。',
+  },
+}
diff --git a/docs/src/pages/@charcoal-ui/tailwind-config/quickstart.page.tsx b/docs/src/pages/@charcoal-ui/tailwind-config/quickstart.page.tsx
@@ -0,0 +1,73 @@
+import Link from 'next/link'
+import { ContentRoot } from '../../../components/ContentRoot'
+import { SSRHighlight } from '../../../components/SSRHighlight'
+import { dedent } from '../../../utils/string'
+import { InlineCode } from '../../../components/InlineCode'
+
+export default function InstallPage() {
+  return (
+    <ContentRoot>
+      <h1>@charcoal-ui/tailwind-config クイックスタート</h1>
+      <Link href="https://www.npmjs.com/package/@charcoal-ui/tailwind-config">
+        <img
+          alt="npm-badge"
+          src="https://img.shields.io/npm/v/@charcoal-ui/tailwind-config?label=%40charcoal-ui%2Ftailwind-config&style=flat-square&logo=npm"
+        />
+      </Link>
+      <h2>インストール</h2>
+      <h3>npm</h3>
+      <SSRHighlight
+        code={dedent`
+                    npm install --save-dev @charcoal-ui/tailwind-config
+                `}
+        lang="shell"
+      />
+      <h3>yarn</h3>
+      <SSRHighlight
+        code={dedent`
+                    yarn add -D @charcoal-ui/tailwind-config
+                `}
+        lang="shell"
+      />
+
+      <hr />
+
+      <h2>概要</h2>
+      <p>
+        <InlineCode>@charcoal-ui/tailwind-config</InlineCode>は、Tailwindに
+        <InlineCode>@charcoal-ui/foundation</InlineCode>を適用します。
+      </p>
+
+      <h2>使い方</h2>
+      <p>
+        tailwind.config.js の中で <InlineCode>require</InlineCode>
+        して使います。
+      </p>
+
+      <h3>デフォルトのconfigを使う</h3>
+      <SSRHighlight
+        code={dedent`
+                const { config } = require('@charcoal-ui/tailwind-config')
+                
+                /** @type {import('tailwindcss').Config} */
+                module.exports = {
+                    content: [],
+                    theme: {
+                        extend: {},
+                    },
+                    plugins: [],
+                    presets: [config]
+                }
+                `}
+        lang="javascript"
+      />
+      <p>
+        テーマの調整などが必要な場合は
+        <Link href="/@charcoal-ui/tailwind-config/customize">
+          カスタマイズする
+        </Link>
+        のページを見てください。
+      </p>
+    </ContentRoot>
+  )
+}
diff --git a/docs/src/tailwind.css b/docs/src/tailwind.css
@@ -0,0 +1,3 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
diff --git a/docs/tailwind.config.js b/docs/tailwind.config.js
@@ -0,0 +1,17 @@
+const { light, dark } = require('@charcoal-ui/theme')
+const { createTailwindConfig } = require('@charcoal-ui/tailwind-config')
+
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: ['./src/pages/**/*.tsx', './src/components/**/*.tsx'],
+  presets: [
+    createTailwindConfig({
+      version: 'v3',
+      theme: {
+        ':root': light,
+        '[data-theme="dark"]': dark,
+      },
+    }),
+  ],
+  safelist: [{ pattern: /.*/ }],
+}