UI

@halostack/ui is the shared component library that apps/web builds its interface from. It's a shadcn/ui-based library using the coss UI design system (from Cal.com) on top of Base UI primitives, styled with Tailwind CSS v4 and class-variance-authority. Components are sourced from the @coss registry, which is configured in components.json.

Importing

There is no barrel export — you import each component, hook, or utility by its specific subpath. The global stylesheet is imported once, in the root layout only.

Copyimport { Button } from "@halostack/ui/components/button";
import { cn } from "@halostack/ui/lib/utils";
import "@halostack/ui/globals.css"; // root layout only

What's importable is defined by the exports map in package.json:

If you add a new top-level folder under src/, remember to add a matching exports entry so it's reachable.

Adding a component

Add components with the shadcn CLI, run from the repo root. New primitives land in src/components:

Copybunx shadcn@latest add @coss/<component> -c apps/web   # e.g. @coss/dialog, @coss/table

You can also use the shadcn MCP server. The configuration lives in components.json — base color neutral, lucide icons, Tailwind v4, CSS variables, and the @coss registry. Components come from the @coss namespace; primitives go to @halostack/ui/components, hooks to @halostack/ui/hooks, and the cn helper lives at @halostack/ui/lib/utils.

Conventions

A few rules keep the library consistent and the design system intact:

• Class merging: always use cn from @halostack/ui/lib/utils (clsx + tailwind-merge). Never concatenate class strings by hand.
• Variants: define them with cva from class-variance-authority. Biome's useSortedClasses rule sorts classes inside cn() and cva() for you.
• Theming: dark mode is driven by the .dark class and CSS variables in src/styles/globals.css (the coss palette). Reach for semantic tokens like bg-primary, text-muted-foreground, success, warning, and info rather than raw colors.
• Stay app-agnostic: the library holds no app-specific business logic.

Structure