---
title: "Make your own orb look"
description: "How to add your own orb style: what a style is, its two files, the WGSL fragment and its settings table, the tests that prove it, the pictures to look at, and the still and lists that put it in the pickers; an agent can follow the make-orb-look skill."
type: "living"
source: "docs/make-your-own-orb-look.md"
verified: "2026-11-14"
group: "Frontends"
---

> **Living doc**, checked against the code 2026-11-14

The orb is the face Vulpine shows while you talk to it. Each way of drawing it is a **style**. Vulpine ships
eighteen of them, and you can add your own. This guide shows how.

A style is a small shader and a short table of settings. You do not write a renderer, a window or any audio code.
The style contract gives your shader two numbers, your voice and the agent's, and the tests tell you when the look
is ready.

An agent can do these steps for you. The skill is `make-orb-look`, in the source at
`.claude/skills/make-orb-look/SKILL.md`: point your agent at it and describe the look you want.

## Before you start

- You need a checkout of the Vulpine source. Styles are compiled into the apps, so a new one means a rebuild. You
  cannot drop a file into a running app yet.
- You need a Mac with Apple silicon and the Rust toolchain the native apps use (1.98.1 on 2026-11-14).
- Your shader must be your own work, or code under the MIT or Apache license. Say where it comes from in the file.

All the paths below are inside `apps/orb-styles`, the crate that holds every style.

## What a style is

A style is one value of the type `OrbStyle` (`src/lib.rs`). It has these parts:

| Part | What it is |
|---|---|
| `id` | The key the apps store, such as `ember`. Lower-case letters, digits and hyphens. |
| `name` | The word a person picks it by and says out loud, such as `Ember`. Letters and single spaces. No other style may use it. |
| `note` | One line that says what it looks like. |
| `provenance` | `Provenance::Vulpine` for a style written here. |
| `labs` | `true` means the style shows only when the Labs switch is on. A new style starts here. |
| `frag` | The shader, in WGSL. It defines one function, `orb`. |
| `params` | The numbers your shader reads, each with a range and a default. At most 40. |
| `colors` | The colors your shader reads, as hex. At most 8. |
| `presets` | What the params and colors become in each of the four states. |

The four states are **idle**, **listening**, **thinking** and **speaking**. A good look reads differently in each,
even with no sound.

## The files

A style is two files in `src/styles/`, plus one line in two lists:

1. `src/styles/ember.wgsl`: the shader.
2. `src/styles/ember.rs`: the `OrbStyle` value that names the shader, the params, the colors and the presets.
3. `src/styles/mod.rs`: add `pub(crate) mod ember;`.
4. `src/registry.rs`: add `&styles::ember::STYLE` to `STYLES` and raise the array's length by one.

The shortest complete example in the tree is Signal: `src/styles/signal.rs` and `src/styles/signal.wgsl`. Copy its
shape.

## The shader

Your file defines one function. It gets a pixel's position and returns that pixel's color:

```wgsl
fn orb(fc: vec2f) -> vec4f {
    let uv = orb_uv(fc);
    // Follow your voice while it listens and its own voice while it speaks.
    let level = clamp(u.input_level * P_listen() + u.output_level * P_talk(), 0.0, 1.0);
    let radius = P_radius() * (1.0 + 0.06 * level + 0.04 * P_kick());
    let r = length(uv) / radius;
    let cover = 1.0 - sstep(0.97, 1.0, r);
    let pulse = 0.5 + 0.5 * sin(6.2831853 * (P_drift() - r));
    let light = clamp(0.35 + 0.45 * pulse + 0.4 * level, 0.0, 1.0);
    let rgb = mix(C_deep(), C_tint(), light);
    return vec4f(rgb * cover, cover);
}
```

That is a soft disc with rings that move outward and swell with the voice. It is a place to start, not a finished
look.

What the shader can read (`src/prelude.wgsl` is put in front of your file):

- `u.input_level`: how loud you are, from 0 to 1.
- `u.output_level`: how loud the agent is, from 0 to 1.
- `u.res`: the size of the frame in pixels. `orb_uv(fc)` turns a pixel into a position where the frame's short side
  runs from -1 to 1.
- `u.time` and `u.anim`: two clocks. Prefer a rate param (below) to reading a clock yourself.
- `u.still`: 1 when the person asked for reduced motion. Draw a calm, still face then.
- `P_<key>()`: one of your params. `C_<key>()`: one of your colors. These are written for you from the tables in
  the `.rs` file.
- Helpers: `hash`, `noise`, `fbm`, `sstep` (use it in place of `smoothstep`), `gmod` (use it in place of `%`) and
  `field_at` (a ready noise texture).

Three rules for the pixel you return:

- Multiply the color by the alpha, as the example does. The frame expects premultiplied color.
- Keep the body about the size of the other styles. A radius near 0.9 does that. Everything is clipped to a circle.
- Do not flash. Nothing may blink more than three times a second.

## The settings

The `.rs` file is the table the driver reads. The driver moves every value smoothly from one state to the next, so
your shader never has to.

```rust
use crate::OrbState::{Idle, Listening, Speaking, Thinking};
use crate::{ColorDef, OrbStyle, ParamDef, Provenance, StatePreset};

pub static STYLE: OrbStyle = OrbStyle {
    id: "ember",
    label: "Ember",
    name: "Ember",
    note: "a warm disc whose rings swell with the voice",
    provenance: Provenance::Vulpine,
    labs: true,
    frag: include_str!("ember.wgsl"),
    params: &[
        ParamDef::rate("drift", "Ring speed", 0.0, 4.0, 0.01, 0.2),
        ParamDef::new("radius", "Radius", 0.3, 1.0, 0.01, 0.9),
        ParamDef::new("listen", "Listening", 0.0, 1.0, 0.01, 0.0),
        ParamDef::new("talk", "Speaking", 0.0, 1.0, 0.01, 0.0),
        ParamDef::new("kick", "Onset", 0.0, 1.0, 0.01, 0.0),
    ],
    colors: &[
        ColorDef::new("tint", "Light", "#ffb070"),
        ColorDef::new("deep", "Shade", "#5a2410"),
    ],
    presets: &[
        StatePreset { state: Idle, params: &[("drift", 0.2)], colors: &[("tint", "#ffb070"), ("deep", "#5a2410")] },
        StatePreset { state: Listening, params: &[("listen", 1.0), ("drift", 0.15)], colors: &[("tint", "#7fd6c8"), ("deep", "#1f4a5a")] },
        StatePreset { state: Thinking, params: &[("drift", 0.9)], colors: &[("tint", "#b9a6ff"), ("deep", "#33286e")] },
        StatePreset { state: Speaking, params: &[("talk", 1.0), ("drift", 0.5)], colors: &[("tint", "#ffd29a"), ("deep", "#8a4f35")] },
    ],
};
```

What each line means:

- `ParamDef::new(key, label, min, max, step, default)` is a plain number.
- `ParamDef::rate(...)` is a speed. The driver turns it into a clock for you, so a change of speed never makes the
  picture jump. Use it for anything that moves.
- Three keys have a fixed meaning, and every style must have them and read them:
  - `listen` is 1 while Vulpine listens and 0 otherwise.
  - `talk` is 1 while it speaks and 0 otherwise.
  - `kick` jumps at each syllable and at the wake word, then falls back.
- A style needs a preset for each of the four states. A preset names only the keys it changes.
- When the microphone is off, the driver fades your colors to gray. If your colors are written inside the shader
  and not in `colors`, add a `mute` param and fade them yourself.

## The tests that prove it

The tests are the contract. Run them from the root of the checkout:

```bash
cargo test --manifest-path apps/orb-styles/Cargo.toml
cargo test --manifest-path apps/orb-styles/Cargo.toml --features wgpu
```

The first command needs no screen. It checks, for every style:

- the shader is valid WGSL and turns into Metal;
- the params and colors fit, every default is inside its range, and every preset names a real key;
- the name is one a person can say, and no other style has it;
- the style reads both voices, the syllables and all four states, and never steps a clock (`src/wiring_tests.rs`).

The second command draws your style on the GPU. It checks that:

- the four states look different at silence;
- your voice changes the listening picture and the agent's voice changes the speaking picture;
- the microphone off turns it gray;
- nothing flashes more than three times a second;
- the body is the same size as the other styles.

Two tests list the styles by name, so they fail until you add yours. That is on purpose: the list of styles is
written down, and a new one is a change someone made. In `src/lib_tests.rs`, add your id to the list of this
repository's own styles and your name to the Labs list, and raise the count.

## Look at it

Draw your style in all four states, without opening a window:

```bash
cargo run --release --features wgpu --manifest-path apps/orb-styles/Cargo.toml --example style_cost -- --out <folder> --only ember
```

You get one picture per state and a contact sheet. For motion, draw a short clip of a whole turn:

```bash
cargo run --release --features wgpu --manifest-path apps/orb-styles/Cargo.toml --example style_clip -- --style ember --out <folder>
```

Neither command uses a microphone. Both replay a made-up voice level.

## How it shows up in the picker

The pickers show each style as a small picture with its name. Four things put yours there:

1. **The still.** Draw the resting picture and pack it to 64 pixels, then add your id to `still_png` in
   `src/stills.rs`:

   ```bash
   python3 tools/apps/orb_style_stills.py render --out <folder>
   python3 tools/apps/orb_style_stills.py pack <folder>
   ```

2. **The desktop app's list.** Add your style to `ORB_STYLES` and `LABS_STYLES` in
   `apps/glyph/src-tauri/src/orb_sidecar.rs`, and to `ORB_STYLE_CHOICES` in `apps/glyph/src/orbStyle.ts`.
3. **The gateway's list.** Add it to `ORB_STYLES` and `LABS_STYLES` in `crates/voice_gateway/src/orb_style.rs`.
   This is what lets you say "change the orb to ember".
4. **The host app.** Vulpine Gateway.app reads the crate itself. It needs only a rebuild.

Each list has a test that compares it with the crate, so a list you forget fails by name.

After a rebuild, your style appears when the Labs switch is on. You can pick it three ways: in the picker, by
voice ("change the orb to ember"), or with `vulpine-glyphctl orb-style ember`. The app remembers the pick.

The site's page of live orb faces uses the same crate, built for the browser. Any change to the crate makes that
copy stale. Check it, and rebuild it if the check says so:

```bash
python3 tools/apps/orb_web_build.py check
```

## When something fails

| What you see | What it means |
|---|---|
| The WGSL test prints a line and a caret | The shader has a syntax or type error at that place. |
| "inputs a style ignores" | Your shader does not read one of the two levels, `kick`, `listen` or `talk`, or a state has no preset. |
| "stepped clocks" | You used `floor` on a clock. Use a rate param and fade between values. |
| "states that read alike at silence" | Two states look the same with no sound. Change a color or a speed in one preset. |
| "a style's body is not the others' size" | The orb is too small or too large. Move the radius toward 0.9. |
| A mirror test names your id | One of the lists in "How it shows up in the picker" does not have it yet. |

## See also

- orb-styles: the crate in full, with the driver, the renderer and every style.
- [What you can say](/docs/install-and-operate/voice-commands): the voice command that changes the orb.
