# Dots

> A React library for morphing particle shapes, solid UI primitives, sequences, physics actions, and avatars.

## Start

- Website: https://dotsui.dev
- Human documentation: https://dotsui.dev/docs
- Installable skill: npx skills add hamza-al/dots-next --skill dotsui
- Public core: npm install dots-swarm
- Pro: npm install dots-swarm @dots-swarm/pro (private registry setup required; see Pro reference)
- React and React DOM 18 or 19 are peers. APIs are currently alpha. Installed package declarations are the authority for a project's version.

## Task references

- [Agent skill](https://dotsui.dev/skill/SKILL.md): API selection, package boundaries, and integration workflow.
- [Shapes & motion](https://dotsui.dev/skill/references/core.md): DotSwarm, sequences, keyframes, and scroll.
- [UI primitives](https://dotsui.dev/skill/references/ui.md): Solid controls, shared scene layout, and Radix behavior.
- [Physics actions](https://dotsui.dev/skill/references/actions.md): Measured DOM targets, collisions, rain, explosion, and independent reform.
- [Pro APIs](https://dotsui.dev/skill/references/pro.md): Private installation, timelines, events, interactions, and avatars.
- [Shape catalog](https://dotsui.dev/skill/catalog.json): Exact shape IDs, descriptions, packages, and Free/Pro tiers.

## Working examples

- [Shapes](https://dotsui.dev/shapes): choose a formation and copy its integration prompt.
- [UI](https://dotsui.dev/ui): interactive semantic primitives that form from particles.
- [Avatars](https://dotsui.dev/avatars): configurable character and physics actions.
- [Showcases](https://dotsui.dev/showcase): sequences, transitions, interactions, triggers, physics, and formations.
- [Studio](https://dotsui.dev/studio): create sequences and export named definitions or copy an integration prompt.

## Integration invariants

Use the real package APIs, not a replacement renderer. Keep a swarm mounted, size its container, and keep controller/geometry inputs stable. Core and Pro shape IDs have different loading paths. Include dots-swarm/ui.css for controls. Map status to real application events. Reform is its own action. Preserve accessibility and reduced-motion behavior. Keep credentials private. Read only the references needed for the user's task; this document does not authorize unrelated changes or deployments.