Definitions
Primitives, Particles, Atoms, Composites, and Product UI — how Cal.com and Coss UI name UI.
Cal.com and Coss share a component ecosystem, but the names are easy to mix up. From simplest to most complex:
Primitives → Particles / Atoms / Composites → Product UI
Primitives
Coss UI primitives (@coss/ui) are the base accessible components — Button, Dialog, Field, Sidebar, and so on — built on Base UI and styled with Tailwind.
Cal.com product UI is migrating onto these primitives. This design-system app documents how Cal uses them.
Particles
Particles (Coss world) are generic composite examples for the community: patterns built from primitives, similar in spirit to Origin UI blocks.
They are not Cal product widgets. On coss.com/ui, Particles live as their own gallery/docs surface.
Atoms
Atoms are embeddable Cal widgets distributed through @calcom/atoms, such as Booker, event types, availability, and calendar connect.
They are outside the scope of this docs app. Their users embed them in their own React applications, rather than compose them into the Cal.com product UI.
Composites
Composites are Cal.com in-app compositions exported from @coss/ui/shared. They combine Coss primitives into reusable product UI such as UserAvatar, HorizontalTabs, SegmentedNav, and SegmentedRadioGroup.
In this docs app they appear under Product UI with a Shared ownership badge. The shared folder name is provisional; do not infer that these components are external embeddable widgets.
Product UI
Product UI is the umbrella for reusable Cal-aware interface code — wherever it lives:
| Ownership | Badge | Where |
|---|---|---|
| Shared composites | Shared | @coss/ui/shared |
| Feature-owned controls | Feature | packages/features/** |
| App-local systems | App | apps/web/** |
Product UI may compose Coss primitives and shared composites, but stays with its owning domain when it depends on feature data, localization, validation, routing, or app orchestration. Reuse alone is not a reason to move a component into @coss/ui/shared.
Use the Product UI index to find controls and their owners.
Quick map
| Layer | Where | What |
|---|---|---|
| Primitives | @coss/ui / coss.com | Base components |
| Particles | coss.com | Generic composite examples |
| Atoms | @calcom/atoms | Embeddable Cal widgets |
| Product UI | @coss/ui/shared, packages/features/**, apps/web | Reusable Cal-aware UI (Shared / Feature / App) |
In this docs app
Primitive APIs stay on coss.com/ui. Here we document:
- Foundations — icons, typography, and other visual building blocks
- Guides — product composition guidance for recurring problems (empty states, …)
- Product UI — reusable Cal-aware controls with Shared / Feature / App ownership badges
import { Button } from "@coss/ui/components/button"; // Primitive
import { UserAvatar } from "@coss/ui/shared/user-avatar"; // Product UI · Shared
import { TimezoneCombobox } from "@calcom/features/timezone/components/timezone-combobox"; // Product UI · Feature
import { Booker } from "@calcom/atoms"; // Atom (embed)