mama/star-cloud
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
daf8b1ebccc2292c3a390a33fc2553c903e4ccec
star-cloud/.agents/skills/ui-minimal-luxury/SKILL.md
sky121113 ea0333d77e
All checks were successful
star-cloud-deploy-demo / deploy-demo (push) Successful in 59s
Details
[STYLE] 系統用語標準化與客戶管理 UI 點選透明度優化 (所屬單位 -> 公司名稱、姓名 -> 名稱)
2026-03-30 10:16:05 +08:00

16 KiB
Raw Blame History

name, description
name description
極簡奢華風 UI 實作規範 (Minimal Luxury UI) 定義 Star Cloud 管理後台的「極簡奢華風」設計規範，包含 CSS Tokens、常用組件樣式、動畫效果與互動模式，確保全站 15+ 模組的視覺一致性。

極簡奢華風 UI 實作規範 (Minimal Luxury UI)

本文件定義了 Star Cloud 專案的核心視覺語言。所有新頁面與組件開發必須嚴格遵守此規範。

1. 核心設計令牌 (Design Tokens)

色彩系統 (CSS Variables)

位於 resources/css/app.css：

  • --color-luxury-deep: #0f172a (深色背景)
  • --color-luxury-card: #1e293b (卡片背景)
  • --color-accent: #06b6d4 (青色點綴，適用於按鈕與標示)

字體 (Typography)

  • 內文字體: Plus Jakarta Sans
  • 標題/顯示字體: Outfit
  • 特性: 標題需帶有 letter-spacing: -0.02em 以增強精密感。

2. 核心組件樣式

豪華卡片 (Luxury Card)

<div class="luxury-card p-6 rounded-2xl animate-luxury-in">
    </div>
  • 特效: 懸停時帶有 Y 軸平移與深度投影。

側邊導覽項 (Luxury Nav Item)

<a href="#" class="luxury-nav-item active">
    <i class="lucide-icon"></i>
    <span>節點名稱</span>
</a>
  • 啟用狀態: 左側帶有圓角直條指示器，並輔以青色發光陰影。

按鈕組件 (Buttons)

  • Primary: .btn-luxury-primary (青色漸層，適用於建立、儲存)
  • Secondary: .btn-luxury-secondary (白色/深色背景，帶邊框，適用於編輯、篩選)
  • Ghost: .btn-luxury-ghost (無背景，適用於取消、查看更多)
<button class="btn-luxury-primary">
    <i class="lucide-plus w-4 h-4"></i>
    <span>建立新機台</span>
</button>

<button class="btn-luxury-ghost">取消</button>

3. 動畫與互動

進場動畫

  • .animate-luxury-in: 所有的主內容區域或卡片在頁面載入時，應具備由下而上的淡入效果。

互動過渡 (Transitions)

  • 標準時間: 所有的懸停、色彩變換等過渡效果，統一建議使用 duration-300 (300ms)。
  • 例外: 極其細微的透明度變化可縮短至 150ms，但涉及背景色與位移的互動一律以 300ms 為準。

Alpine.js 互動模式 (以時間選擇器為例)

  • 互動原則: 點擊觸發下拉選單時，必須使用 x-transition 且帶有 scale 偏移。
  • 樣式要求: 選單背景需使用玻璃擬態 (Glassmorphism) 或帶透明度的深色背景。

4. 實作檢查清單 (Checklist)

  • 列表佈局: 是否採用「整合式卡片」結構且內距設為 p-8？
  • 分頁與總數: 列表底部是否正確召喚 vendor.pagination.luxury？
  • 刪除動作: 是否已全面使用 <x-delete-confirm-modal /> 封裝執行路徑？
  • 文字色階: 符合標題 slate-900/white 與標籤 slate-500 的對比度。
  • 可讀性檢查: 二級資訊是否達到 text-xs (12px) 且權重不超過 font-bold？

5. 開發注意事項 (Important Notes)

技術限制備忘

  • CSS 編譯: 複雜的 box-shadow 或漸層應直接寫原生 CSS 屬性，避免在 @apply 中使用帶空格的數值導致編譯失敗。
  • 深色模式: 互動式按鈕在深色模式下必須強化文字亮度（dark:text-white），並輔以青色發光效果。

即時動態呈現規範

  • 格式: #機台編號 動作內容 (例如 #V-001 執行出貨)。
  • 脈絡: 必須呈現相對時間與機台位置。

6. 頁面佈局規範 (Page Layout)

佈局決策規則 (Layout Decision Rules)

根據篩選條件的複雜程度，選擇適當的清單頁面佈局：

1. 整合式佈局 (Integrated Layout) - 【預設推薦】

  • 適用場景: 絕大多數 CRUD 列表。
  • 實作方式: 篩選器、工具列與資料表格全部封裝在同一個 luxury-card 中。
  • 內距規範: 強制使用 p-8 以獲得最佳空氣感。
  • 元件間距: 篩選區與表格之間固定使用 mb-10。
  • 範例: 帳號管理、角色設定、機台日誌。

2. 分離式佈局 (Split Layout)

  • 適用場景: 複雜查詢 (Filtered Fields >= 3 或多行篩選)。
  • 實作方式: 篩選區獨立為一個 luxury-card，下方間隔 mb-6 後再放置資料清單卡片。
  • 樣式規範: 篩選卡片通常使用 p-6（緊湊式），清單卡片使用 p-8（寬鬆式）。
  • 範例: 交易紀錄、機台日誌。

標準寬版佈局 (Wide Layout)

@section('content')
<div class="space-y-6">
    <div class="flex flex-col md:flex-row md:items-center md:justify-between gap-6">
        <div>
            <h1 class="text-3xl font-black text-slate-800 dark:text-white tracking-tight font-display">{{ __('Title') }}</h1>
            <p class="text-sm font-bold text-slate-500 dark:text-slate-400 mt-1 uppercase tracking-widest">{{ __('Subtitle') }}</p>
        </div>
        <div class="flex items-center gap-3">
            <button class="btn-luxury-primary">
                <i class="lucide-plus w-4 h-4"></i>
                <span>新增</span>
            </button>
        </div>
    </div>

    <div class="luxury-card rounded-3xl p-8 animate-luxury-in">
        <div class="flex items-center justify-between mb-10">
            <form class="relative group">
                <input type="text" class="luxury-input pl-12 pr-6 w-64" placeholder="{{ __('Search...') }}">
            </form>
        </div>

        <div class="overflow-x-auto">
            <table class="w-full text-left border-separate border-spacing-y-0">
                <thead>
                    <tr class="bg-slate-50/50 dark:bg-slate-900/10">
                        <th class="px-6 py-4 text-[11px] font-black text-slate-400 uppercase tracking-[0.2em] border-b border-slate-100 dark:border-slate-800">{{ __('Name') }}</th>
                        <th class="px-6 py-4 text-[11px] font-black text-slate-400 uppercase tracking-[0.2em] border-b border-slate-100 dark:border-slate-800 text-right">{{ __('Action') }}</th>
                    </tr>
                </thead>
                <tbody class="divide-y divide-slate-50 dark:divide-slate-800/80">
                    <tr class="group hover:bg-slate-50/80 dark:hover:bg-slate-800/40 transition-all duration-300">
                        <td class="px-6 py-6 font-extrabold text-slate-800 dark:text-slate-100">Example Name</td>
                        <td class="px-6 py-6 text-right"> </td>
                    </tr>
                </tbody>
            </table>
        </div>

        <div class="mt-8 border-t border-slate-100/50 dark:border-slate-800/50 pt-6">
            {{ $items->links('vendor.pagination.luxury') }}
        </div>
    </div>
</div>
@endsection

佈局核心原則:

  1. 移除重複內距: 根容器 div 應禁止使用 p-6 或 p-10，因為佈局基底已提供基礎間距。
  2. 區塊間隙: 建議使用 space-y-6 或 space-y-8 以獲得最佳空氣感。但在「高密度資料管理」或使用者有特殊緊湊需求的情境下，容許縮減至 space-y-2。
  3. 主容器樣式: 強制對齊為 luxury-card rounded-3xl p-8。
  4. 標題排版:
    • 主標題需應用 font-display (Outfit)。
    • 描述文字需應用 uppercase tracking-widest font-bold 以呈現高級設計感。

7. 表單元件規範 (Form Elements)

針對輸入框與下拉選單，強制使用以下類別以確保深色模式質感。

輸入框與選單

  • 類別: .luxury-input, .luxury-select
  • 特性:
    • 深色模式下具備半透明背景與背景模糊效果。
    • 統一的 rounded-xl 圓角與 font-bold 字體。
    • 聚焦時帶有青色 (Cyan) 發光邊框。
<input type="text" class="luxury-input" placeholder="請輸入內容">

<select class="luxury-select">
    <option value="1">啟用</option>
    <option value="0">禁用</option>
</select>

### 搜尋式下拉選單 (Searchable Select) - 【進階推薦】
- **組件**: `<x-searchable-select />`
- **適用場景**: 選項大於 10 筆或具備層級關聯的篩選器（如：公司名稱、機台編號）。
- **奢華特徵**:
  - **動態旋轉箭頭**: 透過 `::after` 偽元素實作，選單展開時箭頭執行 `300ms` 的 180 度旋轉動畫。
  - **即時過濾**: 輸入關鍵字即時隱藏不匹配項。
  - **選取標示**: 選取的項目右側帶有青色 (`Cyan`) 的勾選小圖標。
  - **全部選項修復 (Space Fix)**: 若用於篩選（如公司篩選），組件內部已實作「空格佔位符」機制。若選單中的「全部」選項在選取後消失，請確保該選項的值為單個空格 (`value=" "`)。這能繞過 Preline 對空標記的隱藏邏輯，並同步觸發 Laravel 的 `blank()` 判定。

```html
<x-searchable-select 
    name="company_id" 
    :options="$companies" 
    :selected="request('company_id')" 
    :placeholder="__('All Companies')"
    onchange="this.form.submit()" 
/>


## 8. 編輯與詳情頁規範 (Detail & Edit Views)

為了讓分層資訊更具視覺引導，各個區塊 (Section) 的圖示應採用不同的顏色意象。

### 區塊圖示色彩意象 (Section Icon Palette)
- **基本資訊 (Basic Info)**: **翠綠色 (`Emerald`)**。代表核心、穩定與起點。
    - 樣式: `bg-emerald-500/10 text-emerald-500`
- **硬體/插槽設定**: **琥珀色 (`Amber/Orange`)**。代表動作、物理連接與硬體警告。
    - 樣式: `bg-amber-500/10 text-amber-500`
- **系統/進階設定**: **靛藍色 (`Indigo`)**。代表邏輯、權限與深層配置。
    - 樣式: `bg-indigo-500/10 text-indigo-500`
- **危險/移除動作**: **玫瑰紅 (`Rose`)**。代表破壞性操作。
    - 樣式: `bg-rose-500/10 text-rose-500`

## 9. 資料表格規範 (Data Tables)

為了確保管理後台資料的可讀性與精密感，表格內的所有文字級別必須對齊以下規範：

### 文字大小與權重 (Typography Hierarchy)
- **表頭 (Table Header)**: 
  - 類別: `text-xs font-bold text-slate-500 dark:text-slate-400 uppercase tracking-[0.15em]`
  - 作用: 提供清晰的欄位定義而不奪取資料視覺焦點。具備足夠對比度。
- **主標題 (Primary Item)**: 
  - 類別: `text-base font-extrabold text-slate-800 dark:text-slate-100`
  - 範例: 公司名稱、機體名稱。
- **次要資訊 (Secondary Info)**: 
  - 類別: `text-xs font-bold text-slate-500 dark:text-slate-400 tracking-wide`
  - 範例: 使用者帳號、備註、權限名稱。
- **狀態標籤 (Status Badge)**: 
  - 範例: 啟用 (`emerald`)、禁用 (`rose`) / 角色名稱 (`sky`/`indigo`)。
  - 特性: `px-2.5 py-1 rounded-lg text-xs font-bold border tracking-wider`

### 空間與反應 (Spacing & Interaction)
- **單元格內距**: 統一使用 `px-6 py-6`。
- **懸停反應**: 必須在 `tr` 套用 `group` 且子<E4B894>### 9.4 標竿刪除確認模式 (Luxury Delete Modal Pattern)
當執行刪除或具備破壞性的操作時，**禁止**使用瀏覽器原生 `confirm()` 或簡易的 `x-modal`。全站統一使用 **`<x-delete-confirm-modal />`** Blade 組件進行二次確認。

1. **參數配置**: 
   - `title`: (選填) 預設為「確認刪除」。
   - `message`: (選填) 定義具體的刪除警告訊息（例如「您確定要永久刪除此帳號嗎？」）。
2. **視覺特徵**:
   - **背景**: `bg-slate-900/60 backdrop-blur-sm`。
   - **容器**: `rounded-3xl shadow-2xl animate-luxury-in`。
   - **圖示**: 警告圖示使用 `bg-amber-100/10 text-amber-600`。
   - **按鈕**: 刪除按鈕使用 `bg-rose-500` 搭配 `shadow-rose-200` 投影，取消按鈕使用 `bg-slate-100`。
3. **交互規範**:
   - **禁止斜體 (No Italics)**: 彈窗標題與按鈕文字嚴禁使用 `italic`，保持直挺專業感。

```html
<!-- 使用範例 -->
<x-delete-confirm-modal :message="__('Are you sure you want to delete this account?')" />

10. 系統兼容性與標準化 (Compatibility & Standardization)

為了確保在不同版本的開發環境中（如目前專案使用的 Tailwind CSS v3.1）UI 都能正確呈現，並維持全站操作感一致，必須遵守以下額外規範。

Tailwind CSS 版本兼容性 (v3.1)

  • 禁止使用 size- 屬性: 舊版不支援 size-4 等語法，請一律分拆寫作 w-4 h-4。
  • 避免非標準間距: 避免使用 4.5 (18px) 等任意值，優先使用標準等級如 4 (16px) 或 5 (20px)。

11. 字體與技術資訊規範 (Typography & Technical Data)

為了確保全站「次要資訊」具備極一致的高級感，必須遵守以下「機台標竿」規範：

核心樣式級別 (Core Typography Scale)

資訊類型 客戶/配置名稱 (標題) 技術代碼 (ID, SN, Code) 清單時間 (Timestamps) 分隔符號 (•)
字體族 font-sans (Plus Jakarta Sans) font-mono (微縮型單雙格) font-mono (或 sans 視場景) font-sans
尺寸 text-base text-xs (不可使用 10px) text-xs text-xs
字重 font-extrabold (800) font-bold (700) font-black (900) font-bold
字距 tracking-tight (-0.02em) tracking-widest (最寬) tracking-widest tracking-normal
格式 保持原始名稱 uppercase (強制大寫) uppercase N/A
色彩 slate-900 / slate-100 slate-500 / slate-400 slate-400 / slate-400/80 slate-300 / slate-700

實作禁忌與準則

  • 禁止斜體 (No Italics): 名稱欄位嚴禁附帶 italic（特別是標題或配置名稱），保持直挺專業感。
  • 作用範圍 (Mono Scoping): font-mono 僅限作用於「純英文/數字」的代碼。Email 或分隔點必須回歸 font-sans 以確保圓潤。
  • 權重載入 (Font Weights): 確保 HTML Header 載入了 800 與 900 權重，避免瀏覽器模擬出的假粗體。
  • 清單資訊密度: 對於高密度清單中的時間資訊，應優先使用 font-black 與 tracking-widest 來建立明確的「標籤感」，而非僅僅是「微縮文字」。

12. 提示與告警規範 (Alerts & Notifications)

為了確保全站操作回饋的一致性與專業感，所有系統內部的提示（成功、錯誤、警告）必須遵循以下規範。

1. 懸浮式自動消失提示 (Auto-hiding Toasts)

  • 視覺樣式:
    • 位置: 固定於畫面上方中央 (fixed top-8 left-1/2 -translate-x-1/2)。
    • 特效: 毛玻璃背景 (backdrop-blur-xl)、圓角 (rounded-2xl)、軟陰影。
    • 動畫: 滑入 (translate-y-0) / 滑出 (-translate-y-4)，配合 opacity 變化。
  • 型態定義:
    • Success (成功): 使用 emerald 色系。
    • Error (錯誤): 使用 rose 色系。
  • 時長規範:
    • 成功提示: 3 秒後消失。
    • 錯誤提示: 5 秒後消失（提供使用者更多閱讀錯誤原因的時間）。
  • 組件實作: 統一調用 <x-toast />。

2. 視窗內操作警告 (Inline Action Warnings)

  • 適用場景: 在 Modal 或編輯頁面中，提示可能導致風險的操作（如編輯自身角色）。
  • 視覺樣式:
    • 背景: bg-amber-500/10 (琥珀色)。
    • 邊框: border-amber-500/20。
    • 進場動畫: animate-luxury-in。
  • 實作範例:
<div class="p-5 bg-amber-500/10 border border-amber-500/20 text-amber-600 rounded-2xl flex items-start gap-4 animate-luxury-in font-bold">
    <!-- Icon & Text -->
</div>

3. 通用豪華確認與告警視窗 (General Luxury Modals)

統一準則: 所有的系統確認 (Confirm) 或重要告警 (Alert/Warning) 必須 捨棄 x-modal 組件，改用 Section 9.4 定義的自定義 Div 結構。

  • 警告模式 (Warning/Alert):
    • 僅提供「關閉/確定」一個按鈕。
    • 樣式同 9.4，但隱藏刪除 Form 與相關色彩。
  • 確認模式 (Confirm):
    • 提供「取消」與「執行」兩個按鈕。
    • 執行按鈕顏色視操作性質而定 (Delete: rose, Save/Action: cyan)。

Important

開發新功能前，必須確認 app.css 中的 .btn-luxury-* 系列組件是否滿足需求。 嚴禁在 Blade 中寫入大量重複的 bg-indigo-600 等舊式類別。

Tip

當遇到未定義的 UI 區塊時，優先參考 admin.dashboard.blade.php 的卡片與即時動態實作方式進行衍生。

Reference in New Issue View Git Blame Copy Permalink