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 https://coss.com/ui/docs (get-started + each component page shows its exact pnpm dlx shadcn@latest add @coss/<name> 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 <project-root> (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:

   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:

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/<name> (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-<name>" }). 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).