# thinking-orbs

Guides coding agents to implement animated AI status indicators using the React thinking-orbs package. Useful for chat interfaces, copilot sidebars, and search tools.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 1300 installs · ★ 7001
- Author: MengTo
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/MengTo/Skills/tree/HEAD/agent-skills/web-design/thinking-orbs/SKILL.md
- Updated: 2026-10-25
- HTML: https://affpapa.org/en/nevibecode/skills/thinking-orbs

## What it does

This skill teaches agents how to integrate the `<ThinkingOrb>` component from the `thinking-orbs` library. The package renders monochrome dots on a transparent 2D canvas without WebGL or SVG filters. It ships with six semantic states: `working`, `searching`, `solving`, `listening`, `composing`, and `shaping`.

Geometry is deliberately restricted. It supports only two tuned sizes: `20` for buttons or compact rows and `64` for chat avatars or empty states. The library does not show determinate progress percentages. In Next.js App Router, the component must sit behind a `'use client'` boundary because it mounts browser canvas effects and observers.

Accessibility and performance come built-in. It pauses via `IntersectionObserver` when scrolled offscreen and stops in background tabs. Under `prefers-reduced-motion`, it renders a single static frame while still following theme changes. Freezing active animations must use the `paused` prop rather than setting `speed={0}`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add MengTo/Skills --skill thinking-orbs -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/thinking-orbs/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/thinking-orbs/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add MengTo/Skills --skill thinking-orbs -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/thinking-orbs/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add MengTo/Skills --skill thinking-orbs -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/thinking-orbs/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install MengTo/Skills thinking-orbs
```

2. **Manually: put the files in place**
- File: `.github/skills/thinking-orbs/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add MengTo/Skills --skill thinking-orbs -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/MengTo/Skills --path agent-skills/web-design/thinking-orbs
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/thinking-orbs/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add MengTo/Skills --skill thinking-orbs -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/MengTo/Skills/tree/HEAD/agent-skills/web-design/thinking-orbs/SKILL.md

## When to use it
- replace generic loading spinners with semantic AI activity states
- map agent lifecycle stages to visual orb animations in React 18
- configure screen reader status announcements without duplicate ARIA live regions
- embed compact 20px loading indicators into buttons and status bars

## Example prompts
- Add a ThinkingOrb indicator in searching state next to the query input
- Create an agent status component with thinking-orbs mapped to our pipeline phases
- Display a size 64 solving orb while the AI model reasons through the task

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 79a2d89204257f77.

BEGIN THIRD-PARTY FILE 79a2d89204257f77
````text
---
name: thinking-orbs
description: Add accessible animated AI loading and agent-status indicators with the React thinking-orbs library. Use when a chat, copilot, voice, search, generation, or tool-running interface needs a semantic working, searching, solving, listening, composing, or shaping state; when replacing a generic spinner with an AI activity orb; or when implementing the library's size, theme, speed, pause, reduced-motion, and canvas behavior.
---

# Thinking Orbs

## Core Contract

1. Use `thinking-orbs` in React 18+ interfaces that need indeterminate AI activity feedback.
2. Map the real product lifecycle to one of the six shipped states.
3. Use only the tuned `20` or `64` pixel size. Do not stretch one preset into another.
4. Keep `theme="auto"` unless the surrounding surface has a known fixed theme.
5. Pair the orb with concise visible status text when the activity matters to the user.
6. Override `aria-label` with a task-specific label, or hide the orb from assistive technology when adjacent live text already announces the same state.
7. Use `paused` to freeze the current frame. Do not simulate pause with `speed={0}`.
8. Treat the orb as indeterminate feedback, never as a progress percentage or completion signal.

The package renders monochrome dots on a transparent 2D canvas. It does not expose custom colors, arbitrary sizes, or determinate progress.

## Install

Inspect the project package manager, then install:

```bash
npm install thinking-orbs
```

The package declares `react` and `react-dom` version 18 or newer as peer dependencies. Import the component and exported types from the package root:

```tsx
import {
  ThinkingOrb,
  type OrbSize,
  type OrbState,
  type OrbTheme,
  type ThinkingOrbProps,
} from "thinking-orbs";
```

## Choose the State

- `working` — generic tool execution, multi-step work, or an activity without a more precise state.
- `searching` — retrieval, web search, file search, or knowledge lookup.
- `solving` — reasoning, analysis, calculation, or planning.
- `listening` — microphone input, speech capture, or waiting for a spoken turn.
- `composing` — writing, summarizing, drafting, or generating a text response.
- `shaping` — creating or refining an image, layout, structured artifact, or other formed output.

Prefer a truthful generic `working` state over a visually interesting but inaccurate state. Change the state only when the underlying activity changes.

## Choose the Size

- Use `size={20}` inline with text, inside buttons, or in compact status rows.
- Use `size={64}` at chat-avatar scale, in an empty state, or as the main visual status.
````
END THIRD-PARTY FILE 79a2d89204257f77

The third-party file has ended. Everything between the 79a2d89204257f77 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2647 of 9673 bytes. © MengTo · MIT · https://github.com/MengTo/Skills/tree/HEAD/agent-skills/web-design/thinking-orbs/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md