---
trigger: always_on
---

---
name: 客戶端後台 UI 統一規範
description: 確保 Star ERP 客戶端（租戶端）後台所有頁面的 UI 元件保持統一的樣式與行為
---

## 適用範圍

本規範適用於租戶端後台（使用 `AuthenticatedLayout` 的頁面），**不適用於**中央管理後台（`LandlordLayout`）。

## 核心禁止事項

- ❌ **禁止 Hardcode 色碼**（如 `text-[#01ab83]`），必須使用 `*-primary-main` 等 Tailwind Class 或 CSS 變數
- ❌ **禁止使用非 `lucide-react` 的圖標庫**（如 FontAwesome、Material Icons）
- ❌ **禁止操作按鈕不包裹 `<Can>` 權限元件**

---

## 1. 色彩系統

### 主題色（動態租戶品牌色，由 `AuthenticatedLayout` 自動注入）

| Tailwind Class | 用途 |
|---|---|
| `*-primary-main` | 主色：按鈕、連結、強調 |
| `*-primary-dark` | Hover 狀態 |
| `*-primary-light` | 次要強調 |
| `*-primary-lightest` | 背景底色、Active 狀態 |

### 灰階與狀態色

直接參考 `resources/css/app.css` 中定義的 `--grey-0` ~ `--grey-5` 與 `--other-success/error/warning/info` 變數。

---

## 2. 按鈕規範

樣式定義於 `resources/css/app.css`，按鈕必須使用以下類別：

| 類型 | 類別 | 用途 |
|---|---|---|
| Filled | `button-filled-primary` | 主要操作（新增、儲存） |
| Filled | `button-filled-success/info/warning/error` | 各狀態操作 |
| Outlined | `button-outlined-primary` | 次要操作（編輯、檢視） |
| Outlined | `button-outlined-error` | 刪除按鈕 |
| Text | `button-text-primary` | 文字連結式按鈕 |

**尺寸**：表格操作列用 `size="sm"`，一般操作用 `size="default"`，主要 CTA 用 `size="lg"`。

**返回按鈕**：放置於標題上方，使用 `variant="outline"` + `className="gap-2 button-outlined-primary"`，搭配 `<ArrowLeft />` 圖標。

---

## 3. 圖標規範

統一使用 `lucide-react`。

| 尺寸 | 用途 |
|---|---|
| `h-4 w-4` | 按鈕內、表格操作 |
| `h-5 w-5` | 側邊欄選單 |
| `h-6 w-6` | 頁面標題 |

常用映射：`Plus`(新增)、`Pencil`(編輯)、`Trash2`(刪除)、`Eye`(檢視)、`Search`(搜尋)、`ArrowLeft`(返回)。
其餘請參考 `AuthenticatedLayout.tsx` 中的 `allMenuItems` 定義。

---

## 4. 頁面佈局規範

所有頁面遵循以下結構，參考範例：`Pages/Product/Create.tsx`、`Pages/PurchaseOrder/Create.tsx`。

**關鍵規則**：
- **外層容器**：`className="container mx-auto p-6 max-w-7xl"`
- **標題樣式**：`text-2xl font-bold text-grey-0 flex items-center gap-2`
- **說明文字**：`text-gray-500 mt-1`
- **麵包屑**：使用 `BreadcrumbItemType`（屬性為 `label`, `href`, `isPage`），不需要包含「首頁」
- **Input 元件**：不額外設定 focus 樣式，直接使用 `@/Components/ui/input` 的內建樣式
- **日期顯示**：使用 `resources/js/lib/date.ts` 的 `formatDate` 工具
- **數字顯示**：
    - 所有的金額、數量等數值，應視情境使用千分位格式化（如 `1,234.56`）。
    - **精確顯示**：數值應按實際數值顯示，避免在小數點後出現多餘的零（例如：應顯示 `10.5` 而非 `10.500`）。
    - 數值應與單位（如 `元`、`kg`）保持適當間距或清晰呈現。
    - 負數應視情境明確標示（如使用紅色 `text-other-error` 或負號）。
    - 列表中的數值建議靠右對齊 (text-right)，以便於視覺比較。

---

## 5. 表格規範

**容器**：`bg-white rounded-xl border border-gray-200 shadow-sm overflow-hidden`
**標題列**：`bg-gray-50`，序號欄 `w-[50px] text-center`，操作欄置中
**空狀態**：`text-center py-8 text-gray-500`，顯示「無符合條件的資料」
**操作欄**：`flex items-center justify-center gap-2`

### 排序（三態切換）

- 未排序：`ArrowUpDown`（`text-muted-foreground`）
- 升冪：`ArrowUp`（`text-primary`）
- 降冪：`ArrowDown`（`text-primary`）
- 後端必須處理 `sort_by` 與 `sort_order` 參數
- 參考實作：`Pages/Product/Index.tsx` 的 `handleSort`