主題

Astromer 使用 data-palette 選擇配色，使用 data-theme + light-dark() 管理亮/暗模式。兩者互相獨立：切換配色會保留目前的亮暗模式。

選擇調色盤

文件與 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；無效值應回到有效預設配色。

切換方式

在 <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。