主题

打开主题展示，在同一页比较三套主题的亮暗外观。

风格与明暗独立选择

默认、Mono 与 Material 风格通过相同公开 API 派生。Mono 使用黑白灰、克制圆角与阴影，并保留语义色；Material 参考 MUI 的中性表面、4px 默认圆角与层级阴影，保留 Apollo 的组件交互规范。公开入口仍为 material3，可在主题展示中比较亮暗效果。

<script setup lang="ts">
import { ConfigProvider, Button } from '@apollo-design/ui';
import { monoPreset } from '@apollo-design/theme/presets/mono';

const theme = {
  preset: monoPreset,
  mode: 'system' as const,
  token: { colorPrimary: '#6455ff', borderRadius: 8 },
  components: { Button: { paddingInline: 20 } },
};
</script>

<template>
  <ConfigProvider :theme="theme">
    <Button type="primary">自定义 Mono</Button>
  </ConfigProvider>
</template>

独立入口分别是 @apollo-design/theme/presets/default、/mono、/material3，具名导出为 defaultPreset、monoPreset、material3Preset，同时提供默认导出。根入口只导出类型与派生服务，不加载全部预设。自定义预设使用公开 ThemePreset 数据结构，无需向 resolver 注册。

ThemeConfig.mode 支持 light | dark | system。实时 Provider 在挂载后响应系统偏好并释放监听；纯函数 getDesignToken(config, systemAppearance?) 与 SSR 缺省按 light 派生，服务端已知偏好时可传第二个参数 'dark'。

覆盖顺序与嵌套边界

派生顺序为：默认种子 → 预设公共 Token → 所选明暗方案 → 用户种子覆盖并派生 → 用户 Map/Alias 最终覆盖。组件 Token 在组件作用域覆盖相应默认值。局部显式 algorithm 优先于继承的 mode；局部显式 mode 优先于继承的 algorithm。因此演示局部暗色算法的 Demo 仍保留自己的意图。

ConfigProvider 默认继承父级原始主题配置，theme.inherit: false 重置继承。独立 ThemeProvider 保留原有默认重置语义；要合并父级，请显式设置 theme.inherit: true。两者都在原始配置层合并，避免把父级派生后的颜色当成下一层种子。并排 Provider、嵌套 Provider、所属 Portal 和通过 App/上下文 API 创建的 Message/Notification 保持各自主题边界。

<ConfigProvider :theme="{ preset: monoPreset, mode: 'dark' }">
  <Button>继承 Mono 暗色</Button>
  <ConfigProvider :theme="{ token: { borderRadius: 12 } }">
    <Button>继承配色，仅覆盖圆角</Button>
  </ConfigProvider>
</ConfigProvider>

静态资源与三种引入方式

JS、组件结构 CSS 与主题选择彼此独立。参见样式引入中的自动按需、手工子路径、全量三种入口及加载顺序。Provider 会在已有组件作用域更新 CSS 变量，不重挂组件；静态 CSS 仍需显式引入。

也可使用可选 @apollo-design/theme/presets/default.css、/mono.css、/material3.css。每份由同一 getDesignToken 公开 API 生成，含 light/dark/system 选择器，不引用另一份预设。选择器示例：

<html data-apollo-preset="mono" data-apollo-theme="system">

自行覆盖原生 CSS 变量无需运行时，但种子变量的覆盖不会自动重算整套派生色阶；需要派生时使用 Provider 或 getDesignToken。同时设置前景与背景，避免暗色文字落在浅色背景上。

文档站实时预览

Header 的主题面板分别提供默认/Mono/Material 与浅色/深色/跟随系统。选择保存在本机，换页和刷新保留，首屏先设置同一公开属性选择器再加载样式；SSR 保留确定的默认结构，挂载后接入客户端选择。站点 --site-* 只引用组件公开 Token，不维护第二套调色板。

内联 Demo 继承站点选择，但其局部 Provider 可覆盖。独立链接携带初始 preset、theme、lang。iframe 在客户端首次创建时携带当前选择，后续以验证 origin、source、frameId 的受控消息更新，不改写 src，不丢失输入、选择与展开状态。文档站为了提供三个可选风格显式加载三份预设 CSS；只用一个风格的应用只需加载自己的入口。