huydp93/theme-giao-dien

UI 主题

English | Tiếng Việt

每个主题都是 themes/ 下的一个文件夹。一个主题包含颜色令牌、共享类、一组强调色和一个示例页面。 每个主题使用相同的令牌名称。切换主题意味着交换 CSS 文件，而不是编辑 HTML。

文件夹和文件名使用越南语（该工具包在越南制作）。README 中包含术语表。

何时使用

• 绘制原型或构建新页面或应用屏幕时。
• 用户发送截图、产品名称或 URL 并希望复制其外观时。参见 them-theme.md。
• 用户说“使用主题 X”、“将强调色切换为 Y”、“暗色模式”。

所有者的风格

在绘制或创建新主题之前，请阅读 phong-cach-owner.md。简而言之：一个明亮、紧凑的 SaaS 仪表板，含有大量数字和一种强调色（蓝色或紫色）。其来源是所有者保存为参考的一组应用。

主题

主题	外观	状态
clickup-radar	类似 ClickUp 的侧边栏、场景库卡片、明亮紧凑、紫色强调色	已批准 2026-11-03
saas-sang	所有者的风格：明亮 SaaS、大数字、蓝色强调色、每主题一个示例页面	已批准 2026-11-04

themes/_mau 是用于新主题的空模板。请勿用它进行绘制。

哪个项目使用哪个主题

如果存在 du-an.md 文件，请在此文件夹中阅读它。这是所有者的私人文件（已通过 gitignore 排除），用于将他们的项目映射到某个主题、主题方向（topic）和强调色，并保存他们的文本约定（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> 绘制图标，并在右下角添加一个**Giao diện（外观）**按钮：亮色/暗色/系统、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 页面上的 Giao diện 面板中的“Ngôn ngữ / Language”行，以及 bang-chon.html 顶部栏的 VI | EN 按钮，后者会传递 ?lang= 给预览。
• 它会翻译文本、placeholder、title、aria-label 以及页面标题，并监视后续添加的内容。
• 示例页面上新增或更改的越南语文本：将确切的字符串及其英文翻译添加到 themes/i18n-en.js，然后使用 ?lang=en 打开页面并检查是否还有残留的越南语。
• i18n 仅用于演示。实际项目不复制 i18n.js；应使用自己的语言编写文本。

选择主题

1. 项目在 du-an.md 中已有记录：使用该主题和强调色。无需再次询问。
2. 用户在消息中指定了主题或强调色：照做。
3. 两者都没有：在聊天中用一个简短的问题询问，问题中列出所有选项，并使用用户的语言。例如：

   此项目尚未设置主题。使用 clickup-radar（明亮、紧凑、紫色强调色），saas-sang（你的风格，蓝色强调色），或者你想发送另一个外观的截图？ clickup-radar 的强调色：紫色、蓝色、天蓝、青色、绿色、橙色、粉色、炭灰色。saas-sang 的强调色：蓝色、紫色、靛蓝、天蓝、青色、绿色、橙色、炭灰色。

4. 用户想要选择和调整颜色：打开调色板（见下文）。

调色板

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

1. 将 tokens.css、components.css 和 mau-nhan.css 粘贴到 <helmet><style> 中。Canvas 无法加载外部文件。
2. 将 Google Fonts <link> 添加到 <helmet>。
3. 用 <div class="t {{mode}}" data-accent="{{accent}}"> 包裹板子。DCLogic 中的 dark 属性会将 mode 设为 dark 或空字符串。省略 data-accent 将使用默认强调色。
4. .t 类会重置其内部的亮色，因此即使 Canvas 本身处于暗色模式，板子也会遵循其属性。

b) 纯 HTML 或 Artifact

1. 将 CSS 复制到 <style> 标签中（Artifact 必须将 CSS 保留在页面内），或者如果页面与主题文件夹位于同一目录，则使用 <link>。
2. 使用 :root；无需 .t 包装器。将 data-theme="light|dark" 和 data-accent="..." 放在 <html> 上。如果没有 data-theme，则跟随系统。
3. 布局：从主题的 vi-du.html（或 saas-sang 主题页面）开始，并删除不需要的部分。

c) React + Tailwind

1. 将 tokens.css、components.css、mau-nhan.css 复制到项目中，并在根 CSS 文件中一次性导入。
2. 将 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)' }
     } }
     

3. 将共享类放在 @layer components 中，以便 Tailwind 类仍然可以覆盖它们。
4. 亮色/暗色或强调色切换只需设置 document.documentElement 上的 data-theme 和 data-accent。

规则

• 图标是描边 SVG，stroke-width 使用 --icon-stroke。不要使用 emoji 作为图标。
• 数字、时间和代码使用 .mono。
• 页面中禁止使用十六进制代码。需要新颜色？向主题添加一个令牌。
• 红色仅用于错误（--bad）。永远不要将红色设为强调色。
• 亮色强调色必须足够暗，以便白色按钮文本达到对比度 4.5。
• 原型数据是样本数据。切勿使用真实数据或从 .env 或数据库中读取。
• 遵循 du-an.md 中的文本约定（语言、如何称呼用户）。
• 在向用户展示之前，请检查亮色和暗色两种模式。

添加主题

参见 them-theme.md。