Cài đặt

1. Cài gói

Peer tuỳ chọn tính theo từng entry — entry nào không import thì bỏ qua peer của nó.

# 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 @tanstack/react-table  # @comitor/ui/data-grid
pnpm add react-hook-form    # @comitor/ui/form
pnpm add @uppy/core @uppy/xhr-upload  # @comitor/ui/uploader

# @comitor/ui/editor and @comitor/ui/chat — every @tiptap package at ONE version
pnpm add @tiptap/core @tiptap/pm @tiptap/react @tiptap/starter-kit @tiptap/markdown   @tiptap/extensions @tiptap/extension-list @tiptap/extension-table @tiptap/extension-image   @tiptap/extension-mention @tiptap/suggestion @tiptap/extension-paragraph   @tiptap/extension-code-block-lowlight lowlight highlight.js

2. Nạp stylesheet

Đây là bước hay sai nhất, và khi sai thì trông như một lỗi hoàn toàn khác.

/* 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

Lệnh import đó làm gì với markup của app

Mọi thứ ở trên là để nạp được file. Nạp xong, khối @layer base của nó tạo kiểu cho cả phần tử của app, không chỉ phần tử đến từ gói — bốn luật mà không class nào của app yêu cầu, và không luật nào tự lên tiếng.

/* @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; }
}

• Luật * là luật hay gây chuyện. --border là màu đường kẻ trang trí, 1,16:1 và cố ý nằm dưới mọi ngưỡng tương phản — nên một điều khiển viết border mà không gọi tên màu sẽ có viền không nhìn thấy, và không gì báo lỗi. Điều khiển luôn gọi tên một màu: border-input, hoặc border-choice-edge cho checkbox hay radio. Xem Màu sắc.
• Focus là một dấu hiệu chung của cả trang. Mọi phần tử focus được đều có outline --ring 2px, lệch 2px, mà app không phải thêm class nào. Component theo quy ước khác thì chủ động tắt nó — hàng của menu và command thay nó bằng nền --accent, vì focus ở đó di chuyển theo phím mũi tên.
• body mang nền, màu chữ, font và khử răng cưa, nên một trang chỉ render chữ đã đúng bộ màu.

Luật con trỏ, một ví dụ cụ thể (1.7.1)

Preflight của Tailwind v3 có button, [role="button"] { cursor: pointer }. Tailwind v4 bỏ nó để theo mặc định của trình duyệt, nên trên v4 mọi <button> tính ra cursor: default — không lỗi build, không cảnh báo, không gì để grep. Trên một thanh công cụ thật, <a> có bàn tay còn hai <button> cạnh nó thì không, dù cả ba trông y hệt nhau; khi đó một nút ghost trên nền phẳng đọc như một nhãn. Gói khôi phục luật này ở lớp base chứ không ở Button, nên cả những <button> thô app tự viết cũng được cùng luật che — rải cursor-pointer bằng tay chỉ giữ được tới component kế tiếp mà ai đó viết.

Disabled bị loại hai lần vì đó là hai phép thử chứ không phải một — và cả hai phép thử nằm trên cả hai selector. :not(:disabled) lo cho điều khiển native; :not([aria-disabled="true"]) lo cho điều khiển Radix, vốn cố ý vẫn focus được nên không bao giờ mang thuộc tính mà phép thử thứ nhất tìm. Giá trị lúc tắt khác nhau chỉ vì các phần tử có mặc định user-agent khác nhau — default cho button, auto cho div; không cái nào là bàn tay. Một điều khiển trong <fieldset disabled> khớp :disabled theo spec HTML, nên một màn chỉ đọc dựng theo cách đó không mời bấm vào đâu.

label[for] có mặt vì một label có đích là một điều khiển gián tiếp: bấm vào nó thì focus hoặc bật tắt thứ nó gọi tên. Một <label> trần không trỏ vào gì và không làm gì, nên cố ý không có luật. Chính trang này là bằng chứng: nó nạp cùng stylesheet, nên di chuột lên bất kỳ nút nào ở đây cũng đã thấy bàn tay.

Một luật nằm ngoài layer: ô nhập 16px trên iOS

Từ 3.13.4, stylesheet có thêm một khối chạm tới markup của app, và nó cố ý nằm ngoài mọi @layer, nên thắng utility mà không cần !important. WebKit trên iOS và iPadOS phóng to cả trang khi một ô có chữ dưới 16px nhận focus, và không thu lại — trên iPhone, một màn đăng nhập phình quá khung nhìn và mất mép phải. Nên chỉ trên hai hệ đó (không trình duyệt nào khác khớp phép thử @supports), mọi ô gõ chữ được giữ ở 16px — hoặc bằng cỡ chữ xung quanh, khi cỡ đó lớn hơn. Android và desktop giữ cỡ mà component đặt: 16px dưới md, 14px từ md trở lên (Input).

/* @comitor/ui/styles.css — section 5e, outside every @layer (3.13.4) */
@supports (-webkit-touch-callout: none) {
  input:not([type="checkbox"], [type="radio"], [type="range"], [type="file"], [type="color"], [type="hidden"]),
  textarea,
  select,
  [contenteditable="true"] {
    font-size: max(16px, 1em);
  }
}

3. Nạp font

Gói trỏ --font-sans vào --font-inter và chờ app định nghĩa biến đó. Để trống thì cả khai báo không hợp lệ lúc tính giá trị — các font dự phòng sau nó không bao giờ được dùng tới.

// 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. Gắn các provider

Bốn trục hiển thị độc lập, tất cả ở root layout, tất cả theo từng người dùng và từng thiết bị. Mỗi provider tự render script chống nháy của nó — không phải thêm gì vào <head>. Chỉ trục theme là thật sự bắt buộc; bỏ ba trục kia nếu không muốn cung cấp.

// 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>
  )
}

Không dùng Next? Bỏ qua bước này và cả entry /shell — entry chính không phụ thuộc framework nào. Xem Display Axes để biết mỗi trục làm gì.

6. Render thử

Thiết lập chỉ có vậy. Mọi component đến từ cùng một lệnh import.

Chín entry

Cách chia không phải để cho gọn. Gói build một ES module cho mỗi file nguồn, nên một barrel re-export một file có import next sẽ buộc mọi nơi dùng gói phải cài Next, nếu không thì hỏng lúc resolve. Vì thế mỗi peer tuỳ chọn nằm sau một cửa riêng.

// 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>
  )
}

Ba điều nên biết sớm

Hai mươi tên xuất hiện ở hơn một entry

export * chỉ báo lỗi tên trùng trong cùng một entry. Một tên được export từ hai entry khác nhau thì hoàn toàn im lặng — không lỗi build, không cảnh báo, và hai lệnh import trông y hệt nhau ở chỗ gọi. Nên cách duy nhất để trả lời “đây là một binding hay hai?” là tra. Hai mươi tên ở vào thế đó, và đúng hai trong số đó thật sự rẽ nhánh.

Luật dùng: hằng ngày lấy binding ở @comitor/ui, và chỉ dùng tới /form khi app đã dùng react-hook-form. Chỉ FormField và FormFieldProps là hai bản hiện thực — đừng bao giờ import cả hai. Mọi tên khác trong bảng là một binding nhìn qua hai cửa, nên dùng cửa nào cũng chỉ đổi dòng import. Điều đó đáng giữ: getVietnameseInitials từng có hai thân hàm viết hoa khác nhau, và cùng một tên lặng lẽ trả về chữ viết tắt khác nhau tuỳ nơi import.

Hai trường hợp suýt trùng không có trong danh sách. Toaster và SonnerToaster là hai component khác nhau với hai tên cố ý khác nhau, nên không bao giờ đụng nhau — cái đầu nhận prop theme, cái sau tự đọc next-themes. Còn useIsMac chỉ có ở @comitor/ui; /shell dùng nó bên trong nhưng không re-export.

Server Component render được gói, nhưng không cấu hình gói bằng hàm được

Phần lớn component mang sẵn 'use client' bên trong gói, nên một trang server render chúng mà không cần chỉ thị riêng — phần đó tự chạy. Thứ không qua được từ server sang client là hàm: một nhãn chèn số, một hàm định dạng, một locale date-fns. Trình kiểm kiểu chấp nhận cả ba, rồi trang không render được. Hook (useRating, useStepper, useComitorLocale…) cố ý ném lỗi trên server. Bản đồ đầy đủ thứ gì chạy ở đâu nằm ở trang Server và client.

// app/products/[id]/page.tsx — a Server Component
import { Rating } from '@comitor/ui'

// ✓ strings, numbers and booleans cross the server → client boundary
<Rating value={4.5} step={0.5} readOnly aria-label="Rated 4.5 out of 5" />

// ✗ a function does not. The page fails to render with
//   "Functions cannot be passed directly to Client Components…"
<Rating value={4.5} step={0.5} readOnly itemLabel={(value) => `${value} étoiles`} />

// Same for a date-fns locale object, a labels key that interpolates a number,
// a formatter. Move the function into a component that starts with
// 'use client', and render THAT from the server page.

Cả chín entry nạp được dưới Node ESM thuần

Không chỉ trong bundler. Mỗi entry tự resolve qua map exports của gói dưới Node, và đó là thứ app dựa vào mỗi khi gói được dùng ngoài một bản build: một script render email hay PDF từ /tokens, một test runner trong môi trường node, một bước sinh mã. Import theo tên gói thay vì thò vào dist/ — đường dẫn sâu bỏ qua map exports và không phải entry được hỗ trợ.

// 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

Tính chất này đáng nói ra vì nó quá dễ mất. Bundler tự bù phần đuôi file bị thiếu; Node thì không, nên chỉ một specifier nội bộ viết next/link thay vì next/link.js là vô hình trong mọi app Next nhưng làm sập một script — ERR_MODULE_NOT_FOUND lúc import, trước khi bất kỳ dòng mã nào của app chạy. Một cổng phát hành nạp cả chín entry theo tên và đánh trượt bản phát hành nếu entry nào không lên, nên điều này đúng cho chính phiên bản được cài chứ không chỉ cho bản đã được test.

Đi tiếp đâu