CSS 主题

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

最小 Manifest

{
  "schema": "nstatus-extension-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",
  "base_theme": "classic",
  "styles": ["theme.css"],
  "files": ["manifest.json", "theme.css", "LICENSE"]
}

schema 是 v1 扩展包的兼容性常量，必须使用示例中的字面值。它不是站点品牌名称。

字段规则

字段	规则
id	3–49 位小写字母、数字或连字符，首位必须为字母
version	SemVer，例如 1.2.0 或 2.0.0-beta.1
type	固定为 theme
mode	css；省略时也按 CSS 处理
base_theme	classic 或主题包使用的 cards 基座
styles	1–4 个包内 .css 文件，按数组顺序加载
files	推荐填写，必须与 ZIP 中全部文件完全一致
preview	可选，指向包内 PNG/JPEG/GIF/WebP/SVG
license	可选 SPDX 风格标识，例如 MIT、Apache-2.0

系统保留 admin、api、cards、classic、extensions、plugins 和 themes 等 ID。

作用域

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

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 层数。主题更新不应要求用户修改生产前端源码。

设计与可访问性

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

包结构

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

ZIP 根目录直接放置 Manifest，不要额外套一层项目文件夹。CSS 中的相对资源路径必须留在包内，不能依赖 CDN 或开发服务器。

版本策略

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

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