diff --git a/.agent/skills/ui-consistency/SKILL.md b/.agent/skills/ui-consistency/SKILL.md index fa2003f..af59d81 100644 --- a/.agent/skills/ui-consistency/SKILL.md +++ b/.agent/skills/ui-consistency/SKILL.md @@ -1,69 +1,130 @@ --- -name: UI 統一性規範 -description: 確保 koori-erp ERP 系統後台所有頁面的 UI 元件保持統一的樣式與行為 +name: 客戶端後台 UI 統一規範 +description: 確保 Star ERP 客戶端（租戶端）後台所有頁面的 UI 元件保持統一的樣式與行為 --- -# UI 統一性規範 +# 客戶端後台 UI 統一規範 ## 概述 -本 skill 提供 koori-erp ERP 系統的 UI 統一性規範，確保所有頁面使用一致的元件、樣式類別、圖標和佈局模式。 +本技能提供 Star ERP 系統**客戶端（租戶端）後台**的 UI 統一性規範，確保所有頁面使用一致的元件、樣式類別、圖標和佈局模式。 + +> **適用範圍**：本規範適用於租戶端後台（使用 `AuthenticatedLayout` 的頁面），**不適用於**中央管理後台（`LandlordLayout`）。 ## 核心原則 -1. **使用統一的 UI 組件庫**：優先使用 `@/Components/ui/` 中的元件 +1. **使用統一的 UI 組件庫**：優先使用 `@/Components/ui/` 中的 47 個元件 2. **遵循既定的樣式類別**：使用 `app.css` 中定義的自定義按鈕類別 3. **統一的圖標系統**：全面使用 `lucide-react` 圖標 4. **一致的佈局模式**：表格、分頁、操作按鈕等保持相同結構 +5. **權限控制**：所有操作按鈕必須使用 `` 元件包裹 --- -## 1. 按鈕規範 +## 1. 專案結構 -### 1.1 按鈕樣式類別 +### 1.1 關鍵目錄 -專案在 `resources/css/app.css` 中定義了統一的按鈕樣式類別，**必須**使用這些類別而非自定義樣式： +``` +resources/ +├── css/ +│ └── app.css # 全域樣式與設計 Token +├── js/ +│ ├── Components/ +│ │ ├── ui/ # 47 個基礎 UI 元件 (shadcn/ui) +│ │ ├── shared/ # 共用業務元件 (Pagination, BreadcrumbNav 等) +│ │ └── Permission/ # 權限控制元件 (Can, HasRole, CanAll) +│ ├── Layouts/ +│ │ ├── AuthenticatedLayout.tsx # 客戶端後台佈局 ⬅️ 本規範適用 +│ │ └── LandlordLayout.tsx # 中央管理後台佈局 +│ └── Pages/ # 頁面元件 +``` -#### Filled 按鈕（實心按鈕） +### 1.2 可用 UI 元件清單 + +``` +accordion, alert, alert-dialog, avatar, badge, breadcrumb, button, +calendar, card, carousel, chart, checkbox, collapsible, command, +context-menu, dialog, drawer, dropdown-menu, form, hover-card, +input, input-otp, label, menubar, navigation-menu, pagination, +popover, progress, radio-group, resizable, scroll-area, +searchable-select, select, separator, sheet, sidebar, skeleton, +slider, sonner, switch, table, tabs, textarea, toggle, toggle-group, +tooltip +``` + +--- + +## 2. 色彩系統 + +### 2.1 主題色 (Primary) + +```css +--primary-main: #01ab83; /* 主題綠色 - 主要操作、連結 */ +--primary-dark: #018a6a; /* 深綠色 - Hover 狀態 */ +--primary-light: #33bc9a; /* 淺綠色 - 次要強調 */ +--primary-lightest: #e6f7f3; /* 最淺綠色 - 背景、Active 狀態 */ +``` + +### 2.2 灰階 (Grey Scale) + +```css +--grey-0: #1a1a1a; /* 深黑 - 標題文字 */ +--grey-1: #4a4a4a; /* 深灰 - 主要內文 */ +--grey-2: #6b6b6b; /* 中灰 - 次要內文、Placeholder */ +--grey-3: #9e9e9e; /* 淺灰 - 禁用文字、輔助說明 */ +--grey-4: #e0e0e0; /* 極淺灰 - 邊框、分隔線 */ +--grey-5: #fff; /* 白色 - 背景、按鈕文字 */ +``` + +### 2.3 狀態色 (State Colors) + +```css +--other-success: #01ab83; /* 成功 - 同主題色 */ +--other-error: #dc2626; /* 錯誤 - 刪除、警示 */ +--other-warning: #f59e0b; /* 警告 - 提醒、注意 */ +--other-info: #3b82f6; /* 資訊 - 說明、提示 */ +``` + +--- + +## 3. 按鈕規範 + +### 3.1 按鈕樣式類別 + +專案在 `resources/css/app.css` 中定義了統一的按鈕樣式，**必須**使用這些類別： + +#### Filled 按鈕（實心按鈕）— 用於主要操作 ```tsx -// 主要操作按鈕（綠色主題色） +// ✅ 主要操作按鈕（綠色主題色）- 新增、儲存、確認 -// 成功操作 +// ✅ 成功操作 -// 資訊操作 +// ✅ 資訊操作 -// 警告操作 +// ✅ 警告操作 -// 錯誤/刪除操作 +// ✅ 錯誤/刪除操作（AlertDialog 內確認按鈕） ``` -#### Outlined 按鈕（邊框按鈕） +#### Outlined 按鈕（邊框按鈕）— 用於次要操作 ```tsx -// 次要操作（主題色邊框） +// ✅ 編輯按鈕（表格操作列） -// 成功樣式邊框 - - -// 資訊樣式邊框 - - -// 警告樣式邊框 - - -// 錯誤/刪除樣式邊框 +// ✅ 刪除按鈕（表格操作列） @@ -72,22 +133,21 @@ description: 確保 koori-erp ERP 系統後台所有頁面的 UI 元件保持統 #### Text 按鈕（文字按鈕） ```tsx -// 文字按鈕 ``` -### 1.2 按鈕大小 +### 3.2 按鈕大小 -使用 shadcn/ui Button 組件的標準尺寸： +| Size | 高度 | 使用情境 | +|------|------|----------| +| `size="sm"` | h-8 | 表格操作列、緊湊佈局 | +| `size="default"` | h-9 | 一般操作、表單提交 | +| `size="lg"` | h-10 | 主要 CTA、頁面主操作 | +| `size="icon"` | 9×9 | 純圖標按鈕 | -- `size="sm"`：小型按鈕（h-8），用於表格操作列 -- `size="default"`：預設按鈕（h-9），用於一般操作 -- `size="lg"`：大型按鈕（h-10），用於主要 CTA -- `size="icon"`：圖標按鈕（size-9），僅含圖標的正方形按鈕 +### 3.3 常見操作按鈕模式 -### 1.3 常見操作按鈕模式 - -#### 新增按鈕（頁面頂部） +#### 頁面頂部新增按鈕 ```tsx @@ -100,7 +160,7 @@ description: 確保 koori-erp ERP 系統後台所有頁面的 UI 元件保持統 ``` -#### 編輯按鈕（表格操作列） +#### 表格操作列編輯按鈕 ```tsx @@ -117,7 +177,7 @@ description: 確保 koori-erp ERP 系統後台所有頁面的 UI 元件保持統 ``` -#### 刪除按鈕（表格操作列，帶確認對話框） +#### 表格操作列刪除按鈕（帶確認對話框） ```tsx @@ -155,19 +215,22 @@ description: 確保 koori-erp ERP 系統後台所有頁面的 UI 元件保持統 --- -## 2. 圖標規範 +## 4. 圖標規範 -### 2.1 圖標庫 +### 4.1 統一使用 lucide-react -**統一使用 `lucide-react`**，不使用其他圖標庫（如 FontAwesome、Material Icons 等）。 +**統一使用 `lucide-react`**，禁止使用其他圖標庫（如 FontAwesome、Material Icons、react-icons 等）。 -### 2.2 圖標尺寸標準 +### 4.2 圖標尺寸標準 -- **小型圖標**：`h-3 w-3`（用於 Badge、小文字旁） -- **標準圖標**：`h-4 w-4`（用於按鈕、表格操作） -- **標題圖標**：`h-6 w-6`（用於頁面標題） +| 尺寸 | 類別 | 使用情境 | +|------|------|----------| +| 小型 | `h-3 w-3` | Badge 內、小文字旁 | +| 標準 | `h-4 w-4` | 按鈕內、表格操作 | +| 標題 | `h-5 w-5` | 側邊欄選單 | +| 大型 | `h-6 w-6` | 頁面標題 | -### 2.3 常用操作圖標映射 +### 4.3 常用操作圖標映射 | 操作 | 圖標組件 | 使用情境 | |------|----------|----------| @@ -185,11 +248,16 @@ description: 確保 koori-erp ERP 系統後台所有頁面的 UI 元件保持統 | 使用者 | ``, `` | 使用者管理 | | 權限 | `` | 角色/權限 | | 排序 | ``, ``, `` | 表格排序 | +| 儀表板 | `` | 首頁/總覽 | +| 商品 | `` | 商品管理 | +| 倉庫 | `` | 倉庫管理 | +| 廠商 | ``, `` | 廠商管理 | +| 採購 | `` | 採購管理 | -### 2.4 圖標使用範例 +### 4.4 圖標使用範例 ```tsx -import { Plus, Pencil, Trash2, Eye, Search } from 'lucide-react'; +import { Plus, Pencil, Trash2, Users } from 'lucide-react'; // 頁面標題

@@ -197,7 +265,7 @@ import { Plus, Pencil, Trash2, Eye, Search } from 'lucide-react'; 使用者管理

-// 按鈕內圖標 +// 按鈕內圖標（圖標在左，帶文字） - + 名稱 操作 @@ -257,33 +306,15 @@ import { Plus, Pencil, Trash2, Eye, Search } from 'lucide-react'; **關鍵要點**： - 使用 `bg-gray-50` 背景色 - 序號欄位固定寬度 `w-[50px]` 並置中 -- 可排序欄位使用 ` - - - - - {/* 刪除確認對話框 */} - - - - -``` +- 操作欄使用 `flex items-center justify-center gap-2` 排列按鈕 --- -## 4. 分頁規範 +## 6. 分頁規範 -### 4.1 統一分頁元件 +### 6.1 統一分頁元件 使用 `@/Components/shared/Pagination` 元件： ```tsx import Pagination from "@/Components/shared/Pagination"; +import { SearchableSelect } from "@/Components/ui/searchable-select"; // 在表格下方
@@ -369,7 +375,7 @@ import Pagination from "@/Components/shared/Pagination";
``` -### 4.2 每頁筆數狀態管理 +### 6.2 每頁筆數狀態管理 ```tsx const [perPage, setPerPage] = useState(filters.per_page || "10"); @@ -386,19 +392,15 @@ const handlePerPageChange = (value: string) => { --- -## 5. Badge 與狀態顯示 +## 7. Badge 與狀態顯示 -### 5.1 基本 Badge - -使用 `@/Components/ui/badge`： +### 7.1 基本 Badge ```tsx import { Badge } from "@/Components/ui/badge"; // Outline 樣式（最常用） - - {item.category?.name || '-'} - +{item.category?.name || '-'} // 預設樣式（主題色背景） 啟用中 @@ -407,9 +409,7 @@ import { Badge } from "@/Components/ui/badge"; 停用 ``` -### 5.2 角色顯示（特殊樣式） - -參考使用者管理的角色顯示模式： +### 7.2 角色顯示（特殊樣式） ```tsx
@@ -439,9 +439,32 @@ import { Badge } from "@/Components/ui/badge"; --- -## 6. 頁面佈局規範 +## 8. 頁面佈局規範 -### 6.1 標準頁面頭部 +### 8.1 頁面結構 + +```tsx +export default function ResourceIndex() { + return ( + + + +
+ {/* 頁面頭部 */} + {/* 主要內容 */} + {/* 分頁元件 */} +
+ + ); +} +``` + +### 8.2 標準頁面頭部 ```tsx
@@ -465,19 +488,11 @@ import { Badge } from "@/Components/ui/badge";
``` -### 6.2 容器寬度 - -```tsx -
- {/* 頁面內容 */} -
-``` - --- -## 7. 權限控制規範 +## 9. 權限控制規範 -### 7.1 使用 Can 元件 +### 9.1 使用 Can 元件 **所有**涉及權限的 UI 元素都必須使用 `` 元件包裹： @@ -497,21 +512,36 @@ import { Can } from "@/Components/Permission/Can"; ``` -### 7.2 權限命名規範 +### 9.2 權限命名規範 遵循 `resource.action` 格式： -- `resource.index`：查看列表 -- `resource.show`：查看詳情 +- `resource.view`：查看列表/詳情 - `resource.create`：新增 - `resource.edit`：編輯 - `resource.delete`：刪除 +### 9.3 多權限判斷 + +```tsx +// 滿足任一權限即可 + +
管理操作
+ + +// 必須滿足所有權限 +import { CanAll } from "@/Components/Permission/Can"; + + + + +``` + --- -## 8. 通知訊息規範 +## 10. 通知訊息規範 -### 8.1 使用 Toast 通知 +### 10.1 使用 Toast 通知 使用 `sonner` 的 `toast` 進行通知： @@ -531,7 +561,7 @@ toast.info('提示訊息'); toast.warning('警告訊息'); ``` -### 8.2 常見操作的 Toast 訊息 +### 10.2 常見操作的 Toast 訊息 ```tsx // 新增成功 @@ -555,38 +585,55 @@ router.delete(route('resource.destroy', id), { --- -## 9. 顏色系統 +## 11. 表單規範 -### 9.1 主題色 +### 11.1 表單容器 -參考 `resources/css/app.css` 中的色彩定義： - -```css ---primary-main: #01ab83; /* 主題綠色 */ ---primary-dark: #018a6a; /* 深綠色 */ ---primary-light: #33bc9a; /* 淺綠色 */ ---primary-lightest: #e6f7f3; /* 最淺綠色背景 */ - ---grey-0: #1a1a1a; /* 深黑色文字 */ ---grey-1: #4a4a4a; /* 深灰色文字 */ ---grey-2: #6b6b6b; /* 中灰色文字 */ ---grey-3: #9e9e9e; /* 淺灰色文字 */ ---grey-4: #e0e0e0; /* 邊框灰色 */ ---grey-5: #fff; /* 白色 */ +```tsx +
+
+ {/* 表單欄位 */} +
+
``` -### 9.2 狀態色 +### 11.2 表單欄位 -```css ---other-success: #01ab83; /* 成功（同主題色）*/ ---other-error: #dc2626; /* 錯誤紅色 */ ---other-warning: #f59e0b; /* 警告橙色 */ ---other-info: #3b82f6; /* 資訊藍色 */ +```tsx +
+ + setData("field", e.target.value)} + placeholder="請輸入..." + className="w-full px-4 py-2 border border-slate-300 rounded-lg focus:ring-2 focus:ring-primary-main focus:border-primary-main" + /> + {errors.field &&

{errors.field}

} +
+``` + +### 11.3 下拉選單 + +使用 `SearchableSelect` 元件： + +```tsx +import { SearchableSelect } from "@/Components/ui/searchable-select"; + + setData("category_id", value)} + options={categories.map(cat => ({ label: cat.name, value: String(cat.id) }))} + placeholder="請選擇分類" + searchThreshold={10} // 超過 10 個選項才顯示搜尋框 +/> ``` --- -## 10. 檢查清單 +## 12. 檢查清單 在開發或審查頁面時，請確認以下項目： @@ -596,27 +643,24 @@ router.delete(route('resource.destroy', id), { - [ ] 編輯操作使用 `button-outlined-primary` - [ ] 刪除操作使用 `button-outlined-error` - [ ] 按鈕尺寸正確（sm/default/lg） -- [ ] 包含適當的圖標（左側或單一圖標） +- [ ] 包含適當的圖標 ### ✅ 圖標 - [ ] 全部使用 `lucide-react` -- [ ] 尺寸正確（h-3/h-4/h-6 w-3/w-4/w-6） +- [ ] 尺寸正確（h-3/h-4/h-5/h-6） - [ ] 顏色與上下文一致 -- [ ] 有明確的語義（編輯=Pencil、刪除=Trash2 等） ### ✅ 表格 - [ ] 使用 `@/Components/ui/table` 元件 -- [ ] 有 `bg-white rounded-lg shadow-sm border` 容器 +- [ ] 有 `bg-white rounded-xl border` 容器 - [ ] 標題列有 `bg-gray-50` 背景 - [ ] 序號欄固定寬度並置中 - [ ] 操作欄使用 `flex justify-center gap-2` - [ ] 空狀態訊息置中顯示 -- [ ] 可排序欄位有排序圖標 ### ✅ 分頁 - [ ] 使用 `@/Components/shared/Pagination` - [ ] 有每頁筆數選擇器（10/20/50/100） -- [ ] 佈局為 `flex justify-between` ### ✅ 權限 - [ ] 所有操作按鈕都用 `` 包裹 @@ -629,23 +673,21 @@ router.delete(route('resource.destroy', id), { ### ✅ 整體 - [ ] 頁面有標準頭部（標題 + 圖標 + 說明 + 新增按鈕） - [ ] 容器寬度使用 `max-w-7xl` -- [ ] 色彩使用符合主題 +- [ ] 使用正確的佈局（`AuthenticatedLayout`） --- -## 11. 常見錯誤與修正 +## 13. 常見錯誤與修正 ### ❌ 錯誤：自定義按鈕樣式 ```tsx -// 錯誤 +// ❌ 錯誤 -``` -```tsx -// 正確 +// ✅ 正確 -``` -```tsx -// 正確 +// ✅ 正確 -
+
@@ -695,12 +731,10 @@ import { Pencil } from 'lucide-react'; // ✅ 使用 lucide-react ### ❌ 錯誤：缺少權限控制 ```tsx -// 錯誤 +// ❌ 錯誤 -``` -```tsx -// 正確 +// ✅ 正確