UI and COSS UI Components

Purpose and Scope

Cal.diy contains two related UI packages for building product surfaces inside the monorepo. @calcom/ui is the established Cal.com design-system package with many named component entrypoints, while @coss/ui is a newer component package organized around direct component, hook, utility, shared, icon, and stylesheet exports. This page is for contributors who need to choose the correct package import, understand which files define the public contract, and recognize how styling and component behavior are wired before changing scheduling screens, settings pages, embeds, or platform-facing UI.

The distinction matters because the packages expose different kinds of contracts. @calcom/ui publishes a curated export map for individual components such as alert, avatar, button, dialog, form controls, layout, navigation, tables, toast, tooltip, and segmented controls. @coss/ui instead uses wildcard export families, so a consumer imports a concrete source-backed module like a component, hook, utility, shared primitive, icon module, or global CSS file. Treat these manifests as the first compatibility boundary: if an import path is not represented there, it is not part of the documented package surface. Sources: packages/ui/package.json, packages/coss-ui/package.json

Relevant Source Files

• packages/ui/package.json - Declares the private @calcom/ui package, its sideEffects setting, main entrypoint, scripts, and the explicit export map for component and style modules.
• packages/ui/components/alert/index.ts - Shows the alert component barrel exporting Alert and its AlertProps type.
• packages/ui/components/avatar/index.ts - Shows the avatar component barrel exporting single-user and group avatar primitives plus their prop types.
• packages/coss-ui/package.json - Declares the private @coss/ui package, CSS side effect, wildcard export families, TypeScript path mappings, scripts, dependencies, and React peer dependency range.
• packages/coss-ui/src/components/button.tsx - Provides a representative COSS client component built with Base UI render helpers, class-variance-authority, React types, and the local cn utility.
• packages/coss-ui/src/components/sidebar.tsx - Provides a stateful COSS layout component that coordinates context, responsive behavior, cookie persistence, keyboard shortcuts, and composed child components.
• packages/coss-ui/src/icons.tsx - Defines the COSS icon surface from lucide-react icon imports and aliases.
• packages/coss-ui/src/styles/globals.css - Defines COSS global CSS, Tailwind custom variants, theme tokens, root variables, semantic colors, radii, and skeleton animation tokens.

Package Surfaces

@calcom/ui is intentionally granular. Its manifest marks the package as private, sets sideEffects to false, and exposes many individual modules under ./components/..., ./styles, and ./classNames. That structure supports tree-shaken imports and discourages consumers from reaching into component internals. The requested source snippets show this pattern directly in alert and avatar: the directory-level index.ts files re-export the public React components and TypeScript prop types from implementation files, which gives downstream packages stable names without coupling them to file layout. Sources: packages/ui/package.json, packages/ui/components/alert/index.ts, packages/ui/components/avatar/index.ts

The alert surface is intentionally small: it exports Alert and the AlertProps type. The avatar surface is broader because avatar use cases include individual users, groups, and organization-aware groups. Its barrel exports Avatar, UserAvatar, AvatarGroup, UserAvatarGroup, UserAvatarGroupWithOrg, AvatarProps, and AvatarGroupProps. When adding a new Cal UI primitive, follow the same contract style: keep the implementation in the component folder, publish only the intended names through the folder index.ts, and then add the package export path if consumers need to import it externally.

@coss/ui presents a different public contract. Its manifest exports ./styles.css, ./icons, ./lib/*, ./components/*, ./hooks/*, and ./shared/*, with matching typesVersions entries so TypeScript consumers resolve the same families. The package declares ./src/styles/globals.css as a side effect, which is important because global CSS must not be tree-shaken away like a pure TypeScript module. It also records dependencies that explain the component implementation style: Base UI primitives, class variance helpers, clsx, lucide-react, and tailwind-merge, with React and React DOM as peers. Sources: packages/coss-ui/package.json

Component Implementation Patterns

The COSS button is a good example of the package’s primitive style. It is a client component, imports mergeProps and useRender from Base UI, uses cva and VariantProps from class-variance-authority, and merges classes through cn from @coss/ui/lib/utils. The visible buttonVariants definition encodes a default variant and size, then enumerates size variants such as default, icon, icon-lg, icon-sm, icon-xl, icon-xs, lg, sm, xl, and xs, plus visual variants such as default, destructive, destructive-outline, ghost, link, and outline. Sources: packages/coss-ui/src/components/button.tsx

That button implementation demonstrates a broader COSS convention: behavior and accessibility hooks come from Base UI, styling decisions are centralized in variant maps, and token names come from the global theme. The long utility class strings are not arbitrary decoration; they encode pointer target handling, focus rings, disabled behavior, icon sizing, active states, and responsive size adjustments. When editing a variant, verify both the semantic token names and the interaction states, because a change to a shared primitive will affect every consumer importing @coss/ui/components/button.

The COSS sidebar shows how larger application primitives compose the smaller ones. It creates a SidebarContext, exposes useSidebar, supports controlled and uncontrolled open state through open, defaultOpen, and onOpenChange, tracks a separate mobile open state, and persists desktop state in a cookie named sidebar_state. It also defines widths for desktop, mobile, and icon-only layouts, listens for Ctrl or Meta plus b to toggle, and composes COSS Button, Input, ScrollArea, Separator, Sheet, Skeleton, and Tooltip components. Sources: packages/coss-ui/src/components/sidebar.tsx

Styling, Icons, and Design Tokens

COSS styling is centered on globals.css. The file defines custom variants for dark mode and fixed layout, maps theme tokens to CSS variables, and initializes root values for background, foreground, cards, popovers, primary and secondary colors, muted and accent colors, destructive, info, success, warning, borders, inputs, rings, chart colors, sidebar colors, radii, and a skeleton animation. Because the package manifest exposes this file as @coss/ui/styles.css, applications that use COSS components should load the stylesheet once at the app boundary rather than duplicating token definitions in feature code. Sources: packages/coss-ui/package.json, packages/coss-ui/src/styles/globals.css

The icon surface is also package-level rather than component-local. The icons.tsx module imports LucideIcon and many concrete icons from lucide-react, aliasing them with Lucide... names. This keeps product code from depending directly on scattered Lucide imports when a common COSS icon surface is available. Use this module when the UI should follow the shared icon set, and reserve direct lucide-react imports for implementation files that have not yet been normalized through the COSS icon export. Sources: packages/coss-ui/src/icons.tsx

Compact Reference

import { Alert } from "@calcom/ui/components/alert";
import { Avatar, AvatarGroup } from "@calcom/ui/components/avatar";
import "@coss/ui/styles.css";
import { Button } from "@coss/ui/components/button";

Contributor Guidance

When working in this area, start from the package manifest before editing implementation files. For @calcom/ui, add or verify explicit export-map entries so consumers can import stable component paths. For @coss/ui, make sure new modules fit the existing wildcard families and that any globally required asset is represented as a side effect. Then check whether the component belongs in the older Cal UI package, the COSS package, or a feature package. A reusable primitive belongs in one of these UI packages; a scheduling-specific workflow usually belongs closer to the feature that owns the behavior.

Next, review how the component consumes styling. COSS components assume the semantic variables in globals.css, while Cal UI components rely on their own exported style and component modules. If you change tokens, button variants, sidebar state behavior, or avatar exports, search for downstream imports in the application before landing the change. Related reading: monorepo-architecture for package layout, web-app-shell-navigation for application shell consumers, and platform-atoms-overview for UI surfaces embedded into external applications.