star-erp/.agents/rules/ui-consistency.md

trigger

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