外观

Orbz 提供两种互斥的外观模式：

选择一个内置 preset；或
省略 preset，设置五个 color-* 属性中的任意属性。

没有 palette 属性，公开名称为 preset。

内置预设

预设	主色	辅色	强调色	高光	核心
`neongate` （默认）	`#6C5CFF`	`#00E9FF`	`#FF4DDE`	`#FFB07A`	`#14142B`
`periwinkle`	`#6667AB`	`#8FB8FF`	`#E66FA9`	`#F3ECFF`	`#111226`
`magenta`	`#BB2649`	`#F06A82`	`#29B8A6`	`#FFDCE4`	`#250A12`
`peach`	`#FFBE98`	`#FF8F70`	`#D987A3`	`#FFF0E7`	`#2A1516`
`mocha`	`#A47864`	`#D3A17E`	`#7FA18F`	`#F2E2D7`	`#211613`
`ivory`	`#F0EEE9`	`#AFC7D3`	`#C8B3D4`	`#FFFFFF`	`#171A20`


<orb-z preset="periwinkle"></orb-z>

即使没有 preset，默认外观仍为 Neongate，因此自定义模式会为未提供的颜色继承 Neongate 值。

构建选择器时使用导出的名称和值：


import {
  DEFAULT_ORBZ_PRESET,
  ORBZ_PRESET_NAMES,
  ORBZ_PRESETS,
  type OrbzPresetName,
} from "@neongate-ai/orbz";
 
function getPreview(name: OrbzPresetName) {
  return ORBZ_PRESETS[name];
}
 
const NeongateColors = getPreview(DEFAULT_ORBZ_PRESET);

Neongate 预设名称

预设名称为 Neongate（neongate），与托管 Orbz 的 GitHub 账号无关。1.0.1 曾误发布从账号派生的 API 键；1.0.2 恢复 neongate 且不改变颜色。本文档使用已发布的 @neongate-ai/orbz@1.0.2。

DEFAULT_ORBZ_PRESET 和默认 preset getter 返回 neongate。新建显式标记请使用规范名称：


<orb-z preset="neongate"></orb-z>

已弃用的账号派生名称仍被预设属性、类型和守卫接受，但会归一化为 neongate，包括属性反射与 getter。transformOrbzConfiguration() 对使用旧名的简洁或完整配置进行归一化，不修改输入。

ORBZ_PRESET_NAMES 列出六个规范名称。弃用的配色键保留为 ORBZ_PRESETS.neongate 的不可枚举、不可变别名，原有直接读取仍有效，不会出现第七个选项。跟随包默认值时优先使用 DEFAULT_ORBZ_PRESET 和 ORBZ_PRESETS[DEFAULT_ORBZ_PRESET]。默认 HTML 可省略 preset：


<orb-z></orb-z>

省略 preset 也会启用自定义颜色。从已安装包的 ORBZ_PRESET_NAMES 生成新选项；从 1.0.1 升级时请阅读 1.0.2 发行说明。

自定义配色

移除或省略 preset，然后设置一个或多个有效 CSS 颜色：


<orb-z
  color-primary="#7C3AED"
  color-secondary="#22D3EE"
  color-accent="#F472B6"
  color-highlight="#FDE68A"
  color-background="#09090B"
></orb-z>

属性	作用
`color-primary`	主体区域颜色
`color-secondary`	对比区域和圆环的颜色
`color-accent`	光晕及辅助能量
`color-highlight`	暖色或明亮高光
`color-background`	球体核心颜色

自定义颜色可只设置部分值。缺失值继承 Neongate 默认值，因此只调整一个颜色也有效：


<orb-z color-accent="#FF6B35"></orb-z>

冲突时预设优先

不要同时提供 preset 与自定义颜色。若运行时同时存在，Orbz 应用预设、忽略自定义颜色，并在控制台列出冲突属性。


<!-- Invalid: preset wins and color-primary is ignored. -->
<orb-z preset="mocha" color-primary="#7C3AED"></orb-z>

自定义属性会保留在宿主上，移除 preset 后生效。因此颜色编辑器应明确切换模式：


const orb = document.querySelector("orb-z");
 
orb?.removeAttribute("preset");
orb?.setAttribute("color-primary", "#7C3AED");

所有框架都写入相同的原生属性，所以规则一致。写入自定义颜色前请移除 preset。

大小与阴影

size 同时控制宽高。HTML 中传入 CSS 长度；JavaScript 属性中的正数解释为像素。


<orb-z size="18rem" elevated></orb-z>

elevated 为球体添加居中的圆形阴影。它是标准布尔属性，存在即为真，elevated="false" 仍启用。禁用时移除属性或将 JavaScript 属性设为 false。

有意不开放定制的部分

内部 CSS 变量、选择器、图层和 Shadow DOM 部分均为私有实现，不是受支持的主题 API。文档属性才是稳定契约，它们保证跨框架外观一致，同时允许 Orbz 改善内部渲染。