# Coss UI > Set up or extend a Next.js web app with Coss/UI — the official Cal.com design system, built on Base UI + Tailwind CSS v4 and installed through the shadcn CLI via the namespaced `@coss/*` registry. Two modes: Init (`shadcn init @coss/style` on a new project) and Add (pull `@coss/ui` primitives, single `@coss/` components, or particles into an existing one). Sets `meta.json#stack.ui = "coss"`. Triggers: "usa Coss/UI", "coss.com/ui", "Cal.com design system", "aggiungi un componente Coss", "init @coss/style", "scaffold con Coss UI", or dev-flow routing when `stack.ui = "coss"`. Requires Tailwind CSS v4 and carries a mixed MIT/AGPLv3 license. Not for: writing the DESIGN.md (use figma-to-design-md / image-to-design-md), the generic Next.js scaffold (design-md-to-app owns it), backend modules (module-add), or React Native (RN uses NativeWind, not Coss). - Skill: `lukedj78/coss-ui` (Agent Skill, multi-file: 7 files) - Install (CLI): `npx skillmds@latest add lukedj78/coss-ui` - Raw SKILL.md: https://api.skillmd.com/api/skills/lukedj78/coss-ui/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Design & Media - Author: lukedj78 (https://skillmd.com/u/lukedj78) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/lukedj78/coss-ui --- # coss-ui — Coss/UI (Cal.com design system) for a dev-flow project This skill owns the **Coss/UI side** of a web project: installing and extending Coss components (the Cal.com design system on **Base UI** + **Tailwind v4**) through the **shadcn CLI** `@coss/*` registry, and keeping Coss's tokens reconciled with the project's `DESIGN.md`. It **composes with** `design-md-to-app` (which owns the generic Next.js scaffold) — it does not re-implement it. ## The one rule that matters most **Never invent the Coss commands or registry.** The source of truth is the live docs at (get-started + each component page shows its exact `pnpm dlx shadcn@latest add @coss/` command) and the repo `cosscom/coss`. Confirm the exact command, the `components.json#registries` config for the `@coss` namespace, and the current registry URL **before** running anything. Coss is young; treat this skill as the workflow + conventions, not a frozen copy of the API. **Swept 2026-08-26 against the live registry** (`coss.com/ui/r/registry.json` — 577 items — plus `style.json`, `ui.json` and the three font items), so the counts, the namespace requirement and the font slots below are read from the registry rather than the docs page. Anything still marked `[VERIFY]` must be checked against the live docs first. ## Why Coss fits dev-flow (and when to pick it) Coss/UI rides the **same machinery** dev-flow already uses: shadcn CLI v4 + `components.json` + **CSS-variable tokens with the same names as shadcn/ui**. So the DESIGN.md → tokens pipeline works unchanged; Coss just supplies the default token set (`@coss/colors-neutral`) plus a curated Base-UI component/particle registry. It is a UI-library choice **inside the shadcn / Base-UI family**, recorded as `stack.ui = "coss"` (with `ui_base = "base"`, since Coss is built on Base UI). Pick Coss when the user wants the Cal.com aesthetic/DX, a Base-UI foundation, and an AI-first copy-paste kit. **Two caveats make it a deliberate choice, not a default:** - **Tailwind CSS v4 is required** — Coss does not work on v3. - **Mixed license**: MIT for the copy-paste primitives (`apps/ui`, `apps/origin`), **AGPLv3** elsewhere. Fine for OSS/internal; a real decision for closed-source products. See `references/deps-and-license.md`. ## Preconditions - `stack.framework` is `"next"` (App Router) or `"monorepo"` (operate in `apps/web/`). Next.js 16 target, per dev-flow. - **Tailwind CSS v4** available (or being set up). If the project pins Tailwind v3, stop and flag it — Coss needs v4. - The shadcn CLI is usable (`pnpm dlx shadcn@latest`). No `components.json` is required up front for `init @coss/style`; for `add @coss/*` on an existing project, the `@coss` registry namespace must be resolvable (see `references/coss-registry.md`). ## Read state, then pick a mode Run `python scripts/check_coss_state.py ` (or inspect manually). It reports: - **No app yet / no Coss markers** → **Init mode**. - **App scaffolded, Coss already installed** (`@coss` in `components.json#registries`, `@base-ui/react` in deps, Coss token block in `globals.css`) → **Add mode**. Do **one** logical operation per invocation, then stop. Both modes are idempotent — re-adding an existing component is detected and skipped. ## Init mode (new / empty project) Goal: a runnable app with Coss/UI installed and its tokens reconciled to `DESIGN.md`. 1. Read `node_modules`/docs and confirm the current init flow (`references/coss-registry.md`). Confirm **Tailwind v4**. 2. Scaffold the framework if absent — hand the generic Next.js scaffold to `design-md-to-app` (dev-flow contract), OR, for a Coss-first empty project, run the recommended one-shot: ```bash pnpm dlx shadcn@latest init @coss/style ``` This installs all UI components, the neutral color system, sidebar variables, base styles and the fonts. ⚠️ **There are three font slots, not two** — read off the registry on 2026-08-26: | Item | `--variable` | Family | npm dependency | |---|---|---|---| | `font-sans` | `--font-sans` | Inter | `@fontsource-variable/inter` | | `font-heading` | `--font-heading` | **Inter as well** | `@fontsource-variable/inter` | | `font-mono` | `--font-mono` | Geist Mono | `geist` | They arrive as **npm font packages**, not `next/font`. And headings default to the *same* family as body — so a DESIGN.md that gives headings their own face has to override `--font-heading` explicitly; inheriting the default silently flattens the type hierarchy to one family. 3. **Reconcile with `DESIGN.md`** (if present). Coss tokens are the same CSS variables as shadcn/ui, so DESIGN.md values override Coss's neutral defaults **in `globals.css`** — do not fork Coss's token structure, override its values. Follow `references/design-md-reconciliation.md`; this is the exact `registry.json` token-install path `design-md-to-app` already uses, with `@coss/colors-neutral` as the base being overridden. 4. Wire the dark/light toggle and the rest of the standard scaffold via `design-md-to-app`'s mandatory steps (theme toggle, error/loading boundaries, folder convention) — Coss primitives slot into `components/ui/` like any shadcn primitive. 5. Update `.workflow/meta.json`: `stack.ui = "coss"`, `stack.ui_base = "base"`, `stack.css_variables = true`, bump `phase` to `scaffolded` (only forward), append `history` (`{ "skill": "coss-ui", "action": "init" }`). ## Add mode (existing scaffolded project) Goal: add ONE thing — a primitive set, a component, or particles — idempotently. 1. Ensure the `@coss` registry is resolvable in `components.json` (`references/coss-registry.md`). If not configured, add it once. 2. Add exactly what was asked, using the verbatim command from the component's docs page: - primitives: `pnpm dlx shadcn@latest add @coss/ui` - one component: `pnpm dlx shadcn@latest add @coss/` (e.g. `@coss/button`, `@coss/combobox`) - tokens only: `pnpm dlx shadcn@latest add @coss/colors-neutral` - particles: per the particle's docs command. 3. Keep tokens reconciled — if the add pulled a fresh token block, re-apply the DESIGN.md overrides (`references/design-md-reconciliation.md`). 4. **Prefer the Coss/Base-UI primitive over hand-rolled components** — the same mandate `design-md-to-app` enforces for shadcn: scan `components/ui/*` before authoring anything custom. 5. Append `history` (`{ "skill": "coss-ui", "action": "add-" }`). No phase bump. ## Definition of Done (per run) - **Init**: `pnpm --filter web lint typecheck build` (or the app's equivalent) exits 0; the app runs; Coss primitives are in `components/ui/`; `globals.css` carries the DESIGN.md-reconciled tokens; `meta.json#stack.ui = "coss"`. - **Add**: the requested component/primitive/particle is present and imports resolve; a re-run detects it and skips (idempotent). - Script stays green: `cd coss-ui/scripts && python3 -m unittest test_check_coss_state`. ## What this skill does NOT do - Doesn't write the `DESIGN.md` (use `figma-to-design-md` / `image-to-design-md`). - Doesn't own the generic Next.js scaffold internals (theme toggle, error boundaries, folder convention) — those are `design-md-to-app`'s; this skill composes with them. - Doesn't wire backend modules (`module-add`) or build React Native (RN uses NativeWind, not Coss). - Doesn't silently ship AGPLv3 code into a closed-source product — it surfaces the license split first. - Doesn't work on Tailwind v3. ## Reference files - `references/coss-registry.md` — exact `@coss/*` commands, the namespaced-registry mechanism, components vs particles vs atoms, AI-first claim (no official MCP server documented). - `references/design-md-reconciliation.md` — Coss tokens = shadcn CSS vars; how DESIGN.md overrides them; tie-in to `design-md-to-app`'s `registry.json` install. - `references/deps-and-license.md` — Tailwind v4, `@base-ui/react`, the MIT/AGPLv3 split, when Coss is the right/wrong pick. - `references/contracts.md` — the `.workflow/` dev-flow contract (vendored copy).