pi-web-theme-studio

Recolor PI WEB: curated theme presets plus a visual --pi-* color customizer.

Packages

Package details

package

Install pi-web-theme-studio from npm and Pi will load the resources declared by the package manifest.

npm report
$ pi install npm:pi-web-theme-studio
Package
pi-web-theme-studio
Version
1.0.0
Published
Aug 13, 2026
Downloads
145/mo · 22/wk
Author
samecorner
License
MIT
Types
package
Size
161.8 KB
Dependencies
0 dependencies · 0 peers
Pi manifest JSON
{
  "image": "https://raw.githubusercontent.com/samecorner/pi-web-theme-studio/main/docs/screenshot.png"
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-web-theme-studio

PI WEB 主题 / 配色自定义插件。两种方式改配色：

Theme Studio

  1. 精选预设：贡献 7 套完整配色（Tokyo Night / Nord / Catppuccin Mocha / Solarized Light / One Dark / Dracula / Gruvbox Dark），直接出现在 PI WEB 自带的主题选择器里，并支持跟随系统明/暗。
  2. Theme Studio 面板：可视化调整每一个 --pi-* 颜色变量，实时预览、存为预设、导出 CSS、一键重置。

⚠️ 兼容性说明：本插件依赖 pi-web 源码中已存在的 themes / themePairs 插件贡献类型（见 src/client/src/plugins/types.ts 的 ThemeContribution / ThemePairContribution）以及那套 --pi-* 设计变量（src/client/src/theme.ts 的 THEME_TOKENS，共 35 个）。这是 pi-web 渲染 UI 时实际消费的变量，组件样式里都是 var(--pi-*)，没有硬编码颜色。若你的 pi-web 版本较旧、没有 themes 贡献类型，预设不会出现在选择器里，但 Theme Studio 面板的自定义覆盖仍有效（见下文原理）。

工作原理

  • 预设（themes 贡献）：宿主在切换主题时，会把每套主题的全部 35 个 --pi-* token 以内联 style 写到 <html>（applyPiWebTheme）。贡献 themes 即把我们的调色板交给宿主，进入原生主题选择器，持久且能跟随系统。
  • 自定义覆盖（Theme Studio）：面板把用户调整的颜色注入一段 <style id="pi-theme-studio-override">，内容为 :root { --pi-*: <值> !important }，挂到 document.head。因为 !important 的样式表规则优先于 <html> 上的非 !important 内联值，所以它能盖过任何主题，并且在你切换主题 / 系统明暗变化 / 热重载时不会被冲掉——相当于一层持久的自定义配色。
  • 持久化：覆盖写入 localStorage（pi-theme-studio:override），插件加载时自动恢复；预设列表存于 pi-theme-studio:presets。

功能

  • 顶部按钮：应用并保存（提交覆盖到本地）、保存为预设、导出 CSS（复制 :root{...} 到剪贴板）、重置全部（清覆盖，回到当前主题）。
  • 精选配色区：一键应用 7 套预设。
  • 实时预览区：accent / success / warning / danger / purple / surface 色板，改色即时反映。
  • 我的预设区：保存 / 加载 / 删除自定义预设。
  • 调色板区：按「背景与表面 / 文本 / 边框 / 品牌色 / 表面与状态 / 叠加与阴影」分组，共 35 个 --pi-* 变量，每个含「拾色器 + CSS 值文本框（支持 8 位 hex / rgba）+ 单项重置」。
  • 命令面板：Open Theme Studio / Reset Custom Theme / Copy Theme CSS。

安装

推荐（发布版）：在 PI WEB 的 Settings → Pi packages 填入 github:samecorner/pi-web-theme-studio，或命令行 pi install github:samecorner/pi-web-theme-studio。

也可以整目录手动放到插件根下：

~/.pi-web/plugins/theme-studio/

~ 即用户主目录（Windows：C:\Users\<你的用户名>\.pi-web\plugins\theme-studio）。

复制安装

# Windows (PowerShell)
$src = "C:\Users\yangj\WorkBuddy\2026-08-13-10-48-04\pi-web-theme-studio"
$dst = "$env:USERPROFILE\.pi-web\plugins\theme-studio"
New-Item -ItemType Directory -Force -Path $dst | Out-Null
Copy-Item -Recurse -Force "$src\*" $dst

# macOS / Linux
cp -R ./pi-web-theme-studio ~/.pi-web/plugins/theme-studio

启用并验证

  1. 重启 sessiond 或刷新 pi-web 页面。
  2. 验证 manifest：curl http://127.0.0.1:8504/pi-web-plugins/manifest.json 应含 "id":"theme-studio"。
  3. 打开 PI WEB：
    • 侧栏出现 Theme 面板（命令面板搜 Theme Studio）。
    • 设置里的主题选择器应多出 Tokyo Night / Nord / Catppuccin Mocha / Solarized Light，以及一对「Theme Studio」（跟随系统）。

调试

  • 预设没出现在主题选择器：多为 pi-web 版本不支持 themes 贡献类型。不影响 Theme Studio 面板的自定义覆盖（走 !important 注入，不依赖该类型）。可在 DevTools 控制台确认 document.getElementById('pi-theme-studio-override') 是否存在来排查覆盖是否注入。
  • 改了色但没生效：确认覆盖 <style> 已注入；!important 会盖过内联主题值，但若别的插件/样式也用 !important 同名变量且后加载，则后者优先。
  • 切换系统明暗后自定义色没了：不会——!important 覆盖在切主题时仍占优。若你清空了覆盖，则回归当前选中主题。
  • 想还原：面板 重置全部，或命令 Reset Custom Theme。

文件结构

pi-web-theme-studio/
├── package.json          # 插件清单（piWeb.plugins[].id = "theme-studio"）
├── pi-web-theme.js        # 入口：activate() 贡献 themes / themePairs / workspacePanels / actions
├── theme-presets.js       # 完整 37 token 基色 + makeTheme + 7 套精选预设 + 分组定义
├── theme-studio.js        # <pi-web-theme-studio> 自定义元素：拾色器 / 预览 / 预设 / 导入导出
├── theme-studio-styles.js # 面板样式（复用 --pi-* 主题变量）
├── theme-runtime.js       # 覆盖注入（!important）、localStorage 持久化、剪贴板
└── README.md

已知限制

  • 依赖 pi-web 的 --pi-* 变量体系；若某组件未来改用硬编码颜色，对应处不受主题影响。
  • 预设仅对支持 themes 贡献类型的 pi-web 版本进入原生选择器。
  • 自定义覆盖用 !important，如遇同样 !important 的其它来源竞争，后加载者胜。
  • <input type=color> 仅支持 6 位 hex；含透明通道（8 位 hex / rgba）的颜色请用旁边的文本框编辑。

License

MIT