Installation

1. Install

The optional peers are per entry point — skip the ones you will not import.

# the package
pnpm add @comitor/ui

# required peers
pnpm add react react-dom lucide-react
pnpm add -D tailwindcss @tailwindcss/postcss

# optional peers — only for the entry you use
pnpm add next next-themes   # @comitor/ui/shell
pnpm add recharts           # @comitor/ui/chart
pnpm add react-hook-form    # @comitor/ui/form
pnpm add @uppy/core @uppy/xhr-upload  # @comitor/ui/uploader

2. Load the stylesheet

This is the step that goes wrong most often, and it fails in a way that looks like something else entirely.

/* app/globals.css — exactly these two lines, in this order */
@import "tailwindcss";
@import "@comitor/ui/styles.css";

/* postcss.config.mjs — Tailwind v4 needs one plugin and nothing else.
   No autoprefixer, no postcss-import; v4 absorbed both. */
const config = {
  plugins: {
    "@tailwindcss/postcss": {}
  }
}

export default config

What that import does to your markup

Everything above is about getting the file loaded. Once it is, its @layer base block styles your elements too, not only the ones that come out of the package — four rules that no class of yours asked for and none of which announce themselves.

/* @comitor/ui/styles.css — the whole @layer base block */
@layer base {
  /* Default border colour for EVERY element. */
  * { @apply border-border outline-ring/50; }

  body { @apply bg-background text-foreground font-sans antialiased; }

  /* Tailwind v4 dropped this from preflight; the package puts it back. */
  button:not(:disabled):not([aria-disabled="true"]),
  [role="button"]:not(:disabled):not([aria-disabled="true"]),
  label[for] { cursor: pointer; }

  /* The focus signature: 2px, offset 2px, --ring. */
  :focus-visible { @apply outline-2 outline-offset-2 outline-ring; }
}

• The * rule is the one that bites. --border is the decorative rule colour, 1.16:1 and deliberately under every contrast threshold — so a control that writes border without naming a colour gets a border you cannot see, and nothing reports it. Controls always name one: border-input, or border-choice-edge for a checkbox or radio. See Colours.
• Focus is a page-wide signature. Every focusable element gets a 2px --ring outline at 2px offset, with no class on your side. Components that follow a different convention opt out explicitly — menu and command rows swap it for an --accent background, because focus there moves under the arrow keys.
• body carries the background, text colour, font and antialiasing, so a page that renders nothing but text is already on-palette.

The cursor rule, as a worked example (1.7.1)

Tailwind v3’s preflight carried button, [role="button"] { cursor: pointer }. Tailwind v4 dropped it to follow the browser default, so on v4 every <button> computes cursor: default — no build error, no warning, nothing to grep for. On one real toolbar the <a> had the hand and the two <button>s beside it did not, though all three looked identical; a ghost button on a flat background then reads as a label. The package restores it in the base layer rather than in Button, so the raw <button>s you write are covered by the same rule — sprinkling cursor-pointer by hand only holds until the next component someone writes.

Disabled is excluded twice because that is two tests, not one — and both tests sit on both selectors. :not(:disabled) covers native controls; :not([aria-disabled="true"]) covers the Radix ones, which stay focusable on purpose and therefore never carry the attribute the first test looks for. The off values differ only because the elements have different user-agent defaults — default for a button, auto for a div; neither is a hand. A control inside <fieldset disabled> matches :disabled per the HTML spec, so a read-only screen built that way invites nothing.

label[for] is in because a label with a target is a control by proxy: clicking it focuses or toggles the thing it names. A bare <label> points at nothing and does nothing, so it deliberately gets no rule. This page is the proof: it loads the same stylesheet, so hovering any button here already gives you the hand.

3. Load the font

The package points --font-sans at --font-inter and expects your app to define it. Leave it undefined and the whole declaration is invalid at computed-value time — the fallbacks after it are never reached.

// app/layout.tsx
import { Inter } from 'next/font/google'

// The package consumes --font-inter; it never loads a font itself.
// The vietnamese subset is not optional — without it Vietnamese
// diacritics fall back to a system font and the text visibly shifts.
const inter = Inter({
  subsets: ['latin', 'vietnamese'],
  weight: ['400', '500', '600', '700', '800'],
  display: 'swap',
  variable: '--font-inter',
})

4. Wire the providers

Four independent display axes, all at the root layout, all per-user and per-device. Each renders its own anti-flash script — you add nothing to <head>. Only the theme axis is strictly required; drop the other three if you do not want to offer them.

// app/layout.tsx
import { ContrastProvider, DensityProvider, FontSizeProvider, ThemeProvider } from '@comitor/ui/shell'
import './globals.css'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    // suppressHydrationWarning is required: all four scripts touch <html>
    // before React hydrates, so server and client HTML never match.
    <html lang="en" suppressHydrationWarning className={inter.variable}>
      <body className="min-h-dvh bg-background font-sans text-foreground antialiased">
        <ThemeProvider>
          <ContrastProvider>
            <DensityProvider>
              <FontSizeProvider>{children}</FontSizeProvider>
            </DensityProvider>
          </ContrastProvider>
        </ThemeProvider>
      </body>
    </html>
  )
}

Not on Next? Skip this step and the /shell entry entirely — the main entry has no framework dependency. See Display Axes for what each one does.

5. Render something

That is the whole setup. Every component comes from the same import.

The six entry points

The split is not tidiness. The package builds one ES module per source file, so a barrel that re-exported a file importing next would force every consumer to install Next or fail at resolve time. Each optional peer therefore sits behind its own door.

// Tier 3 — the whole application frame in one component.
import { AppShell } from '@comitor/ui/shell'

export default function AppLayout({ children }: { children: React.ReactNode }) {
  return (
    <AppShell nav={NAV} workspaces={WORKSPACES} apps={APPS} user={USER}>
      {children}
    </AppShell>
  )
}

Three things worth knowing early

Twenty names appear at more than one entry

export * only errors on a duplicate name within the same entry. A name exported from two different entries is completely silent — no build error, no warning, and the two imports read identically at the call site. So the only way to answer “is this one binding or two?” is to look it up. Twenty names are in that position, and exactly two of them are a real fork.

The rule for using it: take the binding at @comitor/ui day to day, and reach for /form only once the app already uses react-hook-form. Only FormField and FormFieldProps are two implementations — never import both. Every other name in the table is one binding seen through two doors, so which door you use changes nothing but your import line. That is worth keeping: getVietnameseInitials once had two bodies that upper-cased differently, and the same name quietly returned different initials depending on where you imported it from.

Two near-misses that are not on the list. Toaster and SonnerToaster are two different components with two deliberately different names, so they can never collide — the first takes a theme prop, the second reads next-themes itself. And useIsMac ships from @comitor/ui only; /shell uses it internally but does not re-export it.

Default strings are Vietnamese

Including aria-label and sr-only text, which is the half you will not notice by looking. Override through labels.

import { TablePagination } from '@comitor/ui'

// Every default string in the package is Vietnamese, sr-only text included.
// Override per key — the component always spreads over its defaults, and keys
// that interpolate a number are FUNCTIONS, because word order differs by language.
const EN = {
  region: 'Pagination',
  unitLabel: 'items',
  pageSizePrefix: 'Show',
  pageSizeSelect: (unit) => `${unit} per page`,
  range: (start, end, total, unit) => `${start}–${end} of ${total} ${unit}`,
  pageStatus: (page, count) => `Page ${page} of ${count}`,
  firstPage: 'First page',
  previousPage: 'Previous page',
  nextPage: 'Next page',
  lastPage: 'Last page',
}

<TablePagination {...paging} labels={EN} unitLabel="invoices" />

All six entries load under plain Node ESM

Not just inside a bundler. Every entry resolves through the package’s exports map under Node on its own, which is what you are standing on any time the package is used outside a build: a script that renders an email or a PDF from /tokens, a test runner in a node environment, a codegen step. Import by package name rather than reaching into dist/ — the deep path skips the exports map and is not a supported entry.

// A plain Node script — no bundler, no transpile step, no framework.
// Import by package NAME so resolution goes through the exports map;
// reaching into dist/ bypasses it and is not supported.
import { semantic, gold } from '@comitor/ui/tokens'
import { getVietnameseInitials } from '@comitor/ui'

// /shell resolves too, and it is the one you would bet against:
// it reaches for next/*. Every internal specifier in the package
// carries its .js extension, which is what Node demands and what
// a bundler would have papered over.
import { isNavItemActive } from '@comitor/ui/shell'

const cell = `<td style="background:${semantic.light.card};color:${gold[500]}">`
console.log(getVietnameseInitials('Nguyễn Văn An')) // NA

This is a property worth stating because it is so easy to lose. A bundler supplies a missing file extension; Node does not, so a single internal specifier written as next/link instead of next/link.js is invisible in every Next app and fatal in a script — ERR_MODULE_NOT_FOUND at import, before any of your code runs. A publish gate loads all six entries by name and fails the release if any of them will not come up, so this holds for the version you install rather than only for the one that was tested.

Where to go next