主题与 CSS variables
完整 TS/JS SFC 与可交互结果见 主题与四档尺寸示例。文档采用固定 Element Plus 2.14.7 与 ASAM 四档契约；颜色、边框、文字由 tokens 承接，不另造同名空组件。
先加载 element-plus/dist/index.css，再加载 @asam-ui/ui/style.css。默认样式从 --asam-* 语义变量读取颜色、文字、边框、圆角、间距和尺寸，并把常用 Element Plus 变量映射到相同语义。查看 设计系统/基础色板 和 设计系统/主题覆盖示例 的实时结果。
import { applyAsamTheme, createAsamTheme } from '@asam-ui/ui/tokens';
applyAsamTheme(createAsamTheme({ color: { primary: '#0f766e' } }));只覆盖 color.primary 时，hover、active 与渐变起点随之推导；也可分别指定。传入目标元素可把变量限定在局部容器：
const scope = document.querySelector<HTMLElement>('#preview');
if (scope) applyAsamTheme(createAsamTheme({ color: { primary: '#0f766e' } }), scope);也可在安装时传 app.use(AsamUI, { theme, target })。默认写入 document.documentElement；局部 target 只影响其 DOM 后代，挂到 body 的弹出层仍继承全局变量。页面级样式应使用 --asam-*，不依赖内部生成类名。可通过 defaultAsamTheme 与 toAsamCssVariables 查询完整当前变量集；手写变量清单会随 tokens 变化而过期。
字体栈优先列出思源黑体，但包没有附带字体文件。字符串 icon 是兼容属性，不自动加载图标运行时；需要可见图标时传组件或 icon slot。
公开主题接口
@asam-ui/ui/tokens 导出 defaultAsamTheme、createAsamTheme(overrides)、toAsamCssVariables(tokens)、applyAsamTheme(tokens?, target?)、基础色板、设计值和四档密度。AsamThemeTokens 是完整对象类型，DeepPartial<AsamThemeTokens> 是覆盖类型，AsamControlDensityTokens 描述密度。完整返回对象与默认对象相互独立；传入 undefined 的覆盖字段保留默认值。toAsamCssVariables 将嵌套驼峰字段变为 --asam-* 字符串变量。applyAsamTheme 在同一目标再次应用时移除上次已写入而本次不存在的变量；服务端没有 document 且省略 target 时不执行 DOM 操作。
border、typography.lineHeight 和 density.*.formItemMarginBottom 为可选新增字段，保留既有完整对象的类型兼容。用 createAsamTheme 获得包含默认新增字段的对象；旧手写对象缺省这些字段时 CSS 使用默认回退。覆盖的类型仍严格检查字段值，不能把数值传给 CSS 长度字段。
颜色、边框与文字约定
| 范围 | ASAM 承接 |
|---|---|
| 主要色与交互 | color.primary / primaryHover / primaryActive / primaryGradientStart；仅覆写 primary 会推导其余三个值 |
| 场景色 | success / successStrong / warning / danger / info 及其 hover/active；原始扩展色板在 color.palette |
| 中性色 | textPrimary / textRegular / textSecondary，surface / surfacePage / surfaceMuted / surfaceSoft / surfaceInfo / surfaceSuccess，border / divider / shadow |
| 边框样式 | border.width='1px'、border.style='solid'；需要虚线时显式使用 2px dashed，颜色来自 --asam-color-border |
| 圆角 | radius.control / action / card / dialog / pill；独立页面消费 --asam-radius-* |
| 阴影 | shadow.card / dialog，映射原生 normal/light/lighter/dark 变量；ASAM 语义阴影优先，不硬套原生外观值 |
| 字号与字重 | xs/sm/md/lg/xl 为 12/13/14/16/20px；regular/medium/bold 为 400/500/700 |
| 文字行高 | none/compact/regular/loose 为 1/1.3/1.5/1.7；控件高度保持尺寸契约，正文自行选行高 |
暗色通过 createAsamTheme 覆盖 surface、text、border 和语义颜色后应用。示例提供完整局部暗色覆盖与亮暗切换；默认主题仍为既定亮色，不依赖 HTML 的 .dark 自动改变 ASAM tokens。使用原生 dark/css-vars.css 的宿主仍需将 ASAM 语义色与自己的主题一致配置。局部主题不改变 body 级 teleported 弹层；需要同色弹层时应用全局主题，或使用相应组件支持的容器/teleported 配置。
原生 --el-color-error、error-light-3/5/7/8/9 和 error-dark-2 与已有 danger 语义映射一致，默认、全局及局部主题都随当前 danger 变化；无需新增主题字段。原生 MessageBox 的 error 状态等直接消费这些变量的内容也沿用此映射。
六个 --el-color-{primary,success,warning,danger,error,info}-rgb tuple 保留 Element Plus 编译值；applyAsamTheme 首次应用与重复应用都不转换它们，也不承诺动态 RGB 转换 API。rgba(var(--el-color-error-rgb), 0.16) 使用原生 tuple，而 var(--el-color-error) 使用当前 danger 语义色。亮暗示例提供六个实际 tuple 消费面；默认、全局、局部和嵌套应用均验证此保留边界。需要当前语义色的透明背景时使用 color-mix(in srgb, var(--asam-color-danger) 16%, transparent)。
四档尺寸与继承
| size | 适用单行高度 | Button 左右 padding |
|---|---|---|
| large | 40px | 20px |
| big | 36px | 18px |
| default | 32px | 16px |
| small | 28px | 14px |
优先级为显式组件 size → 最近 Group → Form/FormItem → ConfigProvider → default。省略 scope 的 size 继续继承；响应式更新 provider 不覆盖更近的显式 Form/Group。数据包装复用同一个 ASAM injection key，不应复制 size context。big 只在传给原生 Element Plus 时桥接为 default，ASAM 后代与 data-asam-size='big' 仍为 big。自定义组件可用 useAsamControlSize 和 toElementPlusControlSize，仅真实 scope 容器调用 provideAsamControlSize。
Textarea 高度由 rows/autosize 控制；Table、Descriptions、Pagination 等使用字号、图标、padding、gap 或 rowPadding 密度，不强制行高40/36/32/28。Icon/Avatar 的图形尺寸、Drawer 宽高、Space 间距、TimelineItem 节点大小继续保留各自 size 类型，不传四档字符串去替代数值尺寸。
FormItem 间距与布局工具类
2.14.7 在每个 FormItem 上声明 --el-form-item-margin-bottom。ASAM 在同一 item 上将它桥接到 --asam-form-item-margin-bottom，避免只写父容器却被原生局部声明遮住。四档默认均消费既有 layout.fieldGap='20px'；可通过 density.big.formItemMarginBottom 等覆写指定档位。局部旧完整主题省略新增间距字段时，applyAsamTheme 在本次目标上补四档 var(--asam-layout-field-gap) 回退，避免继承根部已经计算好的20px；局部 fieldGap='31px' 或 '0px' 仍有效，显式 density 覆盖优先。toAsamCssVariables 仍按实际对象序列化，缺省字段不会被它新增。嵌套 FormItem 的原生 margin-bottom:0 规则保留，label/content 行高和单行控件高度仍由各组件适配，不把间距变量当高度。
Row/Col 的 xs/sm/md/lg/xl props 提供响应式列布局。hidden-xs-only 等原生可见性工具类需显式 import 'element-plus/theme-chalk/display.css'；ASAM 主样式不自动包含它。使用既定 UnoCSS 工具类的消费项目按自己的扫描和 preset 配置生成 CSS，不能因类名存在就认定样式已加载。响应式列、display.css 隐藏与独立 size 例外均有完整 TS/JS SFC。
内容来源：apps/docs/src/guides/Theme.mdx。本页由同源指南生成；组件 Demo 与 API 从 组件目录 查看。