AI Features

Every AI loading state in ONCE is the same animation: a dotted sphere called the agent orb. There is no second AI loader, no per-feature spinner, and no bespoke “this screen is thinking” treatment. If an agent is working, you see an orb.

The five states

Five states, and only five. Pick the one that is true. When nothing more specific is true, it is Thinking.

The state should track what is actually happening. Where the underlying work reports its own stage (a background fix run, a publishing auto-fill, the release chat’s tool calls), the orb follows it live and changes mid-task. Where it does not, pick the one honest state and hold it. Never animate Searching while the agent is writing.

Colour

The orb is monochrome by design: ONCE Blue #3A455C on light surfaces, ONCE White #FFFFFF on dark. Depth comes from dot size and opacity, never from hue. That is what keeps five different animations reading as one system.

The orb picks its ink from the theme automatically. The one exception is a surface that does not follow the theme, such as a filled ONCE Blue button or an image overlay, where the ink has to be set explicitly or the orb will draw ONCE Blue on ONCE Blue and disappear in light mode.

There is no agent gradient. The four-stop thinking gradient (Orchid Brain, AI Indigo, Sky Smarts, Intellimint) was retired in August 2026, because a second palette for the agent layer made it read as a separate product. Anything that used it for an active state uses ONCE Blue now.

Rest and work

An orb never appears cold. It is always preceded by the round ONCE monogram, which cross-fades into the orb when work starts and back when it stops. It never cuts.

That holds even when there was no idle moment to begin with. A route gate, a generation overlay or a button spinner appears already loading, so it holds the ONCE mark for a beat first and then dissolves. Without that hold there would be no ONCE icon at all on the surfaces people see most.

ONCE has no agent characters. Every agent rests as the same mark. The assistant in the corner used to have a face and a name, and it is ONCE Support and the ONCE monogram now. The transition is what makes an agent read as one continuous thing changing state, rather than two icons swapping places.

Sizes

Two tuned designs ship, at 64px and 20px. They are separate drawings, not one scaled: dot count, dot radius and speed all differ. 64 is avatar scale, for empty states, panels and full-width loaders. 20 sits inline with text.

Any other size renders the nearer design scaled, so a 96px orb is the 64px drawing enlarged rather than the 20px drawing stretched thin.

Orb and words

When an orb sits beside status text, the orb always comes first, then the words.

ONCE status copy stays music-themed, but the phrases are pooled per state so the words agree with the animation on screen. A globe orb never sits next to “tuning the strings.” A phrase is drawn once per state and held, so it does not re-roll on every frame, and it cross-fades when the state changes.

Screen readers hear the plain state name rather than the lyric.

Performance and accessibility

These are handled by the shared component; you do not need to reimplement them.

• Orbs that scroll off-screen stop drawing, and so do orbs in a backgrounded tab.
• An idle agent has no orb mounted at all, so nothing spins behind a resting mark.
• prefers-reduced-motion holds a single frame rather than removing the orb, so the layout and the meaning survive with no movement.

Persistent background process cards

Longer AI work, such as a background fix investigating an issue, uses a compact card inside the conversation:

• Show a plain-language state, an orb matching the stage, and a three-segment progress indicator.
• Keep private reasoning, tool names, provider names, and execution logs out of user-facing cards.
• Use ONCE Blue while active, Applied green for success, and Needs Action amber when a human must continue.
• Keep the card in conversation history after completion so users can leave and return without losing context.
• Pair every terminal state with a short assistant message that says what changed and whether it succeeded.

Agent outcome colours

These are states an agent rests in, not states it loads in. Loading is always the orb.

AI content is azure, never purple

Distinct from the orb, which marks an agent working, there is a colour that marks content a model made: the AI track price line, AI-content badges, provenance and disclosure copy.

That colour is AI Azure: #0EA5E9 on light surfaces, #38BDF8 on dark. Text on white uses the darker end of the ramp (sky-700); the vivid tone is for fills, badges and glow.

It was violet until August 2026. Violet sat 39 perceptual units from Insider Purple, close enough that AI content and paid membership read as the same thing. Azure is 305 away, and it is legible on white and glows on dark.

Purple means membership, and only membership. Never use it for AI, for the fund, or as a general accent.