ui-designer
Skill0 starsChanged 29 days agoMITView on GitHub
UI 设计知识与作业方法总纲(一站式)——配色原理与配色组合、主题令牌系统构建、组件搭配与布局规范、图标设计方法、壁纸与视觉资产创作,以及新增/微调主题的完整作业流程与验证清单。每条含可操作原则、适用场景、实测示例。触发词:配色方案、主题设计、设计系统、UI 规范、组件布局、图标设计、壁纸、视觉设计、界面审美、对比度、色板、新增主题、加一个主题、改深一点、主题配色微调、theme preset。
24 other projects use a version of this.
Adopted by
Most recently taken up by
- zhanguoliang715/agent-pipeline-skillstheir own version, first seen Nov 8, 2026
- Mazalucas/El-DT-Lightweight-Armytheir own version, first seen Oct 26, 2026
- daymade/claude-code-skillstheir own version, first seen Oct 19, 2026
- iberi22/skillstheir own version, first seen Oct 15, 2026
- AidenSbVevo/claude-code-startertheir own version, first seen Oct 8, 2026
- HACK-WU/skillstheir own version, first seen Sep 25, 2026
Used with
Projects with it also use multi-agent-coordinator, build-engineer and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
belokonmSkillmulti-agent-coordinator
An advanced orchestration specialist that manages complex coordination of 100+ agents across distributed systems with hierarchical control, dynamic scaling, and intelligent resource allocation
Also in 4 projects that use this
belokonmSkillbuild-engineer
Expert in monorepo tooling (Turborepo, Nx, Bazel), CI/CD pipelines, and bundler optimization (Webpack/Vite/Rspack).
Also in 3 projects that use this
JohnJBorenSkillux-researcher
User research methods, interview guides, usability testing, and persona development
Also in 4 projects that use this
ihiteshguptaSkillvue-expert
Expert in Vue.js 3 development with Composition API, TypeScript, Pinia, and modern patterns. Use for Vue component development and best practices.
Also in 3 projects that use this
JohnJBorenSkillproduct-manager
Product development workflows, PRDs, prioritization frameworks, and roadmap planning
Also in 5 projects that use this
- +7 more from belokonm
Other versions24 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 24
- daymade/claude-code-skills★ 1.5ksame name
- GulajavaMinistudio/awesome-copilot-id★ 92same name
- Rylaispirit/rylai-codex-hermes-skills★ 56same name
- jshsakura/awesome-opencode-skills★ 30same name
- nilecui/SkillsBase★ 27same name
- belokonm/claude-supercode-skills★ 11same name
- mae616/ai-template★ 9same name
- ccwbb78/design-skills★ 8same name
- Gustavosilveira23/claude-design-skills★ 8same name
- nicolasestrem/antigravity-gemini-skills★ 8same name
14 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository7 other files it gives its agents.
- docx-cnSkill
- excelSkill
- frontend-design-systemSkill
- model-api-referenceSkill
- pdf-intelligence-suiteSkill
- qoder-agent-sdk-skillSkill
- self-improvementSkill
The file
Files
UI 设计师
一站式设计知识与作业方法总纲。含两部分:
- 第一部分 · 设计原则(§1–6)——讲"为什么",原理、判据、规范值
- 第二部分 · 作业流程(§7–10)——讲"怎么做",步骤、脚本、验证
所有数值来自真实项目实测,不是泛泛而谈。本文件自包含,不依赖外部姊妹技能。
使用方式:新做界面 → 按 §1–6 定方向;给已有系统加主题 → 直接跳 §7;微调已有主题颜色 → 跳 §8;贴合 IP / 壁纸 → 跳 §10;交付前 → 走 §11。
第一部分 · 设计原则
1. 三条前置纪律
- 可测量就不凭感觉。 颜色方向看通道序(§2.2),差异看 Lab ΔE(§2.4),可读性看对比度(§2.3)。肉眼判断在低饱和浅色上几乎必然出错。
- 先定结构再定色相。 "白为主、青为辅"这类表述是结构性指令(§3.3)——先决定哪个层承载主色,再挑色值。只换色相不换占比等于没改。
- 改一色要连带检查同族。 外壳一变,描边、分段轨道、选中行、滚动条全部要重算(§3.2 / §8),并检查
--border-soft是否与外壳同色而"隐形"。
2. 配色原理
2.1 HSV 三要素与判读口径
| 要素 | 含义 | 设计中的作用 |
| H 色相 | 颜色种类(0–360°) | 决定"是什么颜色",主题识别的第一要素 |
| S 饱和度 | 纯度(0–100%) | 决定"艳不艳"。低饱和 = 克制耐看;高饱和 = 抢眼但易俗 |
| V 明度 | 亮度(0–100%) | 决定"轻重"。外壳明度直接决定界面气质 |
实测参照:
- 克制型界面外壳:S ≤ 16%,V 90–99%
- 深色系(游戏/夜间)素材:S 0.20–0.39,V 0.32–0.67
- 明亮办公型素材:S ≈ 0.22,V ≈ 0.84
原则:界面主体(外壳、表面、画布)永远低饱和;饱和色只出现在小面积元素(按钮、链接、图表、高亮)。这是"去 AI 味"的核心。
2.2 通道序:一眼判断色相方向(配色不靠猜)
浅色最容易被"米色 / 粉色 / 藕荷"这类观感迷惑。判据是 RGB 三通道的大小顺序:
| 通道序 | 观感 | 示例 | 适用场景 |
| R > G > B | 暖橙调 → 米色 / 藕荷 / 奶油 | #F6E8E4(淡桃,实为米色) | 暖调、纸感、复古 |
| R > B > G | 正粉调 → 淡粉 / 玫瑰 | #F9E6EA(淡粉) | 柔和、亲和 |
| G ≥ R,G > B | 绿 / 青绿 | #E1ECE5(青瓷绿) | 自然、清爽、科研 |
| B 最大 | 蓝 / 青蓝 / 紫蓝 | #E4F2FE(天空蓝) | 专业、冷静、科技 |
| 三通道接近 | 中性灰 | #EAEBE7(暖中性灰) | 通用、办公、低干扰 |
关键技巧:要把"米色"变成"粉色",只需把 G 降到 B 之下(R>B>G),不必重新挑色。反之亦然。
实操案例:外壳
#F6E8E4(R246 G232 B228,读起来是米色)→ 改#F9E6EA(R249 G230 B234)后立刻读作淡粉。
适用场景:任何"这颜色不对"的返工场景,先看通道序再动手,能省掉一半迭代。
2.3 对比度:WCAG 与"家族区间"双重判定
硬指标(WCAG AA):
- 正文文字 ≥ 4.5:1(优选 ≥ 7:1 达 AAA)
- 大号文字(≥18.66px 粗体 或 ≥24px)≥ 3:1
- 图形 / 图标 / 控件边界 ≥ 3:1(1.4.11 非文本对比)
软指标:家族区间。 把同类令牌在所有主题下的对比度算出来形成区间,新主题低于区间下限就要调整,哪怕它仍然"达标"。
实例:主按钮文字对比度家族区间 6.1–18:1。某主题只有 4.66:1——虽过 AA,但明显离群(区间下限 6.3),压深后回到 6.59:1 才落回区间。
计算式:
function lin(c){ c/=255; return c<=0.04045 ? c/12.92 : Math.pow((c+0.055)/1.055, 2.4); }
function Y(rgb){ return 0.2126*lin(rgb[0])+0.7152*lin(rgb[1])+0.0722*lin(rgb[2]); }
function cr(a,b){ const A=Y(hex(a)),B=Y(hex(b)); const hi=Math.max(A,B),lo=Math.min(A,B); return (hi+0.05)/(lo+0.05); }原则:对比度是底线不是目标。达标之后再用家族区间判断是否协调。
2.4 跨色区分度:必须用 Lab ΔE,禁用 RGB 距离
RGB / 曼哈顿距离在暗色上严重失真:#384E4E 与 #3E4A57 曼哈顿距离仅 19(看似差异很大),ΔE 却只有 9.6(人眼几乎分不出)。
门槛(实测校准):
- 主色两两 ΔE ≥ 12(低于此用户切换时感觉"没变")
- 同一次批量新增的主题之间 ΔE ≥ 15
- 放宽条款:主色 ΔE ≥ 10 且 外壳 ΔE ≥ 5 时可接受——界面整体仍一眼可辨
- 外壳允许相近;区分度由主色 + 链接承担
- 若用户明示外壳要与既有主题相同("跟黑白简约差不多的"),ΔE=0 是需求本身不是缺陷,不要为区分度擅自加色
放宽实例:某主题按素材要求取办公蓝,与既有"天空与海"主色 ΔE 只有 10.8。放宽依据 = 两者外壳 ΔE 9(暖纸灰 vs 淡青蓝)。放宽必须写清依据,不能悄悄放过。
function lab(h){ const [r,g,b]=hex(h).map(lin);
const X=(0.4124*r+0.3576*g+0.1805*b)/0.95047, Yy=0.2126*r+0.7152*g+0.0722*b, Z=(0.0193*r+0.1192*g+0.9505*b)/1.08883;
const f=t=>t>0.008856?Math.cbrt(t):(7.787*t+16/116); const fx=f(X),fy=f(Yy),fz=f(Z);
return [116*fy-16, 500*(fx-fy), 200*(fy-fz)]; }
const dE=(a,b)=>{ const A=lab(a),B=lab(b); return Math.sqrt(A.reduce((t,v,i)=>t+(v-B[i])**2,0)); };⚠️ 不要让程序"自动搜索区分度最大的色":目标函数取"最大化最小 ΔE"时,解永远落在约束盒角点——放开饱和度会得到 S29 薰衣草外壳、S95 宝蓝主色,技术上最优、语义上完全不对。正确做法是把家族现实约束(外壳 S≤16、V 90–99;主色饱和度与既有家族同量级)写进搜索,再人工按语义挑选。
2.5 常用配色组合
| 组合 | 定义 | 适用场景 | 示例 |
| 中性 + 单一强调 | 中性色打底(80%),一个强调色(20%) | 最通用。工具类、专业软件、去 AI 味首选 | 中性灰外壳 + 墨色主按钮 + 克制蓝链接 |
| 单色(Monochromatic) | 同色相不同明度/饱和 | 高度统一、低干扰 | 青系:外壳 #EFF5F5 → 主色 #357A7A → 正文 #1E292A |
| 类似色(Analogous) | 相邻 30–60° | 柔和过渡,国风 / 自然主题 | #1B6B5A → #2C6E78 → #2C5F8D |
| 互补(Complementary) | 相隔 180° | 强对比突出重点,慎用 | 蓝底 #CFE7F8 + 琥珀 #D89B33 |
| 分裂互补 | 150° + 210° | 比互补柔和,仍富张力 | 青蓝 + 赭红 + 琥珀 |
| 三角(Triadic) | 相隔 120° | 图表配色、活泼界面 | #33505A / #A88A55 / #21A88C |
60-30-10 法则:主色 60%、辅助 30%、强调 10%。界面设计里通常再保守一档:中性 85% + 主色 10% + 强调 5%。
2.6 语义色与文化色
语义色固定不变(不随主题改色相):成功绿、警告琥珀/橙、危险红、信息蓝。主题化时只调整饱和度与明度去贴合主题气质。
- 低饱和主题 → 语义色也去饱和(如危险态用
#A8483A而非纯红) - 品牌亮色主题 → 语义色保持可辨识度优先
文化色(国风项目):月白、黛青、石青、朱砂、宣纸白、藕荷、天青、赭石、青铜、苍翠。取名与取色都要有出处。
3. 主题令牌系统
3.1 十组角色(按角色分组设计,不要逐项凑色)
一套完整主题约 60–70 项令牌。契约第一:每套主题的令牌项数与名字集合必须完全一致(本项目 66 项)。动手前先实测,不要相信记忆里的数字(曾记录 63/65,实测均为 66)。
| 组 | 令牌 | 作用 |
| 1 外壳 | --bg、--panel-bg、--canvas-bg | 面积最大,承载"主色" |
| 2 边框 | --panel-border、--border、--border-soft、--menu-border | 分隔层次 |
| 3 表面 | --surface、--surface-2、--content-bg、--main-bg(同色系 rgba 0.72) | 卡片/内容底 |
| 4 文字 | --text-1/2/3 | 同色系由深到浅 |
| 5 品牌 | --primary-bg/-hover/-text、--link/-hover | 按钮与链接 |
| 6 强调 | --accent-soft、--accent-text、--accent-wash | 选中/高亮 |
| 7 语义 | --ok*、--warn*、--danger* | 状态反馈(主题色偏移的柔和版,不用纯饱和色) |
| 8 交互态 | --conv-active-bg、--hover-overlay、--selection-bg/-text、--toggle-off、--chip-bg、--scroll-thumb(-hover)、--focus-border | 悬浮/选中/按下 |
| 9 浮层 | --menu-shadow、--card-shadow、--toast-shadow、--focus-glow、--avatar-ring、--overlay | 同一组 rgba 基色派生 |
| 10 文档/图表 | --paper*、--chart-1..6(1 常取主色,其余拉开色相) | 阅读器与数据可视化 |
3.2 层间对比度带与"整族"概念
"外壳镀铬族" = 渲染在外壳底色之上的那一层控件色。成员:
--panel-bg、--panel-border、--border、--border-soft、--menu-border、--accent-soft、--chip-bg、--conv-active-bg、--scroll-thumb、--scroll-thumb-hover、--selection-bg、--toggle-off
层间对比度带(实测):
| 关系 | 对比度带 |
| 分段轨道 / 芯片 vs 外壳 | 1.05 – 1.25 |
| 选中行 vs 外壳 | 1.08 – 1.35 |
| 描边 vs 外壳 | 1.15 – 1.40 |
原则:层间关系靠对比度比值保持,不靠固定 RGB 差值。只改外壳不改这些,选中态会被新底色吃掉(实测:轨道与新底色几乎同色 → 分段轨道与选中会话行视觉消失)。
若外壳改浅(如带色 → 纯白),镀铬层必须同步调浅,否则在白底上显脏偏重。 实例:外壳
#EFF5F5→#FFFFFF后,描边#C6DBDC→#DFE8E8、轨道#DCEAEA→#EAF2F2、选中行#D5E6E6→#E4EEEE。
⚠️ 必查项:--border-soft / --menu-border 若与外壳同色,这些分隔线等于不可见(真实踩过的 bug)。
3.3 "主 / 辅"是结构性指令
用户说"X 为主、Y 为辅"时,描述的是面积占比而非色相偏好:
| 角色 | 落点 |
| 主 | 外壳、画布、表面(--panel-bg / --canvas-bg / --surface* / --content-bg / --bg) |
| 辅 | 主色按钮、链接、描边、选中态、图表(--primary-* / --link* / --accent-* / --conv-active-bg / --chip-bg / --chart-*) |
只把色相换对、占比不换,等于没改。 反例:用户要"白为主、青为辅",却按另一张海报做了深色外壳 + 朱绯主色——色相跑偏且"白"根本不占面积。
辅色还需与既有主题拉开色相差:同色系新主题取相近色相会撞车(青碧取 H180 与既有石绿 H167 的 ΔE 仅够 13.2;若取 H167 附近则完全分不出)。定辅色前先算它到已有主题同角色颜色的 ΔE。
3.4 按钮文字色:侧通道令牌
主按钮文字常被硬编码为白色(color: #FFFFFF !important),这会强制所有主题的主色都必须与白字达 4.5:1,亮品牌色直接不可用(QQ 标准蓝 #12B7F5 对白字仅 2.30:1、官方品牌蓝 #00CAFC 仅 1.9:1)。
❌ 错误修法:把品牌色压深。——品牌色失真是比多一个令牌更大的代价。 ✅ 正确修法:开一条带兜底的侧通道令牌:
.btn-primary { color: var(--btn-primary-text, #FFFFFF) !important; }
:root { --btn-primary-text: #FFFFFF; } /* 兜底:未定义的主题零影响 */
html[data-theme="brand-x"] { --btn-primary-bg: #12B7F5; --btn-primary-text: #08131F; }四条要点:
- 必须带兜底值,否则一次性影响所有主题的渲染
- 不要塞进主令牌契约,与
--btn-primary-bg/--switch-on同属"逐主题单变量覆盖"侧通道,主契约保持纯净 - 验证口径随之改为按该主题自己的文字色判定
- 因为是新令牌名,天然不被"钉回亮色"的作用域块覆盖——这正是它优于复用
--primary-text的地方
动手前先 grep 一次按钮规则,确认文字色是令牌还是硬编码。
3.5 随壁纸二次校准
壁纸就位后,主题配色须跟随壁纸主色调再校一次。三次实践均验证必要:
| 主题 | 壁纸实测 | 调整 |
| 风花雪月 | 98% 青蓝(210–239° 78.1%) | 原青莲紫 H250 与壁纸 H212 不符 → 整体改月夜蓝灰 |
| 办公日常 | 暖白 60% + 深蓝灰 + 办公蓝 + 琥珀 | 主色由暖石墨改办公蓝;外壳改暖纸灰 |
| 燕云十六声 | 95% 青蓝 | 青由 H180 微调 H191 贴合 |
4. 组件搭配与布局
4.1 间距与网格
- 间距体系:4 / 8 / 12 / 16 / 24 / 32(4 的倍数),禁止出现 5、7、13 这类值
- 栅格:3 列 / 4 列常用。卡片总数能被列数整除时视觉最稳(12 张卡 → 4 列 3 行 或 3 列 4 行)
- 列宽参考:左栏 256px、竖条 52px、右栏 320px、内容列最大宽度 920px
- 密集网格改列数时要同步收紧:gap 12→10、卡片 padding 10→9、内距 8→7
4.2 层级与视觉重量
| 层级 | 手段 |
| 背景(最低) | 外壳色 |
| 表面 | 卡片白 / --surface |
| 浮层 | 阴影 + 边框 |
| 强调(最高) | 主色填充 |
原则:用一层阴影 + 一层边框表达浮起,不叠加多层。同一界面内阴影不超过 3 档。
4.3 组件搭配规范
| 组件 | 规范 |
| 按钮 | 主按钮 1 个/视图(唯一主要行动);次要按钮用描边或幽灵样式;圆角与输入/卡片同一体系 |
| 输入框 | 边框与背景对比 ≥3:1;聚焦态用 --focus-border + 轻外发光,不要改高度/尺寸(避免布局跳动) |
| 卡片 | 内边距统一;卡片间距 = 内边距的 1–1.5 倍;卡片内只放一组相关信息(亲密性) |
| 菜单/浮层 | 挂 body + position: fixed,避开父级 overflow: auto 裁剪;z-index 分层 |
| 分段控件 | 选中态用主色填充,轨道用 --accent-soft;轨道与外壳必须可分辨(≥1.05) |
| 开关 | 开启色随主题(--switch-on);关闭态用中性灰,不要用红(红保留给危险) |
| 滚动条 | 滑块与外壳可分辨;hover 再加深一档 |
4.4 状态设计
每个可交互组件都要有 默认 / 悬停 / 按下 / 禁用 四态(图标类另加选中态):
- 悬停:用
--hover-overlay(半透明叠加)而非改背景色,保证跨主题一致 - 禁用:
opacity 0.45+ 说明性提示,仍可点击查看原因(优于静默无响应) - 选中:不关闭菜单(支持连续操作),勾选态用内联 SVG 勾
4.5 动效
- 缓动:
cubic-bezier(0.22, 1, 0.36, 1),时长 150–300ms - 必须提供
prefers-reduced-motion降级(直切) - 内容更新不得触发容器动画(只有进场/退场才动)
- 菜单淡入 0.18s;关闭时从 DOM 摘除,不残留
4.6 排版
- 中文正文行高 ≥ 1.75;英文 1.7–1.82
- 字体:拉丁 Instrument Sans / Inter,中文回退 PingFang SC → HarmonyOS Sans SC → Microsoft YaHei
- 界面字号分级 12 / 12.5 / 13 / 14 / 16 / 20;标题与正文至少差 2 级
- 零 emoji:所有状态/图标一律内联 SVG,不用 emoji 字符
5. 图标设计
5.1 画板与网格
| 项 | 规范 |
| 画板 | 24 × 24 |
| 活动区 | 20 × 20 |
| 安全边距 | 2px |
| 描边 | 1.75px(界面内嵌用 stroke-width: 2),圆头圆角连接 |
| 填充 | 只描边不填充 |
| 颜色 | 单色 currentColor,默认玄黑 #16161D |
内联 SVG 统一属性:viewBox="0 0 24 24"、fill="none"、stroke="currentColor"、stroke-width="2"、stroke-linecap/linejoin="round"。
5.2 几何骨架(保证一套图标视觉等重)
| 形状 | 尺寸 |
| 圆 | Ø 20 |
| 正方 | 16 × 16 |
| 横向矩形 | 20 × 14 |
| 纵向矩形 | 14 × 20 |
原则:所有图标的视觉面积要接近。圆形天然显大,方形需略放大补偿。
5.3 尺寸与光学补偿
尺寸档位:14 / 16 / 20 / 24 / 28 / 32(界面内 9–40px 区间)。
- 小尺寸(≤16)需简化细节、加粗描边、增大间隙
- 像素对齐:关键边落在整像素上,避免半像素模糊
5.4 语义与命名
- 一个图标一个语义,不复用造成歧义(不要既用齿轮表示"设置"又表示"亮度")
- 命名按 功能域 + 动作(
ICON_COPY/ICON_TRASH/ICON_REGEN) - 分组管理:外壳导航 / 会话操作 / 设置导航 / 专业能力 / 文件对象 / 阅读器 / 状态反馈
- 先盘点代码中所有图标点,再设计,保证覆盖无遗漏
5.5 绘制流程
- 盘点现有图标清单(代码 grep)
- 按功能域分组
- 画规范页(画板/描边/骨架/原则/边界)
- 逐个绘制,同源形状复用(复制后是独立副本,改源不同步,源修正后必须同步改副本)
- 语义自检(有无两个图标语义混淆)
- 尺寸档位渲染测试
6. 壁纸与视觉资产
6.1 作用域与构图
作用域纪律:壁纸只作用于中栏容器 + 初始态(欢迎页),不覆盖左右侧栏、不覆盖标题栏固定区。开始对话后立即回落原配色。
构图原则:
- 留白优先:主体偏移到一侧 / 一角,给标题文字留出呼吸区
- 低饱和 / 有颗粒感优于高饱和磨皮质感(更耐看、更有"高级感")
- 压低饱和度反而更能传达氛围(荒寒、静谧)
6.2 与 UI 叠加的可读性
三种取舍,需明确选择其一并说明:
- 纯壁纸不改字——最忠实,但标题可能被压在饱和色块上
- 加半透明蒙层——可读性最好,但削弱壁纸质感
- 改文字色 / 加阴影——折中,但改字色会破坏主题一致性
原则:先测(截图 + 取样),再决定。不要在没人确认时自作主张加蒙层。
6.3 压缩与内联口径
- 长边 1600、JPEG quality 82、
progressive、optimize、LANCZOS 重采样 - 单文件产物 → base64 内联(
data:image/jpeg;base64,...) - CSS 规则必须
!important(内联background简写会重置background-image,且内联优先级更高) - 每条选择器自带完整后缀(
html[data-theme="x"] body.is-initial-chat #centerPanel)——逗号分隔的必须是完整选择器,写成html[data-theme="x"],会退化成裸选择器并打穿整页底色 - 交付前离线逐字节比对 CSS 内 base64 与压缩产物(对比对象是压缩后文件,不是原图)
6.4 其他视觉资产
- 辅助图形:同心墨痕 / 分子网络 / 粒子散点 / 方形朱印——低对比、作背景纹理,不抢内容
- 海报 / 宣传页:禁彩色渐变、禁大色块、禁营销风配色;中性色打底 + 墨色主按钮 + 克制蓝链接
- 品牌资产:四色体系(玄黑
#16161D、石青#2E6E8E、丹朱#CE4928、宣白#F4F0E5)
第二部分 · 作业流程
7. 流程 A:给已有系统新增一整套主题
何时用:给已有的 html[data-theme="x"] 令牌系统加一套全新主题。若只是微调已有主题深浅 → 走 §8。
7.1 先实测契约,不要照抄记忆
每条主题必须恰好 N 项令牌,且名字集合完全一致。N 必须现场量出来——记忆里的数字常常是过期的(本例:记忆写 63,实测 66)。
const s = fs.readFileSync(HTML, 'utf8');
const ids = [...]; // 现有全部主题 id
const sets = {};
for (const id of ids) {
const i = s.indexOf(`html[data-theme="${id}"] {`);
const j = s.indexOf('\n }', i); // 按该缩进找块尾
const names = (s.slice(i, j).match(/--[a-z0-9-]+(?=:)/g) || [])
.filter((v, k, a) => a.indexOf(v) === k);
sets[id] = names;
}
// 断言:所有 sets 两两一致;输出权威顺序备用7.2 找出全部注册点(只看一个就动手是最常见的翻车方式)
用 grep 'data-theme=' 扫源文件,凡出现具体主题 id 的地方都要同步。典型四类:
| 注册点 | 说明 |
| ① 令牌块 | 主体,N 项 |
| ② 作用域覆盖表 | 如"内容画布钉白"把若干主题的 .chat-body/#rightPanel 一并列出——漏加会让新主题下画布颜色异常 |
| ③ 逐主题单变量覆盖 | 如 html[data-theme="x"] { --btn-primary-bg: ... } 这类散落小规则 |
| ④ 机制侧注册 | TS/JS 里的主题列表、选择器卡片数组、i18n 词条、任何遍历主题的脚本 |
7.3 设计配色
按 §3.1 的十组角色分组出方案,不要逐个凑色。要点:
- 外壳差值关系照抄现有主题(§3.2 比值带)
- 先看通道序定色相方向(§2.2)
- 算清与既有主题的 Lab ΔE(§2.4),过门槛或写清放宽依据
- 亮品牌色主按钮走侧通道令牌(§3.4)
7.4 脚本化注入(禁止手工 Edit)
同一个十六进制值会在多个主题块里重复出现(--border: #DCE7F2; 到处都是),手工改必然误伤。做法:切片 → 块内替换 → 拼回。
const i = s.indexOf('html[data-theme="NEW"] {');
const j = s.indexOf('\n }', i);
let blk = s.slice(i, j + 4);
// 仅在 blk 内做带行首缩进的精确替换
s = s.slice(0, i) + blk + s.slice(j + 4);批量替换前给每一处断言命中次数(split(x).length-1 === 1),否则静默漏改。
锚点坑:目标注释常是多行块注释,行尾并没有 */。写锚点时先 JSON.stringify 打印真实片段,别凭印象拼。
7.5 收尾
- 出图:新主题主界面 + 设置页各一张,外加主题选择器总览一张(能同时看到新旧是否协调)
- 改前/改后对照的可复用手法:不要拿旧截图硬拼(状态不一致、常已被覆盖)。做法是从备份源文件抽出旧的令牌块 + 旧的口径覆盖行,用 CDP 往同一页面注入
<style id="__old">覆盖回去渲染 → 截"改前";移除该 style → 截"改后"。同一会话、同一 UI 状态,可比性最高,并打印两次渲染的像素值作为证据 - "限定"类标注:若用户要求"标注但不渲染标识",用代码元数据承载(令牌块注释 + 注册描述符加一个不被读取的
limited字段),卡片文案保持纯主题名,并加一条"卡片名不含限定字样"的断言守住 - 结构、渲染面、阈值一起写进项目长期记忆
8. 流程 B:微调已有主题的深浅(整族同位移下移)
何时用:用户说"XX 主题的淡蓝/浅灰再深一点点",并常给一张纯色参考图。陷阱不是改色本身,而是只改一个令牌会静默破坏层级。
8.1 先取参考色(别靠肉眼猜)
用户给的截图往往是纯色小图,直接取众数:
from PIL import Image
import collections
im = Image.open(path).convert('RGB')
for col, n in collections.Counter(im.getdata()).most_common(3):
print('#%02X%02X%02X' % col, n)若参考图是界面局部,还要在真实截图里实测目标元素当前渲染值,确认改的是哪一层:
im.getpixel((x, y)) # 侧栏、顶栏、分段轨道、选中行各取一点8.2 定位目标令牌,算出位移
从该主题的 CSS 块找到对应令牌(如 --panel-bg),用「参考色 − 原值」得位移 Δ:
原 #F0F6FB (240,246,251) → 参考 #E4F2FE (228,242,254) ⇒ Δ = (−12, −4, +3)8.3 ⚠️ 核心:整族下移,不要只改一个令牌
对外壳镀铬族(§3.2 成员表)施加同一位移,层间色差原样保持。
不要碰(改动无收益且有副作用):
- 文本
--text-* - 品牌
--primary-*/--link* - 语义
--ok*/--warn*/--danger* - 纯白与近白表面:
--canvas-bg/--surface/--content-bg/--input-bg/--menu-bg --paper*族(属 paper 子系统,键在--paper上,与外壳无互动)- 中性
--bg、--surface-2、--bubble-ai-bg - chart 色、各 rgba 叠加层
8.4 用脚本改 + 验收
多主题文件里同一十六进制值会重复出现,必须先切出目标主题块再替换。用 new RegExp 时按整行匹配(如 '\n\s*--border:\s*(#[0-9A-Fa-f]{6});')可避开 --panel-border 里的 -border 误伤。
验收:令牌数不变、括号平衡、块长变化 ≈ 注释长度。改完 grep 旧值,确认剩余命中只在说明注释里(别把注释里的旧值当漏改)。
8.5 回填与复核
- 只改 CSS 时不需要重编 TS,直接跑构建
- CDP 复核四组断言:「新值生效」+「未触碰项原样」+「其他主题未波及」+「既有特性无回归」
- 出图:做一张改前/改后并排对照(两侧裁同一区域),标签写明十六进制值
9. 验证:五组 + 三类对比度断言
9.1 结构/渲染/注册表五组(缺一不可)
| 组 | 内容 |
| A 结构 | 每个主题块在 CSSOM 里的声明数 == N(rule.style.length),比数源码更可信 |
| B 渲染 | 新主题令牌值 + 真实渲染面:侧栏/顶栏/设置外壳底色、.chat-body 与右栏是否按预期钉白/钉色、逐主题变量覆盖(按钮色)是否生效 |
| C 对比度 | 正文 on 外壳 ≥7:1、次要 ≥4.5:1、正文 on 画布 ≥4.5:1、链接 ≥4.5:1、主按钮色 vs 该主题按钮文字色 ≥4.5:1;同族层次(轨道/选中行/描边)可分辨 |
| D 注册表 | 选择器里卡片数、顺序、卡片文案;网格列数与行数;点击切换真实生效 |
| E 非回归 | 抽查其余所有主题的关键令牌未被改动 |
A 组的 CSSOM 坑:同一个 html[data-theme="x"] 选择器会命中多条规则(令牌块 + --btn-primary-bg 覆盖行等)。遍历 document.styleSheets 时若不在首条命中后停止,后一条(不含 --panel-bg 等)会把取到的值清成空串,ΔE 全变 NaN 且表象像"页面坏了"。要么命中即 break,要么取 style.length 最大的那条。
C 组两条独立判据都要过:达 WCAG AA + 落回家族区间(§2.3)。
9.2 对比度断言分三类,别用同一个容差
微调底色时最容易做错的一步:底色变深会让深色文字的对比度必然下降约 4%,那是预期不是回归。
| 类别 | 判定 |
| 同族层间(底 vs 轨道/选中行/描边/滑块) | 守恒:相对偏差 < 2% |
| 文字 on 底 | 达标:正文 ≥ 4.5:1(优选 ≥ 7:1) |
| 白色控件 on 轨道 | 只许变好:新 ≥ 旧 |
9.3 构建注意
- 只改 CSS 不必重编 TS;改了 TS 注册点则要重编
- ⚠️ 构建日志里的
bytes=常是字符数,与文件系统里的 UTF-8 字节数不同,二者不能直接相减比较(含中文产物字节数会明显更大,曾据此误判"产物变小")
10. IP / 壁纸锚定主题的取色流程
当主题要贴合某个 IP(游戏、影视、品牌)或已有指定壁纸时,「符合特色」这类要求只能靠物料实测回答。禁止凭印象定调。
- 取素材:
WebFetch抓官方站/壁纸站页面(markdown 化会剥离图片,需改抓 HTML);必要时用 PowerShell 提直链:
再$r = Invoke-WebRequest -Uri $url -UseBasicParsing -Headers @{'User-Agent'='Mozilla/5.0'} [regex]::Matches($r.Content, 'https?://[^"''\s<>]+?\.(?:jpg|jpeg|png|webp)') | ForEach-Object { $_.Value } | Select-Object -UniqueInvoke-WebRequest -OutFile批量下载(挑符合 IP 核心气质的 8–12 张,不要只取一张)。 - 量化三维指标(Pillow,无需 numpy):
- 平均饱和度 / 明度 —— 判定"高饱和 vs 低饱和"这一档
- 色相分桶直方图(仅统计
S>0.08 且 V>0.10的有色像素,否则近灰像素会淹没分布)—— 判定主色相区间与暖冷占比 - 中位切分(MEDIANCUT)主色 —— 得到可直接使用的具体色值
- 据实测定令牌:外壳/正文/主色/链接都从实测值里取或在其区间内派生;占比很小的那撮色(如暖色只占 13%)只能作点缀(warn / 批注高亮),不能占主色
- 诚实标注偏离:UI 前景区(链接、正文)的饱和度通常必然高于照片均值——文字要满足对比度阈值。这一点要写进注释与交付说明,不要假装全部落在均值内
- 交付时附一张**「素材实测色板 vs 主题令牌」并排证据图**,让"符合特色"可被验证
反例(真实踩坑):某游戏主题凭"边塞 + 器物"的印象用了 H42 S67% 的暖金主色,而官方壁纸实测平均饱和度仅 20.5%、暖色只占 12.9%、青系占 77.9%——饱和度是 3.3 倍且色相方向相反。印象配色必翻车,实测才稳。
11. 交付前检查清单
配色
- 通道序确认色相方向(不是靠肉眼)
- 正文 ≥4.5:1、大字号 ≥3:1、图标/控件 ≥3:1
- 对比度落在家族区间内(不只满足底线)
- 主色两两 ΔE ≥12(或写清放宽依据)
- 语义色色相未变,只调了饱和度/明度
主题
- 令牌项数与名字集合与既有主题完全一致
- 四类注册点全部同步(§7.2)
- 层间对比度:轨道 1.05–1.25 / 选中行 1.08–1.35 / 描边 1.15–1.40
--border-soft与外壳不同色- 亮品牌色主按钮走
--btn-primary-text侧通道(而非压深品牌色)
组件与布局
- 间距全部落在 4 的倍数上
- 卡片总数能被栅格列数整除
- 四态齐全(默认/悬停/按下/禁用)
- 浮层挂 body + fixed,不被父级裁剪
- 动效 150–300ms 且有
prefers-reduced-motion降级 - 界面零 emoji
图标
- 24×24 画板 / 20×20 活动区 / 1.75px 描边 / 只描边
- 视觉面积等重
- 语义无歧义
- 覆盖代码中的全部图标点
壁纸
- 作用域正确(仅中栏 + 初始态),左右栏无壁纸
- 对话后能正确回落
- 每条选择器自带完整后缀 +
!important - 与压缩产物逐字节一致
- 主题配色已按壁纸主色调二次校准(§3.5)
验证
- 五组断言全过(§9.1)
- 三类对比度断言分开判定(§9.2)
- 改前/改后对照图已出
12. 相关技能
| 技能 | 用途 |
apple-design | 流体交互 / 手势界面 / 弹簧动画 / 毛玻璃材质 / 减弱动效 |
impeccable | 前端界面构建(production-grade UI) |
html-inline-i18n | 单文件 HTML 的中英双语切换(不重构 DOM) |
single-file-hash-router | 长滚动单页改造为多页哈希路由 |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

