CSS 主题

CSS 主题在不替换公开页面功能的前提下改变视觉。不执行 JavaScript，适合配色、字体、密度、边框、状态样式与响应式细节。

最小 Manifest

json

{
  "schema": "nie-sla-theme-v1",
  "id": "example-theme",
  "name": "Example Theme",
  "version": "1.0.0",
  "type": "theme",
  "mode": "css",
  "author": "Developer",
  "description": "A restrained NIE-SLA theme.",
  "license": "MIT",
  "styles": ["theme.css"],
  "files": ["manifest.json", "theme.css"]
}

schema 是当前主题包兼容性常量，使用字面值 nie-sla-theme-v1。

字段规则

字段	规则
`id`	3–49 位小写字母、数字或连字符，首位必须为字母
`version`	SemVer，如 `1.2.0` 或 `2.0.0-beta.1`
`type`	固定为 `theme`
`mode`	`css`；省略时按 CSS 处理
`styles`	1–4 个包内 `.css` 文件，按数组顺序加载
`files`	推荐填写，必须与 ZIP 内全部文件完全一致
`preview`	可选，指向包内 PNG/JPEG/GIF/WebP/SVG
`license`	可选 SPDX 风格标识，如 `MIT`、`Apache-2.0`
`repository` / `homepage`	可选无凭据 HTTPS URL，最长 500 字符

name 与 author 最长 64 字符，description 最长 240 字符，license 最长 32 字符。系统保留 admin、api、classic、extensions、plugins、themes 等 ID。未知字段不会成为运行能力，不能用自定义字段申请脚本权限。

作用域

主题专属规则限定在自己的 ID：

css

body[data-extension-theme="example-theme"] {
  --bg: #f5f8f7;
  --paper: #ffffff;
  --text: #13201e;
  --muted: #64736f;
  --line: #d7e0dd;
  --green: #087d71;
  --red: #d9503f;
  --yellow: #b7791f;
  --blue: #2563a8;
  --radius: 6px;
  --shadow: 0 10px 28px rgba(17, 39, 35, 0.08);
}

优先覆盖宿主公开变量，不要依赖深层 nth-child、自动生成 class 或当前 DOM 层数。主题更新不应要求用户修改生产前端源码。

样式可以引用包内字体与图片；远程 URL 受站点 CSP 与供应链策略限制，正式包应自包含。

设计与可访问性

正文与背景对比度达到 WCAG AA。
状态不只依赖颜色，保留文字或图形差异。
不隐藏错误、焦点、状态说明与关键控件。
保留清晰的 :focus-visible。
尊重 prefers-reduced-motion。
字体提供本地回退。
320、375、768、1280、1440 像素宽度无横向溢出。
长 VPS 名、商家、城市、线路与标签不覆盖相邻信息。

包结构

text

manifest.json
theme.css
assets/
  display.woff2
preview.webp

Manifest 在 ZIP 根目录，不要额外套一层项目文件夹。CSS 相对资源路径留在包内，不依赖 CDN 或开发服务器。运行包不接受无扩展名 LICENSE/NOTICE 或 Markdown；完整许可证保留在源码仓库与 Release 页面，ZIP 用 Manifest 的 license 字段。

版本策略

修复颜色或布局缺陷：PATCH。
增加兼容样式与新可选能力：MINOR。
改变既有界面语义或要求新宿主结构：MAJOR。

启用前至少测试安装、默认停用、启用、停用、同 ID 升级与删除。

本地检查

bash

find dist -type f -print | LC_ALL=C sort
(cd dist && zip -X -r ../release/example-theme-1.0.0.zip .)
shasum -a 256 release/example-theme-1.0.0.zip

上传同 ID 新版本会删除旧 revision 且保持停用，不是在线热替换。先在测试部署验证，再由管理员核对 SHA-256 后启用。

CSS 主题 ​

最小 Manifest ​

字段规则 ​

作用域 ​

设计与可访问性 ​

包结构 ​

版本策略 ​

本地检查 ​