主題

Astromer 將外觀分成三個可獨立組合的軸：data-palette 提供語義色彩，data-theme 搭配 light-dark() 管理亮色、暗色或系統模式，data-visual-theme 選擇字體、形狀與排版節奏。切換其中一軸不會更改另外兩軸。

選擇調色盤

文件與 Playground 頂部的「調色盤」可將同一版面套用三套配色。每套都有自己的主色，並同步調整背景、文字、邊框與輔助色。

調色盤	`data-palette`	主色方向
星雲光譜	`nebula`	玫瑰色，呈現星雲的鮮明光譜
晨光天體	`celestial`	青藍色，呈現清澈的天體光線
星際餘暉	`ember`	暖金色，呈現星際光芒與餘暉

三套色彩以宇宙、星雲與天體意象為靈感，主色用於主要操作，輔助色用於裝飾與層次；亮暗版本分別調整明度。它們並非將所有元件換成同一個色碼。實際內容仍需檢查文字對比、焦點與狀態辨識，尤其是在自行覆寫 token 之後。

<html lang="zh-TW" data-palette="celestial" data-theme="dark">

data-palette 接受 nebula、celestial 或 ember。文件與 Playground 預設為 nebula；套件使用者未設定 data-palette 時，沿用原本的預設 tokens。

// 配色與亮暗模式可以分別切換。
document.documentElement.setAttribute("data-palette", "ember");
document.documentElement.setAttribute("data-theme", "light");

文件與 Playground 的選擇器會將配色偏好存入 astromer-palette，跨頁與重新載入時沿用。此儲存行為屬於示範網站的介面，@astromer/tokens 本身只提供 CSS，不會存取 localStorage。整合自己的網站時，可自行管理偏好，讀取時先驗證配色 ID；無效值應回到有效預設配色。

選擇視覺 Theme

視覺 Theme 是選用的 CSS，需在需要它的頁面匯入。Celestial 以現有元件呈現編輯式字體、細線與寬鬆節奏；它不指定 palette，也不要求下載額外字型。未匯入 Theme CSS 或未設定 data-visual-theme 的舊頁面會沿用原有外觀。

@import "@astromer/tokens";
@import "@astromer/core/styles";
@import "@astromer/tokens/themes/celestial";

只在需要套用 Celestial 的頁面根元素設定屬性：

<html lang="zh-TW" data-theme="dark" data-palette="ember" data-visual-theme="celestial">

各屬性的職責保持分開：

data-theme：light、dark 或 auto，決定亮暗色彩模式。
data-palette：nebula、celestial 或 ember，提供背景、文字、品牌與狀態色。
data-visual-theme：例如 celestial，提供視覺樣式，不改寫前兩者。

Theme CSS 不會保存偏好或修改根元素；偏好管理由使用者的應用程式負責。可在 Celestial 跨元件示範檢視標題、按鈕、卡片與表單狀態。

SVG 裝飾元件是另一個可選的 core component subpath，不會由 Theme 自動套用。請參考 SVG ornaments 指南了解靜態符號與 frame 的用法和語意界線。

切換方式

在 <html> 上設定 data-theme：

data-theme="light" — 強制亮色
data-theme="dark" — 強制暗色
data-theme="auto" — 跟隨系統 prefers-color-scheme

範例

<html lang="zh-TW" data-theme="auto">

用 JavaScript 切換並可選持久化：

document.documentElement.setAttribute("data-theme", "dark");
localStorage.setItem("astromer-theme", "dark");

頁面載入時從 localStorage 讀回即可。

Token 層級

Primitive — 原色與數值（@astromer/tokens 的 primitives.css）
Semantic — light-dark() 語義變數（semantic.css）
Component — 元件級覆寫（如 --am-button-bg）

檢查實際元件

Playground 每一頁的頂部都有「主題」選項，可在同一示範直接比較亮色、暗色與系統模式。選取狀態使用原生 radio 呈現，偏好儲存於 astromer-theme；無法使用 localStorage 時，當頁切換仍可操作。

文件站的 Starlight 主題選單與 Playground 各自保存偏好。整合自己的網站時，請以 <html data-theme> 作為 Astromer 元件的主題來源，並在套用儲存值前驗證值為 light、dark 或 auto。