mengrru/spherse/spherse-create-ui-theme

自定义 UI 主题

Spherse 支持通过项目级 CSS 变量覆盖来自定义 UI 外观。在项目根目录创建 .spherse/theme.css，覆盖对应的 CSS 变量即可生效。

所有 design token 统一使用 --sp-* 前缀（Spherse 自有命名空间）。只覆盖你想修改的变量，未覆盖的保持默认。

可用变量

所有变量都支持浅色和深色两套值（深色值由 OS prefers-color-scheme 驱动）。

页面与容器

弹出层

交互元素

文字层级

边框与输入

语义色

圆角

滚动条

应用内所有可滚动区域（聊天消息列表、文件树、内容浏览器、下拉菜单、对话框等）统一使用细滚动条，存在感弱，可在浅色/深色下自动适配。size 控制宽高，thumb / thumb-hover 是滑块常态与悬停色，track 是轨道背景（默认透明）。

变量遵循 CSS 级联，因此可在特定容器作用域内覆盖，实现局部定制。例如只让聊天窗口的滚动条变色：

```css

/ .spherse/theme.css —— 仅聊天窗口滚动条变色 /

[data-chat-root] {

--sp-scrollbar-thumb: rgba(201, 160, 74, 0.6);

--sp-scrollbar-thumb-hover: rgba(201, 160, 74, 0.85);

}

```

如需完全自定义滚动条（如不同方向不同样式、动画），直接在 .spherse/theme.css 中以更高优先级或相同特异性重写 ::-webkit-scrollbar 系列伪元素规则即可（项目主题 CSS 在应用样式之后注入，相同特异性下胜出）。

侧边栏

示例

暖色调主题

/* .spherse/theme.css */
:root {
  --sp-background: #faf8f5;
  --sp-foreground: #3d2c1e;
  --sp-primary: #8b5e34;
  --sp-primary-foreground: #faf8f5;
  --sp-accent: #f0e6d8;
  --sp-accent-foreground: #3d2c1e;
  --sp-muted: #f0e6d8;
  --sp-muted-foreground: #8a7a68;
  --sp-border: #e0d5c8;
  --sp-card: #ffffff;
  --sp-popover: #ffffff;
}
 
@media (prefers-color-scheme: dark) {
  :root {
    --sp-background: #1a1612;
    --sp-foreground: #e8ddd0;
    --sp-primary: #d4a574;
    --sp-primary-foreground: #1a1612;
    --sp-accent: #2d2418;
    --sp-accent-foreground: #e8ddd0;
    --sp-muted: #2d2418;
    --sp-muted-foreground: #a0917e;
    --sp-border: #3d3228;
    --sp-card: #231e18;
    --sp-popover: #231e18;
  }
}

增大圆角

/* .spherse/theme.css */
:root {
  --sp-radius: 0.75rem;
}

钩子与作用域

• 共享交互组件使用 Base UI，不是 Radix。
• 以语义 data-* 钩子和 data-slot 为样式入口，具体对象与状态见各节，可自由组合 CSS 定制外观。
• Portal 浮层位于触发位置的 DOM 层级之外，用自身钩子定制；全局配色放在 :root，便于主布局与浮层共同继承。

应用根容器 / 全局装饰

data-app-root 是应用主布局的根容器，铺满视口（100vh，已 position: relative 且 overflow: hidden），包含 activity bar、项目面板、主内容区与内嵌聊天窗口。它适合用 ::before / ::after 叠加全局背景、噪点纹理、边角装饰等，但不是所有可见 UI 的 DOM 共同祖先：通过 Portal 渲染的对话框、菜单、提示与聊天浮窗等位于其外部，需用各自的钩子定制。

示例：

/* .spherse/theme.css —— 整窗背景（渐变 / 本地图片，相对路径基于 .spherse/ 解析） */
[data-app-root] {
  background: radial-gradient(ellipse at 20% 50%, rgba(201, 160, 74, 0.06) 0%, transparent 50%),
              linear-gradient(180deg, #0c0b12 0%, #11101a 100%);
}
 
/* 用 ::before 叠一层铺满窗口的装饰（纹理 / 噪点），默认位于内容之下 */
[data-app-root]::before {
  content: '';
  position: absolute;
  inset: 0;
  background: url('https://example.com/noise.png') repeat;
  opacity: 0.04;
  pointer-events: none;
  z-index: 0;
}
 
/* 角落装饰：左上角的角标 / 印章 */
[data-app-root]::after {
  content: '';
  position: absolute;
  top: 12px;
  inset-inline-start: 12px;
  width: 64px;
  height: 64px;
  background: url('./assets/corner-mark.png') no-repeat center / contain;
  opacity: 0.5;
  pointer-events: none;
}
 
/* 主布局内的固定装饰层（如水印），层级仍受祖先堆叠上下文约束 */
[data-app-root] > .my-watermark {
  position: fixed;
  inset: 0;
  z-index: 9999;
  pointer-events: none;
}

- [data-app-root] 已是定位上下文，::before / ::after 默认已被应用设为 position: absolute; pointer-events: none（相对整窗定位、不挡交互），因此只需写装饰属性即可，漏写也不会进入 flex 流导致整窗偏移；如需固定层（position: fixed）或可交互叠层（pointer-events: auto），显式覆盖即可。overflow: hidden 会自动裁剪超出窗口的部分。

- 装饰默认处于内容之下：内容区的背景多为半透明或 --sp-background，叠在最外层根容器上的装饰会从内容半透明处透出。若要让装饰盖在内容之上，给伪元素或固定层显式设较高的 z-index 并加 pointer-events: none，避免遮挡交互。

- 根容器内的高 z-index 不保证盖过外部 Portal 浮层；不要通过改变应用根的 transform / filter 等属性来假设所有浮层会一起定位或装饰。

- 本地图片用相对路径（url('./assets/x.png') 基于项目 .spherse/ 目录解析），或远程 URL（项目主题同样以 <link> 从 preview 路由载入，相对 url() 解析到项目文件）。

侧边区域

桌面容器与移动端抽屉是不同渲染分支，不是嵌套关系；抽屉遮罩是独立的兄弟元素，不在 data-side-panel-drawer 内。面板隐藏通过 inert 与位移处理，没有专用的 data-open / data-pinned 属性，定制时保留定位与收起动画。

data-activity-bar 的外层还独立保留了 52px 宽度，只修改该钩子的宽度不会同步改变布局占位。侧边区域内部各面板有自己的背景，修改外层背景不一定可见。

Activity Bar 项目头像

应用最左侧 activity bar 上的项目头像暴露了语义钩子，可在项目级 .spherse/theme.css 中定制其外观（背景、边框、圆角、选中/未选中态等）。

示例：

/* .spherse/theme.css —— 项目头像自定义背景与圆角 */
[data-project-avatar] {
  background: var(--sp-primary);
  color: var(--sp-primary-foreground);
  border-radius: 9999px;
}
 
/* 选中态加描边，未选中态降低透明度 */
[data-project-avatar][data-active] {
  outline: 2px solid var(--sp-primary);
}
[data-project-avatar]:not([data-active]) {
  opacity: 0.4;
}

头像默认选中态为 opacity-100、未选中态为 opacity-30，均通过 class 而非 inline style 控制，可被相同或更高特异性的主题规则覆盖。

项目面板与内容浏览器

除了聊天窗口，项目级 .spherse/theme.css 还可以定制项目面板和内容浏览器的背景与外观。

示例：

/* .spherse/theme.css —— 项目面板背景图 */
[data-project-panel] {
  background: linear-gradient(180deg, #1a1a2e 0%, #16213e 100%);
}
 
/* 内容浏览器背景 */
[data-content-browser] {
  background: url('https://example.com/paper-texture.png') repeat;
}
 
/* 标签栏与活跃标签 */
[data-tab-bar] {
  background: #16213e;
}
[data-tab][data-active="true"] {
  background: #1a1a2e;
  color: #f4d35e;
}

> 项目面板内部使用 shadcn/ui sidebar 组件（--sp-sidebar 系列变量控制纯色背景）。设 background / background-image 可覆盖纯色实现图片/渐变背景。

标签栏定制

标签默认是直角矩形，仅靠右侧边框分隔；形状、间距、活跃态都可在 .spherse/theme.css 中改写。项目主题以无层（unlayered）CSS 注入，普通选择器即可覆盖应用内置的 Tailwind 样式，无需 !important。标签外层有一个 display: contents 的右键菜单包装元素（不产生盒、不影响布局），主题选择器请用后代选择器（如 [data-tab-scroll] [data-tab]），不要对标签用直接子选择器。

/* 圆角「胶囊」标签 + 活跃态渐变与下划线 */
[data-tab-bar] {
  padding: 4px 6px 0;
  border-bottom: none;
}
[data-tab-scroll] {
  gap: 4px;
}
[data-tab] {
  border: none;
  border-radius: 8px 8px 0 0;
}
[data-tab][data-active="true"] {
  background: linear-gradient(180deg, #ffffff, #f3e8ff);
  box-shadow: inset 0 -2px 0 #a855f7;
}
[data-tab]::after {
  content: "";
  position: absolute;
  inset: auto 8px 0;
  height: 2px;
  border-radius: 1px;
  background: transparent;
  transition: background 0.2s;
}
[data-tab]:hover::after { background: #d8b4fe; }
 
/* 按类别区分颜色 */
[data-tab="chat"] { color: #2563eb; }
[data-tab="file"] { color: #059669; }
 
/* 拖拽指示条 */
[data-tab-drop-indicator] { width: 3px; border-radius: 2px; background: #a855f7; }

注意事项：

• 纵向会被裁剪：标签栏固定高度（约 36px）且纵向 overflow: hidden（data-tab-scroll 内横向可滚动）。向外的投影、transform: translateY 上浮等超出标签栏上下边界的效果会被裁掉——优先用 inset 阴影、内边距；确需外溢时同时覆盖 [data-tab-bar] 的 height / padding
• 标签间距加在滚动容器上：[data-tab-bar] 的 gap 只作用于欢迎页标签与 [data-tab-scroll] 之间，各内容标签的间距需对 [data-tab-scroll] 设置
• 伪元素可自由使用：[data-tab] 自身是定位上下文（position: relative），::before / ::after 均未被占用，装饰伪元素记得写 position: absolute，避免挤压标签内容
• 标签内部元素无专属钩子：文字按钮与关闭按钮暂未暴露 data-* 钩子，如需微调只能用 [data-tab] > button 之类的结构选择器，应用更新时可能失效，尽量只在 [data-tab] 层定制
• 欢迎页标签：[data-tab="welcome"] 固定在首位且无关闭按钮，位于 [data-tab-scroll] 外、横向滚动时常驻可见，可用该选择器单独设计
• 标签栏在聊天窗口之外，agent 主题不影响它，只能在项目级 .spherse/theme.css 定制

设置页签（Tabs）

设置与 Agent 编辑表单使用共享 Tabs 组件，与上文文档/会话标签栏的 [data-tab] 不是同一套钩子。

选中态使用 [data-active]，不是 [data-active="true"] 或 [data-state="active"]。列表的 data-variant="line" 变体使用按钮的 ::after 作为指示线，定制伪元素时避免覆盖它。

对话框（Dialog）

使用共享 Dialog 组件的对话框通过 data-slot 暴露样式入口，没有额外的 data-dialog-* 钩子。可在项目级 .spherse/theme.css 中用以下选择器统一定制：

弹窗主体默认使用 --sp-popover / --sp-popover-foreground 配色（见「弹出层」变量表）。这些选择器会匹配所有使用对应组件的对话框，不仅是主题设置弹窗。