---
name: dotsui
description: Add and tune Dots particle effects in React apps using dots-swarm and @dots-swarm/pro. Use for morphing shapes, particle-to-UI primitives, sequences, scroll-driven animations, physics actions, and Dots avatars, or when adapting a dotsui.dev example. Also use for a requested review of where Dots fits an existing interface.
---

# Dots

Dots is a React particle library: the same swarm morphs between shapes, falls or explodes, and assembles into solid, functional UI. Use the package APIs instead of rebuilding a canvas renderer or pasting coordinate arrays.

## Follow the user's task

- **Explore:** explain appropriate effects and their APIs without changing files.
- **Review:** inspect the requested interface and suggest a few specific opportunities. Keep review requests read-only.
- **Implement:** integrate the chosen effect into the existing design and actual application state.
- **Tune:** adjust timing, density, colors, scale, and choreography within the requested effect.

These are natural-language workflows, not executable commands. Installing this skill does not authorize unrelated redesigns, purchases, deployments, or messages.

## Start here

1. Inspect the app's framework, installed Dots version, package manager, styling, and target component. Preserve its conventions. These examples target the 0.1 alpha API; the installed package types take precedence when versions differ.
2. Pick the smallest API that accomplishes the requested behavior. Do not require Pro for a core effect or silently replace a requested Pro effect.
3. Read the relevant reference below, then implement. When copying a compact demo sketch, supply its missing refs, state, layout, handlers, and lifecycle cleanup.
4. Follow the user's verification preferences. Report what changed and any remaining access/configuration requirement accurately; do not claim unperformed checks.

## Choose the right API

| Need | API | Reference |
| --- | --- | --- |
| A shape, loading indicator, or state-to-state morph | `DotSwarm` from `dots-swarm` | [Core](references/core.md) |
| A timed list of formations with independent clip lengths | `DotsSequence` + `DotsSequencePlayer` | [Core](references/core.md) |
| Scroll-controlled shape, color, dispersion, density | `SwarmSequence` + `useSwarmScroll` | [Core](references/core.md) |
| Solid buttons, dialogs, inputs, controls, menus | `dots-swarm/ui` + `dots-swarm/ui.css` | [UI](references/ui.md) |
| Rain, explosion, reassembly, collisions with DOM text | `SwarmSurface` + `swarmActions` | [Actions](references/actions.md) |
| More shapes, overlapping tracks, event graphs, force fields, configurable avatars | `@dots-swarm/pro` subpaths | [Pro](references/pro.md) |

## Install

Core is public and MIT licensed:

```sh
npm install dots-swarm
```

Use the equivalent command for the project's package manager. React and React DOM 18 or 19 are peers. Controls use Radix dependencies; do not describe the package as dependency-free. Pro requires a private registry token: read [Pro installation](references/pro.md) before installing it. The skill itself is public and does not grant Pro access.

## Integration rules that matter

- Keep `DotSwarm` mounted when its `shape` changes. A changing React `key` resets the particle pool and destroys the morph.
- Give every rendering surface measurable width and height. In Next.js, place interactive examples behind a `"use client"` boundary. Import the UI stylesheet once at the app entry/root layout.
- Core shape IDs come from `SHAPES` and `shapeInfo`; Pro IDs come from `PRO_SHAPES` and `proShapeInfo`. Never invent shape names. `mail` is a core shape; `email` is not. Pro shapes use custom points or an explicitly supplied shape registry.
- Stable geometry, targets, keyframes, and controllers belong outside render or in `useMemo`. Preserve particle count across transitions. Dispose subscriptions and pause manually started clocks on unmount.
- `SwarmUI` scenes share one positioned space. Keep inactive scenes mounted; do not `display: none` their measurable targets. A completed primitive is a solid semantic control, not a dotted imitation or an inaccessible canvas hitbox.
- Use real application events for success, error, loading, and progress. A showcase timeout does not mean a real network operation succeeded.
- Rain/explode and reform are independent actions. An explosion does not implicitly return. Reform can target another shape, component, or avatar expression.
- Respect reduced-motion preferences, pointer and keyboard access, readable labels, and the host app's focus behavior. Keep native scrolling by default; if the user requests a gated sequence, preserve backward scrolling and a keyboard-accessible way to continue.
- Prefer a short named sequence over exported coordinates for built-in shapes. Use point arrays for genuinely custom geometry.

## Sources

- API docs: https://dotsui.dev/docs
- Shape catalog: https://dotsui.dev/shapes
- Machine-readable catalog (IDs, descriptions, Free/Pro tier): https://dotsui.dev/skill/catalog.json
- UI: https://dotsui.dev/ui
- Avatars: https://dotsui.dev/avatars
- Working examples: https://dotsui.dev/showcase
- Raw skill: https://dotsui.dev/skill/SKILL.md

If reading this skill by URL, resolve reference links under `https://dotsui.dev/skill/references/`. Read only the reference needed for the current task.