For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /zh/docs/web/theming.md (or send Accept: text/markdown).
产品主题
为你的 SaaS 定制套件的产品界面——不要改动营销品牌主题。
安装与配置
在执行任何步骤之前，请阅读开始之前 和终端基础知识。这些说明假设您在 VS Code 中打开了完整的 supastack monorepo；它的根 package.json 标记存储库根。在 pnpm 命令中，工作区包是应用程序或共享代码文件夹；在产品中，工作空间是团队的数据容器和安全边界。 corepack pnpm --filter ... 从 monorepo 选择一个包，同时从其根运行命令。如果您仅打开同步的移动或桌面文件夹，则它不包含 Web 后端、Docker 设置或根脚本：从此 monorepo 或可访问的托管服务器运行后端，并使用平台文件夹自己的脚本。环境变量是存储在本地 .env 文件或托管仪表板中的命名设置；更改后重新启动相关应用程序，并将服务器机密保留在 NEXT_PUBLIC_ 和 EXPO_PUBLIC_ 值之外。
1. 在 VS Code 中，打开 apps/web/app/app-theme.css 以显示登录产品屏幕，打开 apps/web/src/theme/catalog.ts 以添加颜色包。请勿编辑apps/web/app/theme.css产品颜色；它控制着营销品牌。
2. 从存储库根目录运行 corepack pnpm --filter @supastack/web dev，然后访问 http://localhost:3000/settings/appearance.
3. 更改本地分支中的令牌并刷新预览。预期：仪表板控件更新，而主页保留其选定的营销主题。
营销品牌与产品主题是两个独立文件。编辑 apps/web/app/app-theme.css 来定制控制台、认证、设置、计费、聊天与组织的界面。在 apps/web/src/theme/catalog.ts 中添加配色包。在 apps/web/src/theme/presets.ts 中扩展密度、圆角、字体与布局轴，并在 app-theme.css 中配上对应的 html[data-*] 规则。在 apps/web/src/theme/marketing-theme.ts 中选择营销身份（MARKETING_THEME_MODE：locked | inherit | 某个 pack id），而不是修改 apps/web/app/theme.css——该文件通过 .marketing-theme:not(.app-theme):not([data-theme]):not([data-marketing-theme="inherit"]) 默认锁定 supastack 的黑曜石首页品牌。
在运行时，设置 → 外观 → ThemePicker 会将配色、密度、圆角、字体与布局保存在浏览器 Cookie 和 localStorage 中，以便 theme-boot.ts 在首次绘制前恢复所有维度，并通过 user_appearance（GET/PUT /api/account/appearance）在多端浏览器之间同步已登录用户的完整外观配置。同一页面还挂载了套件 UI 画廊，切换主题包与预设即可实时更新按钮、输入框、卡片、徽章与对话框。设计细节与可直接复制的示例位于 docs/design/kit-product-theme.md 和 docs/design/kit-ui-gallery.md。
/* Edit product chrome here — not theme.css */
.app-theme {
--radius-card: 14px;
background: var(--page);
color: var(--text);
}
.app-theme .button-primary {
background: var(--accent);
color: var(--accent-ink);
}
/* catalog.ts — append a ThemeDefinition with every THEME_TOKEN_NAMES entry */
{
id: "coral",
name: "Coral",
colorScheme: "light",
tokens: { "--page": "#fff7f4", "--accent": "#e06b4f" /* …full token set… */ }
}要复制的命令
按照注释查看命令在哪个文件夹中运行。如果标记了两个终端，请打开两个终端窗口，并在使用第二个命令时保持第一个命令运行。
corepack pnpm --filter @supastack/web dev
# In a second terminal, after changing a theme token:
corepack pnpm test -- apps/web/src/theme/contrast.test.ts实现流程
在应用消费方（app-theme.css、globals.css 别名、WorkspaceShell 路由）优先使用 var(--page|--section|--raised|--text|--muted|--border|--accent|…)。不要重新引入青色/浅色外壳，也不要把黑曜石色值写死进产品 UI。
新增配色包时保持 contrast.test.ts 通过。新增预设 id 时，同时更新 presets.ts 与 app-theme.css 中 html[data-density|data-radius|data-font|data-layout] 的映射，让 ThemePicker 与防 FOUC 启动保持一致。
在营销表面保留 marketing/brand-geometry.ts 中共享的四格品牌几何。页眉标志保持透明；favicon 与应用图标保留圆角黑底。只要 MARKETING_THEME_MODE 保持 "locked"（套件默认），纯营销页面就保持黑曜石风格；产品可以固定另一个配色包或继承访客选择。
验证与排障
如果颜色更改影响营销主页，请检查您是否编辑了 app-theme.css 并检查 apps/web/src/theme/marketing-theme.ts. 如果文本变得难以阅读，请恢复之前的值并从根运行 corepack pnpm test -- apps/web/src/theme/contrast.test.ts，然后重试。
修改套件主题 token 或配色包后，验证 /settings/appearance 上的 ThemePicker 能更新套件 UI 画廊以及 /dashboard、/auth、/billing、/chat 与组织外壳。确认 / 仍保持黑曜石营销锁定（除非 MARKETING_THEME_MODE 另有设定）。运行主题单元契约（catalog、presets、contrast、theme-ownership、kit-ui-gallery），可用时再跑 application-theme 的 Playwright。检查键盘焦点、对比度、320px 与减少动态。