> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# 產品主題

為你的 SaaS 定製套件的產品介面——不要改動營銷品牌主題。

## 安裝與配置

在執行任何步驟之前，請閱讀[開始之前](https://supastack.dev/zh-tw/docs/web/before-you-start.md) 和[終端基礎知識](https://supastack.dev/zh-tw/docs/web/terminal-basics.md)。這些說明假設您在 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 與減少動態。


## 下一篇

[UI 套件與區塊](https://supastack.dev/zh-tw/docs/web/ui-kit.md)