动效与无障碍

Orbz 为每个状态提供专属动效和减少动态效果的静态呈现。应用选择策略，Orbz 负责渲染。

减少动态效果策略

使用 reduced-motion 选择响应方式：

值	行为
`system`	遵循 `prefers-reduced-motion: reduce` 并响应偏好变化
`always`	始终使用减少动态效果的静态呈现
`never`	始终使用动画呈现

默认值为 system。


<orb-z state="idle" reduced-motion="system"></orb-z>

减少动态效果并非统一的空闲画面。各状态具有独特静态构图，所以 listening、thinking、speaking 和 asleep 无需持续动画也能区分。

只有明确需要覆盖系统偏好时才使用 never。面向用户的设置应保存其选择并直接绑定：


import type { OrbzElement, OrbzReducedMotion } from "@neongate-ai/orbz";
 
function setMotionPreference(value: OrbzReducedMotion) {
  const orb = document.querySelector<OrbzElement>("orb-z");
  if (orb) orb.reducedMotion = value;
}

速度

speed 缩放动画时长。大于 1 更快，0 与 1 之间更慢。值必须为正数。


<orb-z speed="0.8"></orb-z>
<orb-z speed="1.25"></orb-z>

默认值为 1。零、负数、非数字及非有限值归一化为默认值。

减少动态效果启用时，速度没有可见影响，因为这些呈现是静态的。

暂停与恢复

布尔属性 paused 冻结当前动画，不会静音、停止录制、取消请求或更改 state。


<orb-z state="thinking" paused></orb-z>


import type { OrbzElement } from "@neongate-ai/orbz";
 
const orb = document.querySelector<OrbzElement>("orb-z");
 
orb?.pause();
orb?.play();
orb?.restart();

控制	效果
`paused` / `pause()`	保持当前画面
`play()`	恢复当前状态动画
`restart()`	从头重建当前状态动画

与 elevated 一样，paused 遵循 HTML 布尔语义。paused="false" 仍表示暂停。请移除属性或将 JavaScript 属性设为 false。

在动画之外传达含义

Orbz 内部球体标记为装饰性内容。状态、错误、权限请求和操作需要由宿主应用提供语义化 HTML。


<section aria-labelledby="assistant-heading">
  <h2 id="assistant-heading">Voice assistant</h2>
 
  <div role="status" aria-live="polite">
    <orb-z state="listening"></orb-z>
    <span>Assistant is listening</span>
  </div>
 
  <button type="button">Stop listening</button>
</section>

周围界面应：

用文字播报重要状态变化，不只依赖颜色或动效
保证麦克风和停止控件可通过键盘操作
明确描述错误和恢复操作
减少动态效果时仍保留有用状态
避免播报每帧动画或装饰性过渡

仅对确需播报的消息使用 role="status" 和 aria-live。若更新对屏幕阅读器用户不重要，普通可见文字可能更适合。

实用默认设置

对于大多数产品：


<orb-z
  state="idle"
  speed="1"
  reduced-motion="system"
></orb-z>

再让邻近文字标签与相同应用状态同步。这样既尊重系统偏好，保留全部状态含义，也不让动效独自承担传达含义的责任。