From 5f0e5c3124b674731d59331b882ba38061db1fc1 Mon Sep 17 00:00:00 2001 From: Frank_zhu <58329837+Frank-zhu0404@users.noreply.github.com> Date: Thu, 17 Sep 2026 17:38:47 +0000 Subject: [PATCH] docs: align theme contract docs with light selector rules (#343) Document that light-token overrides need :root[data-theme="light"], acknowledge plugin ui.theme contributions in the design-system non-goals, and fill base/assets/windowAppearance gaps in the plugin developer guide. --- docs/plugin-development.md | 20 +++++++++++++++++ docs/spec/04-ux/07-ui-design-system.md | 2 +- docs/spec/07-plugins/04-plugin-security.md | 8 ++++++- docs/zh-CN/plugin-development.md | 22 ++++++++++++++++--- docs/zh-CN/spec/04-ux/07-ui-design-system.md | 2 +- .../spec/07-plugins/04-plugin-security.md | 10 ++++++--- 6 files changed, 55 insertions(+), 9 deletions(-) diff --git a/docs/plugin-development.md b/docs/plugin-development.md index a4898f214..397144840 100644 --- 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 index 7b8ff2b31..70abdc292 100644 --- 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 index b298ccce1..abf5237f8 100644 --- 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 `