@yosgo/swap-ui 1.0.142 → 2.0.0-beta.1

package/README.md

@@ -1,61 +1,75 @@
 <img src="https://blog.swap.work/wp-content/uploads/2021/02/cropped-SWAP_web-logo-01-2.png" width="150" />
 
-# 關於 SWAP-UI
+# SWAP UI（v2）
 
-基於 [@material-ui/core](https://material-ui.com/) 的前端框架來開發 SWAP 專屬的介面框架，這個框架的特性如下：
+SWAP（[www.swap.work](https://www.swap.work)）的品牌 UI 套件，基於 [MUI v9](https://mui.com/) 全面重構。
 
-1. 標準化元件。封裝 SWAP 服務內常見的介面場景，減少開發時重新定義相同的佈局、函式...並讓介面保持一致
-2. 易於使用。儘量不需要再寫額外的輔助函式或是過於多層的元件包裝就能使用，避免 Material-ui 多層包裝的缺點
+**v2 的核心理念是 theme-first**：品牌視覺（色彩、圓角、陰影、字體、各元件外觀）全部定義在一份 SWAP theme 裡——
 
-想要參考 swap-ui 可以透過以下方式：
+1. **原生 MUI 元件自動長成品牌樣式**。`import Button from "@mui/material/Button"` 掛上 theme 後就是 SWAP 的六種按鈕，同時擁有 MUI 完整的元件庫與文件。
+2. **swap-ui 只提供 MUI 沒有的東西**。品牌資產（SWAPLogo）、組合元件（Modal、Card、Snackbar…）、業務元件（TaxTextField）與 design tokens。
+3. **效能**。v1（MUI v4 + JSS）的 runtime 樣式爆量問題在 v2（Emotion + theme 靜態化 + CSS variables）根治。
 
-1. 直接訪問 swap 的網站 [www.swap.work](www.swap.work)
-2. 瀏覽 <a href="https://yosgo-open-source.github.io/swap-ui/?path=/docs/swaplogo--%E8%AA%8D%E8%AD%98" target="_blank">Storybook</a>
+元件預覽與使用手冊：`npm run storybook` 或瀏覽 <a href="https://yosgo-open-source.github.io/swap-ui/v2/" target="_blank">Storybook</a>（v1 手冊仍在 <a href="https://yosgo-open-source.github.io/swap-ui/" target="_blank">根路徑</a>）（每個元件都有「Docs」使用指南與可互動的 Playground）。
 
-即將新增
+# 安裝
 
-1. SWAPModal: 增加支援多步驟的 Modal 視窗
-1. SWAPBanner: 顯示於頁面上的警示訊息
-1. SWAPCopyField：可複製文字至剪貼簿的輸入框
-1. SWAPIncomeAndExpenseTypeField：依據工作內容提供所得類型的建議
-1. SWAPPage: 讓用戶在完整的頁面中完成某件事情
-1. SWAPAnnotatedLayout: 用於帳戶設定頁面中，解釋各類型設定
+```bash
+# peerDependencies（emotion 是 @mui/material 的 optional peer，必須明確安裝）
+npm i react react-dom @mui/material @emotion/react @emotion/styled
 
-# 安裝
+# swap-ui
+npm i @yosgo/swap-ui
+```
+
+# 快速開始
+
+App 最外層包一次 `SWAPThemeProvider`（含品牌 theme、CssBaseline 與自托管字體）：
+
+```tsx
+import { SWAPThemeProvider } from "@yosgo/swap-ui";
 
+<SWAPThemeProvider>
+  <App />
+</SWAPThemeProvider>
 ```
-# peerDependencies
-$ yarn add react react-dom styled-components @material-ui/core @material-ui/icons
 
-# install swap-ui
-$ yarn add @yosgo/swap-ui
+之後：
+
+```tsx
+// 一般元件直接用 MUI，樣式由 theme 自動套用
+import Button from "@mui/material/Button";
+<Button variant="primary" size="large">送出</Button>
+
+// SWAP 專屬元件與 tokens 由 swap-ui 匯出
+import { Typography, Modal, SWAPLogo, swapColors } from "@yosgo/swap-ui";
 ```
 
 # 開發
 
+```bash
+npm run storybook        # 元件預覽與手冊（localhost:6006）
+npm test                 # 兩層測試：jsdom 單元 + Storybook 瀏覽器互動測試
+npm run typecheck        # TypeScript 檢查
+npm run build            # 打包（ESM + CJS + d.ts）
 ```
-# 產生一個元件範本
-$ yarn generate NewComponentName
 
-# 使用本機的 storybook 來瀏覽元件
-$ yarn storybook
-```
+新元件慣例：實作（`src/components/X.tsx` + `X.types.ts`）＋ story（含 Playground、controls 白名單）＋ 手冊（`X.mdx`）＋ 測試，並於 `src/index.ts` 匯出。詳見 `docs/superpowers/` 內的設計文件與各計劃。
 
-# 發佈
+# 發佈（⚠️ 安全規則）
 
-```
-# 發佈套件到 NPM 上
-$ npm publish
+現役產品鎖定 `^1.x`，v2 發佈**不可**推上 `latest`，一律：
 
-# 更新 gh-page 上的 Storybook
-$ yarn deploy-storybook
+```bash
+# 預發佈（beta/alpha）一律指定 next tag
+npm publish --tag next
 
-# 確認發佈狀態
-$ npm show @yosgo/swap-ui
+# 發佈前後確認 dist-tags（latest 必須仍指向 1.x，直到正式切換）
+npm dist-tag ls @yosgo/swap-ui
 ```
 
-# 參考資料
+正式 `2.0.0` 需待產品端遷移驗收完成後，才發佈至 `latest`。完整規則見 `docs/superpowers/specs/2026-07-14-mui-v9-theme-first-migration-design.md` §6.1。
+
+# v1 → v2
 
-- [Creating a React Component Library using Rollup, Typescript, Sass and Storybook](https://blog.harveydelaney.com/creating-your-own-react-component-library/)
-- [Material-ui and Typescript error when bundling #29](https://github.com/transitive-bullshit/react-modern-library-boilerplate/issues/29#issuecomment-635883117)
-- [Shopify Polaris](https://5d559397bae39100201eedc1-jyzwfelqxv.chromatic.com/)
+v1 原始碼封存於 `legacy/v1-src/`（master 分支保持 v1 原樣）。**遷移指南見 [MIGRATION.md](https://github.com/yosgo-open-source/swap-ui/blob/v2/MIGRATION.md)**（import 對照表、breaking 清單、Next.js / React Router 接入、常見錯誤對照），Storybook 手冊側欄最上方亦有同步的「遷移指南」頁。