vastsa · Frank-zhu0404 · Sep 17, 2026
diff --git a/docs/plugin-development.md b/docs/plugin-development.md
@@ -541,6 +541,26 @@ Override PI-Desktop design tokens in that CSS. The host sanitizes contributed
 CSS, refuses imports and non-data URLs, caps each file at 256 KiB, and allows up
 to eight themes per plugin. The user selects the theme in Settings.
 
+Theme contract details:
+
+- `base` is `"light"` or `"dark"` and defaults to `dark` — the palette your
+  overrides layer on.
+- Contributed sheets are appended after the app stylesheets, but append order
+  only wins when specificity is equal. Dark/shared tokens live on
+  `:root, :root[data-theme="dark"]`; light tokens live on
+  `:root[data-theme="light"]`. To override light tokens you must write
+  `:root[data-theme="light"] {…}` (match the shell selector for your `base`).
+- Optional `assets` (absolute paths; extension whitelist
+  png/jpg/jpeg/webp/avif/svg/woff2; 4 MB summed) rewrites matching `url()` to
+  `plugin-asset://…`.
+- Optional `contributes.windowAppearance` (`#rrggbb` / `#rrggbbaa`) needs the
+  `ui.window.appearance` permission and applies only while one of this plugin's
+  themes is selected.
+
+See the [manifest schema](spec/07-plugins/02-plugin-manifest-schema.md) and
+[plugin security §3.1](spec/07-plugins/04-plugin-security.md#31-contributed-theme-css)
+for the full field list and sanitizer rules.
+
 ### 6.8 Work panel view
 
 A view is an interface docked in the app's right work panel, next to Review,

diff --git a/docs/spec/04-ux/07-ui-design-system.md b/docs/spec/04-ux/07-ui-design-system.md
@@ -16,7 +16,7 @@ The desktop shell targets a 1:1 visual match with the local Codex desktop client
 1. A consumer-brand identity system with vibrant gradients or playful illustrations
 2. A full component library spec (that is [08-component-spec.md](08-component-spec.md))
 3. Custom font services or CDN font hosting — use local bundling
-4. Complex theme marketplace or user-customizable color palettes (MVP: system/light/dark only)
+4. Complex theme marketplace or end-user palette editors (built-in theme entries remain system/light/dark; plugins may contribute theme entries via `ui.theme`)
 5. Pixel-perfect Figma handoff artifacts
 
 ## 3. Visual principles

diff --git a/docs/spec/07-plugins/04-plugin-security.md b/docs/spec/07-plugins/04-plugin-security.md
@@ -107,7 +107,13 @@ before it is ever sent to the UI:
   `vibrancy` and is never sent one
 - The CSS is read from disk at load time and delivered whole over IPC; the
   renderer injects it into a single dedicated `<style>` element appended after
-  the app's own stylesheets, so it can override tokens but never inject markup
+  the app's own stylesheets, so it can override tokens but never inject markup.
+  Append order only wins when specificity is equal: dark and shared tokens are
+  declared on `:root, :root[data-theme="dark"]` (specificity `(0,1,0)`), while
+  light tokens use `:root[data-theme="light"]` (specificity `(0,2,0)`). A bare
+  `:root {…}` rule therefore wins in dark mode but loses under light; to override
+  light tokens, write `:root[data-theme="light"] {…}` (match the shell selector
+  for the declared `base` so load order decides)
 - Selecting a theme is a settings value (`plugin:<pluginId>:<themeId>`); if the
   providing plugin is disabled or uninstalled the setting falls back to `system`
 

diff --git a/docs/zh-CN/plugin-development.md b/docs/zh-CN/plugin-development.md
@@ -513,9 +513,25 @@ root 本身。`net.fetch` 接受 HTTP(S)，并且只能到达 `manifest.net.doma
 }
 ```
 
-覆盖该 CSS 中的 PI-Desktop 设计标记。楼主对贡献的内容进行了清理
-CSS，拒绝导入和非数据 URL，每个文件的上限为 256 KiB，并允许
-每个插件有八个主题。用户在“设置”中选择主题。
+覆盖该 CSS 中的 PI-Desktop 设计标记。宿主会对贡献的 CSS 做清理，拒绝
+导入和非 data URL，每个文件上限 256 KiB，每个插件最多八个主题。用户在
+「设置」中选择主题。
+
+主题契约要点：
+
+- `base` 为 `"light"` 或 `"dark"`，默认 `dark` —— 覆盖层叠在其上的调色板。
+- 贡献的样式表追加在应用样式表之后，但仅在特异度相同时靠顺序取胜。深色与
+  共享令牌在 `:root, :root[data-theme="dark"]`；浅色令牌在
+  `:root[data-theme="light"]`。要覆盖浅色令牌必须写
+  `:root[data-theme="light"] {…}`（与壳层为你的 `base` 使用的选择器对齐）。
+- 可选 `assets`（绝对路径；扩展名白名单 png/jpg/jpeg/webp/avif/svg/woff2；
+  总量 4MB）会把匹配的 `url()` 改写为 `plugin-asset://…`。
+- 可选 `contributes.windowAppearance`（`#rrggbb` / `#rrggbbaa`）需要
+  `ui.window.appearance` 权限，且只在本插件某个主题被选中时生效。
+
+完整字段与清理规则见
+[清单 Schema](/zh-CN/spec/07-plugins/02-plugin-manifest-schema) 与
+[插件安全 §3.1](/zh-CN/spec/07-plugins/04-plugin-security#31-贡献主题css)。
 
 ### 6.8 MCP 服务器
 

diff --git a/docs/zh-CN/spec/04-ux/07-ui-design-system.md b/docs/zh-CN/spec/04-ux/07-ui-design-system.md
@@ -19,7 +19,7 @@
 1. 具有充满活力的渐变或有趣的插图的消费者品牌识别系统
 2. 完整的组件库规范（即[08-component-spec.md](/zh-CN/spec/04-ux/08-component-spec)）
 3. 自定义字体服务或 CDN 字体托管 — 使用本地捆绑
-4. 复杂的主题市场或用户可自定义的调色板（仅限 MVP：仅限 system/light/dark）
+4. 复杂的主题市场或终端用户调色板编辑器（内置主题项仍为 system/light/dark；插件可通过 `ui.theme` 贡献主题条目）
 5. 像素完美的 Figma 切换伪影
 
 ## 3. 视觉原则

diff --git a/docs/zh-CN/spec/07-plugins/04-plugin-security.md b/docs/zh-CN/spec/07-plugins/04-plugin-security.md
@@ -69,9 +69,13 @@
   `ui.window.appearance`，且只在该插件的某个主题被选中时生效；离开该主题即恢复
   宿主背景，因为颜色由实时主题目录推导而非记忆。macOS 保持 `vibrancy`，
   永不下发颜色
-- CSS 在加载时从磁盘读取并通过 IPC 整体交付；的
-  渲染器将其注入到附加在后面的单个专用 `<style>` 元素中
-  应用程序自己的样式表，因此它可以覆盖令牌但从不注入标记
+- CSS 在加载时从磁盘读取并通过 IPC 整体交付；渲染器将其注入到附加在应用
+  程序自己的样式表之后的单个专用 `<style>` 元素中，因此它可以覆盖令牌但从不
+  注入标记。仅在特异度相同时，追加顺序才决定胜负：深色与共享令牌声明在
+  `:root, :root[data-theme="dark"]`（特异度 `(0,1,0)`），浅色令牌声明在
+  `:root[data-theme="light"]`（特异度 `(0,2,0)`）。因此裸 `:root {…}` 在深色下
+  能赢、在浅色下会输；要覆盖浅色令牌必须写 `:root[data-theme="light"] {…}`
+  （与壳层为所声明 `base` 使用的选择器对齐，再靠加载顺序取胜）
 - 选择主题是一个设置值（`plugin:<pluginId>:<themeId>`）；如果
   如果插件被禁用或卸载，设置将回退到 `system`