主题包 · 配色 · 版式
一个主题包 = 一种版式
🔴 换版式就新建包:<页面>/ 下只有 index.vue 与 colors/,没有「版式」这层目录。曾支持过的 <页面>/<版式>/colors/ 形态已删除——换版式要复制整套配色,两套必然漂移。
themes/
├── default/ ← 版式 A(三端住这里)
│ ├── mobile/<页面>/…
│ └── standard/<页面>/…
└── compact/ ← 版式 B(目录名即包 id 即版式 id)
└── mobile/<页面>/…版式查找范围 = 当前包 × 当前设备。跨包兜底回 default 包(内置包,eager 静态引入,首屏零请求)。
包定义(themes/<包>/index.ts)
ts
import type { MauthThemePackage } from 'skinsuite';
const pkg: MauthThemePackage = {
meta: {
id: 'default', // = 目录名([a-z0-9-])
name: '默认版式',
description: '一句话描述,便于部署方挑选',
preview: { primary: '#1e293b', accent: '#2563eb' } // 可选:面板色卡
},
views: { register: 'compact' } // 可选:包级版式声明(页面名 → 版式 id)
};
export default pkg;views声明的是「该包所有设备、所有配色共用的默认版式」。value 是另一个包的名字(跨包切版式)或本包名;写错 / 未登记一律回退当前包,不会白屏。URL?th参数优先级更高(联调可单次覆盖)。- 配色里的
views只覆盖那一套配色。 - 包定义不再充当「默认配色」——黑白是实体配色目录,与 blue/cyan 平级。
coverage(覆盖范围声明,可选)
ts
coverage: {
devices: ['mobile'], // 缺省 = 全部设备
pages: ['register'], // 缺省 = 全部页面
requiredColors: ['black', 'white'] // 缺省 = ['black','white']
}只影响宿主的目录口径关卡校验,不改变运行时行为;声明范围只能 ≤ 实际目录。
配色定义(colors/<配色>/index.ts)
ts
import type { MauthThemeColor } from 'skinsuite';
const color: MauthThemeColor = {
meta: { id: 'white', name: '白' }, // id = 目录名
tone: 'light', // 🔴 必填:'light' 白系 | 'dark' 黑系
tokens: {
'--mauth-bg': '#ffffff',
'--mauth-text': '#1f2937',
'--mauth-header-bg': 'transparent'
},
views: { login: 'compact' } // 可选:单配色级版式覆盖
};
export default color;tokens 的语义
- 一组扁平值,不分明暗档——每套配色自带完整底色,选谁就是谁。需要深色品牌色就另加一个
tone: 'dark'的颜色目录(如navy),不要写{ light, dark }两档。 - 名字必须
--mauth-<短横线>;取值过白名单(hex / rgb() / hsl() / 长度 /var(--mauth-*)/ 关键字;拒url()与 CSS 颜色名)。 - 若把
--mauth-header-bg设为transparent,必须同时声明--mauth-canvas(页面之外的画布色),否则该色由浏览器内核决定,真机与电脑不一致。
theme.scss(可选样式表)
放 token 表达不了的东西:背景图(url())、伪元素、keyframes。自动带 html[data-mauth-theme='<id>'] 前缀作用域;构建期受信代码,不走运行期校验;惰性加载(?inline 动态 import,不进首屏包)。
配色 id 的唯一性作用域
同包 × 同设备 × 同页面。跨设备 / 跨包 / 跨页面可以同名——mobile/login/colors/black 与 standard/login/colors/black 并存是正常且必要的(两套各自独立的配色)。取一份配色时这三段必然同时给出,歧义在入口就被消解。同范围内重名按路径排序先到先得并告警,不静默覆盖。
解析回退链
getThemeRecord({ id, device, pkg, page }) 的完整回退链(高 → 低):
- 精确四段键;
- 同包同系别(同 tone)首套;
- 该范围兜底色:先显式默认
white(DEFAULT_THEME_COLOR),没有才退该范围 id 字母序第一; - 空记录(注册表没扫到任何东西时)。
「默认」是一个可读的显式值(white / black 成对),不依赖字母序巧合——新增 amber 这类排在 black 前面的 id 不会改掉默认外观。
纯 JS 宿主
包定义与配色定义接受 index.ts / index.js(并存 .ts 优先):定义本质是数据(meta / tone / tokens / views),.js 完全承载得了。无 TS 工具链的前端不必为此引入 TypeScript。