UI 主題

English | Tiếng Việt

每個主題都是一個在 themes/ 中的資料夾。一個主題包含色彩代碼、共用類別、一系列強調色以及一個範例頁面。每個主題都使用相同的代碼名稱。切換主題意味著交換 CSS 檔案，而不是編輯 HTML。

資料夾和檔案名稱是越南語（此套件在越南製作）。README 中有詞彙表。

使用時機

正在繪製草稿或建立新頁面或應用程式畫面。
使用者傳送螢幕截圖、產品名稱或 URL，並希望採用該視覺風格。請參閱 them-theme.md。
使用者說「使用主題 X」、「將強調色切換為 Y」、「深色模式」。

擁有者的風格

在繪製或建立新主題之前，請先閱讀 phong-cach-owner.md。簡而言之：一個輕量、緊湊的 SaaS 儀表板，包含許多數字和一個強調色（藍色或紫色）。其來源是擁有者儲存為參考的一系列應用程式。

主題

主題	外觀	狀態
clickup-radar	類似 ClickUp 的側邊欄、Scenario Library 卡片、輕量緊湊、紫色強調色	已核准 2026-11-03
saas-sang	擁有者的風格：輕量 SaaS、大數字、藍色強調色、每個主題一個範例頁面	已核准 2026-11-04

themes/_mau 是新主題的空白範本。請勿用它來繪製。

哪個專案使用哪個主題

如果存在，請閱讀此資料夾中的 du-an.md。這是擁有者的私人檔案（已加入 gitignore），它將他們的專案對應到一個主題、一個主題類別和一個強調色，並包含他們的文案慣例（UI 語言、如何稱呼使用者）。請遵循它，無需再次詢問。

沒有 du-an.md：一旦擁有者決定專案的主題，請將 du-an.example.md 複製為 du-an.md，並填入內容。當擁有者為專案確定主題時，請立即更新 du-an.md。

主題類別和範例頁面 (主題 saas-sang)

對於新頁面，請選擇最接近的主題類別，複製其範例頁面，然後移除不需要的部分。

主題類別	範例頁面	預設強調色	適用於
報表、分析	`themes/saas-sang/chu-de/bao-cao.html`	藍色 (`xanh-duong`)	儀表板、KPI、流量和產品分析
任務	`themes/saas-sang/chu-de/cong-viec.html`	紫色 (`tim`)	任務看板、工單、專案追蹤
銷售	`themes/saas-sang/chu-de/ban-hang.html`	靛藍 (`cham`)	商店後台、訂單、付款、庫存
新聞、閱讀	`themes/saas-sang/chu-de/tin-tuc.html`	藍色 (`xanh-duong`)	電子報、部落格、精選摘要
登陸頁面	`themes/saas-sang/chu-de/landing.html`	靛藍 (`cham`)	產品和行銷頁面
登入、註冊	`themes/saas-sang/chu-de/dang-ky.html`	靛藍 (`cham`)	任何應用程式的驗證畫面

索引頁面：themes/saas-sang/vi-du.html。
chu-de/chung.js 僅用於範例頁面。它讀取 ?mode= 和 ?accent=，從 <i data-i> 繪製圖示，並在右下角新增一個介面（外觀）按鈕：淺色/深色/系統、8 種強調色、語言以及通往 bang-chon.html 的連結。選擇會儲存在 localStorage 的 saas-sang-xem 中。當您將頁面複製到真實專案時，請移除 chung.js：將 SVG 內嵌或使用 Lucide，並在 tokens.css 上建立專案自己的主題切換器。
saas-sang 有額外的代碼（--chart --chart-2 --grid --acc2 --acc2-soft --deep* --scrim），請參閱主題 README。
新類別（KPI、圖表、分組表格、對話框、新聞、登陸頁面、登入）在 themes/saas-sang/components.md 中。

語言

UI 文案遵循專案的語言（在 du-an.md 中設定）。若無設定，請使用使用者書寫的語言。
範例頁面使用越南語撰寫。themes/i18n.js 搭配字典 themes/i18n-en.js 可在瀏覽器中將其翻譯成英文。
顯示何種語言：優先檢查 ?lang=en|vi，然後是 localStorage 的 ui-lang，最後是瀏覽器語言（vi* 顯示越南語，其他顯示英文）。
切換方式：saas-sang 頁面上介面面板中的「Ngôn ngữ / Language」列，以及 bang-chon.html 頂部欄的 VI | EN 按鈕，它們會將 ?lang= 傳遞給預覽。
它會翻譯文字、placeholder、title、aria-label 和頁面標題，並監聽稍後新增的內容。
範例頁面上新增或更改的越南語文字：將確切的字串及其英文翻譯新增到 themes/i18n-en.js，然後使用 ?lang=en 開啟頁面並檢查是否還有未翻譯的越南語。
i18n 僅用於示範。真實專案不會複製 i18n.js；請以其自己的語言撰寫文案。

選擇主題

專案在 du-an.md 中：使用該主題和強調色。不要再次詢問。
使用者在訊息中指定了主題或強調色：照做。
兩者皆無：在聊天中提出一個簡短問題，問題中包含所有選項，並使用使用者的語言。例如：

此專案尚未設定主題。要使用 clickup-radar（輕量、緊湊、紫色強調色）、saas-sang（您的風格、藍色強調色），還是您想傳送其他外觀的螢幕截圖？ clickup-radar 強調色：紫色、藍色、天藍色、藍綠色、綠色、橙色、粉紅色、炭黑色。saas-sang 強調色：藍色、紫色、靛藍、天藍色、藍綠色、綠色、橙色、炭黑色。
使用者想要挑選和調整顏色：開啟調色盤（如下）。

調色盤

themes/bang-chon.html。一個調色盤包含網站的所有顏色，而不僅僅是一張卡片的顏色。

版面配置： 左側是調色盤，右側是縮小的網站預覽。具有主題頁面的主題（saas-sang，其在 THEMES 中宣告了 trang 和 macDinh）會預覽所選用途的頁面；其他主題則顯示 vi-du.html。頂部欄包含主題選擇器、淺色/深色、VI | EN、重設編輯和複製調色盤。
依用途建議： 頂部有兩行按鈕，「這個網站是做什麼的？」（銷售、任務、報告、登陸頁面、新聞）和「想要什麼風格？」（簡約、專業、溫暖、明亮、大膽、優雅）。選取後，3 個最佳調色盤會移到最上方並附帶一行說明；如果未編輯任何顏色，則套用第一個。再次點選按鈕可清除選擇。建議來自頁面中的規則表 GOI_Y（用途匹配得 2 分，風格匹配得 1 分）；頁面不會呼叫 AI。若要新增用途或風格，請編輯 MUC、KIEU 和 GOI_Y。
選取： 每個調色盤顯示其 5 種主要顏色和十六進位色碼。點選一個，整個網站都會改變。選取另一個調色盤會放棄您的編輯。
編輯目前調色盤： 點選橫幅中的色票，或開啟「網站所有顏色」以按群組（背景、文字和邊框、強調色、狀態、標籤）進行編輯，可使用顏色選擇器或十六進位色碼。網站會立即更新。每個色票會顯示對比度比率，低於 4.5 時會顯示為紅色。已編輯的顏色會出現「重設」按鈕。
淺色和深色 會分開編輯。
複製調色盤： 會產生淺色和深色 CSS 以及一段要貼給 Claude 的文字。當您收到時，請遵循 them-theme.md 的「來自調色盤」章節。

PHOI 陣列中的每個調色盤僅儲存淺色和深色的 4 種基礎顏色（頁面、卡片、文字、強調色）。tinh() 函數會推導出其他背景、文字、邊框和強調色陰影。狀態和標籤顏色則保持與主題相同。

新主題必須新增到此頁面的 THEMES 陣列中。使用者的選擇會儲存在瀏覽器中（鍵值 phoi-mau）。

預覽

使用任何靜態伺服器提供 themes 資料夾：

python -m http.server 8766 -d themes

調色盤：http://localhost:8766/bang-chon.html
一個主題：http://localhost:8766/<theme>/vi-du.html?mode=dark&accent=cam
主題頁面：http://localhost:8766/saas-sang/chu-de/<topic>.html?mode=dark&lang=en

線上示範：https://huydp93.github.io/ui-theme-skill/themes/bang-chon.html

共用代碼名稱

新主題必須定義所有這些代碼，包含淺色和深色模式。完整的註解清單在 themes/_mau/tokens.css 中。

群組	代碼
背景、文字	`--bg --side --surface --sunk --hover --line --line-strong --fg --fg2 --fg3`
強調色	`--acc --acc-hover --acc-fg --acc-soft --acc-line --ink --ink-fg`
狀態	`--ok --bad --err-fg --err-bg --code-bg --code-fg`
陰影	`--shadow --shadow-pop`
類型標籤	`--k-tip --k-tool --k-trend --k-opp --k-news --k-fg`
狀態膠囊	`--s-new --s-watch --s-sent --s-seen` 以及每個的 `-bg` 版本
圓角	`--r-card --r-btn --r-btn-sm --r-badge --r-pill`
高度	`--h-btn --h-btn-sm --h-field`
版面配置	`--w-side --h-top --w-page`
字型	`--font-sans --font-mono --icon-stroke`

共用類別（.card、.btn、.nav...）在每個主題的 components.md 中。

套用主題

務必依此順序載入：字型 → tokens.css → components.css → mau-nhan.css。字型連結位於每個主題的 tokens.css 頂部。

a) Canvas .dc.html

將 tokens.css、components.css 和 mau-nhan.css 貼入 <helmet><style>。Canvas 無法載入外部檔案。
將 Google Fonts <link> 加入 <helmet>。
將面板包裹在 <div class="t {{mode}}" data-accent="{{accent}}"> 中。DCLogic 中的 dark prop 會將 mode 設為 dark 或空字串。移除 data-accent 以使用預設強調色。
.t 類別會重設其內部的淺色，因此面板即使在其本身為深色的 Canvas 中，也會遵循其 prop。

b) 純 HTML 或 Artifact

將 CSS 複製到 <style> 標籤中（Artifact 必須將 CSS 保留在頁面內），如果頁面位於主題資料夾旁邊，則可使用 <link>。
使用 :root；不需要 .t 包裝。在 <html> 上放置 data-theme="light|dark" 和 data-accent="..."。如果沒有 data-theme，則會跟隨系統設定。
版面配置：從主題的 vi-du.html（或 saas-sang 的主題頁面）開始，然後移除不需要的部分。

c) React + Tailwind

將 tokens.css、components.css、mau-nhan.css 複製到專案中，並在根 CSS 檔案中匯入一次。

將 Tailwind 顏色對應到代碼；不要複製十六進位色碼：

Tailwind v4，在根 CSS 中：

@theme inline {
  --color-bg: var(--bg); --color-surface: var(--surface); --color-line: var(--line);
  --color-fg: var(--fg); --color-fg2: var(--fg2); --color-fg3: var(--fg3);
  --color-acc: var(--acc); --color-acc-soft: var(--acc-soft);
  --radius-card: var(--r-card); --font-sans: var(--font-sans); --font-mono: var(--font-mono);
}

Tailwind v3，在 tailwind.config 中：

theme: { extend: {
  colors: { bg: 'var(--bg)', surface: 'var(--surface)', line: 'var(--line)', fg: 'var(--fg)',
            fg2: 'var(--fg2)', fg3: 'var(--fg3)', acc: 'var(--acc)', 'acc-soft': 'var(--acc-soft)' },
  borderRadius: { card: 'var(--r-card)' },
  fontFamily: { sans: 'var(--font-sans)', mono: 'var(--font-mono)' }
} }

將共用類別放在 @layer components 中，這樣 Tailwind 類別仍然可以覆蓋它們。
淺色/深色或強調色切換只需在 document.documentElement 上設定 data-theme 和 data-accent。

規則

圖示是描邊 SVG，stroke-width 來自 --icon-stroke。不使用表情符號作為圖示。
數字、時間和程式碼使用 .mono。
頁面中不使用十六進位色碼。需要新顏色？請在主題中新增一個代碼。
紅色僅用於錯誤（--bad）。絕不要將紅色作為強調色。
淺色強調色必須足夠深，以便白色按鈕文字達到對比度 4.5。
模型資料是範例資料。絕不使用真實資料或從 .env 或資料庫讀取。
遵循 du-an.md 中的文案慣例（語言、如何稱呼使用者）。
在向使用者展示之前，請檢查淺色和深色模式。

新增主題

請參閱 them-theme.md。

UI 主題套件 (theme-giao-dien)